Documentação da API de proxy: Receba listas de proxies via REST API

O que posso fazer com a API?

Use API para que programas obtenham a lista de proxies mais recente automaticamente. Configure crawlers para buscar a lista ao iniciar, após comprar um novo plano ou ao término do período. As listas obtidas via API são idênticas às baixadas do dashboard.

A API é somente leitura. Suporta consulta de saldo, lista de planos e lista de proxies. Pagamentos e compras são feitos no dashboard. Todas as respostas usam UTF-8 e datas no formato ISO 8601 UTC.

Como criar e enviar chaves API?

Crie chaves API na página de chaves do dashboard. As chaves começam com spx_, têm 44 caracteres e são mostradas apenas uma vez. Perdeu? Crie uma nova - a antiga será desativada imediatamente.

Adicione a chave no cabeçalho Authorization usando o método Bearer em cada solicitação. Não aceitamos chaves via query string. Solicitações sem chave ou com chave incorreta retornam erro 401 unauthorized.

curl -H "Authorization: Bearer spx_your_api_key" https://socks5proxy.io/api/v1/account

Consultar saldo e informações da conta: GET /account

Retorna código da conta, saldo, número de planos ativos e proxies. O saldo é exibido com duas casas decimais (USD).

curl -H "Authorization: Bearer spx_your_api_key" https://socks5proxy.io/api/v1/account

{
  "code": "S5-7KQ2-M8PX-4HDA",
  "balance": "125.40",
  "currency": "USD",
  "active_plans": 2,
  "proxies": 125,
  "created_at": "2026-10-22T08:15:02.114Z"
}

Consultar lista de planos: GET /plans

Retorna os planos adquiridos, do mais recente para o mais antigo. O status pode ser active (em uso), expired (período encerrado) ou canceled (cancelado). O id é o código do plano (começa com P-) e pode ser usado como valor de plan em /proxies.

{
  "plans": [
    {
      "id": "P-8WQ4C-NM2KT",
      "product": "dc-private",
      "product_name": "Private Datacenter Proxy",
      "ips": 100,
      "months": 1,
      "country": "us",
      "status": "active",
      "amount": "49.40",
      "created_at": "2026-10-22T08:20:11.002Z",
      "expires_at": "2026-11-22T08:20:11.002Z"
    }
  ]
}

Consulta de lista de proxies: GET /proxies

Retorna os proxies do plano ativo em JSON. Cada proxy inclui endereço, porta HTTP, porta SOCKS5, nome de usuário, senha, país, cidade, código do plano e horário de expiração.

Filtros disponíveis: country (código de 2 letras, ex: us) e plan (código do plano). O campo protocol aparece na resposta, e o JSON inclui ambas as portas.

curl -H "Authorization: Bearer spx_your_api_key" \
  "https://socks5proxy.io/api/v1/proxies?country=us&protocol=socks5"

{
  "count": 1,
  "protocol": "socks5",
  "proxies": [
    {
      "host": "198.51.100.23",
      "http_port": 8231,
      "socks5_port": 1080,
      "username": "spx_k2m8qa",
      "password": "q7rbx2wd9n",
      "country": "us",
      "city": "New York",
      "plan": "P-8WQ4C-NM2KT",
      "product": "dc-private",
      "product_name": "Private Datacenter Proxy",
      "expires_at": "2026-11-22T08:20:11.002Z"
    }
  ]
}

Baixar lista: GET /proxies/download

Retorna um proxy por linha em formato de texto para que os programas possam ler diretamente. Se o protocolo for socks5, a porta SOCKS5 será incluída; se for http, a porta HTTP será incluída. format=url adiciona o prefixo apropriado (socks5:// ou http://) ao endereço.

Em servidores com autenticação por IP permitido, você pode se conectar diretamente no formato ip:port sem nome de usuário. O CSV inclui nomes de coluna na primeira linha e ambas as portas.

curl -H "Authorization: Bearer spx_your_api_key" \
  "https://socks5proxy.io/api/v1/proxies/download?format=url&protocol=socks5" -o proxies.txt

Exemplos de código: Python, Node.js, PHP

O exemplo abaixo recebe a lista e envia a solicitação pelo primeiro proxy. Python precisa do pacote requests[socks] para usar SOCKS5, e ao usar socks5h, a resolução de nomes de domínio também é feita pelo proxy.

import requests

API = "https://socks5proxy.io/api/v1"
H = {"Authorization": "Bearer spx_your_api_key"}

proxies = requests.get(f"{API}/proxies", headers=H, params={"country": "us"}).json()["proxies"]
p = proxies[0]
url = f"socks5h://{p['username']}:{p['password']}@{p['host']}:{p['socks5_port']}"
r = requests.get("https://api.ipify.org?format=json", proxies={"http": url, "https": url}, timeout=30)
print(r.json())

import { ProxyAgent, fetch } from "undici";

const API = "https://socks5proxy.io/api/v1";
const H = { Authorization: "Bearer spx_your_api_key" };

const { proxies } = await (await fetch(`${API}/proxies?country=us`, { headers: H })).json();
const p = proxies[0];
const agent = new ProxyAgent(`http://${p.username}:${p.password}@${p.host}:${p.http_port}`);
const r = await fetch("https://api.ipify.org?format=json", { dispatcher: agent });
console.log(await r.json());

<?php
$ch = curl_init("https://socks5proxy.io/api/v1/proxies/download?format=ip:port:user:pass&protocol=http");
curl_setopt_array($ch, [
  CURLOPT_HTTPHEADER => ["Authorization: Bearer spx_your_api_key"],
  CURLOPT_RETURNTRANSFER => true,
]);
$lines = explode("\n", trim(curl_exec($ch)));
[$host, $port, $user, $pass] = explode(":", $lines[0]);
echo "$host:$port\n";

Códigos de erro e limites de chamadas

Os erros são retornados com códigos de status HTTP no formato { "error": { "code", "message" } }. Cada chave pode ser chamada até 300 vezes por minuto, e exceder esse limite resulta em uma resposta 429 por 1 minuto. Como as listas só mudam na compra ou expiração, recomendamos baixá-las uma vez a cada poucos minutos e reutilizá-las no programa.

Chamadas API não geram cobranças. O saldo só é debitado ao comprar planos no dashboard.