ProxyWarden API Docs — Proxy Intelligence API

Authentication

Every request must include your API key in the X-API-Key header. Get your key from the Dashboard → API Keys.

💡 Keep your API key secret — it's tied to your credits balance.

Request header

X-API-Key: pw_your_key_here

Example with curl

      
curl -s -X POST https://proxywarden.com/api/check \
  -H "X-API-Key: pw_your_key" \
  -H "Content-Type: application/json" \
  -d '{"proxy":"1.2.3.4:8080"}'
    

Base URL

https://proxywarden.com/api

✅ All endpoints use HTTPS. HTTP requests are automatically redirected.

Error Codes

HTTP Code	detail	Meaning
401	invalid_api_key	Key missing or wrong
400	invalid_proxy_format	Proxy string malformed
403	insufficient_credits	Not enough credits
403	plan_does_not_include_intelligence	Upgrade needed for /intel
403	banned	Account suspended
500	internal_error	Server error — try again

Credits & Plans

Each API call costs credits. Credits never expire.

Endpoint	Cost per proxy	Notes
/check	1 credit	Basic connectivity + latency + country
/check/intel	2 credits	Full intelligence: anonymity, fraud score, geo, DNSBL
/check/bulk	1 × N	Concurrent, up to plan limit per call
/check/bulk-intel	2 × N	Concurrent intelligence, Pro+ only

Plans

Trial

50 credits
5 proxies/call
Basic only

Starter

2,500 cr
25/call
Basic+Intel

Standard ⭐

10,000 cr
100/call
Basic+Intel

Pro

30,000 cr
500/call
All endpoints

Reseller

100,000 cr
2000/call
All endpoints

Supported Proxy Formats

All proxy formats are normalized automatically — you can mix formats in bulk requests.

# Basic host:port
1.2.3.4:8080

# With scheme
http://1.2.3.4:8080
socks5://1.2.3.4:1080
socks4://1.2.3.4:1080

# With authentication
user:pass@1.2.3.4:8080
http://user:pass@1.2.3.4:8080
    

Protocols

Protocol	Auto-detected	Notes
HTTP	✅ Yes	Default when no scheme provided
HTTPS	✅ Yes	Via CONNECT tunnel
SOCKS5	✅ Yes	socks5:// prefix
SOCKS4	✅ Yes	socks4:// prefix

POST /check — Basic Check

Check a single proxy. Returns alive status, latency, external IP and detected protocol. Costs 1 credit.

Request body

Field	Type	Required	Description
proxy	string	required	Proxy string in any supported format

Example request

      
POST /api/check
X-API-Key: pw_your_key
Content-Type: application/json

{
  "proxy": "1.2.3.4:8080"
}
    

✅ Alive response

{
  "proxy":      "http://1.2.3.4:8080",
  "alive":      true,
  "latency_ms": 342,
  "out_ip":     "1.2.3.4",
  "protocol":   "HTTP",
  "error":      null
}
        

❌ Dead response

{
  "proxy":      "http://1.2.3.4:8080",
  "alive":      false,
  "latency_ms": 10004,
  "out_ip":     null,
  "protocol":   "HTTP",
  "error":      "timeout"
}
        

curl

Python

Node.js

PHP

      
curl -s -X POST https://proxywarden.com/api/check \
  -H "X-API-Key: pw_your_key" \
  -H "Content-Type: application/json" \
  -d '{"proxy":"1.2.3.4:8080"}'
    

      
import requests

response = requests.post(
    "https://proxywarden.com/api/check",
    headers={"X-API-Key": "pw_your_key"},
    json={"proxy": "1.2.3.4:8080"}
)
data = response.json()
print(data["alive"], data["latency_ms"])
    

      
const res = await fetch("https://proxywarden.com/api/check", {
  method: "POST",
  headers: {
    "X-API-Key": "pw_your_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ proxy: "1.2.3.4:8080" })
});
const data = await res.json();
console.log(data.alive, data.latency_ms);
    

      
$response = file_get_contents('https://proxywarden.com/api/check', false,
  stream_context_create(['http' => [
    'method'  => 'POST',
    'header'  => "X-API-Key: pw_your_key\r\nContent-Type: application/json",
    'content' => json_encode(['proxy' => '1.2.3.4:8080'])
  ]])
);
$data = json_decode($response, true);
    

POST /check/intel — Intelligence Check

Full proxy intelligence: anonymity level, fraud score, geo data, DNSBL blacklist check, IPQS scoring. Costs 2 credits. Available on Starter plan and above.

⚠️ Requires Starter plan or above. Trial accounts get 403 plan_does_not_include_intelligence.

Request body

Field	Type	Required	Description
proxy	string	required	Proxy string in any supported format

Response (alive)

{
  "proxy":       "http://1.2.3.4:8080",
  "alive":       true,
  "latency_ms":  342,
  "out_ip":      "1.2.3.4",
  "protocol":    "HTTP",
  "error":       null,
  "anonymity":   "elite",       // elite | anonymous | transparent | unknown
  "trust_score": 87,             // 0-100, higher = safer
  "verdict":     "CLEAN",        // CLEAN | OK | SUSPICIOUS | BAD | DEAD
  "geo": {
    "country_code": "DE",
    "country_name": "Germany",
    "city":         "Frankfurt",
    "org":          "AS24940 Hetzner Online GmbH",
    "latitude":     50.1109,
    "longitude":    8.6821
  },
  "dnsbl": {
    "listed":   false,
    "lists":    [],
    "checked": 12
  },
  "ipqs": {
    "fraud_score":    8,
    "vpn":            false,
    "proxy":          true,
    "tor":            false,
    "bot_status":     false
  },
  "credits_used": 2
}
    

Anonymity levels

Value	Meaning
elite	No headers reveal proxy use — your real IP is hidden
anonymous	Hides real IP but reveals proxy usage
transparent	Passes your real IP — no protection
unknown	Could not determine

POST /check/bulk — Bulk Basic Check

Check multiple proxies concurrently in a single request. All proxies are checked in parallel — fast. Costs 1 credit per proxy.

Request body

Field	Type	Required	Description
proxies	string[]	required	Array of proxy strings (max depends on plan)

Limits by plan

Plan	Max proxies per call
Trial	5
Starter	25
Standard	100
Pro	500
Reseller	2,000

Example request

POST /api/check/bulk

{
  "proxies": [
    "1.2.3.4:8080",
    "socks5://5.6.7.8:1080",
    "user:pass@9.10.11.12:3128"
  ]
}
    

Response

{
  "results": [
    { "proxy": "http://1.2.3.4:8080", "alive": true,  "latency_ms": 312, "out_ip": "1.2.3.4" },
    { "proxy": "socks5://5.6.7.8:1080",         "alive": false, "latency_ms": 10004, "error": "timeout" },
    { "proxy": "http://9.10.11.12:3128",         "alive": true,  "latency_ms": 589,  "out_ip": "9.10.11.12" }
  ],
  "total":       3,
  "alive_count": 2,
  "dead_count":  1,
  "credits_used":3
}
    

POST /check/bulk-intel — Bulk Intelligence Check

Same as bulk, but runs full intelligence analysis on each proxy. Costs 2 credits per proxy. Available on Pro and Reseller plans.

⚠️ Requires Pro or Reseller plan.

Request body

Field	Type	Required	Description
proxies	string[]	required	Array of proxy strings

GET /check/history — Check History

Returns the last 50 proxy checks for your account. No credits consumed.

Example request

curl https://proxywarden.com/api/check/history \
  -H "X-API-Key: pw_your_key"
    

Response

[
  {
    "proxy":      "http://1.2.3.4:8080",
    "alive":      true,
    "latency_ms": 342,
    "out_ip":     "1.2.3.4",
    "checked_at": "2026-04-25T14:32:11Z"
  },
  ...
]
    

GET /health — Health Check

No auth required. Returns API status. Use for uptime monitoring.

curl https://proxywarden.com/api/health
// → {"status":"ok","version":"1.0"}
    

Ready to integrate?