代理API文檔：使用REST API獲取代理列表

Socks5Proxy API是通過控制台創建的API密鑰獲取賬戶餘額、已購套餐、代理列表(JSON)及txt·csv列表的REST API，基礎地址為https://socks5proxy.io/api/v1，每個密鑰每分鐘限300次調用。

API能做什麼？

當程序需自動獲取最新代理列表時應使用API。可在爬蟲啟動時獲取列表，或在購買新方案/方案到期時讓伺服器自動切換列表。控制台下載列表與API獲取的數據完全一致。

API為只讀。支持餘額查詢、方案列表、代理列表查詢，支付及購買需於控制台完成。所有響應為UTF-8編碼，日期為ISO 8601 UTC格式。

方法	路徑	說明
GET	/account	帳戶代碼、餘額(USD)、使用中的計劃數量、代理數量
GET	/plans	已購買的計劃列表（最近200個），狀態及到期時間
GET	/proxies	正在使用的代理列表（JSON），按國家/計劃篩選
GET	/proxies/download	代理列表可下載為txt或csv單行格式

如何創建及發送API密鑰？

在儀表板的API密鑰畫面中創建密鑰。密鑰以spx_開頭，長度為44個字符，僅在創建時顯示一次。伺服器上只保存密鑰的哈希值，如果丟失可以重新創建，新密鑰創建後舊密鑰將立即失效。

每個請求在Authorization標頭中以Bearer方式加入密鑰。不接受在地址查詢中加入密鑰的方式。如果密鑰缺失或錯誤，會返回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-開頭），可用作/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次