프록시 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

구매한 요금제를 최근 것부터 돌려줘요. status는 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은 protocol에 맞는 주소 앞머리(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회까지 호출할 수 있고, 넘으면 1분 동안 429로 답해요. 목록은 구매나 만료 때만 바뀌므로 몇 분에 한 번 받아 두고 프로그램 안에서 다시 쓰는 방식을 권해요.

API 호출에는 요금이 들지 않아요. 잔액에서 빠지는 것은 대시보드에서 요금제를 살 때뿐이에요.

상태	code	뜻
401	unauthorized	키가 없거나 틀림, 새 키를 만들었다면 새 키로
400	bad_format	format 값이 목록에 없음
404	not_found	없는 경로
429	rate_limited	분당 300회를 넘음