代理API文档：通过REST API获取代理列表

Socks5Proxy API是一个使用仪表板中创建的API密钥获取账户余额、购买的套餐、代理列表的REST API，支持JSON、txt、csv格式，默认地址为https://socks5proxy.io/api/v1，每个密钥每分钟最多可调用300次。

API能实现哪些功能？

API适用于让应用程序自动获取最新代理列表。可在爬虫启动时获取列表，或在套餐变更/到期时自动切换。通过控制台下载与API获取的列表数据完全一致。

API为只读接口，支持余额查询、套餐列表、代理列表获取，支付和购买需在控制台完成。所有响应采用UTF-8编码，日期为ISO 8601 UTC格式。

方法	路径	说明
GET	/account	账户代码、余额(USD)、在用套餐数、代理IP数
GET	/plans	购买的套餐列表（最近200个），状态和到期时间
GET	/proxies	使用中的代理列表(JSON)，按国家/套餐筛选
GET	/proxies/download	代理列表支持txt或csv单行格式

如何创建和发送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

返回账户代码、余额、在用套餐数和代理IP数。余额精确到小数点后两位(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-开头），可用作/proxies中的plan值。

{
  "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 中包含两个端口。

查询	值	说明
country	us、de、jp等	仅限该国代理
plan	P-XXXXX-XXXXX	仅限该套餐代理
protocol	http, socks5	默认http
format	json	默认值，其他格式见/proxies/download

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文件首行为列名且包含双端口信息。

format	单行示例 (protocol=socks5)
ip:port:user:pass (基础)	198.51.100.23:1080:spx_k2m8qa:q7rbx2wd9n
user:pass@ip:port	spx_k2m8qa:q7rbx2wd9n@198.51.100.23:1080
ip:port	198.51.100.23:1080
url	socks5://spx_k2m8qa:q7rbx2wd9n@198.51.100.23:1080
csv	198.51.100.23,8231,1080,spx_k2m8qa,q7rbx2wd9n,us,纽约

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状态码持续1分钟。代理列表仅在购买/过期时更新，建议缓存数分钟并在程序内复用。

API调用不产生费用，仅购买套餐时会从余额扣除。

状态	code	含义
401	unauthorized	密钥缺失或错误，若已创建新密钥请使用新密钥
400	bad_format	format值不在列表中
404	not_found	无效路径
429	rate_limited	每分钟超过300次