Developers

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
Response200
{"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:PASSWORD

Ports & 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.

ProtocolRotating portSticky port
HTTP / HTTPS900010000
SOCKS51100012000
GatewayHost
Nearest to you (default)global.socksnode.com
Europefr.socksnode.com
United Statesus.socksnode.com
Singaporesg.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.org

Targeting & sessions

Append tokens to your username, separated by hyphens, to control the exit location and session behaviour:

TokenMeaning
-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-android

Pools

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.

poolTargetingSticky
1Pool 1Country, state, city and ISP (ASN), combined freely1–1440 min
2Pool 2Country, then one of: a state, a city or an ISP1–60 min
3Pool 3Country; state and city in the US1–1440 min
mixMixPool 1's places; each pool in the Mix serves what it can1–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.

ScopeGrants
read:usageBalance & usage analytics
read:proxiesList saved proxy credentials
write:proxiesGenerate new proxy credentials
purchaseBuy 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_KEY

Errors

Errors return a JSON body { "error": { "code", "message" } } with the matching HTTP status:

StatusMeaning
400Invalid request body or parameters
401Missing, invalid or revoked API key
402Insufficient bandwidth balance to generate proxies
403API key is missing the required scope
404Not found, or not yours.
429Rate limit exceeded — see Retry-After header
503The 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"
Response200
{
  "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

  • productstringOptional

    Which network: residential (default), datacenter or mobile_rotating.

    residentialdatacentermobile_rotatingDefault: residential

  • gbintegerOptional

    Optional. 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"
Response200
{
  "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

  • productstringOptional

    Which network: residential (default), datacenter or mobile_rotating.

    residentialdatacentermobile_rotatingDefault: residential

  • gbintegerRequired

    GB 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
  }'
Response201
{
  "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

  • rangestringOptional

    Time window. An unknown value falls back to 24h.

    1h24h7d30d90dtodaymonth12mallDefault: 24h

  • productstringOptional

    datacenter 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"
Response200
{
  "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"
Response200
{
  "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

  • protocolstringRequired

    Protocol the credentials speak.

    httpsocks5

  • countrystringRequired

    Two-letter country code, or ANY for worldwide.

  • statestringOptional

    US state, full name without spaces, e.g. california.

  • citystringOptional

    City name without spaces, e.g. losangeles. Ignored when asn is set.

  • asnintegerOptional

    ISP network number, e.g. 7922 for Comcast.

  • sessionModestringRequired

    rotating gives a new IP on every request; sticky keeps one IP for stickyDurationMinutes.

    rotatingsticky

  • stickyDurationMinutesintegerOptional

    How long a sticky IP is held, 1–1440 minutes. Required when sessionMode is sticky.

  • countintegerOptional

    How many credentials to create, 1–20.

    Default: 1

  • labelstringOptional

    Your name for them, up to 80 characters. With count above 1 each one gets #n.

  • poolstringOptional

    Residential pool: 1 (default), 2, 3 or mix. See Pools.

    123mixDefault: 1

  • mixPoolsstringOptional

    With pool mix: the pools it draws on, 12, 13, 23 or 123 (default 123).

    121323123Default: 123

  • strictbooleanOptional

    true: 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.

  • gatewaystringOptional

    Entry 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: auto

  • osstringOptional

    Device OS fingerprint: windows, android, ios or mac. Omit for any device.

    windowsandroidiosmac

  • productstringOptional

    Which 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"
  }'
Response201
{
  "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

  • idstringRequired

    The 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"
Response200
{
  "data": { "id": "clx…", "deleted": true }
}

Targeting catalogue: countries, their states and cities

GET/locations

Scope: read:proxies

Query parameters

  • countrystringOptional

    Country code. Returns its states.

  • statestringOptional

    State code, together with country. Returns its cities.

  • productstringOptional

    Whose catalogue to read: residential (default), datacenter or mobile_rotating. Datacenter and rotating mobile also list the country's ASNs.

    residentialdatacentermobile_rotatingDefault: residential

  • poolstringOptional

    Residential 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"
Response200
{
  "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.