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 | 请求主体或参数无效 |
| 401 | API 密钥缺失、无效或已撤销 |
| 402 | 带宽余额不足,无法生成代理 |
| 403 | API 密钥缺少所需的作用域 |
| 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 可附带每个选项当前的空闲量。
1tierstring可选要查看哪个套餐的库存。
economybasicturbo默认值:basicmodemsstring可选与 state 一起设为 1,可列出该州所有调制解调器(空闲和占用),以及每台保持同一 IP 的时长。字段与 /mobile/proxies/PROXY_ID/modems 相同。
1carrierinteger可选运营商 id。配合 modems=1 时只列出该运营商的调制解调器。
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.列出你的移动代理(含凭据)
GET/mobile/proxies
作用域: read:proxies
无参数。
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"
}
]
}单个代理——包含已用流量与最近出口 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"{
"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默认值:basicdurationKeystring必填租期。必须是该套餐出售的租期。
2h12h1d3d7d15d30dquantityinteger可选要租用的端口数,1–50。未能创建的端口不收费。
默认值:
1countryIdinteger可选目录中的国家 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"
}'{
"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"
}'{
"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"{
"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"{
"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}无需 API key —— 只需从控制台复制 1 个链接。打开它(浏览器、curl、定时任务、书签均可)即可换 IP;加上位置参数即可改为切换国家/州/运营商
GET/mobile/proxies/{id}/rotate?token=…
查询参数
tokenstring必填端口的轮换令牌,在控制台的端口卡片中获取。无需 API 密钥。
countryIdinteger可选可选。切换到该位置,而不只是更换 IP。
cityIdinteger可选目录中的州 id。
spIdinteger可选目录中的运营商 id。
formatstring可选响应格式。
jsonhtml默认值: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}读取实时出口 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"{
"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"
}'{
"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 免密码连接。
userpasswhitelistallowedIpsstring[]可选最多 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"
]
}'{
"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"
}'{
"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}