# Proxies.sx - Master Skill File

> Complete infrastructure reference for AI agents. One file, everything you need.

## What Is Proxies.sx

Mobile proxy infrastructure for AI agents. Real 4G/5G connections from 131 physical devices in 6 countries (US, DE, GB, FR, ES, PL). Pay with USDC on-chain via the x402 protocol. Three ways to participate:

- **BUY a dedicated proxy** - Pay with USDC on-chain (Base or Solana) via x402. No accounts, no API keys. $4/GB, 6 countries, HTTP + SOCKS5. One dedicated modem port: `GET /v1/x402/proxy`.
- **BUY pool gateway access** - One USDC payment, one credential that reaches every country in your tier through the shared gateway (no per-country repurchase). Discover tiers at `GET /v1/x402/pool/pricing`, buy at `GET/POST /v1/x402/pool?tier=mbl&country=us&traffic=1` (no payment -> 402 catalog; pay USDC -> credentials). Manage via `X-Session-Token` at `/v1/x402/manage/pool/{credit,topup,usage,regenerate,connection}`. v1 = mbl tier ($4/GB, production modems).
- **EARN USDC** - Share bandwidth as a peer. Per-GB rates by IP type (mobile > residential > datacenter), set by the platform and returned in the `earningsPerGB` field of the registration response. Same rates apply to AI agents, Android SDK devices, and modem 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.

---

## Quick Reference

| What | URL |
|------|-----|
| **Agents Landing** | https://agents.proxies.sx |
| Peer Network | https://agents.proxies.sx/peer/ |
| Buy a Proxy | https://agents.proxies.sx/marketplace/proxy/ |
| **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 |
| 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 x402 Stats | https://api.proxies.sx/v1/x402/info |
| Live Pricing | https://api.proxies.sx/v1/x402/pricing |
| Live Service Status | https://api.proxies.sx/v1/x402/status |
| Relay Server | wss://relay.proxies.sx |
| Gateway Pool | gw.proxies.sx:7000 (HTTP) / 7001 (SOCKS5) |
| Customer Dashboard | https://client.proxies.sx |
| **API Docs (Swagger)** | https://api.proxies.sx/docs/api |
| API Docs (OpenAPI JSON) | https://api.proxies.sx/docs/api-json |
| MCP Server (proxy) | `npx -y @proxies-sx/mcp-server` |

---

## x402 Payment Protocol

HTTP 402 Payment Required for machine-to-machine USDC payments.

### Flow

```
1. Request without payment    GET /v1/x402/proxy?country=US&traffic=1
2. Receive 402 response       { price, recipient wallet, networks }
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  { host, port, username, password, sessionToken, rotationToken }
```

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

Duration is always FREE - you only pay for traffic.

---

## Buy a Proxy (Quick Start)

```bash
# 1. Request proxy (get 402 with payment info)
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: { host, httpPort, socksPort, username, password, sessionToken, expiresAt }

# 3. Use the proxy
curl -x http://USERNAME:PASSWORD@HOST: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/rotate/YOUR_ROTATION_TOKEN
```

---

## Pool Gateway - Direct Usage (no x402 session)

For sustained workloads, the Pool Gateway gives you a long-lived HTTP /
SOCKS5 proxy endpoint authenticated by a `pak_*` pool-access-key
(reseller-minted) or a `psx_*` proxy username + proxy password.

```bash
# Basic curl through HTTPS pool (mbl = production-grade 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 truly immutable IP use peer pool.
curl -x "http://psx_USER_ID-mbl-us-sid-bot01-rot-sticky:PROXY_PASSWORD@gw.proxies.sx:7000" \
  https://api.ipify.org

# SOCKS5
curl -x "socks5://psx_USER_ID-mbl-de:PROXY_PASSWORD@gw.proxies.sx:7001" \
  https://api.ipify.org

# Pool-access-key (reseller-distributed credential).
# The psx_ house username goes in the USERNAME position; the pak_ key is the PASSWORD.
curl -x "http://psx_x402pool-mbl-pl:pak_KEY@gw.proxies.sx:7000" https://api.ipify.org
```

### Which pool? (read this once)

| Pool token | Use when | Notes |
|---|---|---|
| `mbl` | **Production / paying workload.** 10-15 Mbps, sub-1s TTFB, ~100% success | modems - real mobile carriers we operate end-to-end |
| `peer` | Best-effort / hobby / country coverage outside our modem fleet | Third-party SDK fleet. Probe v2 routes around broken peers but pool size varies. ~5-20% live working capacity at any moment |
| `any` | When either pool is acceptable | Health-weighted blend |

Resellers wanting strict quality on a peer-pool customer pak: set
`qualityTier: 'safe'` when minting - the gateway silently rewrites
`peer-*` -> `mbl-*` for that key.

### Username token 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-bot01` | Session id (min 8, max 64 chars, `[a-z0-9_]`) - same `sid` returns to the same modem. **Required for `sticky`/`auto*` to persist across connections** (see note). |
| 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*` → swap modems every N min; `ondemand` → re-pick on a new connection. **`hard` pins like `sticky`** - it does NOT give a new IP per request. |
| failover | `-failover-samecarrier` | When primary endpoint dies |
| ttl | `-ttl-7200` | Session TTL in seconds (max 1h default) |
| pin | `-pin-device-modem001` | (Parsed but not currently honoured) |

> **Stickiness needs a `-sid-`.** Without one, every connection starts a fresh synthetic session (5-min TTL) - so `-rot-sticky` alone won't keep you on the same modem across connections. Always pass `-sid-<name>` (≥ 8 chars) when you want a connection to stick. And note **sticky pins the MODEM, not the IP** - mobile carriers can still re-NAT the egress IP; for a held IP use the residential `peer` pool or a dedicated modem.

### 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_AUTH_INVALID` | 407 | Bad credentials / no balance / disabled key - failMsg surfaces backend reason | Check pak + balance |
| `E_USERNAME_PARSE` | 400 | Username token format wrong | Re-read the token table above |
| `E_RATE_LIMITED_AUTH` | 429 | Too many failed auth attempts | Back off 30s (escalates to 5min) |
| `E_RATE_LIMITED_CONN` | 429 | Over 100 concurrent connections | 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 | 50 sessions max per account | 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 |

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

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

The relay enforces three 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

These all manifest as connection-reset / TLS handshake failure on your
side. Retry - the selector will pick a different peer. Use `mbl` pool
to avoid all three (modems don't have these failure modes).

---

## All x402 Endpoints

### Discovery (no auth)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/x402/pricing` | 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 |

### Proxy Purchase (x402 payment)

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/x402/proxy` | Purchase mobile proxy |
| POST | `/v1/x402/proxy` | Purchase mobile proxy (POST) |

### 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 (needs Payment-Signature) |

**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)
- 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 | `/rotate/:token` | Rotate IP via public token (no auth) |

---

## MCP Server

`@proxies-sx/mcp-server` v2.0.0 - 72 tools for proxy management via Model Context Protocol.

### Install

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

### Claude Desktop Config

```json
// API Key mode (account required)
{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": { "PROXIES_API_KEY": "psx_your_key" }
    }
  }
}

// x402 mode (no account needed)
{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": { "AGENT_WALLET_KEY": "your_private_key", "PREFERRED_NETWORK": "base" }
    }
  }
}
```

### Tool Categories (55 total)

| Category | Count | Key Tools |
|----------|-------|-----------|
| Account | 2 | get_account_summary, get_account_usage |
| Port Mgmt | 7 | list_ports, create_port, delete_port, update_port_credentials, reconfigure_port |
| Port Status | 4 | get_port_status, get_port_ip, ping_port, speed_test_port |
| Rotation | 5 | rotate_port, configure_auto_rotation, get_rotation_history |
| Billing | 3 | get_pricing, calculate_price, purchase_shared_traffic |
| Crypto Pay | 5 | create_crypto_payment, check_crypto_payment_status |
| Support | 5 | create_support_ticket, list_my_tickets, reply_to_ticket |
| x402 Session | 8 | get_x402_session, 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 |

### Account Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `get_account_summary` | Get your full account overview - current balance, total spent, slot usage, traffic allocation and consumption, and your current tier. Use this to understand how much budget you have left. |
| `get_account_usage` | Get detailed traffic breakdown - per-port traffic usage, daily/weekly/monthly trends, and which ports consume the most bandwidth. Useful for optimizing resource allocation. |

### Port Management Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `list_ports` | List all your proxy ports with full details - hostname, HTTP/SOCKS5 ports, credentials, country, carrier, device, expiration, traffic used, and online status. Supports filtering by country, status, or type. |
| `get_port` | Get complete details for a single port by ID - connection strings for HTTP and SOCKS5, current device info, traffic counters, rotation settings, OS fingerprint, and sync status with the modem server. |
| `create_port` | Create a new proxy port. Specify country (required), and optionally city, carrier. System finds an available device with capacity and creates the port on the modem infrastructure. Returns full connection details. |
| `delete_port` | Delete a proxy port permanently. Removes from both your account and the modem server. The device slot is freed for other users. Cannot be undone. |
| `update_port_credentials` | Change the username and/or password for a port. Updated on the modem immediately. Use when you need to rotate credentials for security. |
| `update_os_fingerprint` | Set OS fingerprint spoofing via p0f. Options: Windows 10, macOS, iOS, Android, or none. Makes your traffic appear to come from a specific OS. Useful for bypassing OS-based blocks. |
| `reconfigure_port` | Move a port to a different device - change country, city, or carrier while keeping the same port name and credentials. The old device is released and a new one is allocated. |

### Port Status Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `get_port_status` | Check if a port is online or offline right now. Queries the modem directly for real-time status. Returns online/offline boolean and last check timestamp. |
| `get_port_ip` | Get the current public IP address of a port. Queries the proxy server to find what external IP your traffic exits from. Use to verify you're getting a mobile IP. |
| `ping_port` | Test connectivity and measure latency to a port. Sends a test request through the proxy and measures round-trip time in milliseconds. Returns success/fail and latency. |
| `speed_test_port` | Run a download/upload speed test through a port. Measures real throughput in Mbps. Useful for checking if a device has good cellular signal. Takes 10-30 seconds to complete. |

### Rotation Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `rotate_port` | Manually rotate a port to a new device - gets a new IP address, new carrier, new location (within same country). 5-minute cooldown between rotations. Old device is released. |
| `check_rotation_availability` | Check if a port can be rotated right now. Returns yes/no and time until next rotation is allowed (cooldown check). Also shows if auto-rotation is enabled. |
| `configure_auto_rotation` | Set up automatic IP rotation on a schedule. Specify interval (5-1440 minutes). Can optionally require matching carrier or city. System rotates automatically via cron. |
| `get_rotation_history` | View all past rotations for a port - when, from which device to which device, trigger type (manual/auto/API), and whether it succeeded or failed. |
| `get_rotation_token_url` | Get the public rotation URL that can be called without authentication. Format: `https://api.proxies.sx/rotate/{token}`. Share this with scripts or automation that need to trigger rotations. |

### Billing Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `get_pricing` | Get complete pricing information - $4/GB rate, volume discounts (10-40% based on cumulative purchases), current slot tier, and available slot counts. |
| `calculate_price` | Calculate exact price before purchasing. Specify GB amount. Returns price with applicable volume discount, your current tier, and how this purchase affects your tier progression. |
| `purchase_shared_traffic` | Buy shared traffic in GB using your account balance. $4/GB base price, volume discounts apply. Slot limits auto-upgrade as you buy more. |

### Crypto Payment Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `create_crypto_payment` | Create a crypto payment order to top up your account balance. Specify amount ($10-$1000). Returns a payment link with QR code. Supports 50+ cryptocurrencies (BTC, ETH, USDT, USDC, LTC, DOGE, SOL, etc.). Balance credited automatically on confirmation. |
| `check_crypto_payment_status` | Check if a crypto payment has been confirmed. Returns status: pending, confirming, paid, expired, or cancelled. Paid means balance has been credited. |
| `get_pending_crypto_payments` | List all crypto payment orders that haven't been completed yet. Shows amount, currency, creation time, and expiration. |
| `cancel_crypto_payment` | Cancel a pending crypto payment order. Only works if payment hasn't been sent yet. |
| `get_crypto_payment_info` | Get info about supported cryptocurrencies, minimum amounts, estimated confirmation times, and current exchange rates. |

### Reference Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `list_available_countries` | List all countries where proxy devices are available. Shows country name, ISO code, and number of available devices. Currently: DE, PL, US, FR, ES, GB. |

### Utility Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `get_proxy_connection_string` | Generate a ready-to-use connection string for a port. Formats: `http://user:pass@host:port`, `socks5://user:pass@host:port`, or curl command. Copy-paste into your scripts. |
| `get_all_proxy_formats` | Get every format at once - HTTP URL, SOCKS5 URL, curl command, Python requests snippet, Node.js fetch snippet, and environment variable format. |
| `get_os_fingerprint_options` | List all available OS fingerprint options - Windows 10, macOS, iOS (real), iOS (p0f), Android (real), Android (p0f), or none. Shows the p0f value for each. |

### Support Tools (Detailed)

| Tool | What It Does |
|------|-------------|
| `create_support_ticket` | Open a support ticket with the Proxies.sx team. Specify subject and description. Returns ticket ID. Human support typically responds within 24 hours. |
| `list_my_tickets` | List all your support tickets with status (open, pending, resolved, closed). Shows latest message preview and timestamps. |
| `get_ticket` | Get full conversation history for a ticket - all messages from you and support team, with timestamps. |
| `reply_to_ticket` | Send a reply to an existing open ticket. Include your message text. Ticket status updates to "pending" (waiting for support response). |
| `close_ticket` | Mark a ticket as resolved/closed. Use when your issue is fixed. Can be reopened by creating a new reply. |

### x402 Session Tools (Detailed)

These tools manage your x402 proxy sessions after purchase:

| Tool | What It Does |
|------|-------------|
| `get_x402_session` | Retrieve full session details - ports, traffic used/remaining, expiration, status. Uses your X-Session-Token. |
| `list_x402_ports` | List all ports in your session with their online/offline status and current IPs. |
| `get_x402_port_status` | Check a specific port's status - online/offline, current IP, traffic consumed. |
| `get_sessions_by_wallet` | Look up all sessions for a given wallet address. |
| `get_session_status` | Quick session status check - active/expired, traffic remaining. |
| `replace_x402_port` | Replace an offline/broken port with a new one on a different device. Free, max 3 replacements per session. The failed device is excluded. |
| `calculate_x402_topup` | Preview cost of extending your session. Specify addTrafficGB and/or addDurationSeconds. Duration-only extensions are free. |
| `topup_x402_session` | Pay USDC to add more traffic or extend duration. Requires a new payment transaction. Traffic: $4/GB. |

### x402 Auto Tools (Detailed)

These tools handle the full x402 payment flow automatically using your wallet:

| Tool | What It Does |
|------|-------------|
| `x402_get_proxy` | Purchase a mobile proxy automatically - sends USDC, waits for confirmation, returns proxy credentials. Specify country, traffic GB. |
| `x402_get_pricing` | Get current pricing - $4/GB. Shows min purchase, duration rules. |
| `x402_wallet_balance` | Check your USDC wallet balance on Base or Solana. Shows available funds for proxy purchases. |
| `x402_list_sessions` | List all your active x402 proxy sessions. Shows traffic used, expiration, port status. |
| `x402_check_session` | Check current session status - traffic used, traffic remaining, expiration time, port status. |
| `x402_rotate_ip` | Rotate to a new IP address using the rotation token from your proxy purchase. No payment needed. |
| `x402_extend_session` | Add more traffic or duration to an existing session. Automatically calculates cost and sends payment. |
| `x402_list_countries` | List available countries with live device counts. Shows which countries have available capacity. |
| `x402_list_cities` | List available cities within a specific country. |
| `x402_list_carriers` | List available mobile carriers within a specific country. |
| `x402_service_status` | Health check - verify x402 service is operational and responsive. |

---

## Peer Marketplace - Earn USDC

Share your internet bandwidth, get paid in USDC on Solana.

### Earnings by IP Type

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

**Per-GB rates are set by the platform and can change anytime** based on demand and infrastructure costs. Get current values by reading the `earningsPerGB` field in the response of `POST /v1/peer/agents/register` - that's the live rate at the moment of registration.

**Same rates for everyone:** AI agents, Android SDK devices, and modem 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.

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

### Fastest start: use a ready, tested SDK (does the whole protocol for you)

- Node.js: https://agents.proxies.sx/peer/reference-sdk.js -> `API_KEY=psx_... node reference-sdk.js`
- Go: https://agents.proxies.sx/peer/reference-sdk.go + https://agents.proxies.sx/peer/go.mod -> `go run reference-sdk.go -key=psx_...`
- Windows: https://agents.proxies.sx/peer/proxies-peer-windows.zip (unzip -> setup.bat -> start.bat)
- Android: https://github.com/bolivian-peru/android-peer-sdk

The workflow below is only if you build your own client. Note the relay now uses streaming `tunnel_connect` tunnels; the legacy `proxy_request` flow shown in older snippets is superseded.

### 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. Tunnel       Receive tunnel_connect - open TCP to target - stream bytes both ways
5. 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> } }
#
# 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.
# Save it if your client logic depends on it. Same rates apply to AI agents,
# Android SDK devices, and modem 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
const ws = new WebSocket(register.relay || 'wss://relay.proxies.sx', [`token.${JWT}`]);

ws.onopen = () => {
  ws.send(JSON.stringify({ type: 'device_info', payload: { country: 'US', supportsRelayRedirect: true } }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'proxy_request') {
    const { requestId, method, url, headers, body } = msg.payload;
    fetch(url, { method, headers, body: body ? atob(body) : undefined })
      .then(async (res) => {
        const buf = await res.arrayBuffer();
        ws.send(JSON.stringify({
          type: 'proxy_response',
          payload: { requestId, statusCode: res.status,
                     headers: Object.fromEntries(res.headers),
                     body: btoa(String.fromCharCode(...new Uint8Array(buf))) }
        }));
      });
  }
  if (msg.type === 'heartbeat') ws.send(JSON.stringify({ type: 'heartbeat_ack' }));
};
```

### 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 (3/min 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) |

### WebSocket Message Types

**Outgoing (you send):**
| Type | Description |
|------|-------------|
| `device_info` | Device metadata (country, carrier) |
| `proxy_response` | Response to a proxy request |
| `proxy_error` | Error handling proxy request |
| `heartbeat_ack` | Response to heartbeat ping |

**Incoming (you receive):**
| Type | Description |
|------|-------------|
| `connected` | Connection established |
| `proxy_request` | HTTP request to route |
| `heartbeat` | Keepalive ping |

### Security

| Feature | Value |
|---------|-------|
| JWT expiry | 1 hour |
| Refresh token expiry | 7 days |
| Max connections per device | 2 |
| Message rate limit | 100/min per device |
| Registration rate limit | 3/min per IP |
| Wallet change cooling | 7 days |
| IP classification | Server-side ASN lookup (cannot spoof) |
| Withdrawal rate limit | 3/hour |

### Monthly Earnings Estimates (post-rates-deploy 2026-04-28)

Earnings depend on demand-side traffic - the network earns from real customers; you earn a fixed share of the $4/GB price by IP type (mobile $1.80, residential $1.20, datacenter $0.30 per GB, net). Below are illustrative ranges assuming moderate-to-high demand routing through your IP.

| Connection | Always-On | Part-Time (8h/day) | At 100GB/month |
|------------|-----------|---------------------|----------------|
| Mobile 5G (US) | $250-$600 | $80-$200 | $180 |
| Residential (US) | $50-$200 | $15-$80 | $120 |
| Datacenter VPS | $3-$30 | $1-$10 | $30 |

Actual earnings depend on demand, location, uptime, and carrier ASN reputation. Live demand sources: AI agents purchasing proxies via x402, pool gateway customers, and reseller storefronts.

---

## SDK & Packages

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

| Package | Version | Description |
|---------|---------|-------------|
| [@proxies-sx/mcp-server](https://www.npmjs.com/package/@proxies-sx/mcp-server) | 2.0.0 | MCP server - 72 tools |
| [@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 |

Plus reseller-toolkit packages from `proxy-reseller-kit`: `@proxies-sx/pool-sdk` and `@proxies-sx/pool-portal-react` (v0.1.0 each).

### Other distribution

| Package | Channel | Description |
|---------|---------|-------------|
| `bolivian-peru:android-peer-sdk:1.3.1` | JitPack | Android peer SDK (Kotlin) |

### GitHub Repositories

| Repository | Purpose |
|------------|---------|
| [proxies-sx-mcp-server](https://github.com/bolivian-peru/proxies-sx-mcp-server) | MCP server source (72 tools) |
| [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) |
| [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` - 55 proxy management tools
### Lucid Agents (Daydreams)

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

---

## Live Domains

| Domain | Purpose |
|--------|---------|
| api.proxies.sx | REST API + x402 (38 routes) + Swagger (`/docs/api`) |
| 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 |
| gw.proxies.sx | Pool gateway (HTTP :7000, SOCKS5 :7001, health :7080) |
| proxies.sx | Main marketing website |
| docs.proxies.sx | Documentation |
| reseller.proxies.sx | Reseller portal |

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

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