Documentação da API e de integração
Duas formas de integrar o SocksNode: conecte-se diretamente ao gateway do proxy por HTTP(S) ou SOCKS5, ou gerencie largura de banda, uso e proxies programaticamente por meio da API REST.
Nesta página
Proxies móveis
REST API 4G/5G
Compre e gerencie proxies móveis 4G/5G programaticamente. Cada IP Móvel é um IP de operadora rotativo com até 3 conexões para uma duração escolhida. Aluguéis e renovações são cobrados do crédito pré-pago da sua conta (USD). Usa os escopos read:proxies / write:proxies.
https://socksnode.com/api/v1Autenticação
URL base https://socksnode.com/api/v1. Crie uma chave em Dashboard → API access e envie-a como um token Bearer. As chaves têm escopo — solicite apenas o que você precisa.
| Escopo | Permissões |
|---|---|
| read:usage | Saldo e analytics de uso |
| read:proxies | Listar credenciais de proxy salvas |
| write:proxies | Gerar novas credenciais de proxy |
| purchase | Comprar GB para proxies rotativos residenciais, de datacenter e móveis, comprar e renovar IPs estáticos e ISP, alugar e renovar portas 4G/5G, ativar a renovação automática, comprar IPs de 24 horas e endereços e banda do IP Vault, cobrados do seu saldo. |
Limite de taxa: 120 solicitações por minuto por chave (a geração de proxy é ainda mais limitada). Mantenha sua chave em segredo e no lado do servidor.
GET /api/v1/account HTTP/1.1
Host: socksnode.com
Authorization: Bearer sk_YOUR_API_KEYErros
Os erros retornam um corpo JSON { "error": { "code", "message" } } com o status HTTP correspondente:
| Status | Significado |
|---|---|
| 400 | Corpo da solicitação inválido ou parâmetros inválidos |
| 401 | Chave de API ausente, inválida ou revogada |
| 402 | Saldo de largura de banda insuficiente para gerar proxies |
| 403 | A chave de API não tem o escopo necessário |
| 404 | Não encontrado, ou não é seu. |
| 409 | O estado da porta não permite isso agora, ex.: ela expirou. |
| 429 | Limite de taxa excedido — consulte o cabeçalho Retry-After |
| 502 | A rede de origem falhou. Você não foi cobrado. |
| 503 | O produto está em manutenção. Tente de novo em instantes. |
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"error": {
"code": "no_bandwidth",
"message": "…"
}
}Endpoints da API
durações, países, estados e operadoras
GET/mobile/catalog
Escopo: read:proxies
Parâmetros de consulta
countryintegerOpcionalId do país. Retorna seus estados.
stateintegerOpcionalId do estado. Retorna suas operadoras.
availabilitystringOpcionalUse 1 para incluir quanto de cada opção está livre agora.
1tierstringOpcionalDe qual plano mostrar o estoque.
economybasicturboPadrão:basicmodemsstringOpcionalUse 1 junto com state para listar todos os modems do estado, livres e ocupados, com quanto tempo cada um mantém o IP. Mesmos campos de /mobile/proxies/PROXY_ID/modems.
1carrierintegerOpcionalId da operadora. Com modems=1, lista só os modems dessa operadora.
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.liste seus proxies móveis (com credenciais)
GET/mobile/proxies
Escopo: read:proxies
Sem parâmetros.
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"
}
]
}um proxy
GET/mobile/proxies/{id}
inclui dados usados + último IP de saída
Escopo: read:proxies
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
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"
}
}compre N portas (cobrado do crédito; 402 se estiver baixo demais)
POST/mobile/proxies
Escopo: purchase
Parâmetros do corpo
tierKeystringOpcionalPlano a alugar.
economybasicturboPadrão:basicdurationKeystringObrigatórioDuração do aluguel. Precisa ser uma que o plano vende.
2h12h1d3d7d15d30dquantityintegerOpcionalPortas a alugar, 1–50. Se alguma não puder ser criada, você paga só o restante.
Padrão:
1countryIdintegerOpcionalId do país no catálogo. Omita para pegar qualquer local disponível.
cityIdintegerOpcionalId do estado no catálogo.
spIdintegerOpcionalId da operadora no catálogo.
modemIdstringOpcionalUm id de modem de /mobile/catalog?modems=1 (mesmo plano). Exige cityId e quantity 1. 409 modem_taken se não houver vaga; você não é cobrado.
protocolstringOpcionalProtocolo da porta.
sockshttpPadrão: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
}alterar país/estado/operadora (gratuito)
POST/mobile/proxies/{id}/switch
Escopo: write:proxies
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
Parâmetros do corpo
countryIdintegerObrigatórioId do país no catálogo.
cityIdintegerOpcionalId do estado no catálogo.
spIdintegerOpcionalId da operadora no catálogo.
modemIdstringOpcionalUm id de modem da lista de modems. Exige cityId. A porta vai só para esse modem: 409 modem_taken se estiver cheio, 404 modem_gone se saiu da lista.
protocolstringOpcionalPor padrão, o protocolo atual da porta.
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}lista os modems de um estado para uma porta (livres e ocupados, tempo de IP)
GET/mobile/proxies/{id}/modems
Escopo: read:proxies
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
Parâmetros de consulta
stateintegerObrigatórioId do estado no catálogo. Lista os modems desse estado para o plano desta porta.
carrierintegerOpcionalId da operadora. Com modems=1, lista só os modems dessa operadora.
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.novo IP de saída (gratuito)
POST/mobile/proxies/{id}/rotate
Escopo: write:proxies
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
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}não precisa de chave de API
GET/mobile/proxies/{id}/rotate?token=…
um único link para copiar e colar do seu painel. Abra-o (navegador, curl, uma tarefa cron, um favorito) para fazer a rotação; adicione parâmetros de localização para trocar país/estado/operadora.
Parâmetros de consulta
tokenstringObrigatórioO token de rotação da porta, do cartão dela no painel. Não precisa de chave de API.
countryIdintegerOpcionalOpcional. Muda para este local em vez de só trocar o IP.
cityIdintegerOpcionalId do estado no catálogo.
spIdintegerOpcionalId da operadora no catálogo.
formatstringOpcionalFormato da resposta.
jsonhtmlPadrão: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}leia o IP de saída em tempo real
GET/mobile/proxies/{id}/check-ip
Escopo: read:proxies
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
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" }
}alternar SOCKS5 ↔ HTTP(S)
POST/mobile/proxies/{id}/protocol
Escopo: write:proxies
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
Parâmetros do corpo
protocolstringObrigatórioProtocolo da porta.
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}alternar modo de autenticação
POST/mobile/proxies/{id}/auth
Escopo: write:proxies
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
Parâmetros do corpo
modestringObrigatóriouserpass entra com usuário e senha; whitelist deixa os IPs da lista conectarem sem senha.
userpasswhitelistallowedIpsstring[]OpcionalAté 3 endereços IPv4 ou IPv6 públicos, sem faixas. Necessário para whitelist.
Padrão:
[]
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}estenda a porta (cobrado do crédito)
POST/mobile/proxies/{id}/renew
Escopo: purchase
Parâmetros de caminho
idstringObrigatórioO id do proxy móvel.
Parâmetros do corpo
durationKeystringObrigatórioDuração do aluguel. Precisa ser uma que o plano da porta vende.
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}Pronto para começar?
Gere credenciais no painel ou crie uma chave de API para automatizar isso.