# Use curl

> Configure HTTP or socks5h proxies and inspect failures with curl.
>
> Web page: https://ports.io/docs/guides/curl/
> Documentation index: https://ports.io/llms.txt

Use curl to make a request through an HTTP or SOCKS5 proxy and inspect a connection before configuring a larger application. Set `PORTS_PROXY_URL` to your assigned proxy URL, including its scheme, hostname, and port. Supply the full `rp1_...` key as `PORTS_PROXY_KEY`.

## Configure the proxy transport

| Proxy URL format | Behavior |
| --- | --- |
| `http://HOST:PORT` | HTTP proxy over plaintext TCP |
| `https://HOST:PORT` | HTTP proxy with TLS to the proxy |
| `socks5h://HOST:PORT` | SOCKS5 with the destination hostname resolved by the exit |

These show formats only. Use your assigned endpoint, without embedded credentials, and keep the assigned port. A standard `socks5h://` connection uses plaintext TCP to the proxy, so it cannot be pointed directly at an HTTPS proxy's TLS-only port.

For SOCKS5, use `socks5h://` rather than curl's locally resolving `socks5://` mode. The gateway requires a hostname and rejects destination IP addresses. `--socks5-hostname HOST:PORT` is curl's equivalent remote-DNS option. See the [curl options reference](https://curl.se/docs/manpage.html#--socks5-hostname).

## Request an HTTPS URL

```sh
curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/
```

`--proxy` identifies the proxy; `--proxy-user` supplies the routing username and full key for HTTP Basic or SOCKS5 username/password authentication. The final URL is the destination and must contain a hostname. curl opens an HTTP CONNECT or SOCKS5 tunnel, then negotiates TLS with the HTTPS destination. Keep certificate verification enabled. The timeouts here are example client settings. [curl options reference](https://curl.se/docs/manpage.html).

The password is the complete secret shown when you created a key. Keep it out of source control, shared logs, and pasted diagnostics. Command arguments can be visible to other processes; use your environment's protected credential-loading method for unattended execution.

## Select a country

Change the username while keeping the same endpoint and password.

```sh
curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_rotate_countries_US:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/
```

The route requires an eligible United States exit. A valid country code is a filter, not a guarantee that an exit is currently available. See [routing](https://ports.io/docs/reference/username-reference.md).

## Reuse a sticky route

```sh
curl --proxy "$PORTS_PROXY_URL" \
  --proxy-user "v1_sticky_session_checkout-42:$PORTS_PROXY_KEY" \
  --connect-timeout 10 \
  --max-time 30 \
  https://example.com/
```

Use the same session ID for connections that belong together. Sticky sessions permit failover when the selected exit becomes unavailable. `v1_fixed_session_checkout-42` requests a route that does not fail over. See [sessions](https://ports.io/docs/reference/sessions.md) before choosing between them.

## Inspect a failure

For a local investigation, add `--verbose` to see connection stages. Redact proxy credentials and any destination credentials before sharing output. An error during proxy negotiation, authentication, or tunnel setup happens before the destination response; an HTTP error after tunnel establishment can come from the destination. SOCKS5 setup errors are not HTTP statuses or JSON error codes. See [errors and troubleshooting](https://ports.io/docs/reference/troubleshooting.md).

On Windows PowerShell, use `curl.exe`, read variables as `$env:PORTS_PROXY_URL` and `$env:PORTS_PROXY_KEY`, and put the command on one line.