代理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位字串，僅在建立時顯示完整內容。伺服器端僅保存金鑰指紋(hash)，遺失時可新建金鑰，舊金鑰將立即失效。

每個請求都在Authorization header中使用Bearer方式加入key。不接受在地址查詢中加入key的方式。如果沒有key或key錯誤，則返回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" } } 格式返回。每個API金鑰每分鐘限呼300次，超限將返回429錯誤1分鐘。代理列表僅在購買/到期時變更，建議每隔幾分鐘獲取一次並緩存在程式中重複使用。

API呼叫不收取費用。僅在儀表板購買方案時會從餘額扣除。

狀態	code	說明
401	unauthorized	金鑰不存在或錯誤，若已建立新金鑰請改用新金鑰
400	bad_format	format 值不在清單中
404	not_found	無效路徑
429	rate_limited	每分鐘超過300次