API Documentation
xproxy Residential IP Proxy API — OpenAPI 3.0
Authentication
There are two credentials, and they are used in different places. The API key authenticates the proxy itself (and the self-service portal endpoint below); a bearer token from your console login authenticates the management API.
# Management API — log in, then send the token as a bearer header
TOKEN=$(curl -s -X POST https://xproxy.xlab.nz/api/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"..."}' | jq -r .access_token)
curl -H "Authorization: Bearer $TOKEN" https://xproxy.xlab.nz/api/v1/b2b/account
# Self-service portal — the one endpoint that takes the API key directly
curl -X POST https://xproxy.xlab.nz/api/v1/b2b/portal \
-H 'Content-Type: application/json' \
-d '{"api_key":"<API_KEY>"}'Endpoints
/api/v1/nodesList available proxy nodesBearer tokenQuery available nodes filtered by country, city, IP type, tags, and quality grade.
| Parameter | Type | Description |
|---|---|---|
country | string | ISO 3166-1 alpha-2 country code (e.g. US, DE) |
city | string | City name filter |
ip_type | string | residential | hosting | mobile |
provider_type | string | Exit mechanism filter |
page | integer | Page number (default 1) |
page_size | integer | Results per page (default 20) |
/api/v1/nodes/bestGet the best available nodeBearer tokenReturns the highest-scoring node for the requested country / IP type.
| Parameter | Type | Description |
|---|---|---|
country | string | ISO 3166-1 alpha-2 country code |
ip_type | string | residential | hosting | mobile |
/api/v1/b2b/portalEnterprise self-service portal dataAPI key (in body)Authenticate with your API key and return your account's customer profile, API keys, sessions and usage.
| Parameter | Type | Description |
|---|---|---|
api_key | string | Your API key (request body JSON field) |
Proxy Connection
Connect through the relay with your API key. The credential layout is fixed: username = your API key, password = session-<id> to pin a sticky exit (leave it empty to use the key default).
# SOCKS5(<relay-host>:<port> = 开通账户时提供给你的接入地址) # 用 socks5h 让 DNS 在出口解析——用 socks5 会在本地解析,泄露目标且破坏地理匹配。 curl -x "socks5h://<API_KEY>:@<relay-host>:1080" https://api.ipify.org # 固定出口(同一 session-<id> 复用同一出口 IP) curl -x "socks5h://<API_KEY>:session-task1@<relay-host>:1080" https://api.ipify.org # HTTP/HTTPS 正向代理(同一凭据布局;HTTPS 目标走 CONNECT 隧道,代理看不到内容) curl -x "http://<API_KEY>:session-task1@<relay-host>:8888" https://api.ipify.org
SOCKS5 与 HTTP/HTTPS 正向代理两种入口都已开放,凭据布局相同(用户名 = API Key,密码 = 可选的session-<id>)。具体接入地址与端口以控制台「接入信息」为准; 无凭据或凭据错误时 HTTP 入口返回 407,余额耗尽返回 402。
SDK Quick Start
from proxysdk import ProxyClient
client = ProxyClient(api_key="your-api-key", base_url="https://your-domain")
# List US residential nodes
nodes = client.list_nodes(country="US", ip_type="residential")
# Or let the server pick the best one
best = client.get_best_node(country="US", ip_type="residential")
# Build a proxy URL — relay host/port are supplied when your account is opened
proxy_url = client.get_proxy_url("<relay-host>", 1080, session_id="task1")
print(f"Proxy: {proxy_url}")import { ProxyClient } from 'proxy-sdk';
const client = new ProxyClient({ apiKey: 'your-api-key', baseUrl: 'https://your-domain' });
// List German nodes
const nodes = await client.listNodes({ country: 'DE', ipType: 'residential' });
// Build a proxy URL — relay host/port are supplied when your account is opened
const proxyUrl = client.getProxyUrl('<relay-host>', 1080, { sessionId: 'task1' });
console.log('Proxy:', proxyUrl);package main
import (
"context"
"fmt"
proxysdk "github.com/your-org/proxy-sdk-go"
)
func main() {
client := proxysdk.NewClient("your-api-key", "https://your-domain")
nodes, _ := client.ListNodes(context.Background(), "US", "residential", 10)
fmt.Println("nodes:", len(nodes))
best, _ := client.GetBestNode(context.Background(), "US", "residential")
fmt.Println("best:", best.ID)
}import proxysdk.ProxyClient;
var client = new ProxyClient("your-api-key", "https://your-domain");
// List nodes (raw JSON)
var nodes = client.listNodes("US", "residential", 10);
// Build a proxy URL — relay host/port are supplied when your account is opened
System.out.println("Proxy: " + client.getProxyUrl("<relay-host>", 1080, "socks5h", "task1"));Rate Limits & Errors
Rate Limits
- API requests: 100 req/min per API Key (configurable per plan)
- Session creation: 50 req/min per API Key
- Concurrent sessions: varies by plan (default 100)
Error Codes
| Code | Meaning |
|---|---|
401 | Invalid or missing API credentials |
403 | Insufficient permissions or IP not whitelisted |
429 | Rate limit exceeded |
402 | Insufficient balance or quota exhausted |
503 | No available nodes matching criteria |