API Documentation

xproxy Residential IP Proxy API — OpenAPI 3.0

Base URL: https://xproxy.xlab.nzVersion: v1Auth: Bearer JWT / API Key

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

GET/api/v1/nodesList available proxy nodesBearer token

Query available nodes filtered by country, city, IP type, tags, and quality grade.

ParameterTypeDescription
countrystringISO 3166-1 alpha-2 country code (e.g. US, DE)
citystringCity name filter
ip_typestringresidential | hosting | mobile
provider_typestringExit mechanism filter
pageintegerPage number (default 1)
page_sizeintegerResults per page (default 20)
GET/api/v1/nodes/bestGet the best available nodeBearer token

Returns the highest-scoring node for the requested country / IP type.

ParameterTypeDescription
countrystringISO 3166-1 alpha-2 country code
ip_typestringresidential | hosting | mobile
POST/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.

ParameterTypeDescription
api_keystringYour 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

Python
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}")
Node.js
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);
Go
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)
}
Java
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

CodeMeaning
401Invalid or missing API credentials
403Insufficient permissions or IP not whitelisted
429Rate limit exceeded
402Insufficient balance or quota exhausted
503No available nodes matching criteria