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.
Three steps
- 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) 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.
- Copy your credentials. Your proxy username and password are in the dashboard. In every example on this page, replace
USERNAMEandPASSWORDwith your own values. - Send a request. Point your client at
gw.proxonym.com:8000and 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:
curl -x http://gw.proxonym.com:8000 -U "USERNAME-country-de-session-a7k2:PASSWORD" https://api.ipify.org-x http://gw.proxonym.com:8000sets the proxy. Keep thehttp://scheme even for HTTPS targets: the gateway opens an encrypted tunnel withCONNECT.-U "USERNAME-country-de-session-a7k2:PASSWORD"sends your credentials.-country-deselects an IP in Germany, and-session-a7k2keeps that IP for later requests with the same username, for 10 minutes by default.https://api.ipify.orgis the target. It replies with the IP address it sees, which is your exit IP, for example203.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
- Run
curl https://api.ipify.orgwithout the proxy. That is your own IP, also shown on What is my IP. - Run the proxied command again. The IP should differ from yours and stay the same on every run while the session lasts.
- Remove
-session-a7k2from the username and run the command a few times. Each request now exits from a new IP. - Confirm the location with an IP geolocation service, through the proxy. The
countryfield in the reply should readDE.
curl -s -x http://gw.proxonym.com:8000 \
-U "USERNAME-country-de:PASSWORD" \
https://ipinfo.io/jsonA 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.
Next, control when your IP changes with sessions, choose locations with geo-targeting, or copy a client from the 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.
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:PASSWORDor 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 and 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.
- Find the public IP of the machine that will connect: run
curl https://api.ipify.orgon it. - Add that IP in the dashboard or with
POST /whitelist(see the Whitelist API). - Connect to any
ip:portfrom your datacenter list, without credentials:
curl -x http://198.51.100.23:3129 https://api.ipify.orgWhitelist 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). 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:
- Create a new sub-user with
POST /sub-users, giving it the same traffic limit as the old one. - Deploy the new username and password to every worker.
- Watch the old sub-user's
traffic_used_gbin the dashboard or withGET /sub-users. When it stops growing, nothing uses the old credentials anymore. - 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 | gw.proxonym.com | 8000 | 1080 | Username and password | USERNAME[-options]:PASSWORD |
| Mobile | gw.proxonym.com | 8000 | 1080 | Username and password | USERNAME-type-mobile[-options]:PASSWORD |
| Unlimited residential | 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 | IPs from your list | Port in your list | Same port as HTTP | Username and password from your list | ip:port:username:password |
| Shared datacenter | IPs from your list | 3129 | 1081 | IP whitelist, or username and password | ip:port |
| Dedicated datacenter | 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 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.
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.
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:
USERNAME-country-usRotating 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.
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 or dedicated datacenter proxies.
Example sequence
This script sends three requests in one sticky session, then three rotating requests:
# 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
doneSample output:
203.0.113.41
203.0.113.41
203.0.113.41
203.0.113.187
203.0.113.9
203.0.113.152To 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.
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
-stateor-city, never both in the same username. - Include
-countrywhenever 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, notuk. - Write names in plain lowercase ASCII with underscores:
sao_paulo, notSã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.
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.
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 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:
curl -x http://gw.proxonym.com:8000 \
-U "USERNAME-country-us-type-mobile:PASSWORD" \
https://api.ipify.orgMobile 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.
USERNAME-country-gb-type-mobile-session-m42x-lifetime-3Three 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.
Unlimited residential#
Unlimited residential 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 |
curl -x http://use.unl.proxonym.com:8000 \
-U "USERNAME-country-us-session-a7k2-lifetime-240:PASSWORD" \
https://api.ipify.orgUsername 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.
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.
Fair use
There is no GB cap and concurrency is unlimited. Use is subject to fair use under the acceptable use policy. For sustained volumes beyond the self-serve tiers, see enterprise plans. Background: how unlimited residential proxies work.
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:
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.
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:
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
3129and SOCKS5 on port1081of each IP, with UDP over SOCKS5. - Authenticate with the 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_atin the JSON list or inGET /accountand 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.
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.
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 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:
CONNECT example.com:443 HTTP/1.1
Host: example.com:443
Proxy-Authorization: Basic VVNFUk5BTUUtY291bnRyeS11czpQQVNTV09SRA==
HTTP/1.1 200 Connection establishedThe 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.
curl -x socks5h://gw.proxonym.com:1080 \
-U "USERNAME-country-us:PASSWORD" \
https://api.ipify.orgIn Python, install SOCKS support with pip install "requests[socks]" and use the same scheme:
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 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
# 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. More options in the cURL integration guide.
Python (requests)
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 and our guide to proxies in Python requests.
Python (aiohttp)
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)
// 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.
Node.js (axios with https-proxy-agent)
// 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
$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.
Go (net/http)
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.
Java (HttpClient)
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.
C# (HttpClient)
// .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, Puppeteer, Playwright, Selenium, AdsPower and Multilogin. The full list is on 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 | 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'sCONNECT tunnel failed, response 407or Python'sProxyErrorwithTunnel 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
-vto 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.
Fixing 407
- Test the bare credentials:
-U "USERNAME:PASSWORD". If that works, the problem is in the options. - Check the options: lowercase, joined with dashes, no spaces, and session IDs of 1 to 32 letters or digits.
- Percent-encode special characters of the password inside proxy URLs.
- Check that the whitelisted IP is still your machine's public IP, and that sub-users are
active.
SSL errors
wrong version numberorSSL: WRONG_VERSION_NUMBER: the proxy URL starts withhttps://. Change it tohttp://. 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.
- DNS errors over SOCKS5: use
socks5h://so the proxy resolves hostnames.
Getting help
Answers to common questions are in the help center. 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. 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.
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.
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
502errors.
Respect robots.txt and site terms
- Read
robots.txtand 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.
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
407or402means a configuration or billing problem, a rise in502often means targeting that's too narrow, and504points 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 and the web scraping use case.