Documentazione API proxy: ottenere liste proxy via API REST

Cosa posso fare con l'API?

Quando un programma che utilizza proxy deve ottenere l'elenco più recente, usa l'API. Puoi configurare il crawler per ottenere l'elenco all'avvio, acquistare un nuovo piano o lasciare che il server aggiorni automaticamente l'elenco alla scadenza. L'elenco scaricato dal dashboard e quello ottenuto tramite API contengono gli stessi dati.

L'API è in sola lettura. Supporta la verifica del saldo, l'elenco piani e proxy, mentre pagamenti e acquisti avvengono nel dashboard. Le risposte sono in UTF-8 e le date in formato ISO 8601 UTC.

Come creo e invio una chiave API?

Crea una chiave API nella schermata delle chiavi API del dashboard. La chiave inizia con spx_, è lunga 44 caratteri e viene mostrata solo una volta al momento della creazione. Se la perdi, puoi crearne una nuova, e la chiave precedente sarà immediatamente disabilitata.

Inserisci la chiave nell'header Authorization con metodo Bearer per ogni richiesta. Non accettiamo chiavi nei parametri dell'URL. Se manca o è errata, rispondiamo con 401 unauthorized.

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

Consulta saldo e informazioni dell'account: GET /account

Restituisce il codice account, il saldo, il numero di piani attivi e il numero di proxy. Il saldo è una stringa in USD con due decimali.

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"
}

Lista piani: GET /plans

Restituisce i piani acquistati, dai più recenti. Lo status può essere active (in uso), expired (scaduto) o canceled (annullato). L'id è il codice del piano (inizia con P-) e può essere usato come valore plan in /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 lista proxy: GET /proxies

Restituisce i proxy del piano in uso in formato JSON. Ogni proxy include indirizzo, porta HTTP, porta SOCKS5, username, password, paese, città, codice del piano e ora di scadenza.

È possibile filtrare per country (codice paese di due lettere, es. us) e plan (codice del piano). Il valore protocol viene visualizzato nella risposta e JSON include entrambe le porte.

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"
    }
  ]
}

Scarica la lista: GET /proxies/download

Restituisce un proxy per riga in formato testo per un uso immediato nei programmi. Inserisce la porta SOCKS5 se protocol=socks5, HTTP se protocol=http. format=url aggiunge il prefisso (socks5:// o http://) corrispondente al protocollo.

Su server con autenticazione IP abilitata, puoi connetterti direttamente in formato ip:port senza username. I CSV includono i nomi delle colonne nella prima riga e entrambe le porte.

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

Esempi di codice: Python, Node.js, PHP

L'esempio qui sotto riceve la lista e invia la richiesta al primo proxy. Python richiede il pacchetto requests[socks] per SOCKS5, e con socks5h anche la risoluzione DNS avviene lato 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";

Codici errore e limiti chiamate

Gli errori restituiscono codice HTTP e formato { "error": { "code", "message" } }. Limite: 300 chiamate/minuto per chiave, superato il quale ricevi errore 429 per 1 minuto. Poiché le liste cambiano solo all'acquisto/scadenza, ti consigliamo di scaricarle una volta e riutilizzarle localmente.

Le chiamate API non hanno costi. Il saldo viene scalato solo per l'acquisto di piani nel dashboard.