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/v1Authentication
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. |
| 409 | The port's state does not allow this right now, e.g. it has expired. |
| 429 | Rate limit exceeded — see Retry-After header |
| 502 | The upstream network failed. You were not charged. |
| 503 | The 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
countryintegerOptionalCountry id. Returns its states.
stateintegerOptionalState id. Returns its carriers.
availabilitystringOptionalSet to 1 to add how much of each option is free right now.
1tierstringOptionalWhich plan's stock to report.
economybasicturboDefault:basicmodemsstringOptionalSet 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.
1carrierintegerOptionalCarrier 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"{
"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"{
"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
idstringRequiredThe mobile proxy's id.
curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"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
tierKeystringOptionalPlan to rent.
economybasicturboDefault:basicdurationKeystringRequiredRental length. It must be one the plan sells.
2h12h1d3d7d15d30dquantityintegerOptionalPorts to rent, 1–50. If some cannot be created, you pay only for the rest.
Default:
1countryIdintegerOptionalCountry id from the catalog. Omit it to take any available location.
cityIdintegerOptionalState id from the catalog.
spIdintegerOptionalCarrier id from the catalog.
modemIdstringOptionalA 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.
protocolstringOptionalProtocol 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"
}'{
"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
idstringRequiredThe mobile proxy's id.
Body parameters
countryIdintegerRequiredCountry id from the catalog.
cityIdintegerOptionalState id from the catalog.
spIdintegerOptionalCarrier id from the catalog.
modemIdstringOptionalA 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.
protocolstringOptionalDefaults 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"
}'{
"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
idstringRequiredThe mobile proxy's id.
Query parameters
stateintegerRequiredState id from the catalog. Lists that state's modems for this port's plan.
carrierintegerOptionalCarrier 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"{
"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
idstringRequiredThe mobile proxy's id.
curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"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}no API key needed
GET/mobile/proxies/{id}/rotate?token=…
a single copy-paste link from your dashboard. Open it (browser, curl, a cron job, a bookmark) to rotate; add location params to switch country/state/carrier instead.
Query parameters
tokenstringRequiredThe port's rotation token, from its card in the dashboard. No API key is needed.
countryIdintegerOptionalOptional. Switch to this location instead of only changing the IP.
cityIdintegerOptionalState id from the catalog.
spIdintegerOptionalCarrier id from the catalog.
formatstringOptionalResponse format.
jsonhtmlDefault:json
curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate?token=YOUR_ROTATE_TOKEN"{
"ok": true,
"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
idstringRequiredThe mobile proxy's id.
curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/check-ip" \
-H "Authorization: Bearer sk_YOUR_API_KEY"{
"data": { "ip": "174.208.161.27" }
}switch SOCKS5 ↔ HTTP(S)
POST/mobile/proxies/{id}/protocol
Scope: write:proxies
Path parameters
idstringRequiredThe mobile proxy's id.
Body parameters
protocolstringRequiredProtocol 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"
}'{
"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
idstringRequiredThe mobile proxy's id.
Body parameters
modestringRequireduserpass signs in with username and password; whitelist lets the listed IPs connect without one.
userpasswhitelistallowedIpsstring[]OptionalUp 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"
]
}'{
"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
idstringRequiredThe mobile proxy's id.
Body parameters
durationKeystringRequiredRental 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"
}'{
"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.