# Proxies.sx - Master Skill File

> **Rotation cookbook** (copy-paste IP rotation in curl/python/node + the footguns that trip LLMs): https://agents.proxies.sx/pool/rotation-cookbook.md

> Complete infrastructure reference for AI agents. One file, everything you need.
>
> **WHAT:** A metered mobile + residential proxy network driven over a REST API. **The standard path is an account API key + deposited GB**: mint a `psx_` key, deposit GB, and every proxy byte is metered against that balance. **x402 (USDC on-chain) is the optional alternative** for wallet-only agents that cannot hold an account. The core product is the **Pool Gateway**: one credential over a **massive peer device network** (residential + mobile IPs across 150+ countries and scaling toward millions of devices), backed by production 4G/5G carrier modems in 6 countries. One credential reaches every country; you pay only for bytes actually delivered.
> **WHY:** $4.00/GB (volume-discounted to $2.40/GB at 250 GB+). Duration free. x402 minimum purchase 0.1 GB ($0.40), settlement ~2s (Base) / ~400ms (Solana).
> **FIRST ACTION (buy - standard, recommended):** create an account + API key at https://client.proxies.sx (or `POST /v1/api-keys` with your login JWT), deposit GB, set a proxy password (`PATCH /v1/account/proxy-password`), then `GET /v1/gateway/credentials` returns ready proxy URLs for `gw.proxies.sx:7000` (HTTP) / `:7001` (SOCKS5). Full walkthrough: the **"Buy & Use With an API Key"** section below. Prefer the peer network for breadth (`pool=peer`) or the production modems for guaranteed carrier IPs (`pool=mbl`, 6 countries).
> **FIRST ACTION (buy - wallet-only x402 alternative):** an unpaid `GET /v1/x402/pool` (**Pool Gateway**) returns the 402 payment catalog; pay USDC and retry. `GET /v1/x402/proxy` mints a single **dedicated port** when you need a pinned host:port, SOCKS5, or a public rotate URL. Pricing: `curl -s "https://api.proxies.sx/v1/x402/pool/pricing"`.
> **FIRST ACTION (earn):** `POST https://api.proxies.sx/v1/peer/agents/register` - returns deviceId, JWT, relay URL, and the live `earningsPerGB` rates.
> **Precedence:** the per-product skill files ([/pool/skill.md](https://agents.proxies.sx/pool/skill.md), [/marketplace/skill.md](https://agents.proxies.sx/marketplace/skill.md), [/peer/skill.md](https://agents.proxies.sx/peer/skill.md), [/build/skill.md](https://agents.proxies.sx/build/skill.md)) carry the deep per-product contract. If any document disagrees with the live API, the live API wins.
>
> **Check health before you depend on it:** `GET https://api.proxies.sx/v1/x402/status` returns live per-component status (`api`, `x402`, `relay`, `gateway`), 24h/7d/30d uptime, and recent incidents as JSON. Read it before routing production-critical traffic, and treat a `degraded`/`outage` `overall` as a signal to retry or fall back. Human-readable version: [/status/](https://agents.proxies.sx/status/).

## Contents

1. What Is Proxies.sx - the network + the products
2. Two Products: Pool Gateway (recommended) vs Dedicated Port - the table + decision guide (read this first)
3. Quick Reference - every URL in one table
4. **Buy & Use With an API Key (standard path) - account, deposited GB, gateway credentials [RECOMMENDED, start here]**
5. Optional: x402 Payment Protocol (USDC, account-less) - 402 body shape, networks, pricing
6. Optional: Buy a Dedicated Port with x402 - one pinned modem with its own host:port
7. Optional: x402 Pool Gateway Access - buy metered pool access with USDC
8. Pool Gateway - Direct Usage - username DSL, rotation, error codes (both auth paths)
9. All x402 Endpoints - discovery / purchase / manage / lookup
10. MCP Server - install, config, tool catalog
11. Peer Network - the flagship supply: register, connect, self-test, earn, withdraw
12. Build & Resell - pak keys and reseller REST endpoints
13. SDK & Packages / Live Domains / Social

## What Is Proxies.sx

A metered mobile + residential proxy network for AI agents, driven over a REST API. The standard path is an account API key (`X-API-Key: psx_...`) + deposited GB; x402 USDC on-chain is the optional wallet-only alternative. Two supply networks feed one gateway:

- **Peer network (the flagship).** Residential and mobile IPs from a device fleet spanning **150+ countries** and scaling toward millions of devices - this is the main network and the primary source of coverage and traffic. The gateway probes every peer and routes around dead ones, and you are metered per delivered byte, so broken peers cost you nothing.
- **Carrier modems (`mbl`, supportive tier).** Production 4G/5G ProxySmart modems we operate end-to-end in 6 countries (US, GB, PL, FR, NL, GE) - 10-15 Mbps, sub-1s TTFB, ~100% success. Smaller by design; the guaranteed-quality tier for when you need a real carrier IP.

The **Pool Gateway** is the recommended product: one credential routes over both networks, retargeted per request in the proxy username. **Countries are live data** - read `/v1/x402/countries` (modems) and `/v1/gateway/pool/stock` (full network) for the current set; do not treat any list here as fixed.

Three ways to participate:

- **BUY proxies** - Standard path: account API key + deposited GB. $4/GB (to $2.40/GB at 250 GB+), driven over REST (`X-API-Key`) or the MCP server, every byte metered against your balance - see **"Buy & Use With an API Key"** below. Optional alternative: pay with USDC on-chain (Base or Solana) via x402, no account, no API key - for wallet-only agents. On either path the primary product is **Pool Gateway Access** (one credential that reaches every country - `peer` for 150+-country breadth, `mbl` for guaranteed carrier modems), and a **Dedicated Port** (one pinned modem with its own host:port and SOCKS5) is the specialized option for held-IP / SOCKS5 / rotate-URL needs. See the comparison right below.
- **EARN USDC** - Share bandwidth as a peer. Per-GB rates by IP type (mobile > residential > datacenter), set by the platform and returned live in the `earningsPerGB` field of the registration response - never hardcode these numbers, they change with demand. Same rates apply to AI agents, Android SDK devices, and ProxySmart farmers - a real mobile carrier IP earns the mobile tier regardless of how it joined.
- **BUILD & RESELL** - Embed mobile/residential proxies into your own app. Mint per-customer `pak_*` keys, build branded reseller storefronts, integrate via SDK (npm) or REST API (any language). See [/build/](https://agents.proxies.sx/build/) and the open-source [proxy-reseller-kit](https://github.com/bolivian-peru/proxy-reseller-kit) toolkit (formerly `pool-starter` - that name now redirects).

---

## Two Products: Pool Gateway (recommended) vs Dedicated Port

<!-- CANONICAL: Pool Gateway vs Dedicated Port (x402) - code-verified 2026-07 -->

**Pool Gateway (recommended, the primary product) = one credential on gw.proxies.sx:7000 over the whole network - every country in the tier, with country, session and rotation declared per-request in the proxy username. Dedicated Port = one real port on one modem, its own host:port, one country fixed at purchase, the IP held until YOU hit the rotate URL - the specialized choice when you need SOCKS5, a public rotate URL, or a single pinned host.**

| | Pool Gateway - recommended | Dedicated Port |
|---|---|---|
| **How to buy** | **Standard:** account API key + deposited GB (credential = your `psx_` username + proxy password, or a reseller `pak_`). **Optional:** x402 USDC via `/v1/x402/pool` | **Standard:** account API key + deposited GB via `POST /v1/ports`. **Optional:** x402 USDC via `/v1/x402/proxy` |
| **What an x402 payment mints** | A metered `pak_` credential; no device touched - modem/peer picked live per connection, over the whole 150+-country network | A real port on ONE modem (ProxySmart), bound to that device |
| **Endpoint** | Shared `gw.proxies.sx:7000` for everyone; routing lives in the username | Unique `serverIp:port` per purchase |
| **Country** | Edit the country slot in the username per request - same credential, no repurchase; the full peer network reaches 150+ countries | Fixed at purchase. Change = recreate the port (only with 0 active ports left) |
| **Rotation** | `-rot-` token only: `auto5/10/20/60` re-pick an endpoint on interval, `sticky`/`hard` pin it. No rotate URL; no mode gives per-request IP change | True carrier-IP reset via public `/v1/rotate/<token>` URL (5-min cooldown). Auto-rotation scheduling (5-1440 min) requires an account/API key - not available wallet-only |
| **SOCKS5** | **Yes for every credential shape** - account, reseller, and x402-minted all work on `:7001`, metered identically to HTTP `:7000` (fixed 2026-07-25) | Yes - working `socks5://` URL included |
| **Concurrency** | Parallel sessions on different endpoints via distinct `-sid-` values; capped at 250 sessions / 500 connections per account | One modem. Fan-out = buy more ports |
| **Payment rails (x402 option)** | Solana and Base on-chain only - facilitator rail rejected | Solana, Base, AND facilitator signed intents (EIP-3009) |
| **Failure recovery** | Automatic - dead peers/modems are routed around on the next pick, and you are metered so failures cost nothing; `/manage/pool/regenerate` rotates the secret | `/manage/ports/replace` (free, max 3, new device) or `/ports/recreate` |

**IP caveats (both products):** mobile carriers re-NAT egress IPs on their own cadence - a dedicated port holds a MODEM you control the rotation of, not a fixed IP; pool `-rot-sticky` pins the MODEM for the session, never the IP. Pool sessions need a `-sid-<id>` token to stick across connections (`-session-` is silently ignored).

### PICK POOL GATEWAY WHEN (the default for most agents)

- Country coverage: the peer network reaches 150+ countries; retarget `us → gb → pl → fr → ...` in the username per request from one credential, no repurchase.
- High fan-out: hundreds of parallel sticky sessions (distinct `-sid-` values land on different endpoints) through one credential.
- A fleet of agents shares one secret, one top-up, one credit meter - instead of N ports with N passwords.
- Zero babysitting: default `auto10` rotates every 10 min with no API calls, dead peers/modems are routed around automatically, and you are metered so failures never cost you.

### PICK DEDICATED PORT WHEN

- You need on-demand true carrier-IP resets via the public rotate URL - the pool cannot do this at all (pool rotation only re-picks an endpoint, it never resets a carrier IP).
- Cookie-bound / login / 2FA work where you want one held modem whose IP changes only when you trigger it - no selector re-picks under you.
- You must hard-pin a city or carrier at purchase, or you pay via facilitator signed intents (EIP-3009) - only this product accepts either.

**Same for both:** $4.00/GB (to $2.40/GB at 250 GB+), duration free - you only pay for delivered traffic, on either auth path. Standard: deposited GB on your account is the budget, everything driven with `X-API-Key`. Optional accountless x402 flow (HTTP 402 → pay USDC on Base ~2s or Solana ~400ms → retry with `Payment-Signature`, 0.1 GB / $0.40 minimum), same replay protection, same `x402s_` session token for management. The difference is topology, not price: the Pool Gateway spans the whole network (peer 150+ countries + the 6-country carrier modems), while a Dedicated Port is one carrier modem in one of those 6 countries.

---

## Quick Reference

| What | URL |
|------|-----|
| **Agents Landing** | https://agents.proxies.sx |
| Peer Network | https://agents.proxies.sx/peer/ |
| Buy a Proxy (dedicated port) | https://agents.proxies.sx/marketplace/proxy/ |
| **Pool Gateway Access** | https://agents.proxies.sx/pool/ |
| Pool Gateway Skill (detailed) | https://agents.proxies.sx/pool/skill.md |
| Dedicated Port Skill (detailed) | https://agents.proxies.sx/marketplace/skill.md |
| **Build & Resell (toolkit)** | https://agents.proxies.sx/build/ |
| This Skill File | https://agents.proxies.sx/skill.md |
| Peer Skill (detailed) | https://agents.proxies.sx/peer/skill.md |
| Build Skill (Anthropic format, AI agents) | https://agents.proxies.sx/build/skill.md |
| Go Peer SDK (fleet deploy guide) | https://agents.proxies.sx/peer/go/ |
| Windows Peer SDK (fleet deploy guide) | https://agents.proxies.sx/peer/windows/ |
| Live Uptime & Incident Status | https://agents.proxies.sx/status/ |
| Interactive System Map | https://agents.proxies.sx/system-map/ |
| Peer Network Thesis | https://agents.proxies.sx/thesis/ |
| LLMs.txt | https://agents.proxies.sx/llms.txt |
| Ecosystem Reference | https://agents.proxies.sx/sx-token/ecosystem.md |
| docs-manifest.json (truth) | https://agents.proxies.sx/docs-manifest.json |
| x402 Discovery | https://agents.proxies.sx/.well-known/x402.json |
| Agent Card (A2A) | https://agents.proxies.sx/.well-known/agent-card.json |
| ERC-8004 Registration | https://agents.proxies.sx/.well-known/erc8004-registration.json |
| Live Pricing (standard, API key) | https://api.proxies.sx/v1/billing/pricing |
| Live Pool Stock (no auth, counts only) | https://api.proxies.sx/v1/gateway/pool/stock |
| Live x402 Stats | https://api.proxies.sx/v1/x402/info |
| Live Pricing (x402 dedicated port) | https://api.proxies.sx/v1/x402/pricing |
| Live Pricing (x402 Pool Gateway) | https://api.proxies.sx/v1/x402/pool/pricing |
| Live Service Status | https://api.proxies.sx/v1/x402/status |
| Relay Server | wss://relay.proxies.sx (also wss://relay-us.proxies.sx for US/LATAM) |
| Gateway Pool | gw.proxies.sx:7000 (HTTP) / 7001 (SOCKS5) |
| Customer Dashboard | https://client.proxies.sx |
| **API Docs (Pool Gateway Swagger, public)** | https://api.proxies.sx/docs/gateway |
| API Docs (Reseller OpenAPI JSON, public) | https://api.proxies.sx/v1/reseller/docs/openapi |
| API Docs (full customer Swagger - basic-auth gated, NOT public) | https://api.proxies.sx/docs/api |
| MCP Server (proxy) | `npx -y @proxies-sx/mcp-server` |

---

## Buy & Use With an API Key (Standard Path)

**This is the main way to buy and use Proxies.sx.** Create an account, mint a `psx_` API key, deposit GB, and drive everything over REST with `X-API-Key` (or via the MCP server). Deposited GB is the budget: nothing is charged when you fetch credentials or spawn proxy URL strings - bytes are metered as they flow through the gateway. The x402 sections further down are the optional wallet-only alternative.

```
1. Sign up / sign in   POST /v1/login/signup → POST /v1/login/signin → JWT accessToken
2. Mint an API key     POST /v1/api-keys  (JWT-only step - a key cannot mint keys)
3. Fund + buy GB       top up balance (dashboard: card / hosted crypto checkout), then
                       POST /v1/billing/purchase-traffic {"amount": <GB>}
4. Proxy password      PATCH /v1/account/proxy-password  (REQUIRED - the gateway does
                       NOT fall back to your account login password)
5. Credentials         GET /v1/gateway/credentials → username psx_<id> + ready proxy URLs
6. Connect             gw.proxies.sx:7000 (HTTP) / :7001 (SOCKS5) - metered per byte
```

### Mint the key (one-time JWT step)

```bash
# Sign in → JWT
curl -s -X POST https://api.proxies.sx/v1/login/signin \
  -H 'Content-Type: application/json' \
  -d '{"email":"agent@example.com","password":"YOUR_PASSWORD"}'
# → { "accessToken": "eyJ..." }

# Mint the key (returned ONCE - save it). Or create it in the dashboard: client.proxies.sx
curl -s -X POST https://api.proxies.sx/v1/api-keys \
  -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
  -d '{"name":"agent","scopes":["ports:read","ports:write","ports:rotate","billing:read","account:read","account:write","traffic:read"]}'
# → { "apiKey": "psx_<32 hex>", "keyInfo": { ... } }
```

Every later call authenticates with `-H "X-API-Key: psx_..."` (or `Authorization: ApiKey psx_...`). Keys are scoped, per-key rate-limited (default 100 req/min), max 5 active per account.

### Deposit GB

```bash
# Preview - $4.00/GB base, volume discounts 10% @25GB / 20% @50GB / 30% @100GB / 40% @250GB
curl -s 'https://api.proxies.sx/v1/billing/calculate-price?amount=50' -H "X-API-Key: psx_YOUR_KEY"
# → { "pricePerGB": 3.20, "totalPrice": 160, "discountPercent": 20, ... }

# Convert balance → GB (JWT session on customer accounts - see note below)
curl -s -X POST https://api.proxies.sx/v1/billing/purchase-traffic \
  -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
  -d '{"amount": 50}'
```

Balance top-ups (card / hosted crypto checkout) and the GB conversion are dashboard/JWT operations on customer accounts - a customer API key cannot carry the `billing:write` scope (purchases are deliberately not key-automatable for customers; reseller and admin keys can automate them). Everything else in this section is fully API-key drivable. If the balance cannot cover the price, the purchase fails with `Insufficient balance`.

### Set the gateway credential

```bash
# REQUIRED once - the gateway never accepts your account login password
curl -s -X PATCH https://api.proxies.sx/v1/account/proxy-password \
  -H "X-API-Key: psx_YOUR_KEY" -H 'Content-Type: application/json' \
  -d '{"proxyPassword":"myProxyPass123"}'
# → { "proxyUsername": "psx_<userId>", ... }

# Ready-to-use connection strings any time
curl -s https://api.proxies.sx/v1/gateway/credentials -H "X-API-Key: psx_YOUR_KEY"
# → { "username": "psx_...", "httpProxy": "http://psx_...:PASS@gw.proxies.sx:7000",
#     "socks5Proxy": "socks5://psx_...:PASS@gw.proxies.sx:7001" }
```

### Generate Proxy Strings + Connect (Pool Gateway "spawn")

```bash
# Check live stock first (no auth) - counts per pool/country, never IPs
curl -s https://api.proxies.sx/v1/gateway/pool/stock

# Optional helper: generate N ready proxy URL strings in one call (no charge -
# spawn is pure string construction; metering happens per byte at connect time)
curl -s -X POST https://api.proxies.sx/v1/gateway/pool/spawn \
  -H "X-API-Key: psx_YOUR_KEY" -H 'Content-Type: application/json' \
  -d '{"count":10,"country":"us","pool":"mbl","rotation":"sticky","sessionType":"unique","sessionPrefix":"batch"}'
# → { "proxies": ["http://psx_<uid>-mbl-us-sid-batch1-rot-sticky:<PROXY_PASSWORD>@gw.proxies.sx:7000", ...] }
# Substitute <PROXY_PASSWORD> with the proxy password you set above (it is never echoed).

# Use it - the account credential works on HTTP :7000 AND SOCKS5 :7001
curl -x "http://psx_USER_ID-peer-us-sid-bot01-rot-sticky:myProxyPass123@gw.proxies.sx:7000" https://api.ipify.org
curl -x "socks5://psx_USER_ID-mbl-gb:myProxyPass123@gw.proxies.sx:7001" https://api.ipify.org
```

Full username DSL (pool / country / `-sid-` / rotation / carrier / asn tokens), error codes, and the stickiness sharp edges: the "Pool Gateway - Direct Usage" section below and [/pool/skill.md](https://agents.proxies.sx/pool/skill.md).

### Dedicated port on the same balance

```bash
# One pinned modem with its own host:port + SOCKS5 (needs ports:write)
curl -s -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_YOUR_KEY" -H 'Content-Type: application/json' \
  -d '{"countryId":"<mongoId from GET /v1/countries/with-devices>","expiresAt":86400}'
# countryId discovery: GET /v1/countries/with-devices (authenticated, scope ports:read)
# → { "serverIp", "httpPort", "socksPort", "proxyLogin", "proxyPassword", ... }

# Rotate it (needs ports:rotate)
curl -s -X POST https://api.proxies.sx/v1/ports/PORT_ID/rotate -H "X-API-Key: psx_YOUR_KEY"
```

Auto-rotation scheduling (5-1440 min intervals via the rotation-settings endpoint) exists only on this account path - the wallet-only x402 port cannot schedule rotations. Full dedicated-port catalog: [/marketplace/skill.md](https://agents.proxies.sx/marketplace/skill.md).

### Monitor

| Call | Returns |
|---|---|
| `GET /v1/account/summary` | balance + slots + trafficGB total / used / available + alerts |
| `GET /v1/account/usage?period=30d` | per-port traffic breakdown (`7d` / `30d` / `90d`) |
| `GET /v1/gateway/pool/my-stats` | your pool GB in/out, active connections, pool health |
| `GET /v1/gateway/pool/my-sessions` | live sessions (sessionKey, country, currentIp, bytes, TTL) |
| `DELETE /v1/gateway/pool/my-sessions[/:sessionKey]` | close one / all of your sessions |

When deposited GB runs out, the gateway rejects connects with `Insufficient traffic. Please purchase more shared traffic.` - buy more GB (step 3) and the same credential resumes.

### MCP shortcut (same path, tool-shaped)

```bash
PROXIES_API_KEY=psx_YOUR_KEY npx -y @proxies-sx/mcp-server
```

The MCP server's API-key mode drives this exact path (it sends `X-API-Key` under the hood) - 61 account tools incl. `purchase_shared_traffic`, `create_port`, `pool_get_stock`, `get_account_summary`. See the MCP section below.

---

## Optional: x402 Payment Protocol (USDC, account-less)

**Everything from here through "All x402 Endpoints" is the optional wallet-only alternative** for agents that cannot hold an account - the API-key standard path above is the recommended way in. HTTP 402 Payment Required for machine-to-machine USDC payments.

### Flow

The same 402 flow drives both products - the example below uses the Dedicated Port endpoint (`/v1/x402/proxy`); the Pool Gateway product uses `/v1/x402/pool` (see its section below).

```
1. Request without payment    GET /v1/x402/proxy?country=US&traffic=1
2. Receive 402 response       x402Version 1 body with accepts[] payment options (example below)
3. Send USDC on-chain         Base (~2s settlement) or Solana (~400ms)
4. Retry with payment proof   Header: Payment-Signature: <tx_hash>
5. Receive proxy credentials  nested: proxy{http,socks5,server,httpPort,socksPort,username,password}, rotationUrl, management{sessionToken}
```

### 402 Response Body (live shape)

An unpaid request returns HTTP 402 with an `x402Version: 1` JSON body. Each `accepts[]` entry is one payment option (one per network). Trimmed live example for `GET /v1/x402/proxy?country=US&traffic=0.1`:

```json
{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "400000",
      "resource": "https://api.proxies.sx/v1/x402/proxy?country=US&traffic=0.1",
      "payTo": "0xF8cD900794245fc36CBE65be9afc23CDF5103042",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "maxTimeoutSeconds": 30
    },
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "400000",
      "payTo": "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ]
}
```

How to read it:

- `maxAmountRequired` is micro-USDC (6 decimals): `"400000"` = $0.40 for 0.1 GB; 1 GB would be `"4000000"` = $4.00.
- Send exactly that amount of USDC to `payTo` on your chosen network. `asset` is the USDC token contract.
- Retry the identical request with `Payment-Signature: <tx_hash>`.
- The full live body also carries `outputSchema` (input params + response shape) and an `extra` block (available countries, pricing, limits) per entry.

**Save the `sessionToken` from step 5!** Format: `x402s_...`
You need it for all session management calls (check status, replace ports, top up, etc.).
Without it, manage/* endpoints return HTTP 400.

**Payment-succeeded-but-provisioning-failed is never silent.** If your USDC payment verifies but the proxy port fails to provision on the backend (rare, infra hiccup), the API still returns HTTP 200 with a `sessionToken` and a `recover` object pointing at a recreate endpoint - it never eats your payment with a bare 500. Check for a `recover.recreateEndpoint` field in the response and call it if `ports` comes back empty.

### Payment Networks

| Network | Settlement | Gas | Recipient |
|---------|-----------|-----|-----------|
| Base (EVM) | ~2 sec | ~$0.01 | `0xF8cD900794245fc36CBE65be9afc23CDF5103042` |
| Solana | ~400ms | ~$0.0001 | `6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv` |

USDC contracts:
- Base: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Solana: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`

### Pricing

| Type | Price/GB | Min Purchase |
|------|----------|-------------|
| Shared | $4.00 | 0.1 GB ($0.40) |

**Shared tier only.** The x402 dedicated-port product is shared-only - the backend hardcodes `tier: 'shared'` on every `/v1/x402/proxy` request and ignores any `tier=private` you pass. There is no way to buy a private-tier proxy via x402.

Duration is always FREE - you only pay for traffic.

---

## Optional: Buy a Dedicated Port With x402 (Quick Start)

This is the wallet-only purchase of the **Dedicated Port** product (`/v1/x402/proxy`) - one real port on one modem, its own host:port (see the Two Products comparison above; for the x402 Pool Gateway purchase see the next section). Account holders get the same class of port on deposited GB via `POST /v1/ports` - see the standard-path section above.

```bash
# 1. Request proxy (get 402 with payment info). Quote the URL - the & would
#    otherwise background the command in a shell.
curl -s "https://api.proxies.sx/v1/x402/proxy?country=US&traffic=1"

# 2. Send USDC to the recipient address, then retry with tx hash
curl -s "https://api.proxies.sx/v1/x402/proxy?country=US&traffic=1" \
  -H "Payment-Signature: YOUR_TX_HASH"

# Response (nested): proxy{ http, socks5, server, httpPort, socksPort, username, password, expiresAt },
#                    rotationUrl, sessionId, portId, traffic{...}, management{ sessionToken }

# 3. Use the proxy - proxy.http is a ready-to-use connection string
curl -x http://USERNAME:PASSWORD@SERVER:HTTP_PORT https://api.ipify.org

# 4. Check session
curl -s https://api.proxies.sx/v1/x402/manage/session \
  -H "X-Session-Token: x402s_YOUR_TOKEN"

# 5. Replace offline port (free, max 3 per session)
curl -s -X POST https://api.proxies.sx/v1/x402/manage/ports/replace \
  -H "X-Session-Token: x402s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"country":"US"}'

# 6. Top up session with more traffic
curl -s -X POST https://api.proxies.sx/v1/x402/manage/session/topup \
  -H "X-Session-Token: x402s_YOUR_TOKEN" \
  -H "Payment-Signature: NEW_TX_HASH" \
  -H "Content-Type: application/json" \
  -d '{"addTrafficGB":2,"addDurationSeconds":86400}'

# 7. Rotate IP
curl -s https://api.proxies.sx/v1/rotate/YOUR_ROTATION_TOKEN
```

**Duration-only top-ups are free.** If you only pass `addDurationSeconds` (no `addTrafficGB`), the cost is $0 and on-chain verification is skipped - but the `Payment-Signature` header itself is still required (the endpoint returns 400 without it). Send any placeholder value:

```bash
# Duration-only top-up: free, but the header must still be present
curl -s -X POST https://api.proxies.sx/v1/x402/manage/session/topup \
  -H "X-Session-Token: x402s_YOUR_TOKEN" \
  -H "Payment-Signature: duration-only" \
  -H "Content-Type: application/json" \
  -d '{"addDurationSeconds":86400}'
```

Only traffic top-ups require a real on-chain payment.

---

## Optional: x402 Pool Gateway Access - Buy Metered Pool Access With USDC

This is the wallet-only purchase of Pool Gateway access (account holders: use the standard-path section above instead - same gateway, deposited GB, no crypto needed). It is a **separate product** from the **Dedicated Port** flow above (see the "Two Products: Dedicated Port vs Pool Gateway" comparison near the top). Instead of one modem tied to one session, one USDC payment mints a credential that works across **every country in your tier**, retargeted purely via the proxy username - no repurchase per country. Full detail: [/pool/skill.md](https://agents.proxies.sx/pool/skill.md).

**How it works under the hood:** your payment mints a GB-capped pool access key (`pak_*`) under a one-time house reseller account. The GB cap on the key IS your USDC credit envelope - the gateway meters every byte through the normal pool-billing pipeline and auto-suspends the key when the cap is hit. Top up with more USDC to keep going. This reuses the same metering/audit/auto-suspend machinery as reseller-minted pak keys - there is no separate billing system to learn.

```bash
# No payment -> 402 catalog
curl -s "https://api.proxies.sx/v1/x402/pool?tier=mbl&country=us&traffic=1"

# Pay USDC, retry with tx hash -> credentials + sessionToken
curl -s "https://api.proxies.sx/v1/x402/pool?tier=mbl&country=us&traffic=1" \
  -H "Payment-Signature: YOUR_TX_HASH"

# Use it - one credential, no repurchase. The purchased username looks like
# HOUSE_USER-mbl-us-sid-mybot01-rot-sticky - the country is the 3rd
# hyphen-separated slot (full username DSL: https://agents.proxies.sx/pool/skill.md)
curl -x "http://HOUSE_USER-mbl-us-sid-mybot01-rot-sticky:pak_YOUR_KEY@gw.proxies.sx:7000" https://api.ipify.org
# Same credential - retarget by EDITING the country slot (us -> gb here).
# Do NOT append a country code to the end of the username: a trailing token
# is silently ignored and you stay in the original country. Pick a country
# with live mbl stock (GET https://api.proxies.sx/v1/gateway/pool/stock).
curl -x "http://HOUSE_USER-mbl-gb-sid-mybot01-rot-sticky:pak_YOUR_KEY@gw.proxies.sx:7000" https://api.ipify.org

# Check remaining GB credit
curl -s https://api.proxies.sx/v1/x402/manage/pool/credit -H "X-Session-Token: x402s_YOUR_TOKEN"

# Top up with more USDC
curl -s -X POST https://api.proxies.sx/v1/x402/manage/pool/topup \
  -H "X-Session-Token: x402s_YOUR_TOKEN" \
  -H "Payment-Signature: NEW_TX_HASH" \
  -H "Content-Type: application/json" \
  -d '{"addTrafficGB":5}'

# Per-day usage series
curl -s https://api.proxies.sx/v1/x402/manage/pool/usage -H "X-Session-Token: x402s_YOUR_TOKEN"

# Rotate the pak secret without losing the username (compromise recovery)
curl -s -X POST https://api.proxies.sx/v1/x402/manage/pool/regenerate -H "X-Session-Token: x402s_YOUR_TOKEN"

# Re-fetch credentials if lost
curl -s https://api.proxies.sx/v1/x402/manage/pool/connection -H "X-Session-Token: x402s_YOUR_TOKEN"
```

### x402 Pool Gateway Endpoints

| Method | Path | Auth | Description |
|--------|------|------|--------------|
| GET | `/v1/x402/pool/pricing` | None | Tier catalog, networks, username DSL - always works, no payment needed |
| GET/POST | `/v1/x402/pool` | Payment | No payment -> 402 catalog; pay USDC -> credentials + sessionToken |
| GET | `/v1/x402/manage/pool/credit` | `X-Session-Token` | Real, pak-backed remaining GB (read-through) |
| POST | `/v1/x402/manage/pool/topup` | Token + Payment | More USDC -> more GB (replay-guarded, same rules as dedicated-port top-up) |
| GET | `/v1/x402/manage/pool/usage` | `X-Session-Token` | Per-day MB series |
| POST | `/v1/x402/manage/pool/regenerate` | `X-Session-Token` | New pak secret, same username |
| GET | `/v1/x402/manage/pool/connection` | `X-Session-Token` | Re-emit credentials (recovery) |

### v1 scope - `mbl` tier only

| Tier | Status | What it is |
|------|--------|------------|
| `mbl` | **LIVE (v1, default)** | Production tier - modems we operate end-to-end. Real 4G/5G carriers, 6 countries, 10-15 Mbps, sub-1s TTFB, ~100% success |
| `peer` | **LIVE - purchasable at $4/GB** | The flagship residential network, ~82 countries. Request `tier=peer` for the widest coverage; metered so you pay only for delivered bytes |
| `peer_mobile` | Disabled (returns 400) | Reserved for a future mobile-peer split, off pending gateway ipType enforcement. Use `peer` or `mbl` |

Both `mbl` (6-country carrier modems) and `peer` (the flagship residential network - verify the live country count at `GET /v1/gateway/pool/stock`) are purchasable via `/v1/x402/pool` at $4/GB - the tier you buy is the tier you get. The x402-minted Pool Gateway credential works on both HTTP `:7000` and SOCKS5 `:7001`, metered identically (fixed 2026-07-25). Duration is free (default 30 days, max 90); only traffic is billed, at $4/GB (volume-discounted to $2.40/GB at 250 GB+), minimum purchase 0.1 GB.

---

## Pool Gateway - Direct Usage (username DSL, rotation, error codes)

The Pool Gateway is a long-lived HTTP / SOCKS5 proxy endpoint. It
authenticates with a `psx_*` proxy username + proxy password (the
standard account path above), or a `pak_*` pool-access-key
(reseller-minted, or minted via the optional x402 flow). The username
DSL below is identical for every auth path.

```bash
# Basic curl through HTTPS pool (mbl = production-grade ProxySmart modems)
curl -x "http://psx_USER_ID-mbl-us:PROXY_PASSWORD@gw.proxies.sx:7000" \
  https://api.ipify.org

# Sticky session - pin to one modem for this session.
# Gateway smart-picks the most IP-stable modem available in the country.
# Carrier CGNAT may still rotate the egress IP; for the most stable IP use
# the residential peer pool (home-ISP IPs hold for hours-to-days) or a
# dedicated modem on a static-IP carrier plan.
curl -x "http://psx_USER_ID-mbl-us-sid-bot01-rot-sticky:PROXY_PASSWORD@gw.proxies.sx:7000" \
  https://api.ipify.org

# SOCKS5 - works with psx_ account credentials, reseller-minted pak_ keys,
# and x402-minted credentials alike. Metered identically to HTTP :7000.
curl -x "socks5://psx_USER_ID-mbl-gb:PROXY_PASSWORD@gw.proxies.sx:7001" \
  https://api.ipify.org

# Pool-access-key (reseller-distributed OR x402-minted credential).
# IMPORTANT: the pak_ secret goes in the PASSWORD field, not the username -
# the gateway matches auth by checking whether the password starts with "pak_".
curl -x "http://YOUR_ACCOUNT-mbl-pl:pak_YOUR_KEY@gw.proxies.sx:7000" https://api.ipify.org
```

### Which pool? (read this once)

| Pool token | Use when | Notes |
|---|---|---|
| `peer` | **Default for coverage and scale.** The flagship network - residential + mobile IPs across 150+ countries, scaling toward millions of devices | The gateway probes every peer and routes around dead ones, and you are metered per delivered byte, so broken peers cost you nothing and healthy peers serve normally. This is where most traffic runs |
| `mbl` | **Guaranteed carrier quality in 6 countries.** 10-15 Mbps, sub-1s TTFB, ~100% success | ProxySmart 4G/5G modems we operate end-to-end (US, GB, PL, FR, NL, GE). The supportive tier for when you need a specific carrier IP |
| `any` / `best` | When either network is acceptable | Health-weighted blend across both |

Resellers wanting strict quality on a peer-pool customer pak: set
`qualityTier: 'safe'` when minting - the gateway silently rewrites
`peer-*` -> `mbl-*` for that key. This is exactly the same mechanism the
x402 pool product (above) uses in v1.

### Username tokens

| Token | Example | Meaning |
|---|---|---|
| pool | `-mbl-` / `-peer-` / `-any-` | Which pool |
| country | `-us-` / `-pl-` / `-any-` | ISO 3166-1 alpha-2 |
| city | `-city-newyork` | Soft preference |
| carrier | `-carrier-tmobile` | Soft preference |
| isp | `-isp-spectrum` | Hard filter (residential) |
| asn | `-asn-12345` | Hard filter (exact ASN) |
| sid | `-sid-mybot01` | Session id, `[a-z0-9_]`. **Use 8-64 chars.** At the raw gateway the self-healing parser accepts any 1-64 char value, but the x402 **pool purchase** path requires 8-64 and **silently replaces a shorter sid with a random one** (so your intended stickiness is lost). Staying in 8-64 makes the buy path and the gateway path agree. Same `sid` returns to the same modem. **Required for `sticky`/`auto*` to persist across connections** (see sharp edges below) |
| rot | `-rot-sticky` / `-rot-auto5` / `-rot-auto10` / `-rot-auto20` / `-rot-auto60` / `-rot-ondemand` / `-rot-hard` | Rotation mode (default `auto10`). `sticky`/`hard` pin the same modem (gateway smart-picks the most IP-stable one); `auto*` swaps modems every N min; `ondemand` re-picks on a new connection. **`hard` pins like `sticky`** - it does NOT give a new IP per request; a true carrier-IP reset only happens via the explicit `/rotate` action |
| failover | `-failover-samecarrier` | When primary endpoint dies (also `any`, `samecountry` [default], `samenode`, `strict`) |
| ttl | `-ttl-7200` | Session-row TTL in seconds (60-2,592,000, default 3600). This is a session-record lifetime, not an IP-stability guarantee |
| pin | `-pin-device-modem001` | Pins to a specific port or device id (takes the next two username parts) |

> **Three stickiness sharp edges:**
>
> 1. **Stickiness needs a `-sid-`.** Without one, every connection starts a fresh synthetic `auto_<ts>_<rand>` session (5-min TTL) - so `-rot-sticky` alone won't keep you on the same modem across connections. Always pass `-sid-<name>` (8-64 chars `[a-z0-9_]`) when you want a connection to stick.
> 2. **Sticky pins the MODEM, not the IP.** Mobile carriers (T-Mobile especially) can still re-NAT the egress IP every few seconds even while the modem connection stays up. For a held IP across a workflow, use a **dedicated modem** (one customer per port) with a static-IP carrier plan, or the residential `peer` pool (home-ISP IPs are stable for hours-to-days).
> 3. **`-session-` is not a token.** Unknown tokens are silently skipped - the token is `sid`, not `session`; using the wrong name routes you with zero stickiness.

### Error codes (when curl shows non-200)

Every failure body is `CODE: message (req: <uuid>)`. The req id is for
support tickets - quote it.

| Code | Status | Meaning | What to do |
|---|---|---|---|
| `E_AUTH_REQUIRED` | 407 | No Proxy-Authorization header | Add credentials |
| `E_BALANCE_EXHAUSTED` | 407 | Password valid, no traffic left - add GB (distinct code so you can branch) | Top up |
| `E_AUTH_INVALID` | 407 | Bad credentials / disabled key - failMsg surfaces backend reason | Check pak + balance |
| `E_CAP_EXCEEDED` | 407 | This `pak_*` key hit its GB cap (distinct machine code so you can branch) | Top up the key (`POST /v1/x402/manage/pool/topup` or `POST /v1/reseller/pool-keys/:keyId/topup`) or raise the cap, then retry |
| `E_USERNAME_PARSE` | 400 | Missing or >256-char username (the account id is the real auth gate - optional tokens self-heal instead of 400ing) | Check your account id is present |
| `E_RATE_LIMITED_AUTH` | 429 | Too many failed auth attempts (per-IP 10/min->30s ban, 30/min->5min; per-account 25/min->30s, 60/min->5min) | Back off 30s (escalates to 5min) |
| `E_RATE_LIMITED_CONN` | 429 | Too many concurrent connections (default 500 max per account) | Lower parallelism |
| `E_NO_STOCK_COUNTRY` | 502 | No online endpoints for pool+country | failMsg suggests an alternative - try it or retry in 60s |
| `E_STOCK_DEGRADED` | 502 | Selected endpoint became unavailable | Retry - selector picks a different one |
| `E_SESSION_LIMIT` | 429 | Too many concurrent sessions (default 250 max per account; reseller accounts are often raised further) | Recycle `-sid-` tokens or wait for TTL |
| `E_SSRF_BLOCKED` | 403 | Target is private/cloud-metadata/localhost | Use a public target |
| `E_INTERNAL` | 503 | Unexpected | File a ticket with the req id |

That's **11 of the 14 codes defined** in the gateway's error-code table (`gateway/src/metrics/error-codes.ts`) that actually surface to customers today. Three remain reserved for future categorization and are NOT reachable yet (`E_BALANCE_EXHAUSTED`, `E_ACCOUNT_DISABLED`, `E_UPSTREAM_REFUSED`) - those failure modes currently surface as `E_AUTH_INVALID` with the specific reason in `failMsg`. Do not build branch logic on the 3 reserved codes; they will not appear in a live response.

Authoritative version in
[docs-manifest.json](https://agents.proxies.sx/docs-manifest.json)
under `pool_gateway.error_codes`.

**Support:** maya@proxies.sx or https://t.me/proxies_sx - always quote the `req:` id from the error body.

### What can make your connection drop mid-stream (peer pool)

The relay enforces defenses against broken peer SDKs:

1. **Open watchdog (5s)** - if the peer doesn't pump bytes within 5s of CONNECT 200, tunnel dies
2. **Stall watchdog (30s)** - if a tunnel goes 30s idle in either direction while still open, dies
3. **Backpressure 8MB** - if your downlink is slow and bytes pile in Node's buffer >=8MB, tunnel dies
4. **Data-plane circuit breaker** - if a peer accepts the tunnel but repeatedly drops bytes mid-stream (a known broken-SDK pattern), the gateway auto-pauses that peer for 5 minutes after 3 such failures in 2 minutes, independent of any probe

These all manifest as connection-reset / TLS handshake failure on your
side. Retry and the selector picks a healthy peer - and because you are
metered per delivered byte, a dropped tunnel costs you nothing. For a
workload that cannot tolerate any mid-stream drop, the `mbl` modems don't
have these failure modes.

---

## All x402 Endpoints

### Discovery (no auth)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/x402/pricing` | Dedicated-port pricing tiers and structure |
| GET | `/v1/x402/countries` | Available countries with device counts |
| GET | `/v1/x402/calculate` | Calculate cost for given params |
| GET | `/v1/x402/health` | Service health status |
| GET | `/v1/x402/info` | Master info (pricing, countries, MCP) |
| GET | `/v1/x402/.well-known` | Protocol discovery |
| GET | `/v1/x402/pool/pricing` | Pool Gateway tier catalog, networks, DSL (see section above) |

### Proxy Purchase (x402 payment)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/x402/proxy` | Purchase Dedicated Port (dedicated mobile proxy) |
| POST | `/v1/x402/proxy` | Purchase Dedicated Port (POST) |
| GET/POST | `/v1/x402/pool` | Purchase Pool Gateway Access (see section above) |

### Session Management (X-Session-Token header required)

**IMPORTANT:** These endpoints require a session token (`X-Session-Token: x402s_...`).
You get this token in the response when you purchase a proxy via `/v1/x402/proxy`.
Calling these endpoints without a valid session token returns HTTP 400.

**Correct order:**
1. Purchase proxy -> receive `sessionToken` in response (format: `x402s_abc123...`)
2. Use that token in `X-Session-Token` header for all manage/* calls below

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/x402/manage/session` | Session details via token |
| GET | `/v1/x402/manage/session/credit` | Check remaining credit |
| GET | `/v1/x402/manage/ports` | List all ports in session |
| GET | `/v1/x402/manage/ports/:portId/status` | Port status |
| POST | `/v1/x402/manage/ports/replace` | Replace offline port (free, max 3) |
| POST | `/v1/x402/manage/ports/recreate` | Recreate deleted port with remaining credit |
| GET | `/v1/x402/manage/session/topup/calculate` | Preview top-up cost |
| POST | `/v1/x402/manage/session/topup` | Pay to extend session (Payment-Signature header always required - real tx hash for traffic, any placeholder for free duration-only) |
| GET | `/v1/x402/manage/pool/credit` | Pool Gateway: remaining GB credit |
| POST | `/v1/x402/manage/pool/topup` | Pool Gateway: pay for more GB |
| GET | `/v1/x402/manage/pool/usage` | Pool Gateway: per-day usage series |
| POST | `/v1/x402/manage/pool/regenerate` | Pool Gateway: rotate pak secret |
| GET | `/v1/x402/manage/pool/connection` | Pool Gateway: re-emit credentials |

**Port Replacement Rules:**
- Port must be offline/broken (online ports rejected)
- Max 3 free replacements per session (tracked via session.replacementCount)
- New port created on a **different device** to avoid the same failure
- Session traffic and duration preserved, not reset
- Rate limited: 5 requests/min

**Session Top-Up Rules:**
- Duration-only top-ups are FREE ($0 cost, on-chain verification skipped) - but the Payment-Signature header must still be present; send any placeholder value (e.g. `duration-only`)
- Traffic pricing: $4/GB (same as initial purchase)
- 2% payment tolerance on blockchain verification
- Replay prevention: txHash checked against session.txHash + session.topupTxHashes[]
- All active port expirations extended automatically on top-up
- Rate limited: 5 requests/min

**Port Recreation Rules:**
- Free if session has remaining credit (check via /manage/session/credit)
- Minimum 5 minutes session duration remaining required
- Can optionally change country on recreation
- Original session traffic allocation preserved

### Session Lookup (no auth)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/x402/session/:id` | Session by ID |
| GET | `/v1/x402/session/tx/:txHash` | Session by transaction hash |
| GET | `/v1/x402/sessions/wallet/:wallet` | Sessions by wallet address |

### Agent Registry

| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/x402/agents` | Register new agent |
| GET | `/v1/x402/agents/:wallet` | Get agent by wallet |

### Public

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/rotate/:token` | Rotate IP via public token (no auth). Dedicated Port only - the Pool Gateway credential has no rotate URL (its only rotation lever is the `-rot-` username token) |

---

## MCP Server

`@proxies-sx/mcp-server` - **89 tools in the published npm package** (latest published version `2.4.1`, verified live). Proxy management via Model Context Protocol: 70 API-key tools (incl. ops + pool groups) + 19 wallet-only x402 tools (incl. the x402 pool-purchase group - buy Pool Gateway access with USDC, no account).

> **Version note:** `2.4.1` on npm IS the current source - `npx -y @proxies-sx/mcp-server` installs all 89 tools, including the `pool` group (credentials, proxy-password, pak_ minting/management), the `ops` admin group, and the wallet-side `x402 pool` group (buy Pool Gateway access with USDC, no account). The tool count has not changed since 2.3.0 - 2.4.0 and 2.4.1 were an `ipType` DSL addition and doc/example correctness passes, not new tools. If you see "55 tools", "72 tools" or "79 tools" in older cached docs, those were earlier published versions. This file always describes the currently-installable package.

### Install

```bash
npx -y @proxies-sx/mcp-server
```

### Claude Desktop Config

API Key mode (standard - account API key):

```json
{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": { "PROXIES_API_KEY": "psx_your_key" }
    }
  }
}
```

x402 mode (optional wallet-only alternative, no account needed):

```json
{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": { "AGENT_WALLET_KEY": "your_private_key", "PREFERRED_NETWORK": "base" }
    }
  }
}
```

### Tool Categories (89 total, published)

| Category | Count | Tools |
|----------|-------|-------|
| Account | 2 | get_account_summary, get_account_usage |
| Port Mgmt | 7 | list_ports, get_port, create_port, delete_port, update_port_credentials, update_os_fingerprint, reconfigure_port |
| Port Status | 4 | get_port_status, get_port_ip, ping_port, speed_test_port |
| Rotation | 5 | rotate_port, check_rotation_availability, configure_auto_rotation, get_rotation_history, get_rotation_token_url |
| Billing | 3 | get_pricing, calculate_price, purchase_shared_traffic |
| Crypto Pay | 5 | create_crypto_payment, check_crypto_payment_status, get_pending_crypto_payments, cancel_crypto_payment, get_crypto_payment_info |
| Support | 5 | create_support_ticket, list_my_tickets, get_ticket, reply_to_ticket, close_ticket |
| x402 Session | 8 | get_x402_session, list_x402_ports, get_x402_port_status, get_sessions_by_wallet, get_session_status, replace_x402_port, calculate_x402_topup, topup_x402_session |
| x402 Auto | 11 | x402_get_proxy, x402_get_pricing, x402_wallet_balance, x402_rotate_ip, x402_extend_session, x402_list_sessions, x402_check_session, x402_list_countries, x402_list_cities, x402_list_carriers, x402_service_status |
| Reference | 1 | list_available_countries |
| Utilities | 3 | get_proxy_connection_string, get_all_proxy_formats, get_os_fingerprint_options |
| Pool Gateway (key mgmt needs reseller role) | 16 | pool_get_stock, pool_build_proxy_url, pool_list_sessions, pool_close_session, pool_get_my_credentials, pool_get_my_stats, pool_set_proxy_password, pool_mint_key, pool_list_keys, pool_update_key, pool_topup_key, pool_regenerate_key, pool_reveal_key, pool_delete_key, pool_key_usage, pool_key_audit |
| Ops (admin-scoped keys only) | 11 | ops_get_user, ops_get_user_audit, ops_reconcile_payments, ops_list_tickets, ops_reply_ticket, ops_set_slots, ops_credit_balance, ops_email_user, ops_list_farmers, ops_get_farmer, ops_write_farmer_note |
| x402 Pool (wallet-only) | 8 | x402_get_pool_access, x402_pool_credit, x402_pool_topup, x402_pool_regenerate, x402_pool_connection, x402_pool_usage, x402_pool_pricing, get_pool_stock |

### Tool Details

The server self-describes: connect and call `tools/list` for the authoritative name, description, and input schema of every tool. Per-tool prose lives there and in the [source repo](https://github.com/bolivian-peru/proxies-sx-mcp-server), not here. Contract details worth knowing before you call:

- **Rotation:** `rotate_port` has a 5-minute cooldown between rotations (`check_rotation_availability` reports time remaining); `configure_auto_rotation` accepts intervals of 5-1440 minutes; `get_rotation_token_url` returns a public no-auth rotation URL in the form `https://api.proxies.sx/v1/rotate/{token}`.
- **Crypto top-up:** `create_crypto_payment` accepts $10-$1000 and 50+ cryptocurrencies (BTC, ETH, USDT, USDC, LTC, DOGE, SOL, etc.); balance credits automatically on confirmation. `check_crypto_payment_status` returns pending / confirming / paid / expired / cancelled.
- **Pricing:** `get_pricing` / `calculate_price` reflect the $4/GB rate plus volume discounts (10-40% based on the GB amount of each single purchase) and slot-tier progression (driven by cumulative lifetime GB).
- **Shared tier only:** the product line is shared-tier; there is no `purchase_private_traffic` tool in the published package - use `purchase_shared_traffic`.
- **Countries:** `list_available_countries` / `x402_list_countries` return the live set with device counts - the set shifts with supply, so call the tool rather than assuming a fixed list.
- **x402 session tools** mirror the REST manage endpoints: `replace_x402_port` is free (max 3 per session, failed device excluded); `calculate_x402_topup` / `topup_x402_session` follow the same rules as the REST top-up (duration-only free, traffic $4/GB).
- **Timing:** `speed_test_port` takes 10-30 seconds. Support tickets get a human response typically within 24 hours.

---

## Peer Network - Earn USDC

Share your internet bandwidth, get paid in USDC on Solana. This is the **flagship supply network** behind every Pool Gateway sale: it spans 150+ countries and is scaling toward millions of devices, and it is the primary source of the traffic agents buy above. More supply here means more coverage and more revenue for everyone on it.

### How much you earn

Your payout is a revenue share set by Proxies.sx and customized per partner - there is no fixed public percentage; rates are configured by our team, can be tailored to you, and move with demand - net, with no platform fee taken on top. Mobile and residential IPs earn the higher-demand tiers; datacenter is a low-demand base tier.

**Never hardcode a per-GB dollar figure** - read the live value from the `earningsPerGB` field in the response of `POST /v1/peer/agents/register`. That's the ground truth at the moment of registration, for every tier.

### Earnings by IP Type

| IP Type | Demand Tier | Examples |
|---------|-------------|----------|
| **Mobile** | Highest demand | AT&T, Verizon, T-Mobile, Vodafone, O2 |
| **Residential** | Mid | Comcast, Spectrum, Cox, BT, Deutsche Telekom |
| **Datacenter** | Low (base tier) | AWS, GCP, Azure, Hetzner, OVH, DigitalOcean |

**Same rates for everyone:** AI agents, Android SDK devices, and ProxySmart farmers all earn at the same per-tier rates. A real mobile carrier IP earns the mobile tier regardless of how it joined the network.

**IP classification:** Server-side ASN lookup against the curated lists in `src/peer/data/datacenter-asns.ts` and `mobile-carrier-asns.ts`. Device-reported type is ignored - cannot be spoofed.

**Min payout:** $5 USDC for AI agents (custom integrations) | $10 USDC for Android SDK devices.

**Throughput contract:** every register response now also includes a machine-readable `throughputContract` object (`minKBps`, `probeUrl`, `probeIntervalMin`, `notes`) alongside the human-readable `instructions` string - parse the structured fields if your client checks throughput requirements programmatically rather than regexing the prose.

**The core goal:** Get us an HTTP proxy endpoint from a device with a valuable IP. The relay/SDK/Docker methods below are the standard paths, but freestyle methods are welcome. Custom proxy servers, hardware bridges, IoT fleets, mesh networks - if it delivers an HTTP endpoint from a real IP, we want it. Be creative, code your own solution.

### Workflow

```
1. Register     POST /v1/peer/agents/register - get deviceId + JWT (1h) + refreshToken
                Pass apiKey="psx_..." so earnings auto-link to your account
2. Connect      wss://relay.proxies.sx with Sec-WebSocket-Protocol: token.{JWT}
3. Refresh      POST /v1/peer/agents/{id}/refresh - every ~50 min before JWT expires
4. Route        Handle tunnel_connect: open a TCP socket to the target, confirm
                with tunnel_connected, and pump tunnel_data frames both ways.
                REQUIRED to earn - proxy_request/proxy_response alone is a
                legacy path that fails the routing probe (never routable)
5. Self-test    POST /v1/peer/my-devices/{deviceId}/test - verify your tunnel actually
                forwards bytes before you assume you're earning (see below)
6. Earn         Earnings credited per GB. Request payout: min $5 (agents) / $10 (SDK).
```

### Register

```bash
curl -s -X POST https://api.proxies.sx/v1/peer/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name":"my-agent",
    "type":"claude",
    "walletAddress":"YOUR_SOLANA_ADDRESS",
    "apiKey":"psx_YOUR_API_KEY"
  }'

# Response:
# { "deviceId": "agent_abc123", "jwt": "eyJ...", "refreshToken": "a1b2...",
#   "relay": "wss://relay.proxies.sx",
#   "earningsPerGB": { "mobile": <number>, "residential": <number>, "datacenter": <number> },
#   "throughputContract": { "minKBps": 500, "probeUrl": "https://speed.cloudflare.com/__down?bytes=262144",
#                            "probeIntervalMin": 5, "notes": "..." },
#   "instructions": "..." }
#
# Per-GB rates are set by the platform and can change anytime. The earningsPerGB
# field always returns the LIVE rate at the moment of registration for each tier -
# do not hardcode these numbers anywhere in your client. Same rates apply to AI
# agents, Android SDK devices, and ProxySmart farmers.
#
# apiKey is optional but strongly recommended. Without it, devices register
# as orphans and earnings can't be credited to your account.
```

Save both jwt AND refreshToken. JWT expires in 1 hour. Use refresh token to renew.

### Connect to Relay

Connect to the `relay` URL from your register response (geo-assigned to the
nearest region - US/LATAM peers get `wss://relay-us.proxies.sx`). Advertise
`supportsRelayRedirect: true` and handle the `relay_redirect` message so the
server can move you to a closer relay at runtime (full protocol in
[`/peer/skill.md`](/peer/skill.md)).

```javascript
// Minimal Node.js skeleton. The full, production-tested implementation is
// https://agents.proxies.sx/peer/reference-sdk.js - copy it if you can (it
// adds binary tunnel_data frames, multi-WS, reconnects, relay_redirect).
const WebSocket = require('ws');
const net = require('net');

const ws = new WebSocket(register.relay || 'wss://relay.proxies.sx', [`token.${JWT}`]);
const tunnels = new Map(); // sessionId -> TCP socket

ws.on('open', () => {
  ws.send(JSON.stringify({ type: 'device_info', payload: { country: 'US', supportsRelayRedirect: true } }));
  // YOU send the heartbeat, every 30s. The relay only replies with
  // heartbeat_ack - it never pings you. Miss 4 in a row (120s) and the
  // relay force-closes your socket as a zombie.
  setInterval(() => ws.send(JSON.stringify({ type: 'heartbeat', payload: {} })), 30000);
});

ws.on('message', (raw) => {
  const msg = JSON.parse(raw.toString());
  switch (msg.type) {
    case 'tunnel_connect': {  // <-- THE EARNING PATH. Open a raw TCP socket
      const { sessionId, host, port } = msg.payload;   //     (no tls.connect -
      const sock = net.connect(parseInt(port, 10), host); //  TLS is end-to-end)
      sock.on('connect', () => {
        tunnels.set(sessionId, sock);
        ws.send(JSON.stringify({ type: 'tunnel_connected', payload: { sessionId } }));
      });
      sock.on('data', (data) => ws.send(JSON.stringify({    // target -> relay
        type: 'tunnel_data', payload: { sessionId, data: data.toString('base64') }
      })));
      sock.on('close', () => {
        ws.send(JSON.stringify({ type: 'tunnel_closed', payload: { sessionId } }));
        tunnels.delete(sessionId);
      });
      break;
    }
    case 'tunnel_data': {     // relay -> target bytes (JSON+base64 legacy path;
      const sock = tunnels.get(msg.payload.sessionId); // modern SDKs use binary
      if (sock) sock.write(Buffer.from(msg.payload.data, 'base64')); // frames)
      break;
    }
    case 'tunnel_close': {    // relay asks you to close the tunnel
      const sock = tunnels.get(msg.payload.sessionId);
      if (sock) { sock.end(); tunnels.delete(msg.payload.sessionId); }
      break;
    }
    case 'heartbeat_ack':     // relay acknowledged your heartbeat - no action
      break;
  }
});
```

**Do not build on `proxy_request`/`proxy_response` alone.** That JSON path is legacy - a peer that implements only it accepts connections but drops the TLS bytes that follow, fails every routing probe (`tls_dropped_bernard_pattern`), never becomes routable, and never earns. The `tunnel_connect` + `tunnel_data` handling above is the part most custom SDKs miss.

### Self-Test Your Implementation

Before assuming you're earning, verify your tunnel actually forwards bytes end-to-end - the single most common peer failure mode is accepting the CONNECT/proxy_request but silently dropping the TLS bytes that follow (a broken-SDK pattern, tagged server-side as `tls_dropped_bernard_pattern`).

```bash
curl -s -X POST "https://api.proxies.sx/v1/peer/my-devices/${DEVICE_ID}/test" \
  -H "Authorization: Bearer $JWT"

# Response:
# { "passed": true|false,
#   "diagnosis": { "passed": bool, "reasonCode": "...", "summary": "...", "fix": "..." },
#   "summary": "...",
#   "device": { ..., "probeQuality": { ... } } }
```

Rate limited 5/min. Runs a real throughput-only probe batch through your live connection (same mechanism as the server-side routing probe) and returns a pass/fail diagnosis with a specific `reasonCode` and human-readable `fix` string when it fails - use this to debug before filing a ticket. After **3 consecutive probe successes**, a device auto-promotes to routable (eligible to serve real customer traffic), independent of any manual self-test call.

### Check Earnings

```bash
curl -s "https://api.proxies.sx/v1/peer/agents/${DEVICE_ID}/earnings" \
  -H "Authorization: Bearer $JWT"
```

### Request Payout

```bash
curl -s -X POST "https://api.proxies.sx/v1/peer/agents/${DEVICE_ID}/withdraw" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{}'

# Note: payout goes to the wallet you registered with (or set via PUT /wallet).
# The walletAddress body parameter is intentionally ignored to prevent siphoning.
# Wallet changes have a 7-day cooling period before withdrawals work again.
# Min payout: $5 (agents) / $10 (SDK devices). Admin processes in 24-48h.
```

### Peer API Endpoints

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/v1/peer/agents/register` | - | Register as peer (600/min per IP rate limit) |
| POST | `/v1/peer/agents/:id/refresh` | Refresh token | Refresh JWT (expires 1h) |
| GET | `/v1/peer/agents/:id/status` | JWT | Peer status |
| GET | `/v1/peer/agents/:id/earnings` | JWT | Earnings and traffic stats |
| PUT | `/v1/peer/agents/:id/wallet` | JWT | Update wallet (7-day cooling period) |
| POST | `/v1/peer/agents/:id/withdraw` | JWT | Request payout (min $5 agents / $10 SDK; body ignored - uses registered wallet) |
| POST | `/v1/peer/my-devices/:deviceId/test` | JWT or API key | Self-test your implementation - real throughput probe + pass/fail diagnosis (5/min rate limit) |

### WebSocket Message Types

**Outgoing (you send):**
| Type | Description |
|------|-------------|
| `device_info` | Device metadata (country, carrier) |
| `heartbeat` | Keepalive YOU must send every 30s - miss 4 (120s) and the relay closes your socket |
| `tunnel_connected` | Confirm a `tunnel_connect` succeeded (tunnel is live) |
| `tunnel_data` | Bytes from the target back to the relay (binary frames on modern SDKs; JSON+base64 legacy) |
| `tunnel_closed` | Your TCP socket to the target closed |
| `tunnel_open_failed` | Tunnel open failed (connection_refused / dns_failed / timeout) - lets the gateway fail fast |
| `proxy_response` / `proxy_error` | Legacy JSON HTTP path only - deprecated, does not pass probes alone |

**Incoming (you receive):**
| Type | Description |
|------|-------------|
| `connected` | Connection established |
| `tunnel_connect` | CONNECT tunnel open request - open a TCP socket to the target and pump bytes (REQUIRED to earn) |
| `tunnel_data` | Tunnel bytes to write to your TCP socket (binary frames on modern SDKs; JSON+base64 legacy) |
| `tunnel_close` | Relay asks you to close a tunnel |
| `heartbeat_ack` | Relay acknowledgement of your heartbeat - no action needed |
| `proxy_request` | Legacy JSON HTTP request (deprecated path) |
| `relay_redirect` | Server-directed move to a closer regional relay (advertise `supportsRelayRedirect: true` to receive this) |

### Security

| Feature | Value |
|---------|-------|
| JWT expiry | 1 hour |
| Refresh token expiry | 7 days |
| Max WebSocket connections per device | 6 (multi-WS pool; over-cap evicts oldest - reference SDK opens 4 in parallel by default) |
| Message rate limit | 100/min per device |
| Registration rate limit | 600/min per IP |
| Wallet change cooling | 7 days |
| IP classification | Server-side ASN lookup (cannot spoof) |
| Withdrawal rate limit | 3/hour |

### Monthly Earnings Estimates

Earnings depend entirely on demand-side traffic routed through your IP - there is no fixed monthly figure. Illustrative *relative* shape only (not live numbers - always pull the current `earningsPerGB` at registration time and multiply by your own throughput):

| Connection | Relative earning potential |
|------------|------------------------------|
| Mobile 5G (US) | Highest - premium tier, most demand |
| Residential (US) | Mid |
| Datacenter VPS | Lowest - base tier |

Actual earnings depend on demand, location, uptime, and carrier ASN reputation. Live demand sources: AI agents purchasing proxies via x402 (both dedicated-port and Pool Gateway products), pool gateway customers, and reseller storefronts.

---

## Build & Resell - Pool Access Keys (pak_)

Full guide (PATH A/B/C/D decision tree, SDK code samples, security checklist): [/build/skill.md](https://agents.proxies.sx/build/skill.md). Summary for the master reference:

A `pak_*` pool access key is a GB-capped, optionally time-boxed credential that a reseller (or the x402 pool product) mints for a customer. It authenticates against the Pool Gateway exactly like a `psx_` account: the pak secret goes in the **password** field of the proxy credentials (`password.startsWith('pak_')` is the gateway's auth discriminator), and the account/pool/country/routing tokens go in the **username** field.

```bash
# Correct credential order - pak_ secret in PASSWORD, not username
curl -x "http://YOUR_ACCOUNT-mbl-us:pak_YOUR_KEY@gw.proxies.sx:7000" https://api.ipify.org
```

### REST Endpoints (`/v1/reseller/pool-keys`)

| Method | Path | Notes |
|--------|------|-------|
| POST | `/` | Mint. Gated by `FreshAuthGuard` (JWT < 5min old OR `X-Confirm-Password` header). Supports `Idempotency-Key` header for safe retries |
| GET | `/` | List (masked `pak_xxxx...xxxx` by default) |
| GET | `/audit` | Forensic audit log across all your keys (90-day TTL) |
| GET | `/:keyId/audit` | Audit log for one key |
| GET | `/:keyId/usage` | Per-key daily bandwidth time-series |
| POST | `/:keyId/reveal` | Unmask the full secret (audit-logged) |
| GET | `/:keyId` | Fetch one key |
| PATCH | `/:keyId` | Update (cap, expiry, quality tier, enabled) |
| POST | `/:keyId/topup` | Add GB atomically - **prefer this over PATCH** for extending a cap; avoids the read-modify-write race when concurrent top-ups land on the same key. Also supports `Idempotency-Key` |
| POST | `/:keyId/regenerate` | New secret, same key id. Also gated by `FreshAuthGuard` |
| DELETE | `/:keyId` | Delete |

**Auth-method nuance:** `FreshAuthGuard` only applies to interactive JWT sessions - server-side API-key callers (`authMethod: 'apiKey'`) bypass it (compensated by per-key rate limiting and the audit log). If you're adapting the JWT-based examples in `/build/skill.md` for a script, remember the fresh-auth requirement doesn't apply to your API-key flow.

**Auto-suspend:** a key's `enabled` flag flips to `false` atomically the moment `trafficUsedMB / 1024 >= trafficCapGB` - this bounds financial exposure if a key leaks. Every mint/update/topup/regenerate/reveal/delete/auth-success/auth-failure/auto-suspend event is recorded to the audit log (90-day TTL); list-polling is intentionally not logged.

### npm Reality Check

The published packages are `@proxies-sx/pool-sdk` **v0.9.0** and `@proxies-sx/pool-portal-react` **v0.11.0** (verified live via `npm view`). `pool-sdk@0.9.0` ships typed wrappers for all 11 REST endpoints above (including `poolKeys.reveal()` and `poolKeys.topUp()`), per-customer session scoping (`sessions.list({ pakId })`), carrier/ASN targeting (`asn`/`isp` options + `pool.getCarrierStock()`), a hard `ipType` (mobile/residential/datacenter) filter in `buildProxyUrl`, and client-side sid validation (fail fast instead of a gateway CONNECT error).

---

## SDK & Packages

### npm (published @proxies-sx packages)

| Package | Published version | Description |
|---------|---------|-------------|
| [@proxies-sx/mcp-server](https://www.npmjs.com/package/@proxies-sx/mcp-server) | 2.4.1 | MCP server - 89 tools (70 API-key incl. ops + pool groups, 19 wallet-only x402 incl. pool purchase) |
| [@proxies-sx/x402-core](https://www.npmjs.com/package/@proxies-sx/x402-core) | 1.0.0 | x402 types, utilities |
| [@proxies-sx/x402-hono](https://www.npmjs.com/package/@proxies-sx/x402-hono) | 1.0.0 | x402 Hono middleware |
| [@proxies-sx/x402-solana](https://www.npmjs.com/package/@proxies-sx/x402-solana) | 1.0.0 | Solana tx verification |
| [@proxies-sx/pool-sdk](https://www.npmjs.com/package/@proxies-sx/pool-sdk) | 0.9.0 | Reseller toolkit - typed pak_ key management, gateway URL building, sid validation, carrier/ASN/IP-class targeting |
| [@proxies-sx/pool-portal-react](https://www.npmjs.com/package/@proxies-sx/pool-portal-react) | 0.11.0 | Reseller toolkit - React storefront components (carrier/ASN/IP-class selector, PakQuickstart) |

From the open-source `proxy-reseller-kit` repo (previously named `pool-starter` - that name now 301-redirects here).

### Other distribution

| Package | Channel | Description |
|---------|---------|-------------|
| `bolivian-peru:android-peer-sdk:1.3.1` | JitPack | Android peer SDK (Kotlin) - current release, verified against GitHub Releases |

### GitHub Repositories

| Repository | Purpose |
|------------|---------|
| [proxies-sx-mcp-server](https://github.com/bolivian-peru/proxies-sx-mcp-server) | MCP server source (89 tools, matches npm 2.4.1) |
| [x402-sdk](https://github.com/bolivian-peru/x402-sdk) | x402 payment protocol SDK (3 packages) |
| [android-peer-sdk](https://github.com/bolivian-peru/android-peer-sdk) | Android SDK for peer bandwidth sharing |
| [proxy-reseller-kit](https://github.com/bolivian-peru/proxy-reseller-kit) | Open-source reseller toolkit (SDK + React + Next.js) - canonical name; `pool-starter` redirects here |
| [4g-proxies-providers](https://github.com/bolivian-peru/4g-proxies-providers) | Curated provider list with farm-direct contacts |

### Android SDK

```kotlin
// build.gradle
implementation("com.github.bolivian-peru:android-peer-sdk:1.3.1")

// Usage
ProxiesPeerSDK.init(context, "api-key", config)
ProxiesPeerSDK.getInstance().start()
ProxiesPeerSDK.getInstance().stop()
```

### x402 SDK Example

```javascript
import { x402Middleware } from '@proxies-sx/x402-hono';
import { verifySolanaPayment } from '@proxies-sx/x402-solana';

const app = new Hono();
app.use('/api/*', x402Middleware({
  price: 10000,  // $0.01 in micro-units
  recipient: 'YOUR_SOLANA_WALLET',
  verify: verifySolanaPayment,
}));
app.get('/api/data', (c) => c.json({ data: 'premium content' }));
```

---

## Framework Integrations

### MCP (Model Context Protocol)

Works with Claude Desktop, Cursor, and any MCP-compatible client:
- `npx -y @proxies-sx/mcp-server` - 89 tools (published)

### Lucid Agents (Daydreams)

- `@proxies-sx/lucid-agents` - Daydreams integration package

---

## Live Domains

| Domain | Purpose |
|--------|---------|
| api.proxies.sx | REST API + x402 + Swagger (public: `/docs/gateway`; full customer doc `/docs/api` is basic-auth gated) |
| agents.proxies.sx | AI platform landing, skill files, agents-api (path-routed) |
| client.proxies.sx | Customer portal |
| admin.proxies.sx | Admin dashboard |
| farmer.proxies.sx | Farmer dashboard |
| relay.proxies.sx | WebSocket relay for peer devices (EU hub) |
| relay-us.proxies.sx | WebSocket relay for peer devices (US/LATAM region) |
| gw.proxies.sx | Pool gateway (HTTP :7000, SOCKS5 :7001, health :7080) |
| proxies.sx | Main marketing website |

**For AI agents:** Use the MCP server instead of calling API endpoints directly:
- Proxy MCP: `npx -y @proxies-sx/mcp-server` (89 tools, published)

## Social

| Platform | URL |
|----------|-----|
| Twitter/X | https://x.com/sxproxies |
| Telegram | https://t.me/proxies_sx |
| GitHub | https://github.com/bolivian-peru |

---

*Proxies.sx - Mobile proxy infrastructure for AI agents*