开发者

API 与集成文档

集成 SocksNode 有两种方式:通过 HTTP(S) 或 SOCKS5 直接连接到代理网关,或通过 REST API 以编程方式管理带宽、用量和代理。

本页内容

移动代理

4G/5G REST API

通过 API 购买和管理 4G/5G 移动代理。每个 Mobile IP 是一个轮换的运营商 IP(最多 3 个连接),有效期由你选择。租用和续期从预付的账户余额(USD)中扣除。使用 read:proxies / write:proxies 权限。

https://socksnode.com/api/v1

鉴权

基础 URL https://socksnode.com/api/v1。在 Dashboard → API access 下创建密钥,并以 Bearer 令牌形式发送。密钥具有作用域——只请求你需要的权限。

作用域授予权限
read:usage余额与用量分析
read:proxies列出已保存的代理凭据
write:proxies生成新的代理凭据
purchase为轮换住宅、数据中心和移动代理购买 GB,购买和续费静态 IP 与 ISP IP,租用和续费 4G/5G 端口,开启自动续费,购买 24 小时 IP 以及 IP Vault 地址和流量——从余额扣款。

速率限制:每个密钥每分钟 120 次请求(代理生成会被进一步限流)。请对密钥保密并保存在服务器端。

GET /api/v1/account HTTP/1.1
Host: socksnode.com
Authorization: Bearer sk_YOUR_API_KEY

错误

错误会返回 JSON 主体 { "error": { "code", "message" } },并附带相应的 HTTP 状态码:

状态含义
400请求主体或参数无效
401API 密钥缺失、无效或已撤销
402带宽余额不足,无法生成代理
403API 密钥缺少所需的作用域
404未找到,或不属于你。
409端口当前状态不允许此操作,例如已过期。
429超出速率限制——参见 Retry-After 响应头
502上游网络出错。未向你收费。
503产品维护中。请稍后重试。
HTTP/1.1 402 Payment Required
Content-Type: application/json

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

API 端点

时长、国家、州与运营商

GET/mobile/catalog

作用域: read:proxies

查询参数

  • countryinteger可选

    国家 id。返回其州列表。

  • stateinteger可选

    州 id。返回其运营商列表。

  • availabilitystring可选

    设为 1 可附带每个选项当前的空闲量。

    1

  • tierstring可选

    要查看哪个套餐的库存。

    economybasicturbo默认值: basic

  • modemsstring可选

    与 state 一起设为 1,可列出该州所有调制解调器(空闲和占用),以及每台保持同一 IP 的时长。字段与 /mobile/proxies/PROXY_ID/modems 相同。

    1

  • carrierinteger可选

    运营商 id。配合 modems=1 时只列出该运营商的调制解调器。

curl "https://socksnode.com/api/v1/mobile/catalog?state=12&availability=1" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
响应200
{
  "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.

列出你的移动代理(含凭据)

GET/mobile/proxies

作用域: read:proxies

无参数。

curl "https://socksnode.com/api/v1/mobile/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
响应200
{
  "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"
    }
  ]
}

单个代理——包含已用流量与最近出口 IP

GET/mobile/proxies/{id}

作用域: read:proxies

路径参数

  • idstring必填

    移动代理的 id。

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
响应200
{
  "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"
  }
}

购买 N 个端口(从余额扣除;余额不足返回 402)

POST/mobile/proxies

作用域: purchase

请求体参数

  • tierKeystring可选

    要租用的套餐。

    economybasicturbo默认值: basic

  • durationKeystring必填

    租期。必须是该套餐出售的租期。

    2h12h1d3d7d15d30d

  • quantityinteger可选

    要租用的端口数,1–50。未能创建的端口不收费。

    默认值: 1

  • countryIdinteger可选

    目录中的国家 id。不填则分配任意可用位置。

  • cityIdinteger可选

    目录中的州 id。

  • spIdinteger可选

    目录中的运营商 id。

  • modemIdstring可选

    来自 /mobile/catalog?modems=1 的调制解调器 id(同一套餐)。需要 cityId 且 quantity 为 1。没有空位时返回 409 modem_taken,不会扣费。

  • protocolstring可选

    端口使用的协议。

    sockshttp默认值: 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"
  }'
响应201
{
  "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
}

切换国家/州/运营商(免费)

POST/mobile/proxies/{id}/switch

作用域: write:proxies

路径参数

  • idstring必填

    移动代理的 id。

请求体参数

  • countryIdinteger必填

    目录中的国家 id。

  • cityIdinteger可选

    目录中的州 id。

  • spIdinteger可选

    目录中的运营商 id。

  • modemIdstring可选

    来自调制解调器列表的 id。需要 cityId。端口只会换到这台调制解调器:已满返回 409 modem_taken,已不在列表中返回 404 modem_gone。

  • protocolstring可选

    默认沿用端口当前协议。

    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"
  }'
响应200
{
  "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}

列出某州可供端口使用的调制解调器(空闲/占用、IP 保持时长)

GET/mobile/proxies/{id}/modems

作用域: read:proxies

路径参数

  • idstring必填

    移动代理的 id。

查询参数

  • stateinteger必填

    目录中的州 id。按此端口的套餐列出该州的调制解调器。

  • carrierinteger可选

    运营商 id。配合 modems=1 时只列出该运营商的调制解调器。

curl "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/modems?state=12&carrier=34" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
响应200
{
  "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.

全新出口 IP(免费)

POST/mobile/proxies/{id}/rotate

作用域: write:proxies

路径参数

  • idstring必填

    移动代理的 id。

curl -X POST "https://socksnode.com/api/v1/mobile/proxies/PROXY_ID/rotate" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"
响应200
{
  "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}

读取实时出口 IP

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

作用域: read:proxies

路径参数

  • idstring必填

    移动代理的 id。

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

切换 SOCKS5 ↔ HTTP(S)

POST/mobile/proxies/{id}/protocol

作用域: write:proxies

路径参数

  • idstring必填

    移动代理的 id。

请求体参数

  • protocolstring必填

    端口使用的协议。

    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"
  }'
响应200
{
  "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}

切换认证方式

POST/mobile/proxies/{id}/auth

作用域: write:proxies

路径参数

  • idstring必填

    移动代理的 id。

请求体参数

  • modestring必填

    userpass 使用用户名和密码登录;whitelist 允许名单中的 IP 免密码连接。

    userpasswhitelist

  • allowedIpsstring[]可选

    最多 3 个公网 IPv4 或 IPv6 地址,不支持网段。whitelist 时必填。

    默认值: []

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"
    ]
  }'
响应200
{
  "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}

续期端口(从余额扣除)

POST/mobile/proxies/{id}/renew

作用域: purchase

路径参数

  • idstring必填

    移动代理的 id。

请求体参数

  • durationKeystring必填

    租期。必须是该端口套餐出售的租期。

    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"
  }'
响应200
{
  "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}

准备好开始构建了吗?

在控制台生成凭据,或创建 API 密钥以实现自动化。