Документация API прокси: получение списка прокси через REST API

Что можно делать с API?

API используется, когда программа сама запрашивает актуальный список прокси (например, при старте скрапера или смене тарифа). Данные идентичны спискам из консоли.

API доступен только для чтения. Поддерживает проверку баланса, список тарифов и получение списка прокси. Оплата и покупка выполняются в панели управления. Все ответы в UTF-8, даты в формате ISO 8601 UTC.

Как создать и отправить API-ключ?

Создайте API ключ на странице ключей в панели управления. Ключ начинается с spx_, состоит из 44 символов и показывается только один раз при создании. На сервере хранится только хэш ключа, поэтому, если вы его потеряете, создайте новый. Новый ключ сразу отключит предыдущий.

Добавляйте ключ в заголовок Authorization с типом Bearer. Мы не поддерживаем передачу ключа в параметрах URL. При отсутствии или ошибке ключа возвращается 401 unauthorized.

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

Запрос информации о балансе и аккаунте: GET /account

Возвращает код аккаунта, баланс, количество активных планов и прокси. Баланс отображается с точностью до двух знаков после запятой (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"
}

Получение списка тарифов: GET /plans

Возвращает купленные тарифы, начиная с последних. Статус может быть active (активен), expired (истек), canceled (отменен). id - это код тарифа (начинается с P-), его можно использовать как значение plan в /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"
    }
  ]
}

Получение списка прокси: GET /proxies

Возвращает используемые прокси в формате JSON. Для каждого прокси указаны адрес, HTTP-порт, SOCKS5-порт, имя пользователя, пароль, страна, город, код тарифа и время истечения.

Можно фильтровать по country (двухбуквенный код страны, например us) и plan (код тарифа). Поле protocol отображается в ответе, а JSON содержит оба порта.

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

Скачать список: GET /proxies/download

Программа возвращает один прокси на строку в текстовом формате. Если protocol=socks5, используется SOCKS5 порт, если http - HTTP порт. format=url добавляет префикс (socks5:// или http://) в зависимости от протокола.

На серверах с включенной авторизацией по IP можно подключаться в формате ip:port без имени пользователя. CSV содержит заголовки в первой строке и оба порта.

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

Примеры кода: Python, Node.js, PHP

Пример ниже получает список и отправляет запрос через первый прокси. Для Python с SOCKS5 нужен пакет requests[socks], а socks5h также разрешает доменные имена через прокси.

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

Коды ошибок и лимиты запросов

Ошибки возвращаются с HTTP-статусом в формате { "error": { "code", "message" } }. Лимит - 300 запросов в минуту на один ключ; при превышении в течение минуты возвращается 429. Списки обновляются только при покупке или истечении срока, поэтому рекомендуем загружать их раз в несколько минут и использовать локально.

API-вызовы не тарифицируются. Списание с баланса происходит только при покупке тарифов в панели управления.