Tài liệu API proxy: Nhận danh sách proxy qua REST API

Có thể làm gì với API?

Dùng API khi muốn chương trình tự động lấy danh sách proxy mới nhất. Trình thu thập có thể lấy danh sách khi khởi động hoặc tự động thay đổi khi mua gói mới hoặc hết hạn. Danh sách tải từ bảng điều khiển và API là dữ liệu giống nhau.

API chỉ đọc. Hỗ trợ kiểm tra số dư, danh sách gói dịch vụ, tra cứu danh sách proxy. Thanh toán và mua hàng thực hiện trong dashboard. Mọi phản hồi UTF-8, ngày tháng định dạng ISO 8601 UTC.

Làm thế nào để tạo và gửi API key?

Tạo API key trên màn hình API key của bảng điều khiển. Key bắt đầu bằng spx_ và có 44 ký tự, chỉ hiển thị một lần khi tạo. Máy chủ chỉ lưu hash của key, vì vậy nếu bạn mất key, bạn có thể tạo key mới và key cũ sẽ ngừng hoạt động ngay lập tức.

Thêm khóa theo phương thức Bearer vào tiêu đề Authorization cho mỗi yêu cầu. Không hỗ trợ phương thức thêm khóa vào truy vấn địa chỉ. Nếu khóa không có hoặc sai, sẽ trả về lỗi 401 unauthorized.

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

Truy vấn thông tin số dư và tài khoản: GET /account

Trả về mã tài khoản, số dư, số lượng kế hoạch đang sử dụng và số lượng proxy. Số dư được hiển thị đến hai chữ số thập phân (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"
}

Xem danh sách gói: GET /plans

Trả về các gói đã mua theo thứ tự từ gần đây nhất. Trạng thái có thể là active (đang sử dụng), expired (hết hạn), hoặc canceled (đã hủy). ID là mã gói (bắt đầu bằng P-) và có thể được sử dụng làm giá trị plan trong /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"
    }
  ]
}

Truy vấn danh sách proxy: GET /proxies

Trả về proxy của gói đang sử dụng dưới dạng JSON. Mỗi proxy bao gồm địa chỉ, cổng HTTP, cổng SOCKS5, tên người dùng, mật khẩu, quốc gia, thành phố, mã gói và thời gian hết hạn.

Có thể lọc bằng country (mã quốc gia 2 chữ cái, ví dụ: us) và plan (mã gói dịch vụ). Giá trị protocol hiển thị nguyên trong phản hồi, JSON chứa đủ cả hai cổng.

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

Tải danh sách: GET /proxies/download

Trả về mỗi proxy một dòng để chương trình đọc trực tiếp. Nếu protocol là socks5 sẽ dùng cổng SOCKS5, http sẽ dùng cổng HTTP. format=url thêm tiền tố địa chỉ (socks5:// hoặc http://) tương ứng protocol.

Đối với các máy chủ đã bật xác thực IP được phép, bạn có thể kết nối trực tiếp bằng định dạng ip:port mà không cần tên người dùng. File csv có tên cột ở dòng đầu tiên và chứa cả hai cổng.

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

Ví dụ mã: Python, Node.js, PHP

Ví dụ dưới đây nhận danh sách và gửi yêu cầu đến proxy đầu tiên. Để sử dụng SOCKS5 trong Python, bạn cần gói requests[socks], và nếu sử dụng socks5h, việc phân giải tên miền cũng sẽ được thực hiện bởi 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";

Mã lỗi và giới hạn request

Lỗi trả về dạng { "error": { "code", "message" } } cùng mã trạng thái HTTP. Mỗi key được gọi tối đa 300 lần/phút, vượt quá sẽ nhận mã 429 trong 1 phút. Danh sách chỉ thay đổi khi mua hoặc hết hạn, nên tải về vài phút một lần rồi sử dụng lại trong chương trình.

Gọi API không tính phí. Chỉ trừ số dư khi mua gói dịch vụ trong dashboard.