# /marketplace - Proxies.sx Mobile Proxy (Dedicated Port)

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

> Machine-readable catalog for AI agents - buy the standard way with an account + `psx_` API key + deposited GB, or wallet-only with x402 USDC. Canonical contract: this file for the Mobile Proxy; the per-product skill.md for the other products. If any file disagrees with a skill.md, the skill.md wins. If a skill.md disagrees with the live API, the live API wins.

> **Two distinct products - do not confuse them.** This file sells the **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 Access** is the other product: one credential on `gw.proxies.sx:7000`, every country in the tier - country, session and rotation are declared per-request in the proxy username. Pool contract: https://agents.proxies.sx/pool/skill.md

**Two ways to buy this product:**

| Path | For | First request |
|------|-----|---------------|
| **Account + API key + deposited GB** (the standard way - how most users buy) | Anyone with a Proxies.sx account; deposit balance by card or hosted crypto checkout, no per-purchase on-chain payment | `POST /v1/ports` with `X-API-Key` - see "Buy with your account + API key" below |
| **x402 USDC** (wallet-only alternative) | Account-less agents paying per purchase on-chain | `GET /v1/x402/proxy` (the 402 response IS the catalog) |

**First action, standard path (account + API key):**

```bash
curl -s "https://api.proxies.sx/v1/countries/with-devices?pool=dedicated" -H "X-API-Key: psx_YOUR_KEY"
# -> countries with free dedicated-port modems + the countryId you need for POST /v1/ports
#    (authenticated, scope ports:read). Without ?pool=dedicated the list also includes every
#    peer-pool country with peerDeviceCount / peerMobileCount (dedicatedAvailable:false, no _id).
```

**First action, x402 path (no auth, no payment):**

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

Then request `GET /v1/x402/proxy` without payment - the HTTP 402 response IS the catalog (exact amount, recipient, asset). Pay USDC on-chain, retry with `Payment-Signature: <tx_hash>`, receive credentials. Full sequence below.

## The three maintained products

| Product | What it is | First request | Price |
|---------|------------|---------------|--------------|
| **Mobile Proxy** (this file) | Dedicated 4G/5G port, one modem, yours for the session | `POST /v1/ports` (API key) or `GET/POST /v1/x402/proxy` (x402) | $4/GB |
| **Pool Gateway Access** | One credential, every country in the tier via `gw.proxies.sx:7000` | `GET/POST /v1/x402/pool` - contract: https://agents.proxies.sx/pool/skill.md | $4/GB |
| **Peer Network** (earn side) | Share bandwidth, get paid in USDC per GB | `POST /v1/peer/agents/register` - contract: https://agents.proxies.sx/peer/skill.md | earn per GB |

## Overview

A real 4G/5G mobile proxy. Two purchase paths:

- **Standard (most users):** Proxies.sx account + API key + deposited GB. Create ports with `POST /v1/ports`, manage/rotate them over the REST API. See "Buy with your account + API key" below.
- **x402 (wallet-only):** pay USDC per purchase, no signup, no API keys. `GET/POST /v1/x402/proxy`. See "Universal x402 Payment Flow" below.

- **Payment:** deposited GB from your account balance (card via Stripe, or hosted crypto checkout), OR x402 USDC on Solana (~400ms settlement) / Base (~2s settlement)
- **Infrastructure:** Real 4G/5G mobile proxies from 6 countries (NL, PL, US, GE (Georgia), FR, GB - live set shifts with supply, see /v1/x402/countries). For broader coverage (~127 countries with live stock), buy the Pool Gateway `tier=peer` instead: https://agents.proxies.sx/pool/skill.md
- **Pricing:** $4/GB. Duration is FREE - only pay for traffic.
- **Tier:** shared only. A `tier=private` request is silently served as shared at the $4/GB rate (never rejected) - just omit the parameter.

---

## Buy with your account + API key (the standard way)

This is how most users buy the Dedicated Port: create a Proxies.sx account, deposit balance, convert balance to GB, then create and manage ports over the REST API with an API key. Deposited GB is the traffic budget - there is no charge at port creation, GB is debited as traffic flows. No on-chain payment per purchase.

**API key basics:**

- Format: `psx_` + 32 hex chars. Returned **once** at creation - store it. Max **5 active keys** per account.
- Send it as `X-API-Key: psx_...` **or** `Authorization: ApiKey psx_...` on any endpoint below.
- Per-key rate limit: default 100 req/min (configurable 10-1000).
- Keys are managed with a **JWT session only** (`Authorization: Bearer` from `/v1/login/signin`) - you cannot mint or revoke a key with a key.
- Scopes a customer key can carry: `ports:read`, `ports:write`, `ports:rotate`, `billing:read`, `account:read`, `account:write`, `traffic:read`, `tickets:read`, `tickets:write`. Default if none given: `ports:read, account:read, traffic:read`. Customer keys can NOT carry `billing:write` - the balance-to-GB purchase runs in the account (JWT) session; reseller/admin keys may automate purchases.

### Setup (once)

```bash
# 1. Create an account, open the verification link emailed to it (valid 24 hours; sign-in answers 401
#    until then; from a script: GET /v1/login/verify-email?token=<token from the link>), sign in (JWT)
curl -X POST https://api.proxies.sx/v1/login/signup \
  -H 'Content-Type: application/json' -d '{"email":"agent@example.com","password":"..."}'
curl -X POST https://api.proxies.sx/v1/login/signin \
  -H 'Content-Type: application/json' -d '{"email":"agent@example.com","password":"..."}'
# -> { "access_token": "<JWT>" }

# 2. Mint the API key (JWT-only step; the key is shown once)
curl -X POST https://api.proxies.sx/v1/api-keys \
  -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' \
  -d '{"name":"agent","scopes":["ports:read","ports:write","ports:rotate","billing:read","account:read","traffic:read"]}'
# -> { "apiKey": "psx_<32hex>", "keyInfo": { ... } }
```

### Fund + deposit GB

Top up money via the portal (Stripe card / saved card, or hosted crypto checkout - JWT session), then convert balance to GB:

```bash
# Preview the price (works with a billing:read key)
curl 'https://api.proxies.sx/v1/billing/calculate-price?amount=50' -H "X-API-Key: psx_..."
# -> { "pricePerGB": 3.20, "totalPrice": 160, "discountPercent": 20, ... }

# Convert balance -> GB (JWT session for customers)
curl -X POST https://api.proxies.sx/v1/billing/purchase-traffic \
  -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"amount":50}'
# 400 "Insufficient balance. Required: X, Available: Y" if balance < price
```

Pricing: **$4/GB**, volume-discounted - 10% at 25 GB, 20% at 50 GB, 30% at 100 GB, 40% at 250+ GB. Duration is free. Live numbers: `GET /v1/billing/pricing`.

### Create the port

```bash
curl -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_..." -H 'Content-Type: application/json' \
  -d '{"countryId":"<MongoId from GET /v1/countries/with-devices?pool=dedicated>","expiresAt":86400}'
# -> { "_id", "serverIp", "httpPort", "socksPort", "proxyLogin", "proxyPassword", ... }
```

- `countryId` (required) is a Mongo ObjectId from `GET /v1/countries/with-devices?pool=dedicated` (authenticated - API key or JWT, scope `ports:read`; also returns each country's free device count) - NOT a 2-letter code (that is the x402 path's `country=US` param; do not mix them up).
- `expiresAt` (required) is the port lifetime in seconds, 60 to 31536000.
- Optional: `cityId`, `carrierId`, `osFingerprint`.
- Rate limit: 5 port-creations per 10 seconds.
- When deposited GB runs out, ports are suspended; buying more GB auto-unsuspends them.

### Manage + rotate (API-key scope per row)

| Method + path | Scope | Purpose |
|---|---|---|
| GET `/v1/ports` | `ports:read` | List your ports |
| GET `/v1/ports/:id` | `ports:read` | Port detail |
| GET `/v1/ports/:id/status` / `/ip` / `/ping` | `ports:read` | Online status, current exit IP, connectivity |
| PUT `/v1/ports/:id/credentials` | `ports:write` | Change proxy login/password |
| DELETE `/v1/ports/:id` | `ports:write` | Delete the port |
| POST `/v1/ports/:id/rotate` | `ports:rotate` | Rotate to a new device now |
| GET/PATCH `/v1/ports/:id/rotation-settings` | `ports:rotate` | Auto-rotation config |
| GET `/v1/ports/:id/rotation-history` | `ports:read` | Rotation audit trail |
| GET `/v1/ports/:id/can-rotate` | `ports:read` | Rotation eligibility (cooldown etc.) |
| GET `/v1/account/summary` | `account:read` | Balance + GB total/used/available |
| GET `/v1/account/usage?period=30d` | `traffic:read` | Per-port traffic breakdown (`7d`/`30d`/`90d`) |
| GET `/v1/billing/payments` | `billing:read` | Payment history |

### MCP shortcut

The same standard path, tool-shaped: `PROXIES_API_KEY=psx_xxx npx -y @proxies-sx/mcp-server` - the MCP server authenticates with your `psx_` API key (sent as `X-API-Key`), not x402.

---

## Universal x402 Payment Flow

Wallet-only alternative - no account, no API key. Pay USDC per purchase on-chain.

1. Call the proxy endpoint without payment.
2. Server returns HTTP 402. The body is the payment contract (live shape, abbreviated - each `accepts[]` entry also carries an `outputSchema` describing the input params and output fields):

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

   Read these fields: pick the `accepts[]` entry for your network. `maxAmountRequired` is the authoritative price in micro-USDC (6 decimals - `"4000000"` = $4.00 for `traffic=1`). `payTo` is the recipient, `asset` is the USDC token contract.
3. Send exactly `maxAmountRequired` micro-USDC of `asset` to `payTo` (any USDC wallet - Phantom, MetaMask, etc).
4. Retry the SAME request with the `Payment-Signature: <tx_hash>` header.
5. Server verifies the on-chain transaction and returns proxy credentials (HTTP 200).

Replay protection: each tx hash can be used only once. 2% payment tolerance allowed (cover gas/rounding).

## Wallets

| Network | Recipient | USDC Contract | Settlement |
|---------|-----------|---------------|------------|
| Solana | `6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv` | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` | ~400ms (~$0.0001) |
| Base | `0xF8cD900794245fc36CBE65be9afc23CDF5103042` | `0x833589fcd6edb6e08f4c7c32d4f71b54bda02913` | ~2s (~$0.01) |

---

## Mobile Proxy - request contract

Real 4G/5G mobile proxy. HTTP and SOCKS5. IP rotation, OS fingerprint spoofing.

```bash
curl -s "https://api.proxies.sx/v1/x402/proxy?country=US&traffic=1&duration=3600"
```

**Required parameters:**

| Param | Value |
|-------|-------|
| `country` | 2-letter ISO code from the live set (`GET /v1/x402/countries`); as of last edit: NL, PL, US, GE (Georgia), FR, GB |
| `traffic` | GB, minimum 0.1 |
| `duration` | seconds, 3600 to 2592000 (duration is free - price is traffic only) |

**Optional:** `city`, `carrier`.

**Success response - persist these fields:**

| Field | Why |
|-------|-----|
| `management.sessionToken` | Auth for every manage endpoint below (nested under `management`, NOT top-level) (`X-Session-Token` header). Not recoverable if lost. |
| `proxy.http`, `proxy.socks5` | Ready-to-use connection URLs |
| `proxy.server`, `proxy.httpPort`, `proxy.socksPort` | Where to connect (the field is `server`, not `host`) |
| `proxy.username`, `proxy.password` | Proxy auth |
| `rotationUrl` | Public no-auth IP-rotate URL - the only place the rotate token appears |
| `proxy.expiresAt`, `traffic.allocatedGB` / `traffic.remainingGB`, `location.country` + `location.countryCode` | Session bounds (all nested - there are no top-level `expiresAt` / `trafficGB` / `country` fields) |

Pricing: $4/GB. Duration is FREE - only pay for traffic.

### Post-Purchase Management (X-Session-Token header)

```
GET  /v1/x402/manage/session                   - Session details
GET  /v1/x402/manage/session/credit             - Remaining credit
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              - Add traffic ($4/GB) or duration (free)
GET  /v1/rotate/:token                          - Rotate IP (no auth)
```

Top-up note: the `Payment-Signature` header is ALWAYS required on `POST /v1/x402/manage/session/topup` - for a $0 duration-only top-up send any non-empty placeholder value (it is not verified when the cost is 0).

---

## Pool Gateway Access (one credential, every country)

Buy metered gateway access instead of a single dedicated port: one credential reaches every country in your tier through `gw.proxies.sx:7000`, retargeted via the username - no repurchase per country. Same x402 flow: unpaid `GET /v1/x402/pool` returns the 402 catalog; pay USDC; retry with `Payment-Signature`.

Full contract (parameters, username DSL, recovery matrix): https://agents.proxies.sx/pool/skill.md

---

## Peer Network (Earn USDC)

Share mobile/residential bandwidth and get paid in USDC. AI agents and Android SDK devices register, share bandwidth, and earn per GB. Rates are dynamic: per-GB rates by IP type (mobile > residential > datacenter) are returned in the `earningsPerGB` field of the registration response - read that field, never assume a fixed rate.

```
POST https://api.proxies.sx/v1/peer/agents/register
```

Full contract: https://agents.proxies.sx/peer/skill.md

---

## SDK / Tooling

| Package | Install | Purpose |
|---------|---------|---------|
| `@proxies-sx/x402-core` | `npm i @proxies-sx/x402-core` | Types, payment requirement utilities |
| `@proxies-sx/x402-hono` | `npm i @proxies-sx/x402-hono` | Hono middleware for gating your own service |
| `@proxies-sx/x402-solana` | `npm i @proxies-sx/x402-solana` | Solana on-chain verification |
| `@proxies-sx/mcp-server` | `PROXIES_API_KEY=psx_xxx npx -y @proxies-sx/mcp-server` | MCP server with 70 tools published on npm (Claude Desktop, Cursor, Windsurf) - authenticates with your `psx_` API key (`X-API-Key`), not x402 |

---

## Discovery & Health

| Resource | URL |
|----------|-----|
| This catalog (machine-readable) | https://agents.proxies.sx/marketplace/skill.md |
| Master skill (full infra) | https://agents.proxies.sx/skill.md |
| Buy a proxy | https://agents.proxies.sx/marketplace/proxy/ |
| Pool Gateway Access contract | https://agents.proxies.sx/pool/skill.md |
| x402 discovery | https://agents.proxies.sx/.well-known/x402.json |
| llms.txt | https://agents.proxies.sx/llms.txt |
| Live status | https://agents.proxies.sx/status/ |
| Pricing API | https://api.proxies.sx/v1/x402/pricing |
| Peer Network | https://agents.proxies.sx/peer/ |

Support: maya@proxies.sx or https://t.me/proxies_sx - quote the req id from any error message.

---

*Managed by Maya (openclaw bot) | Mobile Proxy + Pool Gateway Access + Peer Network*