Proxy gateway and tools API

Start

Quickstart

1. Get your API key. Create an account, then copy the master key (nr-…) from Dashboard → Settings. Keep it in an environment variable, not in source code.

   shellCopy

   export NULLROUTE_KEY="nr-your-key"

2. Build the proxy URL. Username = the exit you want, password = the key.

   formatCopy

   http://<username>:<api-key>@gw.nullroute.tools:32424

3. Send a request through a residential US exit and check the IP it left from.

   curlCopy

   curl -x "http://res-us:[email protected]:32424" \
     "https://api.ipify.org?format=json"
   
   # {"ip":"203.0.113.24"}

Proxy

Endpoint and login

Every protocol uses the same host and port; the gateway detects the protocol from the first byte. Port 32443 carries the same four protocols inside TLS.

Encrypted connection (TLS)

Port 32443 speaks HTTP, HTTPS CONNECT, SOCKS4/4a and SOCKS5 inside TLS. The login is the same; only the proxy scheme and port change. Connect by hostname, not by IP: the certificate is issued for gw.nullroute.tools, so a client that dials the raw address fails certificate validation.

# https:// scheme = TLS to the gateway first, then the normal request
curl --proxy https://gw.nullroute.tools:32443 --proxy-user "res-us:$NULLROUTE_KEY" https://api.ipify.org

Credentials

nr- is your account's master key. sk- keys are sub-keys with their own limits; give those to teammates, scripts and clients.

Proxy

Targeting

The username is <type>-<country>, then any of the verified filters: -st-, -city-, -zip-, -asn-, -os-. A sticky session (-sid-) replaces the filters.

res-us                        # residential, United States, new IP per connection
dc-de                         # datacenter, Germany
mob-gb                        # mobile carrier IP, United Kingdom
res-any                       # residential, random country
res-us-city-chicago           # residential, Chicago
res-us-st-texas-os-windows    # residential, Texas, Windows exits
res-us-zip-10001              # residential, US ZIP 10001
res-us-asn-7922               # residential, AS7922 only
res-us-os-android             # residential, Android exits
res-us-sid-4821               # sticky: same IP while you reuse sid 4821
sr_res-us                     # smart retry on blocked responses

• Can I combine filters? Yes: res-us-st-texas-os-windows, res-us-city-new_york-asn-7922. Every filter in the username must match the same exit.
• What if nothing matches? The gateway verifies the filter against the exit before it hands traffic over. With no matching exit the connection gets 502 no exit matching filter and nothing is charged.
• Which locations have exits right now? Ask /api/geo/availability: countries, states and cities where exits answered in the last 24 hours, with counts and a ready login for each. It never lists a place we haven't seen an exit in.
• Filters and sticky sessions? Not together. -sid- pins one exit, so a username can have either filters or a session id.
• Datacenter fallback. If the datacenter network has no exit in that country right now, a plain dc-<cc> or sticky dc-<cc>-sid-<id> login is served by a residential exit of the same country at the datacenter price. A sticky session stays on the network that gave it its first IP, even after datacenter comes back. Logins with filters (-st-, -city-, -zip-, -asn-, -os-) are never swapped.

In the tools API, where city, ASN and session are separate fields, precedence is city > ASN > session: if you send several, only the first one applies.

Proxy

Sessions

• New IP: change the id, e.g. res-us-sid-4822. Use random ids (8+ digits) so parallel workers don't share an exit by accident.
• Self-healing: if a sticky exit dies (two failed connects in a row, or a tunnel that drops before any data), NullRoute moves the session to a new IP. The id keeps that new IP afterwards, so your session stays stable instead of failing.
• Private ids: ids are scoped to your account. Your sid-1 and another customer's sid-1 are different exits.
• Idle timeout: a connection with no traffic in either direction for 3 minutes is closed. A single connection lives at most 24 hours. Reconnecting with the same id gets the same IP.
• Header instead of username: HTTP clients can send X-Session-Id: 4821. With curl and HTTPS sites use --proxy-header "X-Session-Id: 4821".

Proxy

Code examples

Replace nr-your-key or $NULLROUTE_KEY with your key. Each tab is copy-paste ready.

# HTTP proxy
curl -x "http://res-us:[email protected]:32424" https://api.ipify.org

# SOCKS5, DNS resolved on the exit
curl -x "socks5h://res-us:[email protected]:32424" https://api.ipify.org

# Sticky session in Germany
curl -x "http://res-de-sid-4821:[email protected]:32424" https://api.ipify.org

# PowerShell: type curl.exe, not curl (curl is an alias for Invoke-WebRequest).
# Always pass the proxy with -x; curl.exe ignores Windows proxy settings.
$env:NULLROUTE_KEY = "nr-your-key"
curl.exe -x "http://res-us:$env:[email protected]:32424" https://api.ipify.org
curl.exe -x "socks5h://res-us:$env:[email protected]:32424" https://api.ipify.org

import os, requests

key = os.environ["NULLROUTE_KEY"]
proxy = f"http://res-us:{key}@gw.nullroute.tools:32424"
# SOCKS5: pip install "requests[socks]" and use
# proxy = f"socks5h://res-us:{key}@gw.nullroute.tools:32424"

r = requests.get("https://api.ipify.org?format=json",
                 proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.json())

// npm i undici
import { fetch, ProxyAgent } from "undici";

const agent = new ProxyAgent({
  uri: "http://gw.nullroute.tools:32424",
  token: "Basic " + Buffer.from(`res-us:${process.env.NULLROUTE_KEY}`).toString("base64"),
});
const res = await fetch("https://api.ipify.org?format=json", { dispatcher: agent });
console.log(await res.json());

// Chromium can't authenticate to SOCKS5 proxies: use the HTTP proxy.
import { chromium } from "playwright";

const browser = await chromium.launch({
  proxy: {
    server: "http://gw.nullroute.tools:32424",
    username: "res-us-sid-4821",
    password: process.env.NULLROUTE_KEY,
  },
});
const page = await browser.newPage();
await page.goto("https://api.ipify.org");
console.log(await page.textContent("body"));
await browser.close();

# Antidetect browsers, proxy extensions, bots: host:port:user:pass
gw.nullroute.tools:32424:res-us-sid-4821:nr-your-key

# Or fill the fields separately
Type      HTTP  (or SOCKS5)
Host      gw.nullroute.tools
Port      32424
Username  res-us-sid-4821
Password  nr-your-key

For a browser profile use a sticky username (-sid-), one id per profile, so the IP doesn't change between page loads.

Proxy

Smart retry

Prefix the username with sr_. When a response looks blocked, NullRoute sends the request again from a fresh exit in the same country, up to 3 attempts, and returns the first clean response.

• Counts as blocked: Cloudflare challenge (cf-mitigated: challenge, or 503 from Cloudflare), DataDome block, captcha or "access denied" pages, HTTP 429.
• Costs $0.001 per request that needed a retry and then succeeded. First-try successes cost bandwidth only.
• Works for plain http:// requests through the HTTP proxy. HTTPS tunnels and SOCKS are end-to-end encrypted, so the gateway can't read the response. For HTTPS targets, use POST /api/fetch, where retry is on by default.

curl -x "http://sr_res-us:[email protected]:32424" http://example.com/

Proxy

Keys and limits

Sub-keys

Create sk-… keys in Dashboard → API keys and use them anywhere the master key works: as the proxy password or as the API bearer token. Disable or delete one without touching the master key. Each sub-key can have:

Limits are checked when a connection opens; a connection already running finishes. The account's daily spend limit (in API keys) applies to every key.

IP allowlist

Connections from an allowlisted IP or CIDR range don't need a key. Send only the exit as the username:

# from an allowlisted server
curl -x http://[email protected]:32424 https://api.ipify.org

IPv4 or IPv6, single address or CIDR, up to 50 entries. SOCKS5 still needs a username and a password field: send res-us and any non-key password. Allowlisted traffic bills the master balance.

Proxy

Troubleshooting

Tools API

Authentication

The tools API runs checks through NullRoute exits and bills your balance per call. Send your key as a bearer token. Master keys (nr-…) and sub-keys (sk-…) both work; sub-key scope rules apply.

Authorization: Bearer nr-your-key

• Base URL: https://nullroute.tools. JSON in, JSON out.
• X-API-Key: nr-your-key also works. A key query or body field is accepted but ends up in logs, so prefer the header.
• Every successful response has a charged field: what the call cost in USD.
• Exit targeting fields (type, country, city, asn, session) mirror the username parameters. Defaults: res, us.

Tools API

Endpoints

curl https://nullroute.tools/api/fetch \
  -H "Authorization: Bearer $NULLROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","country":"de"}'

{
  "status": 200,
  "final_url": "https://example.com/",
  "headers": { "content-type": "text/html", "server": "cloudflare" },
  "body": "<!doctype html>…",
  "body_base64": null,
  "bytes": 1712,
  "truncated": false,
  "ttfb_ms": 412,
  "total_ms": 468,
  "attempts": 1,
  "blocked": null,
  "exit_type": "res",
  "country": "de",
  "charged": 0.0010005
}

curl https://nullroute.tools/api/geo-check \
  -H "Authorization: Bearer $NULLROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","countries":["us","de","jp"]}'

{
  "url": "https://example.com",
  "exit_type": "res",
  "results": [
    { "country": "us", "ok": true, "status": 200, "ttfb_ms": 380, "total_ms": 402,
      "final_url": "https://example.com/", "redirected": false, "title": "Example Domain",
      "content_length": 1256, "content_hash": "84238dfc8092e5d9c0dac8ef93371a07",
      "blocked": null, "fingerprint": ["Cloudflare"] },
    { "country": "jp", "ok": false, "error": "upstream_timeout" }
  ],
  "checked": 2,
  "consistent": true,
  "charged": 0.0040008
}

curl -G https://nullroute.tools/api/inspect \
  -H "Authorization: Bearer $NULLROUTE_KEY" \
  --data-urlencode "url=http://vercel.com" -d country=us

{
  "url": "http://vercel.com",
  "final_url": "https://vercel.com/",
  "status": 200,
  "redirects": [
    { "url": "http://vercel.com/", "status": 308, "location": "https://vercel.com/" },
    { "url": "https://vercel.com/", "status": 200, "location": null }
  ],
  "hops": 2,
  "headers": { "server": "Vercel", "x-vercel-id": "fra1::…", … },
  "fingerprint": ["Vercel"],
  "security": {
    "present": ["strict-transport-security", "content-security-policy", "x-content-type-options",
                "x-frame-options", "referrer-policy"],
    "missing": ["permissions-policy"],
    "score": 83
  },
  "title": "Vercel",
  "blocked": null,
  "ttfb_ms": 290,
  "total_ms": 351,
  "country": "us",
  "charged": 0.0010732
}

curl -H "Authorization: Bearer $NULLROUTE_KEY" \
  "https://nullroute.tools/api/dns?name=example.com&type=A&country=de"

{
  "name": "example.com",
  "type": "A",
  "country": "de",
  "answers": [
    { "name": "example.com", "type": "A", "ttl": 214, "data": "23.192.228.80" },
    { "name": "example.com", "type": "A", "ttl": 214, "data": "23.215.0.136" }
  ],
  "answer_count": 2,
  "charged": 0.0002
}

curl -H "Authorization: Bearer $NULLROUTE_KEY" \
  "https://nullroute.tools/api/exit-ip?type=res&country=gb&session=4821"

{
  "exit_ip": "203.0.113.24",
  "exit_type": "res",
  "country": "gb",
  "session": "4821",
  "latency_ms": 640,
  "charged": 0.0002
}

curl https://nullroute.tools/api/proxy-test \
  -H "Authorization: Bearer $NULLROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"proxies":["socks5://user:[email protected]:1080","198.51.100.9:8080"]}'

{
  "results": [
    { "proxy": "socks5://198.51.100.7:1080", "scheme": "socks5", "ok": true, "alive": true,
      "status": 200, "latency_ms": 312, "exit_ip": "198.51.100.7" },
    { "proxy": "http://198.51.100.9:8080", "scheme": "http", "ok": true, "alive": false,
      "latency_ms": 10004, "error": "timeout" }
  ],
  "tested": 2,
  "alive": 1,
  "dead": 1,
  "charged": 0.001
}

curl https://nullroute.tools/api/detect/bulk \
  -H "Authorization: Bearer $NULLROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ips":["198.51.100.7","203.0.113.24","10.0.0.1"]}'

{
  "results": [
    { "ip": "198.51.100.7", "status": "proxy", "proxy": true, "providers": ["ExampleVPN"] },
    { "ip": "203.0.113.24", "status": "clean", "proxy": false, "providers": [] },
    { "ip": "10.0.0.1", "status": "unknown", "proxy": false, "providers": [] }
  ],
  "checked": 2,
  "proxies": 1,
  "clean": 1,
  "charged": 0.0002
}

curl -H "Authorization: Bearer $NULLROUTE_KEY" \
  "https://nullroute.tools/api/geo/availability?type=res&country=us&state=tx"

{
  "type": "res",
  "country": "us",
  "window_hours": 24,
  "exits": 412,
  "states": [
    { "code": "tx", "name": "Texas", "exits": 412, "last_seen": 1793088000, "login": "res-us-st-tx" }
  ],
  "cities": [
    { "code": "houston", "name": "Houston", "state": "tx", "exits": 96,
      "last_seen": 1793087940, "login": "res-us-st-tx-city-houston" }
  ]
}

curl https://nullroute.tools/api/geo/check \
  -H "Authorization: Bearer $NULLROUTE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"logins":["res-us-st-tx-city-houston","res-us-st-wy","mob-de"]}'

{
  "checked": 3,
  "available": 2,
  "results": [
    { "login": "res-us-st-tx-city-houston", "available": true, "verified_exits": 14, "network": "res" },
    { "login": "res-us-st-wy", "available": false, "verified_exits": 0 },
    { "login": "mob-de", "available": true, "verified_exits": null, "network": "mob" }
  ]
}

Resellers

Reseller API

Issue proxy keys to your customers from your own shop or bot. Each key gets an expiry, a speed cap and an optional traffic cap; its traffic is charged to your balance at your wholesale price.

• Base URL: https://nullroute.tools/api/v1/reseller. JSON in, JSON out.
• Auth: Authorization: Bearer nr-…, your master key from Settings. Sub-keys are refused with 401 use_master_key.
• Accounts without reseller access get 403 not_a_reseller; a paused reseller account gets 403 reseller_disabled.
• No access yet? Unlock it from Billing for a one-off $170 — that buys the rights only (API, wholesale rates, client keys); traffic keeps billing your balance. An admin can re-price it or attach your domain afterwards.
• When your balance reaches $0, every key you issued stops authenticating. When a key expires, is disabled or runs out of traffic, its open tunnels close within about 30 seconds.

export PROXY_API_KEY="op-your-master-key"
export API="https://nullroute.tools/api/v1/reseller"

Create a key

curl -X POST $API/keys \
  -H "Authorization: Bearer $PROXY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"hours":2,"speed_mbps":500,"label":"order-1042"}'

{
  "key": "sk-3f9c…",
  "label": "order-1042",
  "active": true,
  "expired": false,
  "created_at": "2026-10-05T12:00:00Z",
  "expires_at": "2026-10-05T14:00:00Z",
  "speed_mbps": 500,
  "traffic_limit_gb": null,
  "traffic_used_gb": 0.0,
  "cost_usd": 0.0,
  "allowed_types": "",
  "online": false,
  "now_mbps": 0.0,
  "connect": {
    "host": "gw.nullroute.tools",
    "port": 32424,
    "username_example": "res-any",
    "http": "http://res-any:sk-3f9c…@gw.nullroute.tools:32424",
    "socks5": "socks5://res-any:sk-3f9c…@gw.nullroute.tools:32424",
    "line": "gw.nullroute.tools:32424:res-any:sk-3f9c…"
  }
}

Send connect.line or connect.http to the customer as is. They can change res-any to any targeting username. Errors: 400 invalid_duration, invalid_speed, invalid_traffic_gb, invalid_allowed_types; 402 insufficient_balance when your balance is $0 or less.

Manage keys

PATCH takes any of extend_hours (added to the current expiry, or to now if the key already expired), active, speed_mbps, traffic_gb, label, and returns the updated key object.

K=sk-3f9c…

# Extend by 24 hours
curl -X PATCH $API/keys/$K -H "Authorization: Bearer $PROXY_API_KEY" \
  -H "Content-Type: application/json" -d '{"extend_hours":24}'

# Disable now (re-enable with {"active":true})
curl -X PATCH $API/keys/$K -H "Authorization: Bearer $PROXY_API_KEY" \
  -H "Content-Type: application/json" -d '{"active":false}'

# Delete
curl -X DELETE $API/keys/$K -H "Authorization: Bearer $PROXY_API_KEY"

# Balance and hourly usage
curl $API/balance -H "Authorization: Bearer $PROXY_API_KEY"
curl "$API/keys/$K/usage?hours=24" -H "Authorization: Bearer $PROXY_API_KEY"

{
  "balance_usd": 42.5,
  "wholesale_per_gb": { "res": 0.35, "dc": 0.12, "mob": 0.6 },
  "gb_left": { "res": 121.43, "dc": 354.17, "mob": 70.83 },
  "gateway": "gw.nullroute.tools"
}

{
  "points": [
    { "hour": "2026-10-05T12:00:00Z", "bytes": 73400320 },
    { "hour": "2026-10-05T13:00:00Z", "bytes": 18874368 }
  ]
}

Hours are UTC. Hours without traffic are left out.

Example: sell a key from a bot

import os, requests

API = "https://nullroute.tools/api/v1/reseller"
HEADERS = {"Authorization": f"Bearer {os.environ['PROXY_API_KEY']}"}

def sell_key(order_id: str, hours: int, mbps: int = 0, gb: float = 0) -> str:
    """Call after payment. Returns the text to send to the customer."""
    r = requests.post(f"{API}/keys", headers=HEADERS, timeout=15, json={
        "label": order_id, "hours": hours,
        "speed_mbps": mbps, "traffic_gb": gb,
    })
    if r.status_code == 402:
        raise RuntimeError("Reseller balance is empty: top up before selling")
    r.raise_for_status()
    k = r.json()
    return (f"Your proxy (valid until {k['expires_at']} UTC):\n"
            f"{k['connect']['line']}\n"
            f"HTTP: {k['connect']['http']}")

# bot.send_message(chat_id, sell_key("tg-551-1042", hours=24, mbps=100))

Reference

Pricing and limits

Prepaid balance in USD; top up from $5 in the dashboard. Proxy traffic is billed per byte in both directions at the exit type's rate.

"Bandwidth" is the response size at the exit type's per-GB rate. Rate limits are per account; going over returns 429 rate_limited. A daily spend limit and per-key caps are set in Dashboard → API keys.

Reference

API errors

API errors are JSON with an HTTP status and a stable code:

HTTP/1.1 402 Payment Required
{ "error": "insufficient_balance" }

Proxy connection errors (407, 502, 403) are covered in troubleshooting.