Proxy setup and API documentation.

# HTTP (CONNECT) on port 7000, SOCKS5 on port 7001; same username and password
http://<username>:<password>@gw.portproof.org:7000
socks5h://<username>:<password>@gw.portproof.org:7001

# <username> = USERNAME-<pool>-<country>[-sid-<name>][-carrier-<name>][-rot-<mode>][-ttl-<seconds>]
#   lower case, hyphen separated, no hyphen inside a value
# USERNAME and the password (pak_••••) are in the dashboard under Proxies, and in GET /v1/traffic

USERNAME-mbl-us-rot-auto10                  # mobile 4G/5G, United States, new exit every 10 minutes
USERNAME-peer-es-rot-ondemand               # residential, Spain, new exit on every connection
USERNAME-any-fr-rot-auto60                  # whichever pool answers in France, hourly
USERNAME-mbl-gb-sid-cart7-rot-sticky        # sticky session "cart7": the same device while it is online
USERNAME-mbl-pl-carrier-<name>-rot-auto5    # prefer one carrier in Poland (a preference; we publish no carrier list yet)

# your exit address, as the destination sees it
curl -x "http://USERNAME-mbl-us-rot-auto10:$PROXY_PASSWORD@gw.portproof.org:7000" https://api.portproof.org/v1/echo-ip

# SOCKS5 with remote DNS
curl -x "socks5h://USERNAME-peer-es-rot-ondemand:$PROXY_PASSWORD@gw.portproof.org:7001" https://api.portproof.org/v1/echo-ip

# a sticky session: both requests leave through the same device
curl -x "http://USERNAME-mbl-gb-sid-cart7-rot-sticky:$PROXY_PASSWORD@gw.portproof.org:7000" https://api.portproof.org/v1/echo-ip
curl -x "http://USERNAME-mbl-gb-sid-cart7-rot-sticky:$PROXY_PASSWORD@gw.portproof.org:7000" https://api.portproof.org/v1/echo-ip

import os, requests

API = "https://api.portproof.org/v1"
H = {"Authorization": f"Bearer {os.environ['PORTPROOF_API_KEY']}"}

# balance, expiry and credentials (expires_at is null while GB never expire)
t = requests.get(f"{API}/traffic", headers=H, timeout=10).json()
c = t["credentials"]
print(t["gb_left"], "GB left; expires", t["expires_at"] or "never")

# build the username yourself, or let the API validate it for you
username = f"{c['username_base']}-mbl-us-rot-auto10"
proxy = f"http://{username}:{c['password']}@{c['host']}:{c['http_port']}"

r = requests.get("https://api.portproof.org/v1/echo-ip", proxies={"http": proxy, "https": proxy}, timeout=30)
print("exit:", r.json())

import { ProxyAgent, fetch as ufetch } from 'undici';

const API = 'https://api.portproof.org/v1';
const H = { authorization: `Bearer ${process.env.PORTPROOF_API_KEY}`, 'content-type': 'application/json' };

// the API builds and validates the URL: pool, country, rotation, optional session, protocol
const built = await (await fetch(`${API}/traffic/build-url`, {
  method: 'POST',
  headers: H,
  body: JSON.stringify({ pool: 'residential', country: 'ES', rotation: 'ondemand', protocol: 'http' }),
})).json();

// undici's ProxyAgent speaks HTTP CONNECT
const agent = new ProxyAgent(built.url);
console.log(await (await ufetch('https://api.portproof.org/v1/echo-ip', { dispatcher: agent })).json());

import { chromium } from 'playwright';

// one sticky session per browser context: the same device for the whole visit
const session = `run${Date.now().toString(36)}`;
const browser = await chromium.launch();
const context = await browser.newContext({
  proxy: {
    server: 'http://gw.portproof.org:7000',
    username: `USERNAME-mbl-us-sid-${session}-rot-sticky`,
    password: process.env.PROXY_PASSWORD,
  },
  locale: 'en-US',
  timezoneId: 'America/New_York',
});
const page = await context.newPage();
await page.goto('https://api.portproof.org/v1/echo-ip');
console.log(await page.textContent('body'));
await browser.close();

# Cloud browsers and scrapers take the same three values: server, username, password
{ "proxy": { "server": "http://gw.portproof.org:7000",
             "username": "USERNAME-peer-us-rot-ondemand",
             "password": "pak_••••" } }

# Scrapy settings.py
HTTPPROXY_ENABLED = True
# then per request: meta={"proxy": "http://USERNAME-peer-us-rot-ondemand:PASSWORD@gw.portproof.org:7000"}

# balance, expiry, credentials and limits
curl https://api.portproof.org/v1/traffic -H "Authorization: Bearer $PORTPROOF_API_KEY"
# -> { "gb_total": 25, "gb_used": 3.2, "gb_left": 21.8, "expires_at": null, "enabled": true,
#      "credentials": { "host": "gw.portproof.org", "http_port": 7000, "socks_port": 7001, "username_base": "...", "password": "pak_••••" },
#      "limits": { ... } }

# countries with devices online now, per pool (cached 60 s)
curl https://api.portproof.org/v1/traffic/countries -H "Authorization: Bearer $PORTPROOF_API_KEY"

# build and validate a proxy URL with snippets
curl -X POST https://api.portproof.org/v1/traffic/build-url -H "Authorization: Bearer $PORTPROOF_API_KEY" -H "Content-Type: application/json" \
  -d '{"pool":"mobile","country":"US","rotation":"sticky","session":"cart7","protocol":"http"}'

# test a connection from our side: whether it works, the exit IP and the latency (6 per minute)
# it does not confirm the exit country: look the IP up in the geolocation database your target uses
curl -X POST https://api.portproof.org/v1/traffic/test -H "Authorization: Bearer $PORTPROOF_API_KEY" -H "Content-Type: application/json" \
  -d '{"pool":"mobile","country":"US","rotation":"auto10"}'

# new password (the old one keeps working for about 30 seconds)
curl -X POST https://api.portproof.org/v1/traffic/regenerate -H "Authorization: Bearer $PORTPROOF_API_KEY" -H "Idempotency-Key: $(uuidgen)"

# buy whole GB from your account balance (key scope ports:write). accept_terms: true is required, as at checkout:
# it records that you accept the terms and the acceptable-use policy and ask for the service to start at once.
# The same Idempotency-Key with the same body replays the same order; a refused purchase stays under its key for 24 h,
# so after fixing the cause (for example a top-up) send a new key.
curl -X POST https://api.portproof.org/v1/traffic/buy -H "Authorization: Bearer $PORTPROOF_API_KEY" -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" -d '{"gb":25,"accept_terms":true}'

# prices: the per-GB ladder
curl https://api.portproof.org/v1/pricing

// verify Portproof-Signature: t=<unix>,v1=<hex hmac-sha256(secret, t + "." + body)>
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(secret, header, rawBody) {
  if (typeof header !== 'string') return false;
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300 || typeof parts.v1 !== 'string') return false;
  const expected = Buffer.from(createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex'));
  const received = Buffer.from(parts.v1);
  return received.length === expected.length && timingSafeEqual(received, expected);
}
// traffic events: usage.80pct, usage.cap_reached (once per purchase cycle, also sent by email)

// stdio MCP server. buy_traffic needs confirm:true, accept_terms:true and idempotency_key.
// Ask the user to accept the terms, acceptable-use policy and immediate start of service first.
{
  "mcpServers": {
    "portproof": {
      "command": "npx",
      "args": ["-y", "@portproof/mcp"],
      "env": { "PORTPROOF_API_KEY": "pk_...", "PORTPROOF_API_URL": "https://api.portproof.org/v1" }
    }
  }
}
// tools: get_pricing, get_traffic, list_countries, build_proxy_url, test_connection, buy_traffic (account balance), get_status