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

Mobile proxies

4G/5G REST API

Buy and manage 4G/5G mobile proxies programmatically. Each Mobile IP is one rotating carrier IP (up to 3 connections) for a chosen duration. Rentals and renewals are charged to your prepaid account credit (USD). Uses the read:proxies / write:proxies scopes.

https://socksnode.com/api/v1

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.
409The port's state does not allow this right now, e.g. it has expired.
429Rate limit exceeded — see Retry-After header
502The upstream network failed. You were not charged.
503The product is under maintenance. Try again shortly.
HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "code": "no_bandwidth",
    "message": "…"
  }
}

API endpoints

durations, countries, states & carriers

GET/mobile/catalog

Scope: read:proxies

Query parameters

  • countryintegerOptional

    Country id. Returns its states.

  • stateintegerOptional

    State id. Returns its carriers.

  • availabilitystringOptional

    Set to 1 to add how much of each option is free right now.

    1

  • tierstringOptional

    Which plan's stock to report.

    economybasicturboDefault: basic

  • modemsstringOptional

    Set to 1 with state to list every modem there, free and busy, with how long each holds its IP. Same fields as /mobile/proxies/PROXY_ID/modems.

    1

  • carrierintegerOptional

    Carrier id. With modems=1, lists only that carrier's modems.

curl "https://socksnode.com/api/v1/mobile/catalog?state=12&availability=1" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Response200
{
  "data": {
    "carriers": [
      { "id": 34, "name": "5G AT&T", "status": "ok", "pct": 82 },
      { "id": 35, "name": "5G T-Mobile", "status": "low", "pct": 11 },
      { "id": 36, "name": "5G Verizon", "status": "none", "pct": 0 }
    ]
  }
}
// status: "ok" | "low" | "none" | "unknown"
// Country and state stock is refreshed every ~15 min;
// carrier stock is checked live, right before you choose.

list your mobile proxies (with credentials)

GET/mobile/proxies

Scope: read:proxies

No parameters.

curl "https://socksnode.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Response200
{
  "data": [
    {
      "id": "clx…",
      "name": "Port 1",
      "host": "mobile.socksnode.com",
      "port": 9094,
      "protocol": "socks5",
      "username": "sn_a1b2c3d4",
      "password": "…",
      "authMode": "userpass",
      "allowedIps": [],
      "country": "UNITED STATES",
      "state": "FLORIDA",
      "carrier": "5G AT&T",
      "rotationMinutes": 15,
      "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
      "status": "active",
      "paused": false,
      "bytesUsed": 0,
      "lastExitIp": null,
      "expiresAt": "2026-10-30T04:46:53.000Z"
    }
  ]
}

one proxy

GET/mobile/proxies/{id}

includes data used + last exit IP

Scope: read:proxies

Path parameters

  • idstringRequired

    The mobile proxy's id.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Response200
{
  "data": {
    "id": "clx…",
    "name": "Port 1",
    "host": "mobile.socksnode.com",
    "port": 9094,
    "protocol": "socks5",
    "username": "sn_a1b2c3d4",
    "password": "…",
    "authMode": "userpass",
    "allowedIps": [],
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "rotationMinutes": 15,
    "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
    "status": "active",
    "paused": false,
    "bytesUsed": 0,
    "lastExitIp": null,
    "expiresAt": "2026-10-30T04:46:53.000Z"
  }
}

buy N ports (charged to credit; 402 if too low)

POST/mobile/proxies

Scope: purchase

Body parameters

  • tierKeystringOptional

    Plan to rent.

    economybasicturboDefault: basic

  • durationKeystringRequired

    Rental length. It must be one the plan sells.

    2h12h1d3d7d15d30d

  • quantityintegerOptional

    Ports to rent, 1–50. If some cannot be created, you pay only for the rest.

    Default: 1

  • countryIdintegerOptional

    Country id from the catalog. Omit it to take any available location.

  • cityIdintegerOptional

    State id from the catalog.

  • spIdintegerOptional

    Carrier id from the catalog.

  • modemIdstringOptional

    A modem id from /mobile/catalog?modems=1 (same tier). Needs cityId and quantity 1. 409 modem_taken if it has no free slot; you are not charged.

  • protocolstringOptional

    Protocol the port speaks.

    sockshttpDefault: socks

curl -X POST "https://socksnode.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "durationKey": "30d",
    "quantity": 1,
    "countryId": 1,
    "cityId": 12,
    "spId": 34,
    "protocol": "socks"
  }'
Response201
{
  "data": [
    {
      "id": "clx…",
      "name": "Port 1",
      "host": "mobile.socksnode.com",
      "port": 9094,
      "protocol": "socks5",
      "username": "sn_a1b2c3d4",
      "password": "…",
      "authMode": "userpass",
      "allowedIps": [],
      "country": "UNITED STATES",
      "state": "FLORIDA",
      "carrier": "5G AT&T",
      "rotationMinutes": 15,
      "modem": { "id": "3f9c0a1b2d4e5f607182", "code": "K7QM" },
      "status": "active",
      "paused": false,
      "bytesUsed": 0,
      "lastExitIp": null,
      "expiresAt": "2026-10-30T04:46:53.000Z"
    }
  ],
  "charged": 40
}

change country/state/carrier (free)

POST/mobile/proxies/{id}/switch

Scope: write:proxies

Path parameters

  • idstringRequired

    The mobile proxy's id.

Body parameters

  • countryIdintegerRequired

    Country id from the catalog.

  • cityIdintegerOptional

    State id from the catalog.

  • spIdintegerOptional

    Carrier id from the catalog.

  • modemIdstringOptional

    A modem id from the modem list. Needs cityId. The port moves to that modem only: 409 modem_taken if it is full, 404 modem_gone if it has left the list.

  • protocolstringOptional

    Defaults to the port's current protocol.

    sockshttp

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/switch" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "countryId": 3,
    "cityId": 12,
    "spId": 34,
    "modemId": "8d21e7c40b9a6f5e3c12"
  }'
Response200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

list a state's modems for a port (free and busy, IP hold time)

GET/mobile/proxies/{id}/modems

Scope: read:proxies

Path parameters

  • idstringRequired

    The mobile proxy's id.

Query parameters

  • stateintegerRequired

    State id from the catalog. Lists that state's modems for this port's plan.

  • carrierintegerOptional

    Carrier id. With modems=1, lists only that carrier's modems.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/modems?state=12&carrier=34" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Response200
{
  "data": {
    "modems": [
      {
        "id": "3f9c0a1b2d4e5f607182",
        "code": "K7QM",
        "carrier": "5G AT&T",
        "free": true,
        "current": true,
        "yours": 0,
        "yourPorts": [],
        "rotationMinutes": 30,
        "lastIp": "174.208.161.27",
        "lastOkAt": "2026-10-28T03:12:40.000Z",
        "failing": false
      },
      {
        "id": "8d21e7c40b9a6f5e3c12",
        "code": "R4XB",
        "carrier": "5G AT&T",
        "free": false,
        "current": false,
        "yours": 0,
        "yourPorts": [],
        "rotationMinutes": 60,
        "lastIp": null,
        "lastOkAt": null,
        "failing": false
      }
    ],
    "free": 1,
    "total": 2
  }
}
// free: has a slot for one more port. current: this port is on it.
// yours: your other live ports on it (they share its IP); yourPorts: their port numbers.
// rotationMinutes: how long the modem keeps one IP.

fresh exit IP (free)

POST/mobile/proxies/{id}/rotate

Scope: write:proxies

Path parameters

  • idstringRequired

    The mobile proxy's id.

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Response200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

read the live exit IP

GET/mobile/proxies/{id}/check-ip

Scope: read:proxies

Path parameters

  • idstringRequired

    The mobile proxy's id.

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/check-ip" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
Response200
{
  "data": { "ip": "174.208.161.27" }
}

switch SOCKS5 ↔ HTTP(S)

POST/mobile/proxies/{id}/protocol

Scope: write:proxies

Path parameters

  • idstringRequired

    The mobile proxy's id.

Body parameters

  • protocolstringRequired

    Protocol the port speaks.

    sockshttp

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/protocol" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "http"
  }'
Response200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

switch auth mode

POST/mobile/proxies/{id}/auth

Scope: write:proxies

Path parameters

  • idstringRequired

    The mobile proxy's id.

Body parameters

  • modestringRequired

    userpass signs in with username and password; whitelist lets the listed IPs connect without one.

    userpasswhitelist

  • allowedIpsstring[]Optional

    Up to 3 public IPv4 or IPv6 addresses, no ranges. Needed for whitelist.

    Default: []

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/auth" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "whitelist",
    "allowedIps": [
      "203.0.113.7"
    ]
  }'
Response200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  }
}
// + every other field of GET /mobile/proxies/{id}

extend the port (charged to credit)

POST/mobile/proxies/{id}/renew

Scope: purchase

Path parameters

  • idstringRequired

    The mobile proxy's id.

Body parameters

  • durationKeystringRequired

    Rental length. It must be one the port's plan sells.

    2h12h1d3d7d15d30d

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/renew" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "durationKey": "30d"
  }'
Response200
{
  "data": {
    "id": "clx…",
    "host": "mobile.socksnode.com",
    "port": 9095,
    "protocol": "socks5",
    "country": "UNITED STATES",
    "state": "FLORIDA",
    "carrier": "5G AT&T",
    "status": "active"
  },
  "charged": 40
}
// + every other field of GET /mobile/proxies/{id}

Ready to build?

Generate credentials in the dashboard or create an API key to automate it.