ProxyNomad / Quickstart
First request to first success.
There is no SDK and nothing to install. If your HTTP client can use a proxy, you are already integrated; this page is the whole manual.
01Endpoints
ports 7000 to 7301One gateway, four doors.
Everything routes through gate.proxynomad.com. The port picks the product; your credentials work on all of them, each drawing from its own prepaid balance.
| Product | HTTP CONNECT | SOCKS5 | Rotation default |
|---|---|---|---|
| Residential | gate.proxynomad.com:7000 | gate.proxynomad.com:7001 | Per request |
| Mobile | gate.proxynomad.com:7100 | gate.proxynomad.com:7101 | Per request |
| ISP | gate.proxynomad.com:7200 | gate.proxynomad.com:7201 | Static, you address your IPs |
| Datacenter | gate.proxynomad.com:7300 | gate.proxynomad.com:7301 | Per request |
02Authenticate
proxy auth or ip allowlistCredentials in the proxy URL.
You get a username and password from the dashboard. Standard proxy auth, nothing custom: put them in the proxy URL and go. Routing instructions are appended to the username as hyphen-separated segments, so switching city or carrier is a string edit, not a config system.
Prefer no credentials in code? Allowlist your server IPs in the dashboard and the gateway trusts them directly; targeting then travels in an X-Nomad-Route header with the same syntax. Rotate your password from the dashboard any time; old sessions drain, new connections use the new secret.
# rotating residential, Berlincurl -x "http://USER-country-de-city-berlin:PASS\@gate.proxynomad.com:7000" https://ifconfig.me# run it twice: two different Berlin addresses
import requests p = ("http://USER-country-de-city-berlin" ":PASS@gate.proxynomad.com:7000")r = requests.get("https://ifconfig.me", proxies={"http": p, "https": p}, timeout=30)print(r.status_code, r.text)
import { ProxyAgent } from "undici"; const agent = new ProxyAgent( "http://USER-country-de-city-berlin" + ":PASS@gate.proxynomad.com:7000");const res = await fetch("https://ifconfig.me", { dispatcher: agent });console.log(res.status, await res.text());
03Target
lowercase, underscores for spacesRouting syntax, complete.
Segments combine left to right, all optional, all lowercase. Values with spaces use underscores: city-mexico_city, city-sao_paulo.
| Segment | Example | Meaning |
|---|---|---|
country-<cc> | country-de | ISO 3166-1 alpha-2 country code |
city-<name> | city-berlin | City, used with country. Residential and mobile. |
asn-<number> | asn-3320 | Pin the autonomous system: a specific ISP or carrier |
session-<id> | session-job42_a | Sticky session. Any id you invent, letters, digits, underscore. |
ip-<address> | ip-203_0_113_44 | ISP only: address one specific IP from your allocation |
Example, assembled: USER-country-br-city-sao_paulo-session-cart_19 means a São Paulo residential exit that holds for this session id.
04Sessions
one identity per session idSticky when you say so.
Without a session segment every request gets a fresh exit. With one, the exit holds: up to 30 minutes on residential, up to 10 on mobile, where the physics of phones has the final word. Reuse the id to keep the identity; change it to rotate deliberately. Run parallel identities by running parallel ids, one per logical visitor, which is how crawlers keep carts, logins and A/B cohorts from bleeding into each other.
If the device behind your session goes offline, the gateway replaces it from the same targeting scope and your id keeps working. Your code never learns the difference unless it checks the IP, which, for session-critical flows, it should.
BASE="http://USER-country-it-city-milan"GATE="gate.proxynomad.com:7000" curl -x "$BASE-session-visitor_a:PASS@$GATE" https://ifconfig.mecurl -x "$BASE-session-visitor_b:PASS@$GATE" https://ifconfig.me# two stable Milan identities, one per session id
05The pattern that saves money
a port number in your retry logicDatacenter first, residential on block.
The single most effective cost optimization in this business is a port number in your retry logic. Send everything through datacenter at $0.60/GB; only the requests that come back blocked pay residential rates on the second attempt. On mixed target lists the blended cost typically lands near the datacenter price while the success rate looks residential.
Tune the trigger to your targets: a 403 or 429 is unambiguous, but plenty of sites serve their block as a 200 with a challenge page or a suspiciously empty body. Match on what your parser failed to find, not only on status codes.
DC = "http://USER-country-us:PASS@gate.proxynomad.com:7300"RES = "http://USER-country-us:PASS@gate.proxynomad.com:7000" def fetch(url): r = requests.get(url, proxies={"http": DC, "https": DC}, timeout=30) if r.status_code in (403, 429) or looks_blocked(r): r = requests.get(url, proxies={"http": RES, "https": RES}, timeout=60) return r
06Errors
what it costs: nothing, unless deliveredWhat the gateway tells you, and what it costs.
| Response | Meaning | Billed | What to do |
|---|---|---|---|
407 | Credentials rejected | No | Check username segments and password; test without targeting first |
402 | Balance for this product is empty | No | Top up, or set the low-balance alert you skipped |
502 | No healthy exit matched your targeting | No | Widen targeting, or tell us: frequent 502 on a broad scope is our bug |
504 | Exit accepted, then died before answering | No | Retry; it is already a different exit |
| Anything else | The target speaking, delivered through the tunnel | Yes | That includes 403s and CAPTCHA pages: rotate, slow down, or move up a proxy tier |
CONNECT and cannot read or modify what is inside. That is a privacy property you should demand from any proxy, and it has a practical corollary: your TLS fingerprint is your own. If a target fingerprints clients, fix your client stack; no exit can disguise it for you.