# /pool - Proxies.sx Pool Gateway Access (x402 USDC)

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

> Buy metered Pool Gateway Access with one USDC payment. One credential reaches every country in your tier through gw.proxies.sx:7000. No account, no signup, no API key - just a wallet.

> **Two products - know which one you are buying.** This file is the POOL GATEWAY: one credential on gw.proxies.sx:7000, every country in the tier - country, session and rotation are declared per-request in the proxy username. The other product is the DEDICATED PORT (`/v1/x402/proxy`): one real port on one modem, its own host:port, one country fixed at purchase - the modem is exclusively yours and rotates only when YOU hit the rotate URL (carrier NAT can still re-issue the exit IP), and it is the one with SOCKS5. Pick the dedicated port for cookie-bound/login/2FA work in one country, SOCKS5, or on-demand true carrier-IP resets - its skill file is [/marketplace/skill.md](https://agents.proxies.sx/marketplace/skill.md); pick this pool credential for multi-country work, high fan-out and zero babysitting. Same $4.00/GB, same 0.1 GB minimum, same modems - the difference is topology, not hardware or price. Full comparison: [Pool Access vs Dedicated Port](#pool-access-vs-dedicated-port---which-to-buy).

**Economics:** $4.00/GB, minimum purchase 0.1 GB ($0.40). Duration is free.

**First request (no auth, no payment):**

```bash
curl -s "https://api.proxies.sx/v1/x402/pool/pricing"
```

Then request `GET /v1/x402/pool` without payment - the HTTP 402 response IS the catalog (exact amount, recipient, asset). Pay USDC on-chain, retry the same request with `Payment-Signature: <tx_hash>`, and you receive credentials. Full sequence: [Complete Purchase Workflow](#complete-purchase-workflow).

> **Hierarchy:** this skill.md is the canonical Pool Gateway Access contract. If any other file disagrees with it, this file wins. If this file disagrees with the live API, the live API wins.

## Overview

This skill lets a wallet-only AI agent purchase Pool Gateway Access via the x402 protocol. You pay USDC on-chain (Base or Solana), retry the request with the transaction hash, and receive a working proxy credential plus a session token (`x402s_*`) for self-service management (credit, top-up, usage, regenerate).

How it works under the hood: your payment mints a GB-capped pak key (`pak_*`) - it goes in the proxy **password** field. The GB cap IS your credit envelope - the gateway meters every byte, and the credential auto-suspends when the cap is reached. Top up with more USDC to keep going.

- **Payment:** USDC on Solana (~400ms settlement) or Base (~2s settlement)
- **Price (v1, `mbl` tier):** $4.00/GB, minimum purchase 0.1 GB ($0.40)
- **Duration:** FREE - you only pay for traffic. Default 30 days, maximum 90 days.
- **Coverage:** one credential covers EVERY country in your tier with live stock - retarget via the username, no repurchase per country
- **Protocol:** HTTP proxy on `gw.proxies.sx:7000` only in v1 (no SOCKS5)

**The honest quality story:**

| 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, metered so you pay only for delivered bytes. Request `tier=peer` for the widest coverage. |
| `peer_mobile` | Disabled (returns 400) | Reserved for future mobile-peer separation, off pending gateway ipType enforcement. Use `peer` or `mbl`. |

The `mbl` credential is quality-locked: even if you write `peer` in the username, the gateway silently serves you from production modems. That is by design - you can never accidentally land on the community pool.

---

## Quick Reference

| Action | Endpoint | Auth |
|--------|----------|------|
| Discover pricing | `GET /v1/x402/pool/pricing` | None |
| Buy access | `GET` or `POST /v1/x402/pool` | x402 payment (10/min) |
| Check live stock | `GET /v1/gateway/pool/stock` | None (counts only, never IPs) |
| Check credit | `GET /v1/x402/manage/pool/credit` | `X-Session-Token` |
| Re-emit credentials | `GET /v1/x402/manage/pool/connection` | `X-Session-Token` |
| Usage history | `GET /v1/x402/manage/pool/usage?days=30` | `X-Session-Token` |
| Regenerate password | `POST /v1/x402/manage/pool/regenerate` | `X-Session-Token` (3/hour) |
| Top up | `POST /v1/x402/manage/pool/topup` | `X-Session-Token` + payment (5/min) |
| Use the proxy | `http://USERNAME:pak_KEY@gw.proxies.sx:7000` | Credential from purchase |

**Base URL:** `https://api.proxies.sx`
**Gateway:** `gw.proxies.sx:7000` (HTTP proxy, CONNECT supported)

---

## Complete Purchase Workflow

### Step 1: Discover Pricing

```http
GET https://api.proxies.sx/v1/x402/pool/pricing
```

**Response (live, abbreviated):**
```json
{
  "product": "pool",
  "tiers": [
    {
      "tier": "mbl",
      "pricePerGB": 4,
      "currency": "USDC",
      "minPurchaseGB": 0.1,
      "quality": "production tier - ProxySmart modems, 6 countries, 10-15 Mbps, sub-1s TTFB, 100% success",
      "allowedIpTypes": ["mobile"]
    }
  ],
  "defaultTier": "mbl",
  "durationFree": true,
  "maxDurationSeconds": 7776000,
  "stockUrl": "https://api.proxies.sx/v1/gateway/pool/stock",
  "usernameDsl": "psx_<house>-{pool}-{country}[-sid-{8-64 a-z0-9_}][-rot-{sticky|hard|auto5|auto10|auto20|auto60|ondemand}][-carrier-..][-city-..]",
  "networks": [
    { "network": "base", "usdcAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "recipientAddress": "0xF8cD900794245fc36CBE65be9afc23CDF5103042" },
    { "network": "solana", "usdcAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "recipientAddress": "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv" }
  ]
}
```

Check live per-country stock BEFORE buying for a specific country (the catalog's country list can drift from live stock):

```bash
curl -s https://api.proxies.sx/v1/gateway/pool/stock
# Returns endpoint COUNTS per pool + country. Never exposes IPs.
```

### Step 2: Request Without Payment (the 402 IS the catalog)

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

You get an HTTP 402 with everything needed to pay:

```json
{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "4000000",
      "payTo": "0xF8cD900794245fc36CBE65be9afc23CDF5103042",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "description": "Pool Gateway mbl access: 1 GB at $4/GB = $4 USDC. One credential, every country in the tier, metered + capped."
    },
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "4000000",
      "payTo": "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ],
  "pool": {
    "tier": "mbl",
    "pricePerGB": 4,
    "trafficGB": 1,
    "amountUSDC": 4,
    "stockUrl": "https://api.proxies.sx/v1/gateway/pool/stock",
    "management": {
      "credit": "GET /v1/x402/manage/pool/credit",
      "topup": "POST /v1/x402/manage/pool/topup",
      "usage": "GET /v1/x402/manage/pool/usage",
      "regenerate": "POST /v1/x402/manage/pool/regenerate",
      "connection": "GET /v1/x402/manage/pool/connection"
    }
  }
}
```

**IMPORTANT - which 402 fields to trust:**
- `accepts[].maxAmountRequired` (micro-USDC, 6 decimals) is the authoritative price. `accepts[].payTo` + `accepts[].asset` are the authoritative recipient + token.
- The `pool` block is the authoritative pool catalog.
- **Ignore `accepts[].outputSchema`** - it is inherited from the dedicated-port product and is WRONG for pool purchases (it claims `tier: shared`, `duration` required, a `socksPort` output, and a 30-day max). The real pool parameters are in the table below.

**Purchase parameters** (query string on GET, JSON body on POST - both merged):

| Param | Required | Values | Default |
|-------|----------|--------|---------|
| `tier` | No | `mbl` (6-country carrier modems) or `peer` (flagship, ~82 countries) - both $4/GB | `mbl` |
| `country` | No | 2-letter ISO code or `any`. Only sets the country token in your STARTING username - you can retarget any country later | `any` |
| `traffic` | Yes | GB, 0.1 to 1000 | - |
| `duration` | No | Seconds, up to 7776000 (90 days). FREE - does not change the price | 2592000 (30 days) |
| `sid` | No | Session id, 8-64 chars `[a-z0-9_]`. Auto-generated if absent or invalid | auto |
| `rot` | No | `sticky`, `hard`, `auto5`, `auto10`, `auto20`, `auto60`, `ondemand` | `sticky` |

### Step 3: Pay USDC On-Chain

Send the exact `maxAmountRequired` (micro-USDC) to the `payTo` address of your chosen network. A 2% underpay tolerance is allowed (gas dust / rounding). The transaction must be a direct on-chain USDC transfer, confirmed, and less than 24 hours old.

| Network | Recipient | USDC Contract / Mint | Settlement |
|---------|-----------|----------------------|------------|
| Base | `0xF8cD900794245fc36CBE65be9afc23CDF5103042` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` | ~2s, ~$0.01 gas |
| Solana | `6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | ~400ms, ~$0.0001 gas |

Example sends ($4.00 = 4000000 micro-USDC):

```bash
# Base (any EVM tooling works - this is foundry's cast)
cast send 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 \
  "transfer(address,uint256)" \
  0xF8cD900794245fc36CBE65be9afc23CDF5103042 4000000 \
  --rpc-url https://mainnet.base.org --private-key $PRIVATE_KEY
# Save the printed transaction hash (0x...)

# Solana (spl-token CLI; amount is in whole USDC)
spl-token transfer EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v 4 \
  6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv \
  --fund-recipient --allow-unfunded-recipient
# Save the printed transaction signature (base58)
```

**Payment rules (verified on-chain by the server):**
- The recipient AND the USDC asset are pinned - a payment to any other address or in any other token is rejected.
- Only direct on-chain transactions are accepted. Signed-intent / facilitator payloads are rejected - settle on-chain and send the tx hash.
- Each transaction hash mints exactly ONE credential. The same hash can NOT also buy a dedicated port (`/v1/x402/proxy`) - that returns 409.

### Step 4: Retry With the Payment Proof

Send the same request with the `Payment-Signature` header (aliases `X-Payment-Signature` and `Payment` also work on this endpoint):

```bash
# Base
curl -s "https://api.proxies.sx/v1/x402/pool?tier=mbl&country=us&traffic=1&sid=myagent01&rot=sticky" \
  -H "Payment-Signature: 0xYOUR_BASE_TX_HASH"

# Solana
curl -s "https://api.proxies.sx/v1/x402/pool?tier=mbl&country=us&traffic=1&sid=myagent01&rot=sticky" \
  -H "Payment-Signature: YOUR_SOLANA_TX_SIGNATURE"
```

**Response (HTTP 200):**

```json
{
  "product": "pool",
  "proxy": {
    "host": "gw.proxies.sx",
    "httpPort": 7000,
    "username": "psx_x402pool-mbl-us-sid-myagent01-rot-sticky",
    "password": "pak_a1b2c3d4e5f6...",
    "http": "http://psx_x402pool-mbl-us-sid-myagent01-rot-sticky:pak_a1b2c3d4e5f6...@gw.proxies.sx:7000",
    "socks5": null,
    "usernameTemplate": "psx_x402pool-{pool}-{country}[-sid-{8-64 a-z0-9_}][-rot-{sticky|hard|auto5|auto10|auto20|auto60|ondemand}][-city-..][-carrier-..]",
    "allowed": { "tier": "mbl", "ipTypes": ["mobile"], "countries": "any with stock - see stockUrl" }
  },
  "credit": {
    "allocatedGB": 1,
    "usedGB": 0,
    "remainingGB": 1,
    "expiresAt": "2026-07-12T00:00:00.000Z",
    "enabled": true
  },
  "sessionToken": "x402s_abc123...",
  "manage": {
    "credit": "GET /v1/x402/manage/pool/credit",
    "topup": "POST /v1/x402/manage/pool/topup",
    "usage": "GET /v1/x402/manage/pool/usage",
    "regenerate": "POST /v1/x402/manage/pool/regenerate",
    "connection": "GET /v1/x402/manage/pool/connection"
  },
  "stockUrl": "https://api.proxies.sx/v1/gateway/pool/stock",
  "quality": { "tier": "mbl", "story": "production tier - ProxySmart modems, 6 countries, 10-15 Mbps, sub-1s TTFB, 100% success" },
  "caveats": [
    "sticky pins the MODEM, not the IP - carrier NAT may re-issue exit IPs; for a held IP use the dedicated port product (/v1/x402/proxy)",
    "sticky/auto* require -sid- (8-64 chars a-z0-9_) to persist across connections",
    "no token value may contain '-' (username is lowercased and split on '-')",
    "mbl tier: peer routes in the username are silently served from modems (quality-tier safe rewrite) - by design",
    "HTTP :7000 only in v1 - SOCKS5 :7001 rejects this credential",
    "cap suspension lands within ~5-35s of the GB cap; no refunds of unused GB"
  ],
  "payment": { "txHash": "0x...", "network": "base", "amountUSDC": 4 }
}
```

**Save THREE things:**
1. `proxy.password` (the `pak_*` key) - your proxy password
2. `sessionToken` (`x402s_*`) - required for ALL manage endpoints
3. `payment.txHash` - your last-resort recovery handle

**Idempotent retries:** if the response is lost (timeout, crash), retry the exact same call with the same `Payment-Signature`. The server recognizes the already-redeemed transaction and re-emits the SAME credentials and session token. You are never double-charged.

### Step 5: Connect Through the Gateway

The username is a `-`-delimited token string. It is lowercased and split on `-`, so no token value may itself contain a `-` (write `tmobile`, never `t-mobile`). The password is always your `pak_*` key.

```
psx_x402pool-{pool}-{country}[-sid-{name}][-rot-{mode}][-city-{city}][-carrier-{carrier}]
```

```bash
# Use the credential exactly as returned
curl -x "http://psx_x402pool-mbl-us-sid-myagent01-rot-sticky:pak_YOUR_KEY@gw.proxies.sx:7000" \
  https://api.ipify.org

# Retarget a different country - SAME credential, no repurchase.
# Just edit the country token. The live set is whatever stockUrl reports -
# check it first. As of last edit: us, gb, pl, fr, nl, ge (ge = Georgia, not Germany):
curl -x "http://psx_x402pool-mbl-nl-sid-myagent01-rot-sticky:pak_YOUR_KEY@gw.proxies.sx:7000" \
  https://api.ipify.org

# Rotate every 10 minutes instead of pinning:
curl -x "http://psx_x402pool-mbl-us-sid-myagent01-rot-auto10:pak_YOUR_KEY@gw.proxies.sx:7000" \
  https://api.ipify.org

# Parallel isolated sessions - one sid per worker:
curl -x "http://psx_x402pool-mbl-us-sid-worker_001-rot-sticky:pak_YOUR_KEY@gw.proxies.sx:7000" \
  https://api.ipify.org
```

**Username tokens:**

| Token | Example | Meaning |
|-------|---------|---------|
| pool | `-mbl-` | Pool tier. With this credential any pool token is served from production modems (safe rewrite) |
| country | `-us-` / `-nl-` / `-any-` | ISO 3166-1 alpha-2 or `any`. Check live stock before targeting |
| sid | `-sid-myagent01` | Session id, 8-64 chars `[a-z0-9_]`. Same sid returns to the same modem. REQUIRED for `sticky`/`auto*` to persist across connections |
| rot | `-rot-sticky` | Rotation mode (table below). If you omit the token entirely, the gateway default is `auto10` |
| city | `-city-newyork` | Soft preference |
| carrier | `-carrier-tmobile` | Soft preference |
| failover | `-failover-samecarrier` | If the exit dies mid-request, where to retry: `any`, `samecountry` (default), `samecarrier`, `samenode` (same relay server), `strict` (fail instead of retrying elsewhere) |
| ttl | `-ttl-7200` | Session-row TTL in seconds, clamped 60-2592000, default 3600. NOT an IP-hold guarantee |

**Rotation modes:**

| Mode | Behavior |
|------|----------|
| `sticky` | Pin one modem for the session (gateway picks the most IP-stable one). Recommended default |
| `sticky-strict` | Pins like `sticky` but hardens the IP-stability weighting - best for login/cookie/2FA flows. The gateway parses it as `rot=sticky` plus a `strict` flag, so its internal hyphen is safe. Needs a `-sid-` |
| `hard` | Pins like `sticky`. It does NOT mean a new IP per request |
| `auto5` / `auto10` / `auto20` / `auto60` | Switch to a different modem every 5/10/20/60 minutes |
| any other `auto<N>` | The gateway snaps it to the nearest of 5/10/20/60 (e.g. `auto30` -> `auto20`) and records the fix in its corrections log - do not invent intervals |
| `ondemand` | Re-pick a modem on each new connection |

> **Sticky pins the MODEM, not the IP.** Mobile carriers re-issue NAT egress IPs on their own cadence, so a perfectly pinned modem can still surface different exit IPs. If your workflow needs one immutable IP, use the dedicated port product (`/v1/x402/proxy`) instead.

> **HTTP only in v1.** Connect to `gw.proxies.sx:7000` as an HTTP proxy (CONNECT tunneling works for HTTPS targets). SOCKS5 on :7001 is not supported for this credential.

---

## Manage Your Credential

All management endpoints authenticate with the session token from the purchase response:

```
Header: X-Session-Token: x402s_...
```

### Check Credit

```bash
curl -s https://api.proxies.sx/v1/x402/manage/pool/credit \
  -H "X-Session-Token: x402s_YOUR_TOKEN"
```

```json
{
  "tier": "mbl",
  "allocatedGB": 1,
  "usedGB": 0.2143,
  "remainingGB": 0.7857,
  "enabled": true,
  "expiresAt": "2026-07-12T00:00:00.000Z",
  "sessionToken": "x402s_..."
}
```

Metering is read-through and live: `remainingGB = allocatedGB - usedGB`. When `usedGB` reaches the cap, `enabled` flips to `false` automatically (within ~5-35s) and the gateway starts rejecting auth with 407. Top up to re-enable.

### Re-Emit Connection Details

Lost the password but kept the session token? This re-emits the full purchase response (credentials, username template, credit, caveats):

```bash
curl -s https://api.proxies.sx/v1/x402/manage/pool/connection \
  -H "X-Session-Token: x402s_YOUR_TOKEN"
```

### Usage History

```bash
curl -s "https://api.proxies.sx/v1/x402/manage/pool/usage?days=30" \
  -H "X-Session-Token: x402s_YOUR_TOKEN"
# Response: { "tier": "mbl", "days": 30, "usage": [ per-day traffic series ] }
# days: 1-365, default 30
```

### Regenerate the Password

If the `pak_*` key leaks, mint a new secret. The old password stops working immediately; the username and remaining credit are unchanged. Rate limited to 3/hour.

```bash
curl -s -X POST https://api.proxies.sx/v1/x402/manage/pool/regenerate \
  -H "X-Session-Token: x402s_YOUR_TOKEN"
# Response: full connection shape with the NEW pak_ password
```

### Top Up (more GB and/or more time)

Traffic costs money (priced at YOUR session's locked-in per-GB rate). Duration extension is free. A successful traffic top-up also re-enables a cap-suspended credential.

```bash
# 1. Ask without payment -> 402 tells you the exact amount
curl -s -X POST https://api.proxies.sx/v1/x402/manage/pool/topup \
  -H "X-Session-Token: x402s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addTrafficGB": 2}'
# 402: "Top-up requires payment: 2GB at $4/GB = $8 USDC. Send USDC then retry with Payment-Signature."

# 2. Send USDC on-chain (same recipients as the purchase), then retry with the NEW tx hash
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": 2, "addDurationSeconds": 2592000}'
# Response: updated credit object

# Duration-only extension is FREE - no payment header needed:
curl -s -X POST https://api.proxies.sx/v1/x402/manage/pool/topup \
  -H "X-Session-Token: x402s_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"addDurationSeconds": 2592000}'
```

**Top-up rules:**
- Each tx hash is redeemable exactly once. Reusing your purchase hash or a previous top-up hash returns 409 and adds nothing.
- Same 2% underpay tolerance. Underpaid returns 400 with the exact micro-USDC amount needed.
- `addDurationSeconds` is clamped to 90 days per call. Rate limited to 5/min.
- This endpoint reads the payment proof from the `Payment-Signature` header only.

---

## Error Handling

### Purchase + management errors (API, JSON bodies)

| Status | When | What to do |
|--------|------|------------|
| 402 | No payment header - this is the catalog, not a failure | Pay, retry with `Payment-Signature` |
| 402 | `underpaid: need N USDC micro ... got M` | Send the difference as a NEW tx for the full amount, retry with the new hash |
| 402 | Payment verification failed (wrong recipient/asset, unconfirmed, older than 24h, unsupported format) | Fix the payment; only direct on-chain Base/Solana USDC transfers are accepted |
| 400 | Bad params (`traffic must be a number between 0.1 and 1000 GB`, unknown/disabled tier, bad topup amounts) | Fix the request. Only `mbl` is purchasable in v1 |
| 400 | `invalid or expired session token` / `this session is not a pool-access session` | Use the `x402s_*` token from a POOL purchase |
| 409 | `transaction already redeemed for a dedicated port` | One tx = one product. Send a new payment |
| 409 | `topup payment already redeemed (replay) - no GB added` | Each tx hash works once. Send a new payment |
| 409 | `provisioning race - please retry with the same payment` | Retry the identical call - it re-emits your credentials |
| 429 | Throttled: buy 10/min, topup 5/min, regenerate 3/hour | Back off and retry |
| 503 | `pool product not configured` | Product is disabled server-side. Try later or file a ticket |

### Connection-time errors (gateway, `CODE: message (req: <uuid>)` bodies)

| Code | Status | Meaning | What to do |
|------|--------|---------|------------|
| `E_AUTH_REQUIRED` | 407 | No Proxy-Authorization | Send username + pak_ password |
| `E_AUTH_INVALID` | 407 | Bad credential, GB cap reached, or key disabled | Check credit; top up if `remainingGB` is 0 |
| `E_USERNAME_PARSE` | 400 | Username missing or over 256 chars. The parser self-heals bad optional tokens (sanitizes + defaults) rather than rejecting, so this only fires on a missing/oversized username, not on a malformed `-sid-`/`-rot-` value | Ensure the account id and a username are present and under 256 chars |
| `E_RATE_LIMITED_AUTH` | 429 | Too many failed auth attempts | Back off 30s (escalates to 5min) |
| `E_RATE_LIMITED_CONN` | 429 | Over 500 concurrent connections per account (default; resellers can be raised) | Lower parallelism |
| `E_NO_STOCK_COUNTRY` | 502 | No online endpoints for that country | failMsg suggests an alternative; check stockUrl; retry in 60s |
| `E_STOCK_DEGRADED` | 502 | Selected endpoint dropped mid-request | Retry - the selector picks another |
| `E_SESSION_LIMIT` | 429 | Over 250 concurrent sessions per account (default; resellers can be raised) | Recycle `-sid-` values |
| `E_SSRF_BLOCKED` | 403 | Target is private/localhost/cloud-metadata | Use a public target |
| `E_INTERNAL` | 503 | Unexpected | File a ticket with the req id |

Authoritative list: [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 - quote the `req` id from the error body.

### Recovery matrix

| You still have | Recovery |
|----------------|----------|
| `sessionToken` | `GET /v1/x402/manage/pool/connection` re-emits everything |
| Only the purchase `txHash` | Retry `GET /v1/x402/pool` with `Payment-Signature: <txHash>` - re-emits the same credentials + session token |
| Leaked password | `POST /v1/x402/manage/pool/regenerate` - new secret, same credit |
| Nothing | Unrecoverable. Always persist `sessionToken` + `txHash` at purchase time |

---

## Caveats (Read Before You Build)

These come back verbatim in every purchase response - they are the contract:

1. **Sticky pins the MODEM, not the IP.** Carrier NAT may re-issue exit IPs even on a pinned modem. For a held IP use the dedicated port product (`/v1/x402/proxy`).
2. **`sticky`/`auto*` require a `-sid-`** (8-64 chars `[a-z0-9_]`) to persist across connections. Without one, every connection starts a fresh synthetic session.
3. **No token value may contain `-`** - the username is lowercased and split on `-`.
4. **mbl tier is quality-locked:** `peer` routes in the username are silently served from modems (safe rewrite) - by design, never a bug.
5. **HTTP `:7000` only in v1.** SOCKS5 `:7001` is not supported for this credential.
6. **Cap suspension lands within ~5-35s** of hitting the GB cap. **No refunds of unused GB.** Top-ups re-enable a suspended credential.
7. **Per-GB metered only.** There is no flat-rate or unlimited plan. Duration is free; traffic is the only thing you pay for.

---

## End-to-End Worked Example

Buying 0.5 GB ($2.00) of US-targeted production mobile access with USDC on Solana:

```bash
BASE=https://api.proxies.sx

# 1. Discover the price and the recipient
curl -s $BASE/v1/x402/pool/pricing
# -> mbl $4/GB, Solana recipient 6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv

# 2. Confirm US stock exists (counts only)
curl -s $BASE/v1/gateway/pool/stock

# 3. Get the exact quote (402 = catalog). 0.5 GB -> maxAmountRequired "2000000" (micro-USDC)
curl -s "$BASE/v1/x402/pool?tier=mbl&country=us&traffic=0.5&sid=demo_agent_01&rot=sticky"

# 4. Pay $2.00 USDC on Solana
spl-token transfer EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v 2 \
  6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv \
  --fund-recipient --allow-unfunded-recipient
# -> Signature: 5KtP...xyz

# 5. Retry with the signature -> credentials
curl -s "$BASE/v1/x402/pool?tier=mbl&country=us&traffic=0.5&sid=demo_agent_01&rot=sticky" \
  -H "Payment-Signature: 5KtP...xyz"
# -> Save: proxy.password (pak_...), sessionToken (x402s_...), payment.txHash

# 6. Use it - US mobile exit through a production modem
curl -x "http://psx_x402pool-mbl-us-sid-demo_agent_01-rot-sticky:pak_YOUR_KEY@gw.proxies.sx:7000" \
  https://api.ipify.org

# 7. Retarget the UK with the SAME credential - no repurchase
#    (pick any country stockUrl reports live mbl stock for - as of last edit: us, gb, pl, fr, nl, ge)
curl -x "http://psx_x402pool-mbl-gb-sid-demo_agent_01-rot-sticky:pak_YOUR_KEY@gw.proxies.sx:7000" \
  https://api.ipify.org

# 8. Watch the meter
curl -s $BASE/v1/x402/manage/pool/credit -H "X-Session-Token: x402s_YOUR_TOKEN"
# -> { "allocatedGB": 0.5, "usedGB": 0.0312, "remainingGB": 0.4688, "enabled": true }

# 9. Running low? Top up 1 GB ($4.00) - new payment, new tx hash
spl-token transfer EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v 4 \
  6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv
curl -s -X POST $BASE/v1/x402/manage/pool/topup \
  -H "X-Session-Token: x402s_YOUR_TOKEN" \
  -H "Payment-Signature: NEW_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{"addTrafficGB": 1}'
# -> { "allocatedGB": 1.5, ... } - and a cap-suspended key is re-enabled
```

---

## Pool Access vs Dedicated Port - Which to Buy

| | Pool Gateway Access (this skill) | Dedicated Port (`/v1/x402/proxy`) |
|---|---|---|
| Endpoint | `GET/POST /v1/x402/pool` | `GET/POST /v1/x402/proxy` |
| What you get | One credential, every country in the tier, shared modem pool | One dedicated modem port in one country |
| Country switching | Edit the username token - instant, free | New purchase per country |
| IP stability | Sticky pins a modem; carrier NAT may still re-issue the IP | Same carrier-NAT caveat, but the modem is exclusively yours |
| IP rotation | `rot` modes (modem switching) | Explicit `/rotate/:token` (carrier IP reset) |
| Protocols | HTTP :7000 only (v1) | HTTP + SOCKS5 |
| Price | $4/GB, min 0.1 GB | $4/GB, min 0.1 GB |

Both are paid the same way (x402 USDC, Base or Solana). One tx hash buys exactly one of them - never both.

---

## Links

| Resource | URL |
|----------|-----|
| This skill file | https://agents.proxies.sx/pool/skill.md |
| Live pricing API | https://api.proxies.sx/v1/x402/pool/pricing |
| Live stock (counts only) | https://api.proxies.sx/v1/gateway/pool/stock |
| Master skill (full infra) | https://agents.proxies.sx/skill.md |
| Dedicated port skill | https://agents.proxies.sx/marketplace/skill.md |
| Earn as a peer | https://agents.proxies.sx/peer/skill.md |
| x402 discovery | https://agents.proxies.sx/.well-known/x402.json |
| docs-manifest.json (truth) | https://agents.proxies.sx/docs-manifest.json |
| llms.txt | https://agents.proxies.sx/llms.txt |

---

## Changelog

- **2026-06-12**: Initial release. v1 = `mbl` tier only ($4/GB, production modems, HTTP :7000). Buy via `GET/POST /v1/x402/pool` (402 catalog -> pay USDC on Base/Solana -> `Payment-Signature` retry). Management via `X-Session-Token`: credit, connection, usage, regenerate (3/hour), topup (5/min, replay-guarded, re-enables cap-suspended keys). Idempotent purchase retries by tx hash. `peer`/`peer_mobile` tiers gated off pending gateway IP-type enforcement.

---

*Managed by Maya (openclaw bot) | Pool Gateway Access (x402)* | <https://agents.proxies.sx/pool/skill.md>