Dokumentacja API proxy: pobieranie listy proxy za pomocą REST API

Co można zrobić za pomocą API?

API jest używane, gdy program korzystający z proxy pobiera najnowszą listę bezpośrednio. Możesz skonfigurować crawlera do pobierania listy przy każdym uruchomieniu, zakupie nowego planu lub po zakończeniu okresu. Lista pobierana z panelu i przez API to te same dane.

API jest tylko do odczytu. Obsługuje sprawdzanie salda, listy planów i listy proxy. Płatności i zakupy odbywają się w panelu. Wszystkie odpowiedzi są w UTF-8, a daty w formacie ISO 8601 UTC.

Jak utworzyć i wysłać klucz API?

Wygeneruj klucz API w panelu. Klucz zaczyna się od spx_, ma 44 znaki i jest wyświetlany tylko raz. Serwer przechowuje tylko jego skrót (hash), więc jeśli go zgubisz, po prostu wygeneruj nowy - stary natychmiast traci ważność.

Do każdego żądania dodaj klucz w nagłówku Authorization w formacie Bearer. Nie akceptujemy kluczy dodawanych w zapytaniach URL. Jeśli klucz jest brakujący lub nieprawidłowy, otrzymasz odpowiedź 401 unauthorized.

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

Sprawdź saldo i informacje o koncie: GET /account

Zwraca kod konta, saldo, liczbę aktywnych planów i liczbę proxy. Saldo jest podane w formacie tekstowym z dokładnością do dwóch miejsc po przecinku (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"
}

Lista planów: GET /plans

Zwraca zakupione plany, od najnowszych. Status może być active (aktywny), expired (wygasły) lub canceled (anulowany). Id to kod planu (zaczyna się od P-), który można użyć jako wartość plan w /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"
    }
  ]
}

Pobieranie listy proxy: GET /proxies

Zwraca aktywne proxy w formacie JSON. Każde proxy zawiera adres, port HTTP, port SOCKS5, nazwę użytkownika, hasło, kraj, miasto, kod planu i czas wygaśnięcia.

Możesz filtrować po country (kod kraju dwuliterowy, np. us) i plan (kod planu). Wartość protocol jest wyświetlana w odpowiedzi, a JSON zawiera oba porty.

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

Pobierz listę: GET /proxies/download

Program może odczytać listę bezpośrednio, zwracając jeden proxy w każdej linii tekstu. Jeśli protocol to socks5, używa portu SOCKS5, jeśli http, używa portu HTTP. format=url dodaje odpowiedni prefiks adresu (socks5:// lub http://) zgodnie z protokołem.

Na serwerach z włączoną autoryzacją IP możesz łączyć się w formacie ip:port bez nazwy użytkownika. Plik CSV zawiera nazwy kolumn w pierwszym wierszu i oba porty.

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

Przykłady kodu: Python, Node.js, PHP

Poniższy przykład pobiera listę i wysyła żądanie przez pierwszy proxy. Aby użyć SOCKS5 w Pythonie, potrzebny jest pakiet requests[socks], a jeśli użyjesz socks5h, rozpoznawanie nazw domen również odbywa się po stronie 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";

Kody błędów i limity wywołań

Błędy zwracane są w formacie { "error": { "code", "message" } } z kodem statusu HTTP. Limit to 300 wywołań na klucz na minutę - przekroczenie zwraca błąd 429 na 1 minutę. Listy proxy zmieniają się tylko przy zakupie/wygaśnięciu, więc zalecamy pobranie ich raz i przechowywanie lokalnie.

Wywołania API nie są płatne. Saldo jest zmniejszane tylko przy zakupie planów w panelu.