Documentation

API & Reference

Complete reference for proxy usage, endpoints, and integrations. Everything you need to get started.

Getting Started

01 Register

02 Dashboard

View your usage, generate proxy strings, and monitor real-time stats.

03 Connect

Use any HTTP/SOCKS client. Use the proxy endpoint shown in your dashboard.

Proxy Types

7 proxy types are available. Each type determines how IPs are assigned and rotated.

res — Residential (Rotating): Rotates IP on every request. Best for scraping and general use.
res_sc — Residential (State/City): Target a specific state and city with rotating residential IPs.
resfix — Residential (Long Session): Hold the same IP for longer sessions using long-session tokens.
stc — Static ISP Residential: ISP-grade static IPs that don't rotate. Great for accounts and automation.
stc_sc — Static ISP (State/City): Static ISP IPs targeted to a specific state and city.
mob — Mobile: Real mobile carrier IPs (3G/4G/5G). Highest trust scores.
dc — Datacenter: Fast datacenter IPs. Best for speed-critical tasks.

Use ANY as the country code to get a random location.

Authentication

Every proxy request requires authentication. Your API key is your password. The username determines the proxy type, country, and routing options.

# HTTP / HTTPS proxy
Proxy-Authorization: Basic base64(username:api_key)

# SOCKS5
username = proxy_username    (e.g. res-us)
password = api_key           (e.g. pgw-abc123...)

# SOCKS4 / SOCKS4a
userid = username:api_key    (e.g. res-us:pgw-abc123...)

Username Format

The username controls routing. The password is always your API key.

Basic Country Targeting

{type}-{country}

res-any         # Residential rotating, random country
res-us          # Residential rotating, United States
stc-nl          # Static ISP, Netherlands
mob-uk          # Mobile, United Kingdom
dc-de           # Datacenter, Germany

Sticky Session (same IP for multiple requests)

{type}-{country}-sid-{session_id}

res-us-sid-123456789    # Same IP while session is alive
stc-jp-sid-987654321    # Static sticky session

State / City Targeting

{type}_sc-{country}_{state}_{city}

res_sc-us_california_losangeles     # Residential, LA
stc_sc-us_texas_dallas              # Static ISP, Dallas

Long Session

resfix-{country}-nnid-{token}

resfix-us-nnid-0              # Start a long session
resfix-us-nnid-yourtoken      # Reuse returned token

Code Examples

cURL

# HTTP proxy
curl -x "http://res-us:YOUR_API_KEY@DASHBOARD_PROXY_ENDPOINT" https://httpbin.org/ip

# SOCKS5
curl -x "socks5://res-us:YOUR_API_KEY@DASHBOARD_PROXY_ENDPOINT" https://httpbin.org/ip

# Sticky session
curl -x "http://res-us-sid-123456789:YOUR_API_KEY@DASHBOARD_PROXY_ENDPOINT" https://httpbin.org/ip

Python (requests)

import requests

API_KEY = "pgw-your-api-key"
PROXY_ENDPOINT = "your-endpoint-from-dashboard"

proxies = {
    "http": f"http://res-us:{API_KEY}@{PROXY_ENDPOINT}",
    "https": f"http://res-us:{API_KEY}@{PROXY_ENDPOINT}",
}
r = requests.get("https://httpbin.org/ip", proxies=proxies)
print(r.json())

Node.js (fetch)

import { ProxyAgent } from "undici";

const agent = new ProxyAgent(`http://res-us:${API_KEY}@${PROXY_ENDPOINT}`);
const res = await fetch("https://httpbin.org/ip", { dispatcher: agent });
console.log(await res.json());

Error Codes

Code	Meaning	Action
200	OK	Request succeeded.
400	Bad Request	Malformed request.
403	Forbidden	Target restricted, or data limit exhausted.
407	Proxy Auth Required	Missing or wrong credentials (API key).
429	Too Many Requests	Rate limit hit. Slow down.
502	Bad Gateway	Upstream failed. Retry.

Best Practices

Match country to the target

Most anti-bot systems weight source country heavily. Use the country picker to align exit country with target audience; this single change often halves your block rate.

Use sticky sessions for logged-in flows

Anything that requires session continuity (cookies, OAuth flows) should use res-{country}-sid-{N}. Use a fresh random N per logical session.

Don't hammer one IP

Even with sticky sessions, sending 1000 requests/second from one residential IP gets you blacklisted on the target. Spread load across many session IDs.

Backoff on 502 / 504, not on 403

Upstream errors are transient — exponential backoff with jitter typically recovers quickly. 403 means policy denial or out of data; retrying won't change the outcome.