Proxy API dokümantasyonu: REST API ile proxy listesi alma

API ile neler yapabilirim?

Proxy kullanan programın doğrudan güncel listeyi almasını istediğinizde API kullanın. Crawler her başladığında listeyi alabilir veya yeni bir plan satın alındığında/süresi bittiğinde sunucu otomatik olarak listeyi değiştirebilir. Dashboard'dan indirilen liste ile API'den alınan liste aynı veridir.

API salt okunurdur. Bakiye kontrolü, plan listesi, proxy listesi sorgulama desteklenir, ödeme ve satın alma işlemleri dashboard'dan yapılır. Tüm yanıtlar UTF-8'dir ve tarihler ISO 8601 UTC formatındadır.

API anahtarı nasıl oluşturulur ve gönderilir?

Kontrol panelindeki API anahtarı ekranında bir anahtar oluşturun. Anahtar spx_ ile başlayan 44 karakterdir ve sadece oluşturulduğu anda görüntülenir. Sunucuda sadece anahtarın parmak izi (hash) saklanır, kaybederseniz yeni bir anahtar oluşturabilirsiniz. Yeni bir anahtar oluşturulduğunda eski anahtar hemen kullanılamaz hale gelir.

Her istekte Authorization başlığına Bearer yöntemi ile anahtarınızı ekleyin. Adres sorgusuna anahtar ekleme yöntemini kabul etmiyoruz. Anahtar yoksa veya yanlışsa 401 unauthorized yanıtı alırsınız.

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

Bakiye ve hesap bilgilerini sorgulama: GET /account

Hesap kodu, bakiye, aktif plan ve proxy sayısını döndürür. Bakiye 2 ondalık basamağa kadar gösterilir (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"
}

Fiyatlandırma listesi sorgulama: GET /plans

Satın alınan planları en yeni olandan başlayarak listeler. status: active (kullanımda), expired (süresi dolmuş), canceled (iptal edilmiş). id: plan kodu (P- ile başlar), /proxies'de plan değeri olarak kullanılabilir.

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

Proxy listesi sorgulama: GET /proxies

Kullanımda olan planın proxy'lerini JSON olarak döndürür. Her proxy için adres, HTTP portu, SOCKS5 portu, kullanıcı adı, şifre, ülke, şehir, plan kodu ve son kullanma tarihi bulunur.

country (iki harfli ülke kodu, örn: us) ve plan (plan kodu) ile filtreleyebilirsiniz. protocol değeri yanıtta görüntülenir, JSON'da her iki port da bulunur.

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

Liste indirme: GET /proxies/download

Programınızın doğrudan okuyabilmesi için her satırda bir proxy bilgisi döndürülür. protocol socks5 ise SOCKS5 portu, http ise HTTP portu eklenir. format=url seçeneği protocol'e uygun adres ön ekini (socks5:// veya http://) ekler.

İzin verilen IP kimlik doğrulaması açık olan sunucularda ip:port formatında kullanıcı adı olmadan doğrudan bağlanabilirsiniz. CSV ilk satırda sütun adlarını içerir ve her iki portu da barındırır.

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

Kod örnekleri: Python, Node.js, PHP

Aşağıdaki örnek, listeyi alıp ilk proxy üzerinden istek gönderir. Python'da SOCKS5 kullanmak için requests[socks] paketi gerekir ve socks5h kullanırsanız, alan adı çözümlemesi de proxy tarafında yapılır.

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";

Hata kodları ve çağrı limitleri

Hatalar HTTP durum kodu ile birlikte { "error": { "code", "message" } } formatında döndürülür. Her anahtar için dakikada 300 çağrı yapılabilir, aşıldığında 1 dakika boyunca 429 yanıtı verilir. Liste yalnızca satın alma veya süre sonunda değiştiği için birkaç dakikada bir alıp program içinde tekrar kullanmanızı öneririz.

API çağrıları ücretlendirilmez. Bakiye sadece dashboard'dan plan satın alırken düşer.