---
title: "Proxy Documentation: Setup, Auth & Geo-Targeting | Proxonym"
description: "Set up Proxonym proxies: hosts and ports, authentication, rotating and sticky sessions, geo-targeting, code examples in 7 languages and error codes."
url: https://proxonym.com/docs
updated: 2026-10-01T21:01:06+00:00
---

# Proxonym documentation

Everything you need to connect to Proxonym: endpoints and ports, authentication, sessions, geo-targeting, code examples and error handling.

- Gateway `gw.proxonym.com`
- HTTP / HTTPS `8000`
- SOCKS5 `1080`
- Targeting `USERNAME-country-us-session-a7k2`

### Contents

Quick reference

- **Gateway**: `gw.proxonym.com`
- **HTTP / HTTPS**: `8000`
- **SOCKS5**: `1080`
- **Country**: `-country-de`
- **City**: `-city-berlin`
- **Sticky IP**: `-session-a7k2`
- **Hold for**: `-lifetime-30`

Gateway errors

- `407` Credentials or whitelist
- `402` Balance or plan expired
- `403` Target blocked by the AUP
- `429` Rate guard, slow down
- `502` Peer failed, retry
- `504` Target timed out

**Stuck?** The help center covers billing, errors and account questions.

[Help center](https://proxonym.com/help) [Test a proxy](https://proxonym.com/proxy-checker)

## Quick start

This guide takes you from a new plan to a working proxy request in a few minutes. It uses residential proxies on the shared gateway, `gw.proxonym.com`. Other products connect the same way through their own host or proxy list; see [Endpoints and ports](https://proxonym.com/docs#endpoints-and-ports).

### Three steps

1. **Top up and choose a plan.** Add funds to your balance in crypto from $30, then pick a product and size in the dashboard (see the [pricing page](https://proxonym.com/pricing)) and pay from your balance. Residential, mobile, unlimited residential, shared datacenter and SERP API plans are active at once. ISP and dedicated IPs are delivered in under an hour.
2. **Copy your credentials.** Your proxy username and password are in the dashboard. In every example on this page, replace `USERNAME` and `PASSWORD` with your own values.
3. **Send a request.** Point your client at `gw.proxonym.com:8000` and authenticate with your username and password. Options such as country and session go in the username.

### Send your first request

This command sends one request through a residential IP in Germany and prints the IP address the target sees:

**Shell**

```bash
curl -x http://gw.proxonym.com:8000 -U "USERNAME-country-de-session-a7k2:PASSWORD" https://api.ipify.org
```

- `-x http://gw.proxonym.com:8000` sets the proxy. Keep the `http://` scheme even for HTTPS targets: the gateway opens an encrypted tunnel with `CONNECT`.
- `-U "USERNAME-country-de-session-a7k2:PASSWORD"` sends your credentials. `-country-de` selects an IP in Germany, and `-session-a7k2` keeps that IP for later requests with the same username, for 10 minutes by default.
- `https://api.ipify.org` is the target. It replies with the IP address it sees, which is your exit IP, for example `203.0.113.58`.

On Windows, type `curl.exe` instead of `curl`. Windows PowerShell 5.1 maps `curl` to `Invoke-WebRequest`, which takes different options.

### Verify the exit IP

1. Run `curl https://api.ipify.org` without the proxy. That is your own IP, also shown on [What is my IP](https://proxonym.com/what-is-my-ip).
2. Run the proxied command again. The IP should differ from yours and stay the same on every run while the session lasts.
3. Remove `-session-a7k2` from the username and run the command a few times. Each request now exits from a new IP.
4. Confirm the location with an IP geolocation service, through the proxy. The `country` field in the reply should read `DE`.

**Shell**

```bash
curl -s -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-de:PASSWORD" \
  https://ipinfo.io/json
```

A `407` response means the proxy rejected your credentials. Check them for typos and make sure options are joined with dashes, without spaces. Every other code is explained in [Errors and troubleshooting](https://proxonym.com/docs#errors-and-troubleshooting).

Next, control when your IP changes with [sessions](https://proxonym.com/docs#rotating-and-sticky-sessions), choose locations with [geo-targeting](https://proxonym.com/docs#geo-targeting), or copy a client from the [code examples](https://proxonym.com/docs#code-examples).

## Authentication

Proxonym authenticates proxy connections in two ways: a username and password sent with each connection, or an IP whitelist that lets listed machines connect without credentials. The methods available depend on the product.

| Product | Username and password | IP whitelist |
| --- | --- | --- |
| Residential, mobile, unlimited residential | Yes, with username options | No |
| Shared datacenter | Yes | Yes, 3 IPs included |
| ISP | Yes, credentials in your proxy list | No |
| Dedicated datacenter | Yes, credentials in your proxy list | No |

The account API and the SERP API use API keys instead. See the [API reference](https://proxonym.com/docs/api#authentication).

### Username and password

Your proxy username and password are in the dashboard. Clients send them with HTTP Basic proxy authentication (the `Proxy-Authorization` header) or with the SOCKS5 username/password method. Most tools accept them in one of two forms:

- inside a proxy URL: `http://USERNAME:PASSWORD@gw.proxonym.com:8000`
- as separate settings, such as cURL's `-U USERNAME:PASSWORD` or the proxy-auth option of your HTTP library

On residential, mobile and unlimited residential, the username also carries options, appended with dashes: `USERNAME-country-us-city-new_york-session-a7k2-lifetime-30`. The password stays the same whatever options you add. Options are covered in [Rotating and sticky sessions](https://proxonym.com/docs#rotating-and-sticky-sessions) and [Geo-targeting](https://proxonym.com/docs#geo-targeting).

If your password contains characters such as `@`, `:`, `/` or `#`, percent-encode them inside proxy URLs: `@` becomes `%40`. Unencoded, they break URL parsing and cause `407` errors or connection failures. Separate username and password settings need no encoding.

### IP whitelist (shared datacenter)

Shared datacenter proxies can authenticate by source IP instead of credentials, which helps with tools that can't send a proxy username. Every shared datacenter plan includes 3 whitelisted IPs.

1. Find the public IP of the machine that will connect: run `curl https://api.ipify.org` on it.
2. Add that IP in the dashboard or with `POST /whitelist` (see the [Whitelist API](https://proxonym.com/docs/api#whitelist)).
3. Connect to any `ip:port` from your datacenter list, without credentials:

**Shell**

```bash
curl -x http://198.51.100.23:3129 https://api.ipify.org
```

Whitelist only machines with a fixed public IP, such as servers. Home and office connections often change IP, and requests from an IP that isn't listed fail with `407`. When all 3 slots are in use, remove an IP before you add a new one. If you'd rather not manage IPs, authenticate with your username and password instead.

### Sub-users

Sub-users are extra sets of proxy credentials under your account. Each one has its own username, password, optional traffic limit and status, and its traffic counts against your account balance. Use them to give each team, client or project its own credentials, cap a job's traffic in GB, track usage per sub-user, and revoke one set of credentials without touching the others.

Create them in the dashboard or with `POST /sub-users` (see the [Sub-users API](https://proxonym.com/docs/api#sub-users)). A sub-user's username takes the same options as yours, for example `sub_k3v9q2xd-country-gb-session-x91`. Once a sub-user reaches its traffic limit, its requests fail with `402` until you raise the limit. A disabled sub-user gets `407`.

### Rotating credentials safely

Treat proxy credentials like any other secret:

- Keep them in environment variables or a secrets manager, never in source code, repositories or client-side apps.
- Give each service its own sub-user, so a leak exposes one set of credentials, not all of them.
- Rotate on a schedule, and right away if you suspect a leak.

To rotate without downtime, run the old and new credentials side by side:

1. Create a new sub-user with `POST /sub-users`, giving it the same traffic limit as the old one.
2. Deploy the new username and password to every worker.
3. Watch the old sub-user's `traffic_used_gb` in the dashboard or with `GET /sub-users`. When it stops growing, nothing uses the old credentials anymore.
4. Delete the old sub-user with `DELETE /sub-users/{id}`.

After a leak, don't wait for a rollout: reset the password with `PATCH /sub-users/{id}` and the body `{"reset_password": true}`. The old password stops working immediately. Rotate API keys the same way: create a new key in the dashboard, deploy it, then revoke the old one.

## Endpoints and ports

Rotating products connect through a hostname. Static products give you a list of proxy IPs that you connect to directly. This table lists every entry point.

| Product | Host | HTTP port | SOCKS5 port | Auth | Format |
| --- | --- | --- | --- | --- | --- |
| [Residential](https://proxonym.com/residential-proxies) | `gw.proxonym.com` | `8000` | `1080` | Username and password | `USERNAME[-options]:PASSWORD` |
| [Mobile](https://proxonym.com/mobile-proxies) | `gw.proxonym.com` | `8000` | `1080` | Username and password | `USERNAME-type-mobile[-options]:PASSWORD` |
| [Unlimited residential](https://proxonym.com/unlimited-residential-proxies) | `de.unl.proxonym.com`, `use.unl.proxonym.com` or `usw.unl.proxonym.com`, as chosen at checkout | `8000` | `1080` | Username and password | `USERNAME[-options]:PASSWORD` |
| [ISP](https://proxonym.com/isp-proxies) | IPs from your list | Port in your list | Same port as HTTP | Username and password from your list | `ip:port:username:password` |
| [Shared datacenter](https://proxonym.com/datacenter-proxies) | IPs from your list | `3129` | `1081` | IP whitelist, or username and password | `ip:port` |
| [Dedicated datacenter](https://proxonym.com/dedicated-datacenter-proxies) | IPs from your list | Port in your list | Same port as HTTP | Username and password from your list | `ip:port:username:password` |

`[-options]` stands for optional username options such as `-country-us-session-a7k2`. Lists are covered in [Datacenter, ISP and dedicated proxy lists](https://proxonym.com/docs#proxy-lists).

### HTTPS targets

HTTP ports serve both `http://` and `https://` targets. For HTTPS, the proxy opens a `CONNECT` tunnel and TLS runs end to end, so you don't install any certificate. Write the proxy URL with `http://` even when the target uses HTTPS. Details are in [Protocols](https://proxonym.com/docs#protocols-https).

### APIs

| API | Base URL | Authentication |
| --- | --- | --- |
| Account API | `https://api.proxonym.com/v1` | `Authorization: Bearer <API_KEY>` |
| Google SERP API | `https://serp.proxonym.com/v1` | `X-API-Key` header |

Both are documented in the [API reference](https://proxonym.com/docs/api).

### Firewalls

Ports 8000, 1080, 3129 and 1081 aren't standard web ports, and some corporate networks and cloud security groups block them. If connections hang before any response, allow outbound TCP to the proxy host and port you use, plus UDP if you send UDP over SOCKS5.

## Rotating and sticky sessions

On residential, mobile and unlimited residential, the username decides when your exit IP changes. There are two modes: rotating, the default, and sticky.

### Rotating (default)

Without a session option, every request gets a new IP from the pool:

**Text**

```text
USERNAME-country-us
```

Rotating suits stateless jobs that fetch many independent pages. Each request looks like a different visitor, and a blocked IP costs you one request, not a whole job.

The gateway assigns an IP each time it routes a new request. Requests sent over a reused HTTPS connection travel through the same `CONNECT` tunnel and keep its IP. For a new IP every time, open a new connection per request, or use sticky sessions to decide exactly when the IP changes.

### Sticky sessions

Add `-session-{id}` to keep the same IP across requests. Every request that sends the same username, session ID included, uses the same IP until the session ends.

**Text**

```text
USERNAME-country-us-session-a7k2
USERNAME-country-us-session-a7k2-lifetime-30
```

- `-session-{id}`: 1 to 32 letters or digits, chosen by you. A new ID starts a new session on a new IP.
- `-lifetime-{minutes}`: how long the session keeps its IP. Without it, a session lasts 10 minutes.

| Product | Lifetime | Longest session |
| --- | --- | --- |
| Residential | 1–120 minutes, default 10 | `-lifetime-120` (2 hours) |
| Unlimited residential | 1–720 minutes, default 10 | `-lifetime-720` (12 hours) |
| Mobile | 1–3 minutes, set it explicitly | `-lifetime-3` (3 minutes) |

Residential and mobile IPs belong to real devices that can go offline. Treat the lifetime as a maximum, not a promise: a session can lose its IP early, and the request then fails with `502`. If you need the same IP for days, use [ISP](https://proxonym.com/isp-proxies) or [dedicated datacenter](https://proxonym.com/dedicated-datacenter-proxies) proxies.

### Example sequence

This script sends three requests in one sticky session, then three rotating requests:

**Shell**

```bash
# Sticky: same session ID, same IP for up to 30 minutes
for i in 1 2 3; do
  curl -s -x http://gw.proxonym.com:8000 \
    -U "USERNAME-country-us-session-job42-lifetime-30:PASSWORD" \
    https://api.ipify.org; echo
done

# Rotating: no session option, a new IP on every request
for i in 1 2 3; do
  curl -s -x http://gw.proxonym.com:8000 \
    -U "USERNAME-country-us:PASSWORD" \
    https://api.ipify.org; echo
done
```

Sample output:

**Text**

```text
203.0.113.41
203.0.113.41
203.0.113.41
203.0.113.187
203.0.113.9
203.0.113.152
```

To move a sticky session to a new IP before it ends, change the ID, for example to `-session-job43`.

### Best practices

- **Rotate** for stateless pages: search results, product pages, listings.
- **Stick** when the site expects one visitor across steps: logins, carts and checkouts, multi-step forms, pagination tied to a cookie.
- Use one session per worker, browser profile or account, with random IDs, so parallel jobs never share an IP by accident.
- Set the lifetime close to the length of the task. Shorter sessions spread your traffic over more IPs.
- Send exactly the same username for every request in a session. Changing the country or another option mid-session can move you to a different IP.
- After a block or a CAPTCHA, switch to a new session ID instead of retrying on the same IP.

For a longer look at when to use each mode, read our [comparison of rotating and sticky sessions](https://proxonym.com/blog/rotating-vs-sticky-sessions).

## Geo-targeting

Add location options to the username to choose where your exit IP is. They work on residential, mobile and unlimited residential. Static products are located by the IPs in your list, so filter the list by country instead.

### Parameters

| Option | Format | Examples |
| --- | --- | --- |
| `-country-{cc}` | ISO 3166-1 alpha-2 code, lowercase. Omit it for a random country. | `-country-us`, `-country-gb`, `-country-de` |
| `-state-{name}` | State or region, lowercase, spaces as underscores | `-state-california`, `-state-new_york` |
| `-city-{name}` | City, lowercase, spaces as underscores | `-city-new_york`, `-city-sao_paulo` |
| `-asn-{number}` | Autonomous system number of a network | `-asn-7922` (Comcast) |

### Rules

- Use `-state` or `-city`, never both in the same username.
- Include `-country` whenever you target a state, city or ASN. Many city names exist in more than one country.
- Country codes follow ISO 3166-1, so the United Kingdom is `gb`, not `uk`.
- Write names in plain lowercase ASCII with underscores: `sao_paulo`, not `São Paulo`.
- Keep options in the order used throughout these docs: country, state or city, ASN, type, session, lifetime.

### Examples

| Goal | Username |
| --- | --- |
| Random country | `USERNAME` |
| United States | `USERNAME-country-us` |
| California | `USERNAME-country-us-state-california` |
| New York City | `USERNAME-country-us-city-new_york` |
| Comcast subscribers in the US | `USERNAME-country-us-asn-7922` |
| São Paulo, Brazil | `USERNAME-country-br-city-sao_paulo` |
| London, same IP for 30 minutes | `USERNAME-country-gb-city-london-session-a7k2-lifetime-30` |
| US mobile carrier IP | `USERNAME-country-us-type-mobile` |

To check where an IP is, request an IP geolocation service through the proxy, as shown in [Verify the exit IP](https://proxonym.com/docs#quick-start-verify-exit-ip).

### Availability

- **Residential:** 55M+ IPs in 195+ countries. The largest pools are the United States (8.3M), Brazil (5.2M), India (3.2M), the United Kingdom (2.3M), Mexico (1.8M), Argentina (1.5M), Indonesia (1.4M) and the Philippines (1.1M).
- **Unlimited residential:** about 10M IPs in 180+ countries.
- **Mobile:** the United States (`us`), the United Kingdom (`gb`) and Austria (`at`), with more countries rolling out.

The narrower the target, the smaller the pool. A country has many IPs online at any moment; a small city or a single ASN may have few, so expect more retries and fewer distinct IPs. Country coverage is listed on [Locations](https://proxonym.com/locations).

### When no IP matches

The gateway returns `502` if no IP matches; broaden targeting. It retries before giving up, so a `502` that repeats for the same username usually means the combination is too narrow or misspelled.

To broaden, move from city to state, from state to country, or drop the ASN. Check spelling too: `-city-newyork` or `-country-uk` matches nothing.

## Mobile proxies

[Mobile proxies](https://proxonym.com/mobile-proxies) route your traffic through 3G, 4G and 5G carrier IPs. Carriers put many subscribers behind each public IP, so sites are careful about blocking them, which makes these IPs a good fit for social platforms and mobile-first apps.

### Connect

Mobile uses the residential gateway and your usual credentials. Add `-type-mobile` to the username:

**Shell**

```bash
curl -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-us-type-mobile:PASSWORD" \
  https://api.ipify.org
```

Mobile traffic draws from the same GB balance as residential. There is no separate mobile balance to top up.

### Locations

Mobile IPs are available in the United States (`-country-us`), the United Kingdom (`-country-gb`) and Austria (`-country-at`), with more countries rolling out. A country without mobile coverage has no matching IP, so the gateway returns `502`.

### Rotation and sessions

- **Rotating:** mobile IPs rotate per connection. Each new connection gets a new IP, and requests on a kept-alive connection share its IP.
- **Sticky:** add `-session-{id}` with a lifetime of 1 to 3 minutes. Always set the lifetime explicitly on mobile.

**Text**

```text
USERNAME-country-gb-type-mobile-session-m42x-lifetime-3
```

Three minutes covers a short flow, such as loading a profile page and its assets. Design longer flows to survive an IP change by keeping cookies and state in your client. For accounts that need one IP for days, use [ISP proxies](https://proxonym.com/isp-proxies).

## Unlimited residential

[Unlimited residential](https://proxonym.com/unlimited-residential-proxies) plans are billed by bandwidth and term instead of by GB. Traffic isn't metered: you get about 10M residential IPs in 180+ countries, and your plan's speed sets the maximum combined throughput.

### Gateway servers

Each plan runs on a dedicated gateway server that you choose at checkout. Pick the one closest to the machines that send the traffic; you can still target any country with `-country`.

| Server | Location | HTTP port | SOCKS5 port |
| --- | --- | --- | --- |
| `de.unl.proxonym.com` | Germany | `8000` | `1080` |
| `use.unl.proxonym.com` | US East | `8000` | `1080` |
| `usw.unl.proxonym.com` | US West | `8000` | `1080` |

**Shell**

```bash
curl -x http://use.unl.proxonym.com:8000 \
  -U "USERNAME-country-us-session-a7k2-lifetime-240:PASSWORD" \
  https://api.ipify.org
```

Username options work as on residential: country, state, city, ASN, session and lifetime. Connect only to the server of your plan.

### Bandwidth tiers and terms

Plans come in 100, 200, 400, 600 and 800 Mbps and 1 Gbps, for 1, 7 or 30 days. The tier caps the combined speed of all your connections, not the amount of data. Plans never auto-renew: when the term ends, requests fail with `402` until you renew. Prices are on the [pricing page](https://proxonym.com/pricing).

### Sticky sessions up to 12 hours

Unlimited residential accepts lifetimes from 1 to 720 minutes, so one session can keep its IP for up to 12 hours with `-lifetime-720`. As on residential, an IP can still go offline before its lifetime ends.

### UDP add-on

The UDP add-on, selected at checkout, enables UDP through SOCKS5 on port `1080` with the SOCKS5 `UDP ASSOCIATE` command. Without it, the gateway carries TCP only. See [UDP support](https://proxonym.com/docs#protocols-udp).

### Fair use

There is no GB cap and concurrency is unlimited. Use is subject to fair use under the [acceptable use policy](https://proxonym.com/acceptable-use). For sustained volumes beyond the self-serve tiers, see [enterprise plans](https://proxonym.com/enterprise). Background: [how unlimited residential proxies work](https://proxonym.com/blog/unlimited-residential-proxies-explained).

## Datacenter, ISP and dedicated proxy lists

Static products don't use the gateway. You connect directly to the proxy IPs assigned to your plan, which you download as a list.

### Download your list

Download the list from the dashboard, or fetch it with the account API:

**Shell**

```bash
curl -H "Authorization: Bearer $PROXONYM_API_KEY" \
  "https://api.proxonym.com/v1/proxies/datacenter?format=txt&country=us"
```

The product in the path is `datacenter`, `isp` or `dedicated`. `format` is `txt` (one proxy per line) or `json`, and `country` filters by country code. Details are in the [API reference](https://proxonym.com/docs/api#proxy-lists).

### Formats

| Product | Line format | Example line | Proxy URL |
| --- | --- | --- | --- |
| Shared datacenter | `ip:port` | `198.51.100.23:3129` | `http://198.51.100.23:3129` with a whitelisted IP, or `http://USERNAME:PASSWORD@198.51.100.23:3129`. SOCKS5: same IP, port `1081` |
| ISP | `ip:port:username:password` | `198.51.100.61:6200:isp_k8w2m4:Tz6pW1qR8nVb3xYc` | `http://username:password@ip:port` or `socks5h://username:password@ip:port` |
| Dedicated datacenter | `ip:port:username:password` | `198.51.100.112:6200:ded_r4n7c2:Mb9xK2vQ7tLp4wZe` | `http://username:password@ip:port` or `socks5h://username:password@ip:port` |

Always take the host and port from your list.

### Spreading requests over a list

Static IPs don't rotate on their own: each line always exits from its own IP. To spread requests, cycle through the list in your code:

**Python**

```python
import itertools

import requests

# proxies.txt holds one ISP or dedicated proxy per line: ip:port:username:password
with open("proxies.txt") as f:
    lines = [line.strip() for line in f if line.strip()]

def to_url(line: str) -> str:
    ip, port, user, password = line.split(":", 3)
    return f"http://{user}:{password}@{ip}:{port}"

pool = itertools.cycle([to_url(line) for line in lines])

for _ in range(5):
    proxy = next(pool)
    r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=30)
    print(r.text)
```

### Shared datacenter

- 40,000 IPs in 9 countries (United States, Brazil, Germany, France, United Kingdom, Canada, Thailand, Italy and Spain) plus a mixed pool. IPs are shared with other customers.
- HTTP on port `3129` and SOCKS5 on port `1081` of each IP, with UDP over SOCKS5.
- Authenticate with the [IP whitelist](https://proxonym.com/docs#authentication-ip-whitelist) (3 IPs included) or with your username and password.
- The list is static, with no rotation by default.
- Monthly bandwidth tiers of 250 GB, 1 TB, 5 TB or Unlimited. The Unlimited tier is subject to fair use.

### ISP proxies

- Static IPs registered to consumer ISPs, private to your account, with unlimited bandwidth.
- 17 locations: the United States (New York, Los Angeles, Virginia, a Comcast pool and a Verizon pool), Canada, Germany, the United Kingdom, Hong Kong, Japan, France, Italy, Poland, Spain, Singapore, Moldova and South Korea.
- Terms of 1, 7, 30 or 90 days, delivered in under an hour. Plans never auto-renew: check `expires_at` in the JSON list or in `GET /account` and renew when you choose.
- HTTP and SOCKS5 on the same port, with TCP and UDP over SOCKS5.

New to static residential IPs? Read [what an ISP proxy is](https://proxonym.com/blog/what-is-an-isp-proxy).

### Dedicated datacenter

- Private IPs reserved to your account in 8 countries: the United States, Canada, Germany, France, Italy, Japan, India and Taiwan.
- Username and password authentication, with credentials in your list. HTTP and SOCKS5 on the same port.
- Unlimited bandwidth, billed per IP per month.
- IP replacements on request: under **My plans** in the dashboard, choose **Replace IPs** and list the IPs with the reason.

## Protocols

Every product supports HTTP, HTTPS and SOCKS5. Use whichever your client supports: the IPs, credentials and username options are the same on every protocol. For the trade-offs, read our [SOCKS5 and HTTP comparison](https://proxonym.com/blog/socks5-vs-http-proxies).

### HTTP

For `http://` targets, your client sends the full request to the proxy, which forwards it to the target. Use the HTTP port and an `http://` proxy URL. More on the [HTTP proxies](https://proxonym.com/http-proxies) page.

### HTTPS (CONNECT)

For `https://` targets, your client asks the proxy to open a tunnel with `CONNECT`, then negotiates TLS with the target through it. Encryption is end to end and the certificate is the target's own, so no extra CA setup is needed. The proxy URL still starts with `http://`, because the connection to the proxy is plain HTTP until the tunnel opens. The exchange looks like this:

**Text**

```text
CONNECT example.com:443 HTTP/1.1
Host: example.com:443
Proxy-Authorization: Basic VVNFUk5BTUUtY291bnRyeS11czpQQVNTV09SRA==

HTTP/1.1 200 Connection established
```

The Base64 value encodes `USERNAME-country-us:PASSWORD`. Your HTTP library builds it for you.

### SOCKS5

SOCKS5 carries any TCP traffic, not only HTTP, and UDP on some products. Use port `1080` on the residential gateway and the unlimited servers, port `1081` on shared datacenter IPs, and the list port on ISP and dedicated IPs. Authentication uses the SOCKS5 username/password method, with the same credentials and username options as HTTP.

Resolve hostnames on the proxy side with `socks5h://`, where the `h` stands for remote DNS. With plain `socks5://`, your machine resolves the target's hostname itself: the lookup leaks to your own resolver and can return addresses meant for your location instead of the exit IP's.

**Shell**

```bash
curl -x socks5h://gw.proxonym.com:1080 \
  -U "USERNAME-country-us:PASSWORD" \
  https://api.ipify.org
```

In Python, install SOCKS support with `pip install "requests[socks]"` and use the same scheme:

**Python**

```python
import requests

proxy = "socks5h://USERNAME-country-us:PASSWORD@gw.proxonym.com:1080"
r = requests.get("https://api.ipify.org", proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.text)
```

More on the [SOCKS5 proxies](https://proxonym.com/socks5-proxies) page.

### UDP support

UDP runs over SOCKS5 with the `UDP ASSOCIATE` command defined in RFC 1928. Your client needs a SOCKS5 library that implements it; HTTP proxies can't carry UDP, and cURL doesn't support SOCKS5 UDP.

| Product | HTTP and HTTPS | SOCKS5 over TCP | SOCKS5 over UDP |
| --- | --- | --- | --- |
| Residential | Port 8000 | Port 1080 | No |
| Mobile | Port 8000 | Port 1080 | No |
| Unlimited residential | Port 8000 | Port 1080 | With the UDP add-on, port 1080 |
| ISP | List port | List port | Yes, list port |
| Shared datacenter | Port 3129 | Port 1081 | Yes, port 1081 |
| Dedicated datacenter | List port | List port | No |

If you need UDP, use ISP proxies, shared datacenter proxies, or unlimited residential with the UDP add-on.

## Code examples

Each example sends one request through a rotating US residential IP on `gw.proxonym.com:8000` and prints the response from `api.ipify.org`, which contains your exit IP. Replace `USERNAME` and `PASSWORD`, and change targeting by editing the username, for example `USERNAME-country-de-session-a7k2-lifetime-30`. In production, read credentials from environment variables.

### cURL

**Shell**

```bash
# Rotating US IP: a new IP on every run
curl -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-us:PASSWORD" \
  "https://api.ipify.org?format=json"

# Sticky New York IP for 30 minutes
curl -x http://gw.proxonym.com:8000 \
  -U "USERNAME-country-us-city-new_york-session-a7k2-lifetime-30:PASSWORD" \
  "https://api.ipify.org?format=json"
```

For SOCKS5, see [SOCKS5](https://proxonym.com/docs#protocols-socks5). More options in the [cURL integration guide](https://proxonym.com/integrations/curl).

### Python (requests)

**Python**

```python
import requests

USERNAME = "USERNAME-country-us"
PASSWORD = "PASSWORD"
GATEWAY = "gw.proxonym.com:8000"
URL = "https://api.ipify.org?format=json"

proxy = f"http://{USERNAME}:{PASSWORD}@{GATEWAY}"
proxies = {"http": proxy, "https": proxy}

# Rotating: each requests.get() opens a new connection and gets a new IP
r = requests.get(URL, proxies=proxies, timeout=(10, 60))
print(r.status_code, r.json())

# Sticky: the session ID keeps the IP; a Session also reuses the connection
sticky = f"http://{USERNAME}-session-a7k2-lifetime-30:{PASSWORD}@{GATEWAY}"
sticky_proxies = {"http": sticky, "https": sticky}
with requests.Session() as s:
    for _ in range(3):
        print(s.get(URL, proxies=sticky_proxies, timeout=(10, 60)).json())
```

The timeout tuple is (connect, read) in seconds. See the [Python requests integration](https://proxonym.com/integrations/python-requests) and our [guide to proxies in Python requests](https://proxonym.com/blog/python-requests-proxies).

### Python (aiohttp)

**Python**

```python
import asyncio

import aiohttp

PROXY = "http://gw.proxonym.com:8000"
AUTH = aiohttp.BasicAuth("USERNAME-country-us", "PASSWORD")
URL = "https://api.ipify.org?format=json"

async def fetch(session: aiohttp.ClientSession, n: int) -> None:
    async with session.get(URL, proxy=PROXY, proxy_auth=AUTH) as resp:
        data = await resp.json()
        print(n, resp.status, data["ip"])

async def main() -> None:
    timeout = aiohttp.ClientTimeout(total=60)
    async with aiohttp.ClientSession(timeout=timeout) as session:
        # 10 concurrent requests, each on its own connection, so each gets its own IP
        await asyncio.gather(*(fetch(session, n) for n in range(10)))

asyncio.run(main())
```

### Node.js (undici)

**JavaScript**

```javascript
// npm install undici, then save as proxy.mjs and run: node proxy.mjs
import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent("http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000");

const res = await fetch("https://api.ipify.org?format=json", {
  dispatcher,
  signal: AbortSignal.timeout(60_000),
});
console.log(res.status, await res.json());
```

The agent keeps connections alive, so consecutive requests through one `ProxyAgent` can share an IP. Use session IDs when you need explicit control. More in the [Node.js integration guide](https://proxonym.com/integrations/nodejs).

### Node.js (axios with https-proxy-agent)

**JavaScript**

```javascript
// npm install axios https-proxy-agent, then run as an ES module: node proxy.mjs
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const agent = new HttpsProxyAgent("http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000");

const { status, data } = await axios.get("https://api.ipify.org?format=json", {
  httpsAgent: agent,
  proxy: false, // the agent handles the proxy; turn off axios's own proxy handling
  timeout: 60_000,
});
console.log(status, data);
```

`HttpsProxyAgent` handles `https://` targets. For `http://` targets, pass an `HttpProxyAgent` from the `http-proxy-agent` package as `httpAgent`.

### PHP (cURL)

**PHP**

```php
<?php
$ch = curl_init('https://api.ipify.org?format=json');
curl_setopt_array($ch, [
    CURLOPT_PROXY          => 'http://gw.proxonym.com:8000',
    CURLOPT_PROXYUSERPWD   => 'USERNAME-country-us:PASSWORD',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_TIMEOUT        => 60,
]);
// For SOCKS5 with remote DNS, use CURLOPT_PROXY => 'socks5h://gw.proxonym.com:1080'

$body = curl_exec($ch);
if ($body === false) {
    fwrite(STDERR, 'cURL error: ' . curl_error($ch) . PHP_EOL);
    exit(1);
}
echo curl_getinfo($ch, CURLINFO_RESPONSE_CODE), ' ', $body, PHP_EOL;
```

More in the [PHP integration guide](https://proxonym.com/integrations/php).

### Go (net/http)

**Go**

```go
package main

import (
    "fmt"
    "io"
    "log"
    "net/http"
    "net/url"
    "time"
)

func main() {
    proxyURL, err := url.Parse("http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000")
    if err != nil {
        log.Fatal(err)
    }

    client := &http.Client{
        Transport: &http.Transport{Proxy: http.ProxyURL(proxyURL)},
        Timeout:   60 * time.Second,
    }

    resp, err := client.Get("https://api.ipify.org?format=json")
    if err != nil {
        log.Fatal(err)
    }
    defer resp.Body.Close()

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(resp.StatusCode, string(body))
}
```

More in the [Go integration guide](https://proxonym.com/integrations/go).

### Java (HttpClient)

**Java**

```java
import java.net.Authenticator;
import java.net.InetSocketAddress;
import java.net.PasswordAuthentication;
import java.net.ProxySelector;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class ProxyExample {
    public static void main(String[] args) throws Exception {
        // Java disables Basic auth for HTTPS proxy tunnels by default. Re-enable it
        // before the first HttpClient is built, or start the JVM with
        // -Djdk.http.auth.tunneling.disabledSchemes=
        System.setProperty("jdk.http.auth.tunneling.disabledSchemes", "");

        HttpClient client = HttpClient.newBuilder()
                .proxy(ProxySelector.of(new InetSocketAddress("gw.proxonym.com", 8000)))
                .authenticator(new Authenticator() {
                    @Override
                    protected PasswordAuthentication getPasswordAuthentication() {
                        if (getRequestorType() != RequestorType.PROXY) {
                            return null;
                        }
                        return new PasswordAuthentication("USERNAME-country-us", "PASSWORD".toCharArray());
                    }
                })
                .connectTimeout(Duration.ofSeconds(10))
                .build();

        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.ipify.org?format=json"))
                .timeout(Duration.ofSeconds(60))
                .build();

        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}
```

Requires Java 11 or later. Save as `ProxyExample.java` and run `java ProxyExample.java`. More in the [Java integration guide](https://proxonym.com/integrations/java).

### C# (HttpClient)

**C#**

```csharp
// .NET 6 or later: create a console app with "dotnet new console" and replace Program.cs
using System.Net;

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://gw.proxonym.com:8000")
    {
        Credentials = new NetworkCredential("USERNAME-country-us", "PASSWORD")
    },
    UseProxy = true
};

// Create one HttpClient per proxy configuration and reuse it
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(60) };

var body = await client.GetStringAsync("https://api.ipify.org?format=json");
Console.WriteLine(body);
```

### Browsers and frameworks

Setup guides for other tools: [Scrapy](https://proxonym.com/integrations/scrapy), [Puppeteer](https://proxonym.com/integrations/puppeteer), [Playwright](https://proxonym.com/integrations/playwright), [Selenium](https://proxonym.com/integrations/selenium), [AdsPower](https://proxonym.com/integrations/adspower) and [Multilogin](https://proxonym.com/integrations/multilogin). The full list is on [Integrations](https://proxonym.com/integrations).

## Errors and troubleshooting

When the proxy itself rejects or fails a request, it answers with one of the status codes below. Any other status comes from the target website.

### Proxy status codes

| Code | Meaning | Common causes | Fix |
| --- | --- | --- | --- |
| `407` | Proxy authentication required | Wrong username or password, a typo in the username options, an unencoded special character in the password, or, on shared datacenter, a source IP that isn't whitelisted | Copy the credentials from the dashboard again, check the options, percent-encode the password in URLs, or whitelist your IP |
| `402` | Payment required | Traffic balance used up, plan expired, or a sub-user at its traffic limit | Top up or renew; plans never auto-renew. Check balances with `GET /account`, or raise the sub-user's limit |
| `403` | Forbidden | The target is blocked by the [acceptable use policy](https://proxonym.com/acceptable-use) | Don't retry: the block applies to every account. Dedicated datacenter customers can ask about verification in a ticket |
| `429` | Too many requests | The request rate guard: your account went over the burst limit of about 10,000 requests per second | Lower your request rate and retry with exponential backoff |
| `502` | Bad gateway | The upstream peer failed or went offline, or no IP matches your targeting | Retry. If it repeats, broaden targeting, or switch to a new session ID on sticky sessions |
| `504` | Gateway timeout | The target didn't respond within 60 seconds | Retry, ideally on a new IP, and check that the target is up |

### Proxy error or target error?

A `403` or `429` can come from the proxy or from the website you're requesting. Proxy errors need a fix on your side or in your account; target errors mean the site refused the request.

- **HTTPS targets:** proxy errors arrive as the answer to `CONNECT`, before anything reaches the target. Clients report them as proxy or tunnel errors, for example cURL's `CONNECT tunnel failed, response 407` or Python's `ProxyError` with `Tunnel connection failed: 407`. A status code you read from a normal response comes from the target.
- **HTTP targets:** the proxy's error is the response itself. Run cURL with `-v` to see the whole exchange.

If the target blocks you with `403`, `429` or CAPTCHA pages, lower your rate, rotate IPs and match the IP's country to the site's audience. On well-protected sites, residential and mobile IPs are blocked less often than datacenter IPs. More in our guide to [web scraping without getting blocked](https://proxonym.com/blog/web-scraping-without-getting-blocked).

### Fixing 407

1. Test the bare credentials: `-U "USERNAME:PASSWORD"`. If that works, the problem is in the options.
2. Check the options: lowercase, joined with dashes, no spaces, and session IDs of 1 to 32 letters or digits.
3. Percent-encode special characters of the password inside proxy URLs.
4. Check that the whitelisted IP is still your machine's public IP, and that sub-users are `active`.

### SSL errors

- **`wrong version number` or `SSL: WRONG_VERSION_NUMBER`:** the proxy URL starts with `https://`. Change it to `http://`. The proxy port speaks plain HTTP; TLS to the target runs inside the tunnel.
- **Certificate verification failed:** TLS runs end to end, so the certificate is the target's. Update your CA bundle (in Python, `pip install -U certifi`), check the system clock, and look for a corporate TLS-inspection proxy on your network.
- **Handshake failure on a single target:** the site may reject your client's TLS settings. Update the client or library to a current version.

Don't turn off certificate checks (`curl -k`, `verify=False`) in production. It hides the cause and exposes your traffic to interception.

### Timeouts

- The proxy waits up to 60 seconds for the target, then returns `504`. With a shorter client timeout, you see a client-side timeout instead.
- Set a connect timeout of about 10 seconds and a read timeout of about 60 seconds. If you can't connect to the proxy within 10 seconds, look at your network or firewall, not the target.
- Residential IPs run on real home connections and respond more slowly than datacenter IPs. If latency matters more than IP type, test ISP or datacenter proxies.
- Timeouts that cluster on one sticky session usually mean its IP went offline. Switch to a new session ID.

### Connection errors

- **Refused or reset at once:** wrong port or protocol. HTTP uses port 8000 on the gateways and 3129 on shared datacenter; SOCKS5 uses 1080 and 1081.
- **Hangs with no response:** a firewall blocks the proxy port; see [Firewalls](https://proxonym.com/docs#endpoints-and-ports-firewalls).
- **DNS errors over SOCKS5:** use `socks5h://` so the proxy resolves hostnames.

### Getting help

Answers to common questions are in the [help center](https://proxonym.com/help). Refunds, IP replacements and your data are requests in the dashboard, under **Support**, and accounts with an active dedicated datacenter plan can open tickets there. In a ticket, include the time of the request with its time zone, the username options you used (never the password), the target domain, the status code or error message, and the output of `curl -v` if you have it. We do not take messages by e-mail.

## Limits and fair use

These limits apply to every account.

| Limit | Value | When reached |
| --- | --- | --- |
| Concurrent connections and sessions | Unlimited, on every product | Not applicable |
| Request rate | Burst of about 10,000 requests per second per account | The proxy returns `429` |
| Target response time | 60 seconds | The proxy returns `504` |
| Sticky session lifetime | 120 minutes on residential, 720 on unlimited residential, 3 on mobile | The session ends; a new session starts on a new IP |
| Unlimited residential throughput | Your plan's speed, from 100 Mbps to 1 Gbps | Combined speed stays at the plan's tier |
| Shared datacenter bandwidth | 250 GB, 1 TB or 5 TB per month, or Unlimited under fair use | The proxy returns `402` once the allowance is used |
| Account API | 60 requests per minute | The API returns `429` with `Retry-After` |
| SERP API | Your plan's monthly requests; 1 request returns 1 results page | The API returns `403` with `quota_exceeded` |

### Acceptable use

All traffic must follow the law and the [acceptable use policy](https://proxonym.com/acceptable-use). The policy is the authoritative text. In short, Proxonym can't be used for:

- fraud, phishing, scams or any other illegal activity,
- unauthorized access, such as credential stuffing, account takeover, brute-force logins, or scanning systems without permission,
- spam and unsolicited bulk messaging,
- denial-of-service attacks or deliberately overloading websites,
- distributing malware or controlling botnets,
- collecting personal data unlawfully.

Requests to targets blocked under the policy get `403` from the proxy. Some sensitive use cases need verification before they're enabled; dedicated datacenter customers can start it in a ticket.

### Fair use

Unlimited residential plans and the Unlimited bandwidth tier on shared datacenter have no traffic cap. They are subject to fair use under the acceptable use policy. For sustained volumes, combine several plans; see [Proxonym for teams](https://proxonym.com/enterprise).

## Best practices

### Reuse connections

Each new connection costs a TCP handshake, a `CONNECT` and a TLS handshake. Reuse one client per job: a `requests.Session`, one `aiohttp.ClientSession`, one undici `ProxyAgent`, one Go `http.Client` or one .NET `HttpClient`. Keep in mind how reuse interacts with rotation:

- A reused HTTPS connection keeps its tunnel, and so its IP. For a new IP on every request, open a new connection each time, or control IPs explicitly with session IDs.
- On sticky sessions, reuse only helps: same IP, fewer handshakes.

### Retry with backoff

Some failures are normal at scale: residential peers go offline and slow targets time out. Retry `429`, `502`, `503` and `504` and network errors with exponential backoff and jitter, up to 3 to 5 attempts. Don't retry `402`, `403` or `407` from the proxy: they need a fix, not another attempt.

**Python**

```python
import random
import time

import requests

PROXY = "http://USERNAME-country-us:PASSWORD@gw.proxonym.com:8000"
PROXIES = {"http": PROXY, "https": PROXY}
RETRY_STATUS = {429, 502, 503, 504}
NO_RETRY = ("402", "403", "407")

def fetch(url: str, attempts: int = 4) -> requests.Response:
    for attempt in range(1, attempts + 1):
        try:
            r = requests.get(url, proxies=PROXIES, timeout=(10, 60))
            if r.status_code not in RETRY_STATUS:
                return r
        except requests.exceptions.ProxyError as e:
            # The proxy refused the tunnel: 402, 403 and 407 need a fix, not a retry
            if any(f"failed: {code}" in str(e) for code in NO_RETRY):
                raise
        except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
            pass
        if attempt < attempts:
            time.sleep(min(30, 2 ** attempt) + random.random())  # 2, 4, 8 s plus jitter
    raise RuntimeError(f"{url}: still failing after {attempts} attempts")
```

Each retry without a session option goes out on a new IP. On sticky sessions, switch to a new session ID after repeated `502` or `504` errors.

### Match the location to the target

- Use exit IPs in the market whose content you need: prices, rankings and ads change by country and city.
- Keep the rest of the request consistent with the IP: `Accept-Language`, currency and, in browsers, time zone and locale.
- Don't target narrower than you need. Country targeting has the largest pool and the fewest `502` errors.

### Respect robots.txt and site terms

- Read `robots.txt` and the site's terms before you collect data, and follow them.
- Limit your request rate per domain so your crawl doesn't slow the site down for its users.
- Collect public data, and handle any personal data in line with applicable law. Proxies raise success rates; they don't bypass the law or a site's terms.

Our residential and mobile IPs come from people who opted in through partner apps and SDKs, are informed, and can opt out. Read how the network is built on [Ethics and IP sourcing](https://proxonym.com/ethics).

### Monitor success rate

- Log the status code, target domain, username options and latency of every request.
- Track the success rate per target and per country. A drop on one target usually means the site changed its defenses; a drop everywhere points at your setup or your account.
- Alert on proxy codes: a rise in `407` or `402` means a configuration or billing problem, a rise in `502` often means targeting that's too narrow, and `504` points at slow targets.
- Follow traffic in the dashboard or with `GET /usage`, and give each project its own sub-user so usage is attributed correctly.

To choose the right IP type for each target, read our comparison of [residential and datacenter proxies](https://proxonym.com/blog/residential-vs-datacenter-proxies) and the [web scraping use case](https://proxonym.com/use-cases/web-scraping).

- [Integrations](https://proxonym.com/integrations): Step-by-step setup for 12 tools
- [API reference](https://proxonym.com/docs/api): Account, usage, proxy lists, SERP API
