API & integration documentation
Two ways to integrate SocksNode: connect directly to the proxy gateway over HTTP(S) or SOCKS5, or manage bandwidth, usage and proxies programmatically through the REST API.
On this page
Rotating proxies (residential, datacenter, mobile)
Quickstart
Point any HTTP(S) or SOCKS5 client at the gateway and authenticate with your proxy username and password. Targeting is set inside the username.
Rotating US proxy over HTTP. Replace USERNAME and PASSWORD with your credentials.
The entry gateway is picked for where you are — the nearest door is usually the fastest. You can override it.
Prefer a full walkthrough for your stack? Each guide covers setup, rotating and sticky sessions, and country targeting.
curl -x http://global.socksnode.com:9000 \
-U "USERNAME-country-us:PASSWORD" \
https://api.ipify.org?format=json{"ip": "104.28.219.14"}Proxy connection
Every proxy uses the same four parts — host:port:username:password. Your username and password come from the proxy generator in your dashboard. Country, city and session targeting are appended to the username as tokens (see below).
global.socksnode.com:9000:USERNAME-country-us:PASSWORDPorts & gateways
The entry gateway affects latency — the one nearest you is usually fastest, so we auto-pick it. If a proxy feels slow, change the gateway. The exit country is chosen with the country token, independent of the gateway.
| Protocol | Rotating port | Sticky port |
|---|---|---|
| HTTP / HTTPS | 9000 | 10000 |
| SOCKS5 | 11000 | 12000 |
| Gateway | Host |
|---|---|
| Nearest to you (default) | global.socksnode.com |
| Europe | fr.socksnode.com |
| United States | us.socksnode.com |
| Singapore | sg.socksnode.com |
# 9000: a new exit IP on every request
curl -x http://global.socksnode.com:9000 \
-U "USERNAME-country-us:PASSWORD" \
https://api.ipify.orgTargeting & sessions
Append tokens to your username, separated by hyphens, to control the exit location and session behaviour:
| Token | Meaning |
|---|---|
| -country-<cc> | ISO country code, e.g. -country-us |
| -state-<name> | US state, e.g. state-california (full name, no spaces). Pairs with a city or an ISP. |
| -city-<name> | City, e.g. city-losangeles (name, no spaces or underscores). |
| -asn-<number> | Target a specific ISP by ASN, e.g. asn-7922 (Comcast). Combines with a state or a city. |
| -os-<name> | Only return IPs on one device OS: windows, android, ios or mac. Narrows the pool, so expect fewer IPs. |
| -session-<id> | Keep the same IP across requests (sticky) |
| -lifetime-<min> | Sticky session duration, 1–1440 minutes |
# Rotating: a fresh IP on every request
USERNAME-country-us
# Sticky: the same IP for 30 minutes
USERNAME-country-us-session-a1b2c3d4-lifetime-30
# State + city
USERNAME-country-us-state-california-city-losangeles
# City + ISP (ASN)
USERNAME-country-us-city-chicago-asn-7922
# Device OS
USERNAME-country-us-os-androidPools
Residential bandwidth works on all three pools at the same price. Send pool with POST /proxies to choose one; leave it out for Pool 1, exactly as before. A Mix spreads requests across the pools in mixPools, in equal shares. A pool that can't serve the target sits out, and a target only one pool serves runs on Pool 1: each line's pool, mixPools and poolNote say what it runs on.
| pool | Targeting | Sticky | |
|---|---|---|---|
| 1 | Pool 1 | Country, state, city and ISP (ASN), combined freely | 1–1440 min |
| 2 | Pool 2 | Country, then one of: a state, a city or an ISP | 1–60 min |
| 3 | Pool 3 | Country; state and city in the US | 1–1440 min |
| mix | Mix | Pool 1's places; each pool in the Mix serves what it can | 1–1440 min with Pools 1 + 3 (Pool 2 sits out past 60); 1–60 min otherwise |
Places for Pool 2 and Pool 3: GET /locations?pool=2 (or 3). Names work as well as codes: "Los Angeles", "losangeles" and "los_angeles" are the same city.
# Pool 3, Los Angeles, the same IP for 30 minutes
curl -X POST "https://socksnode.com/api/v1/proxies" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pool": "3", "protocol": "http", "country": "us",
"state": "california", "city": "losangeles",
"sessionMode": "sticky", "stickyDurationMinutes": 30}'
# A Mix of all three pools, a new IP on every request
curl -X POST "https://socksnode.com/api/v1/proxies" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pool": "mix", "mixPools": "123", "protocol": "http",
"country": "gb", "sessionMode": "rotating", "count": 5}'
# Pool 2's own states, cities and ISPs in one country
curl "https://socksnode.com/api/v1/locations?pool=2&country=gb" \
-H "Authorization: Bearer YOUR_API_KEY"REST API
Authentication
Base URL https://socksnode.com/api/v1. Create a key under Dashboard → API access and send it as a Bearer token. Keys are scoped — request only what you need.
| Scope | Grants |
|---|---|
| read:usage | Balance & usage analytics |
| read:proxies | List saved proxy credentials |
| write:proxies | Generate new proxy credentials |
| purchase | Buy GB for rotating residential, datacenter and mobile proxies, buy and renew static and ISP IPs, rent and renew 4G/5G ports, turn on auto-renew, buy 24-hour IPs and IP Vault addresses and bandwidth — charged to your wallet. |
Rate limit: 120 requests per minute per key (proxy generation is throttled further). Keep your key secret and server-side.
GET /api/v1/account HTTP/1.1
Host: socksnode.com
Authorization: Bearer sk_YOUR_API_KEYErrors
Errors return a JSON body { "error": { "code", "message" } } with the matching HTTP status:
| Status | Meaning |
|---|---|
| 400 | Invalid request body or parameters |
| 401 | Missing, invalid or revoked API key |
| 402 | Insufficient bandwidth balance to generate proxies |
| 403 | API key is missing the required scope |
| 404 | Not found, or not yours. |
| 429 | Rate limit exceeded — see Retry-After header |
| 503 | The product is under maintenance. Try again shortly. |
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": {
"code": "no_bandwidth",
"message": "…"
}
}bandwidth balance
GET/account
Scope: read:usage
No parameters.
curl "https://socksnode.com/api/v1/account" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"balance": {
"purchasedGb": 50,
"usedGb": 12.34,
"remainingGb": 37.66
},
"datacenterBalance": {
"purchasedGb": 0,
"usedGb": 0,
"remainingGb": 0
},
"mobileRotatingBalance": {
"purchasedGb": 10,
"usedGb": 1.2,
"remainingGb": 8.8
},
"creditUsd": 40
}Price ladder and quote for rotating GB
GET/pricing
Scope: read:usage
Query parameters
productstringOptionalWhich network: residential (default), datacenter or mobile_rotating.
residentialdatacentermobile_rotatingDefault:residentialgbintegerOptionalOptional. A whole number of GB from 5 to 10,240 to get a quote for.
curl "https://socksnode.com/api/v1/pricing?product=datacenter&gb=100" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"product": "datacenter",
"currency": "USD",
"minGb": 5,
"maxGb": 10240,
"bandwidthExpires": false,
"tiers": [
{ "gb": 5, "priceUsd": 3.05, "perGbUsd": 0.61 },
{ "gb": 100, "priceUsd": 49, "perGbUsd": 0.49 },
{ "gb": 10240, "priceUsd": 2969.6, "perGbUsd": 0.29 }
],
"quote": { "gb": 100, "totalUsd": 49, "perGbUsd": 0.49 }
}Buy rotating GB from your balance
POST/orders
Scope: purchase
Body parameters
productstringOptionalWhich network: residential (default), datacenter or mobile_rotating.
residentialdatacentermobile_rotatingDefault:residentialgbintegerRequiredGB to buy, from 5 to 10,240. Charged to your wallet at the ladder price, with your rank discount; the GB is credited at once and never expires.
curl -X POST "https://socksnode.com/api/v1/orders" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"product": "datacenter",
"gb": 100
}'{
"order": {
"id": "cmv…",
"orderNumber": "SN-MVFRMPRO-B26F94",
"product": "datacenter",
"gb": 100,
"amountUsd": 49,
"discountUsd": 0,
"status": "paid"
},
"balanceUsd": 51
}analytics
GET/usage
Scope: read:usage
Query parameters
rangestringOptionalTime window. An unknown value falls back to 24h.
1h24h7d30d90dtodaymonth12mallDefault:24hproductstringOptionaldatacenter reads datacenter usage; anything else reads residential.
residentialdatacentermobile_rotatingDefault:residential
curl "https://socksnode.com/api/v1/usage?range=30d" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"range": "30d",
"product": "residential",
"granularity": "day",
"totalGb": 12.34,
"series": [{ "period": "2026-09-01", "gb": 1.2 }],
"requests": {
"total": 10420,
"successful": 10310,
"failed": 110,
"successRate": 98.9,
"avgLatencyMs": 280
},
"byCountry": [{ "country": "us", "requests": 8200, "gb": 9.1 }],
"truncated": false
}list saved credentials
GET/proxies
Scope: read:proxies
No parameters.
curl "https://socksnode.com/api/v1/proxies" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": [
{
"id": "clx…",
"product": "residential",
"label": "scraper",
"protocol": "http",
"country": "us",
"sessionMode": "rotating",
"host": "global.socksnode.com",
"port": 9000,
"username": "USERNAME-country-us",
"pool": "1",
"status": "active",
"createdAt": "2026-09-30T08:12:44.000Z"
}
]
}generate credentials (password returned once)
POST/proxies
Scope: write:proxies
Body parameters
protocolstringRequiredProtocol the credentials speak.
httpsocks5countrystringRequiredTwo-letter country code, or ANY for worldwide.
statestringOptionalUS state, full name without spaces, e.g. california.
citystringOptionalCity name without spaces, e.g. losangeles. Ignored when asn is set.
asnintegerOptionalISP network number, e.g. 7922 for Comcast.
sessionModestringRequiredrotating gives a new IP on every request; sticky keeps one IP for stickyDurationMinutes.
rotatingstickystickyDurationMinutesintegerOptionalHow long a sticky IP is held, 1–1440 minutes. Required when sessionMode is sticky.
countintegerOptionalHow many credentials to create, 1–20.
Default:
1labelstringOptionalYour name for them, up to 80 characters. With count above 1 each one gets #n.
poolstringOptionalResidential pool: 1 (default), 2, 3 or mix. See Pools.
123mixDefault:1mixPoolsstringOptionalWith pool mix: the pools it draws on, 12, 13, 23 or 123 (default 123).
121323123Default:123strictbooleanOptionaltrue: only the exact state, city or ISP; false: fall back to the country when it has no free IP. Default true on Pool 1 and false on a Mix; a strict Mix runs on Pool 1.
gatewaystringOptionalEntry gateway the line dials: fr, us or sg — or auto (default), which returns the geo-routed host and lets DNS pick the nearest. Residential only.
autofrussgDefault:autoosstringOptionalDevice OS fingerprint: windows, android, ios or mac. Omit for any device.
windowsandroidiosmacproductstringOptionalWhich balance pays and which network the proxies come from: residential (default), datacenter or mobile_rotating. For mobile_rotating, country targeting is the default; state, city and ASN targeting count traffic twice, and a sticky IP is held for at most 120 minutes.
residentialdatacentermobile_rotatingDefault:residential
curl -X POST "https://socksnode.com/api/v1/proxies" \
-H "Authorization: Bearer sk_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"protocol": "http",
"country": "us",
"sessionMode": "rotating",
"count": 2,
"label": "scraper"
}'{
"data": [
{
"id": "clx…",
"host": "global.socksnode.com",
"port": 9000,
"username": "USERNAME-country-us",
"password": "shown once",
"protocol": "http",
"country": "us",
"state": null,
"city": null,
"sessionMode": "rotating",
"stickyDurationMinutes": null,
"label": "scraper #1",
"product": "residential",
"pool": "1",
"mixPools": null,
"poolNote": null
}
]
}delete a saved credential
DELETE/proxies/{id}
Scope: write:proxies
Path parameters
idstringRequiredThe saved proxy's id, as GET /proxies returns it.
curl -X DELETE "https://socksnode.com/api/v1/proxies/PROXY_ID" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": { "id": "clx…", "deleted": true }
}Targeting catalogue: countries, their states and cities
GET/locations
Scope: read:proxies
Query parameters
countrystringOptionalCountry code. Returns its states.
statestringOptionalState code, together with country. Returns its cities.
productstringOptionalWhose catalogue to read: residential (default), datacenter or mobile_rotating. Datacenter and rotating mobile also list the country's ASNs.
residentialdatacentermobile_rotatingDefault:residentialpoolstringOptionalResidential pool whose places to list: 1 (default), 2 or 3. A Mix targets with Pool 1's list.
123Default:1
curl "https://socksnode.com/api/v1/locations?country=us" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": {
"country": "us",
"states": [
{ "code": "california", "name": "California", "cities": 212 },
{ "code": "texas", "name": "Texas", "cities": 187 }
]
}
}Ready to build?
Generate credentials in the dashboard or create an API key to automate it.