# Proxies.sx - Mobile Proxies for AI Agents

> Real mobile + residential proxies for AI agents. Standard path: account + `psx_` API key +
> deposited GB (or the MCP server). Wallet-only alternative: pay per purchase with USDC on Base
> or Solana via x402 - no account or API key needed.
> One Pool Gateway credential routes the whole network - a flagship peer fleet across 150+ countries,
> backed by guaranteed carrier modems in 6 countries.
> Plus a Peer Network where agents and devices earn USDC by sharing bandwidth.
>
> Canonical contract: the per-product skill.md. If anything in this file disagrees with a
> skill.md, the skill.md wins. If a skill.md disagrees with the live API, the live API wins.

## Buy (start here)

### Standard path - account + API key + deposited GB (the main way to buy)

1. Sign up + sign in: `POST /v1/login/signup` -> `POST /v1/login/signin` -> JWT `accessToken`.
2. Mint a `psx_` API key: `POST /v1/api-keys` (JWT-only step); every later call uses `X-API-Key: psx_...`.
3. Deposit GB: top up balance (card / hosted crypto checkout in the dashboard), then
   `POST /v1/billing/purchase-traffic {"amount": <GB>}` - $4/GB, volume-discounted.
4. Set the gateway password (REQUIRED - the gateway never accepts your account login password):
   `PATCH /v1/account/proxy-password {"proxyPassword":"..."}`.
5. Connect via `gw.proxies.sx:7000` (HTTP) / `:7001` (SOCKS5) - ready connect strings from
   `GET /v1/gateway/credentials`; bytes are metered as they flow. For a dedicated port instead:
   `POST /v1/ports`.

Full sequence: https://agents.proxies.sx/skill.md ("Buy & Use With an API Key") and
https://agents.proxies.sx/pool/skill.md

### Wallet-only alternative - x402 USDC in 5 steps (no account)

1. Discover pricing (no auth, no payment):
   `curl -s "https://api.proxies.sx/v1/x402/pricing"`
2. Request the product WITHOUT payment - the HTTP 402 response IS the catalog:
   - Pool Gateway Access (recommended):  `curl -s "https://api.proxies.sx/v1/x402/pool?tier=peer&country=us&traffic=1"`
   - Dedicated Port:                     `curl -s "https://api.proxies.sx/v1/x402/proxy?country=US&traffic=1&tier=shared&duration=86400"`
3. Pay `accepts[].maxAmountRequired` (a STRING in micro-USDC, 6 decimals) to `accepts[].payTo` on Base or Solana. The USDC contract/mint is `accepts[].asset`.
4. Retry the SAME request with header `Payment-Signature: <tx_hash>`.
5. Persist from the response: `sessionToken` (format `x402s_...`, needed for every `/v1/x402/manage/*` call), the proxy credentials (username + password; for Pool Gateway the password is your `pak_*` key), and your tx hash.

The 402 body shape is shown in "x402 Payment Protocol" below.

## Quick Links

- Agent research index (one screen: every page + what it answers): https://agents.proxies.sx/index.md
- Landing: https://agents.proxies.sx
- Dedicated Port (buy a mobile proxy): https://agents.proxies.sx/marketplace/proxy/
- Pool Gateway Access: https://agents.proxies.sx/pool/
- Pool Gateway Skill (agent guide: drive the gateway with an account API key + deposited GB - the standard path - or buy wallet-only with x402 USDC): https://agents.proxies.sx/pool/skill.md
- Rotation Cookbook (copy-paste IP rotation, curl/python/node + footguns): https://agents.proxies.sx/pool/rotation-cookbook.md
- Private Pool API (named country-scoped credentials + Reserved IPs held exclusively for you; full REST reference): https://agents.proxies.sx/private-pool/skill.md
- Peer Network (EARN USDC): https://agents.proxies.sx/peer/
- Peer Skill: https://agents.proxies.sx/peer/skill.md
- Mac Compute Network (EARLY ACCESS — register Apple Silicon Macs to serve AI models): https://agents.proxies.sx/compute/
- Ground Truth (field-intelligence feed for agents — verified, source-backed, provenance-tagged): https://agents.proxies.sx/news/ · machine-readable: https://agents.proxies.sx/news/feed.md
- Build & Resell (toolkit + SDK): https://agents.proxies.sx/build/
- Build Skill (Anthropic format, AI-agent integration guide): https://agents.proxies.sx/build/skill.md
- Master Skill File: https://agents.proxies.sx/skill.md
- Ecosystem Reference: https://agents.proxies.sx/sx-token/ecosystem.md
- proxy-reseller-kit (reseller toolkit GitHub): https://github.com/bolivian-peru/proxy-reseller-kit
- @proxies-sx/pool-sdk on npm: https://www.npmjs.com/package/@proxies-sx/pool-sdk
- @proxies-sx/pool-portal-react on npm: https://www.npmjs.com/package/@proxies-sx/pool-portal-react
- API Docs (Pool Gateway Swagger, public, no auth): 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 at /docs/api is basic-auth gated - NOT public)
- x402 Discovery: https://agents.proxies.sx/.well-known/x402.json
- MCP Server (proxy): npx -y @proxies-sx/mcp-server
- Twitter: https://x.com/sxproxies
- Telegram: https://t.me/proxies_sx

---

## Ground Truth (news / field intelligence for agents)

A verified, source-backed feed on the substrate you run on — compute, models, proxies, payments.
Claims are provenance-tagged: REPORTED (third-party, attributed), ESTABLISHED (checkable
mechanism), OURS (live against a named Proxies.sx endpoint). Each post ends in an action.

- Feed (human): https://agents.proxies.sx/news/
- Feed (machine-readable, parse this): https://agents.proxies.sx/news/feed.md
- Latest: "The VRAM wall broke on a $1,600 GPU — and Apple Silicon walked through it" —
  a ~125B MoE served at 250k context on one 24GB GPU via RAM expert-offload; why unified-memory
  Macs skip the offload entirely; and how to rent one whole. https://agents.proxies.sx/news/moe-vram-wall/

---

## Products (one-line map)

1. **Pool Gateway Access** - RECOMMENDED. Buy with an account API key + deposited GB (the standard path - used directly at `gw.proxies.sx:7000`) or wallet-only with USDC at `/v1/x402/pool`. One metered credential that reaches every country in its tier via `gw.proxies.sx:7000` - routes the whole network: `tier=peer` for the flagship peer fleet (residential + mobile IPs across 150+ countries, scaling toward millions of devices), `tier=mbl` for guaranteed carrier modems in 6 countries. Both $4.00/GB, minimum 0.1 GB, duration free.
2. **Dedicated Port** - the specialized option: your own pinned modem port in one of the 6 carrier-modem countries, with SOCKS5 and a public rotate URL. Buy with `POST /v1/ports` (API key) or wallet-only with USDC at `/v1/x402/proxy`. $4.00/GB, minimum 0.1 GB = $0.40, duration free.
3. **Peer Network** (`/v1/peer/*`) - EARN USDC by sharing bandwidth. The flagship supply behind the gateway - 150+ countries, scaling toward millions of devices. 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. Always read your live per-GB rate from `earningsPerGB` at registration.

## Pool Gateway vs Dedicated Port (pick the right product)

**Pool Gateway (recommended) = one credential on gw.proxies.sx:7000 over the whole network, every country in the tier - country, session and rotation are 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 holds until YOU hit the rotate URL.**

| | Pool Gateway (`/v1/x402/pool`) - recommended | Dedicated Port (`/v1/x402/proxy`) |
|---|---|---|
| What 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 5-1440 min) |
| SOCKS5 | Yes - HTTP `:7000` and SOCKS5 `:7001` both work, GB metered identically on either | 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 | 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` |

**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.

**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).

**Same for both:** $4.00/GB, 0.1 GB ($0.40) minimum, duration free - you only pay for traffic. Accountless x402 flow (HTTP 402 -> pay USDC on Base ~2s or Solana ~400ms -> retry with `Payment-Signature`), 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 (US, GB, PL, FR, NL, GE).

---

### 1. Pool Gateway Access ($4.00/GB - one credential, the whole network) [RECOMMENDED]

One USDC payment mints one metered credential. That credential reaches EVERY country in
its tier through `gw.proxies.sx:7000` - retarget countries by editing the proxy username,
no repurchase per country. Two tiers, both $4/GB: `tier=peer` is the flagship peer network
(residential + mobile IPs across 150+ countries, scaling toward millions of devices);
`tier=mbl` is the guaranteed-quality carrier modems in 6 countries (US, GB, PL, FR, NL, GE).
The gateway probes peers and routes around dead ones - metered per delivered byte, so broken
peers cost you nothing. This x402 path needs no account, signup, or API key; the same gateway
is also driven the standard way with an account API key + deposited GB (see "Buy" above).

**First request (no auth):** `curl -s "https://api.proxies.sx/v1/x402/pool/pricing"` - tier catalog, networks, username DSL, stock URL.

**Buy:** GET/POST `https://api.proxies.sx/v1/x402/pool?tier=peer&country=us&traffic=1`
- Without `Payment-Signature`: returns the HTTP 402 catalog.
- With a valid tx hash in `Payment-Signature`: returns credentials.
- Swap `tier=peer` (150+-country breadth) for `tier=mbl` (guaranteed carrier modems, 6 countries) any time - same $4/GB.

**In the pool 402 response:** trust `accepts[].maxAmountRequired` / `payTo` / `asset` and the `pool` block. **IGNORE `accepts[].outputSchema`** - it is inherited from the Dedicated Port product and does not describe pool purchases. Full contract: https://agents.proxies.sx/pool/skill.md

**Connect:** HTTP proxy at `gw.proxies.sx:7000` (CONNECT tunneling works for HTTPS targets), or
SOCKS5 at `:7001` - both work for this credential and are metered identically (fixed 2026-07-25;
earlier v1 responses advertised a null SOCKS5 field for x402-pool credentials, which is now stale).
The username is the routing DSL string from the purchase response; the password is your `pak_*` key.

**Stock check (no auth, counts only, never IPs):** `GET https://api.proxies.sx/v1/gateway/pool/stock`

**Post-Purchase Management (X-Session-Token header required):**

```
GET  /v1/x402/manage/pool/credit         - Remaining GB (read-through, pak-backed)
POST /v1/x402/manage/pool/topup          - Pay more USDC for more GB (Payment-Signature header, replay-guarded)
GET  /v1/x402/manage/pool/usage          - Per-day usage series (?days=30)
POST /v1/x402/manage/pool/regenerate     - New pak secret, same username (use if the key leaks)
GET  /v1/x402/manage/pool/connection     - Re-emit full credentials (recovery if you lost the password)
```

---

### 2. Dedicated Port - Mobile Proxy ($4.00/GB, minimum 0.1 GB = $0.40)

The specialized option: a dedicated host:port on one real 4G/5G modem in one of the 6
carrier-modem countries, with HTTP and SOCKS5. Pick it when you need a public rotate
URL for a true carrier-IP reset, or a single pinned host:port; for broader 150+-country
coverage use the Pool Gateway above (its credential also speaks HTTP and SOCKS5).

**Endpoint:** GET/POST https://api.proxies.sx/v1/x402/proxy

**Features:**
- HTTP & SOCKS5 support
- Auto IP rotation via `GET /v1/rotate/:token` (rotation token comes in the purchase response)
- Countries: live set via `GET /v1/x402/countries`; as of last edit: NL, PL, US, GE (Georgia), FR, GB
- Free port replacement (up to 3x if port goes offline)
- Session top-up (pay more to extend traffic/duration)
- Port recreation for sessions with remaining credit
- Session status check (traffic usage, expiration)

**Pricing:**
- Shared: $4.00/GB (multiple users share device)
- Duration is always FREE - you only pay for traffic
- Minimum purchase: 0.1 GB ($0.40)

**Post-Purchase Management (X-Session-Token header required):**

The session token (format `x402s_...`) is returned in the proxy purchase response - persist it.
Purchase first: without a valid `X-Session-Token` header, these endpoints return HTTP 400.

```
GET  /v1/x402/manage/session                   - Session details
GET  /v1/x402/manage/session/credit             - Check remaining credit
POST /v1/x402/manage/ports/recreate             - Recreate deleted port (free)
POST /v1/x402/manage/ports/replace              - Replace offline port (free, max 3)
GET  /v1/x402/manage/session/topup/calculate    - Preview top-up cost
POST /v1/x402/manage/session/topup              - Pay to extend (Payment-Signature header)
```

**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, no payment needed)
- 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)
- Session must have 0 active ports (HTTP 400 if any port is still active - use /manage/ports/replace for a broken-but-active port instead)
- Minimum 5 minutes session duration remaining required
- Can optionally change country on recreation
- Original session traffic allocation preserved

**MCP Server:** npx -y @proxies-sx/mcp-server

**Core tools** (the server self-describes its full tool set via MCP `tools/list`):
- x402_get_proxy: Buy a proxy with USDC (wallet mode)
- x402_rotate_ip: Rotate the proxy IP
- x402_check_session: Check session status

---

### 3. Peer Network - EARN USDC

AI agents earn by sharing internet bandwidth. Connect via WebSocket, route traffic, get paid automatically.

**Earnings model:** your payout is a revenue share set by Proxies.sx and customized per partner, paid NET (no platform fee taken on top) - there is no fixed public percentage; rates are configured by our team, can be tailored to you, and move with demand. Never hardcode a number; read the live value from the `earningsPerGB` field in your registration response.

**Revenue share by IP Type:**
- Mobile IPs: highest-demand tier (carrier networks like AT&T, Verizon, T-Mobile)
- Residential IPs: mid tier (home ISPs like Comcast, Spectrum)
- Datacenter IPs: low-demand base tier (AWS, GCP, Azure, VPNs)

**Registration (Public, Rate Limited):**
```
POST https://api.proxies.sx/v1/peer/agents/register
Content-Type: application/json

{
  "name": "my-agent",
  "type": "claude",
  "walletAddress": "optional-solana-address"
}
```

**Response:**
```json
{
  "deviceId": "agent_abc123def456",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "a1b2c3d4...",
  "relay": "wss://relay.proxies.sx",
  "earningsPerGB": { "mobile": <number>, "residential": <number>, "datacenter": <number> }
}
```

(The response also includes a `throughputContract` and human-readable `instructions`.)

Persist from this response:
- `jwt` - required for every authenticated peer endpoint below. Expires in 1 hour.
- `refreshToken` - the JWT expires in 1 hour; renew it via POST /v1/peer/agents/{deviceId}/refresh (do this every ~50 min or your relay connection dies with no recovery).
- `deviceId` - used in earnings/withdraw paths below.
- `relay` - the geo-assigned relay WebSocket URL to connect to (US/LATAM peers get wss://relay-us.proxies.sx).
- `earningsPerGB` - the live per-GB rates. Platform-set, can change anytime; never hardcode them.
- Min payout: $5 (agents) / $10 (Android SDK devices).

**Connect to Relay (use header auth, NOT URL params):**
1. Open WebSocket to the `relay` URL from your register response (geo-assigned to the nearest region; falls back to wss://relay.proxies.sx) with `Sec-WebSocket-Protocol: token.{JWT}` header
2. Send device_info: {"type": "device_info", "payload": {"country": "US", "supportsRelayRedirect": true}}
3. Handle `tunnel_connect` messages - open a TCP socket to the target and stream bytes both ways via binary `tunnel_data` frames. The legacy JSON `proxy_request`/`proxy_response` flow alone will NOT pass routing probes or earn.
4. Respond to every heartbeat with heartbeat_ack (active ACK required)
5. Handle `relay_redirect` messages by reconnecting your whole socket pool to the given relay
6. Earn automatically based on traffic

Full binary tunnel protocol + implementer checklist: https://agents.proxies.sx/peer/skill.md
Easiest path: run the ready reference SDK - https://agents.proxies.sx/peer/reference-sdk.js

**Check Earnings:**
```
GET https://api.proxies.sx/v1/peer/agents/{deviceId}/earnings
Authorization: Bearer YOUR_JWT
```

**Request Payout (minimum $5.00):**
```
POST https://api.proxies.sx/v1/peer/agents/{deviceId}/withdraw
Authorization: Bearer YOUR_JWT
Content-Type: application/json

{"walletAddress": "YOUR_SOLANA_ADDRESS"}
```

**Wallet binding:** payouts are sent ONLY to the wallet registered on your device - the
`walletAddress` body param above is ignored. Wallet changes are limited to 1/day and start
a 7-day cooling period before withdrawal.

**Full Documentation:** https://agents.proxies.sx/peer/
**Skill File:** https://agents.proxies.sx/peer/skill.md

---

## x402 Payment Protocol

Every paid endpoint uses the same HTTP 402 flow:

1. Request without payment:
   `GET /endpoint`

2. HTTP 402 response (live shape - `x402Version` 1 with an `accepts[]` array; example
   below is for a 0.1 GB Dedicated Port purchase = $0.40 = "400000" micro-USDC):

```json
{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "400000",
      "payTo": "0xF8cD900794245fc36CBE65be9afc23CDF5103042",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "maxTimeoutSeconds": 30
    },
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "400000",
      "payTo": "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ]
}
```

   Field guide:
   - `maxAmountRequired` - the price, as a STRING in micro-USDC (6 decimals). "400000" = $0.40.
   - `payTo` - the recipient wallet on that network. Always pay the address from YOUR live 402 response, not from documentation.
   - `asset` - the USDC contract (Base) / mint (Solana) on that network.

3. Send exactly `maxAmountRequired` USDC to `payTo` on your chosen network.

4. Retry the SAME request with payment proof:
   `GET /endpoint` with header `Payment-Signature: <tx_hash>`

5. Receive the product JSON. Persist `sessionToken`, credentials, and your tx hash.

---

## Endpoint Reference (buy side: x402 + gateway stock + rotation)

All endpoints at https://api.proxies.sx - grouped by auth requirement. Peer (earn side) endpoints are in the Peer Network section above and in https://agents.proxies.sx/peer/skill.md.

### Discovery (no auth, no payment)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/pricing` | Returns pricing ($4/GB), min purchase, duration rules |
| POST | `/v1/x402/pricing` | Same as GET (POST variant for agents that prefer POST) |
| GET | `/v1/x402/calculate` | Calculate exact cost before buying. Params: `?traffic=1&tier=shared&duration=86400` |
| POST | `/v1/x402/calculate` | Same as GET (POST variant) |
| GET | `/v1/x402/countries` | List available countries with live device counts per country |
| GET | `/v1/x402/info` | Master info endpoint - returns pricing, countries, MCP tools, everything in one call |
| GET | `/v1/x402/.well-known` | x402 protocol discovery document |
| GET | `/v1/x402/health` | Health check - returns OK if service is running |
| POST | `/v1/x402/health` | Same as GET (POST variant) |
| GET | `/v1/x402/pool/pricing` | Pool Gateway tier catalog: prices, networks, username DSL, stock URL |
| GET | `/v1/gateway/pool/stock` | Live Pool Gateway endpoint COUNTS per pool + country (never IPs) |

### Dedicated Port Purchase (x402 payment required)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/proxy` | Purchase a mobile proxy. Without `Payment-Signature` header: returns HTTP 402 with payment info. With valid tx hash: creates proxy and returns credentials. Params: `?country=US&traffic=1&tier=shared&duration=86400` |
| POST | `/v1/x402/proxy` | Same as GET (POST variant). Body can include `{ country, traffic, tier, duration }` |

**Response after payment** (nested; persist `management.sessionToken`, `rotationUrl`, `proxy.username`/`proxy.password`):
```json
{
  "proxy": {
    "http": "http://psx_user:randompass@server-ip:30001",
    "socks5": "socks5://psx_user:randompass@server-ip:31001",
    "server": "server-ip",
    "httpPort": 30001,
    "socksPort": 31001,
    "username": "psx_user",
    "password": "randompass",
    "expiresAt": "2026-03-06T12:00:00Z"
  },
  "rotationUrl": "https://api.proxies.sx/v1/rotate/rot_xyz789",
  "sessionId": "...",
  "portId": "...",
  "traffic": { "allocatedGB": 1.0, "usedGB": 0, "remainingGB": 1.0 },
  "location": { "country": "United States", "countryCode": "US" },
  "management": { "sessionToken": "x402s_abc123...", "authMethod": "Header: X-Session-Token: x402s_..." }
}
```

### Pool Gateway Access Purchase (x402 payment required)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/pool` | Purchase Pool Gateway access. Without `Payment-Signature` header: returns the HTTP 402 catalog. With valid tx hash: returns gateway credentials. Params: `?tier=mbl&country=us&traffic=1` |
| POST | `/v1/x402/pool` | Same as GET (POST variant); body params merged with query |

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

These endpoints manage your purchase AFTER payment. Include `X-Session-Token: x402s_YOUR_TOKEN` header.

Dedicated Port sessions:

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/manage/session` | Get full session details: ports, traffic used, traffic remaining, expiration, status |
| GET | `/v1/x402/manage/session/credit` | Check remaining credit. Returns `canRecreatePort: true` if session has unused traffic |
| GET | `/v1/x402/manage/ports` | List all ports in your session with their current status |
| GET | `/v1/x402/manage/ports/:portId/status` | Check if a specific port is online/offline, get current IP |
| POST | `/v1/x402/manage/ports/recreate` | Recreate a deleted/expired port if session has remaining credit. Free. Body: `{ "country": "US" }` |
| POST | `/v1/x402/manage/ports/replace` | Replace an offline/broken port with a new one on a different device. Free, max 3 per session. Body: `{ "country": "US" }` |
| GET | `/v1/x402/manage/session/topup/calculate` | Preview cost of adding more traffic/duration. Params: `?addTrafficGB=2&addDurationSeconds=86400` |
| POST | `/v1/x402/manage/session/topup` | Pay to extend session. Requires `Payment-Signature` header with new tx hash. Body: `{ "addTrafficGB": 2, "addDurationSeconds": 86400 }` |

Pool Gateway sessions:

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/manage/pool/credit` | Remaining GB on your pak key |
| POST | `/v1/x402/manage/pool/topup` | Pay more USDC for more GB. Requires `Payment-Signature` header with new tx hash |
| GET | `/v1/x402/manage/pool/usage` | Per-day usage series. Params: `?days=30` |
| POST | `/v1/x402/manage/pool/regenerate` | Rotate the pak secret; username and remaining credit unchanged |
| GET | `/v1/x402/manage/pool/connection` | Re-emit the full purchase response (credential recovery) |

### Session Lookup (no auth)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/session/:id` | Look up session by its MongoDB ID |
| GET | `/v1/x402/session/tx/:txHash` | Look up session by the original payment transaction hash |
| GET | `/v1/x402/sessions/:id/status` | Get session status by ID |
| GET | `/v1/x402/sessions/wallet/:wallet` | List all sessions for a given wallet address |

### Agent Registry

| Method | Path | What It Does |
|--------|------|-------------|
| POST | `/v1/x402/agents` | Register as an x402 agent (public). Body: `{ "walletAddress": "0x...", "name": "my-agent" }` - `walletAddress` is required (min 20 chars); optional extras: `network`, `description`, `contactEmail`, `website` |
| GET | `/v1/x402/agents/:wallet` | Get agent profile by wallet address |

### IP Rotation (public)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/rotate/:token` | Rotate IP using rotation token from proxy purchase. No auth needed. Returns new IP. |

### Admin Only (JWT required, admin role)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/agents` | List all registered agents |
| PUT | `/v1/x402/agents/:wallet` | Update agent details |
| DELETE | `/v1/x402/agents/:wallet` | Delete agent |
| GET | `/v1/x402/sessions` | List all sessions |
| GET | `/v1/x402/stats` | Revenue and usage statistics |
| GET | `/v1/x402/admin/audit-logs` | Audit logs for all x402 operations |
| GET | `/v1/x402/admin/audit-stats` | Aggregate audit statistics |
| GET | `/v1/x402/admin/receipts` | List all payment receipts |
| GET | `/v1/x402/admin/receipts/:id` | Get specific receipt |
| GET | `/v1/x402/admin/dashboard` | Combined dashboard data |

---

## Payment Networks

**Base (Ethereum L2)**
- Chain ID: 8453
- Asset: USDC
- Settlement: ~2 seconds
- Gas: ~$0.01

**Solana**
- Asset: USDC (SPL)
- Settlement: ~400ms
- Gas: ~$0.0001

---

## MCP Integration

Add to Claude Desktop config. The server needs credentials to start - pick one of the two auth modes:

API-key mode (account required, 70 tools):

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

x402 wallet mode (no account needed, 19 wallet tools):

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

`PROXIES_API_URL` is optional and defaults correctly (https://api.proxies.sx - do NOT add a /v1 suffix; endpoint paths already include it).

---

## GitHub & NPM

**Repositories:**
- https://github.com/bolivian-peru/proxies-sx-mcp-server
- https://github.com/bolivian-peru/x402-sdk
- https://github.com/bolivian-peru/android-peer-sdk

**NPM Packages:**
- https://www.npmjs.com/package/@proxies-sx/mcp-server

---

## Framework Integrations

### MCP (Model Context Protocol)

- Proxy MCP: npx -y @proxies-sx/mcp-server (89 tools published on npm, v2.4.1)

### Lucid Agents (Daydreams)

- @proxies-sx/lucid-agents - Proxies.sx buying integration for the Lucid Agents (Daydreams) framework. First call: `npm install @proxies-sx/lucid-agents`, then follow the package README.
- npm: https://www.npmjs.com/package/@proxies-sx/lucid-agents

---

## Support

- Email: maya@proxies.sx
- Telegram: https://t.me/proxies_sx
- Twitter: https://x.com/sxproxies
- Dashboard: https://client.proxies.sx

Gateway errors follow `CODE: message (req: uuid)` - when reporting a problem, quote the `req` id.