Developer Documentation

PROXIES.SX API Documentation

Mobile proxy infrastructure for developers and AI agents. Create an API key, deposit GB balance, and start building — or pay per-request with USDC on-chain if you need an account-less integration. Create ports, rotate IPs, monitor usage, and automate your proxy infrastructure.

101 MCP tools6 npm packages
Documentation

Base URL

https://api.proxies.sx/v1

Authentication

All API requests require authentication via API key. Get your API key from the dashboard

Header: X-API-Key: psx_your_api_key_here

API Key Scopes

ScopeDescription
ports:readRead port information and pool session tools
ports:writeCreate, update, delete ports
ports:rotateRotate ports to new devices
billing:readRead prices, payments and balance
billing:topupStart a card top-up (a Stripe Checkout link a person pays; daily cap per key)
modems:purchaseBuy, renew and auto-renew Private modems from the balance
traffic:readRead traffic usage data
account:readRead account information
account:writeUpdate account settings and the proxy password
tickets:read, tickets:writeSupport tickets

Quick Start Integration Guide

Step 1: Check Your Resources

curl https://api.proxies.sx/v1/account/summary \
  -H "X-API-Key: psx_your_key"

Step 2: Get Available Locations

curl "https://api.proxies.sx/v1/countries/with-devices?pool=dedicated" \
  -H "X-API-Key: psx_your_key"

Step 3: Create a Port

curl -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"countryId":"COUNTRY_ID","expiresAt":86400}'

Step 4: Use Your Proxy

# HTTP Proxy
http://proxyLogin:proxyPassword@serverIp:httpPort

# SOCKS5 Proxy
socks5://proxyLogin:proxyPassword@serverIp:socksPort

Step 5: Rotate IP When Needed

# Option A: API rotation (authenticated)
curl -X POST https://api.proxies.sx/v1/ports/PORT_ID/rotate \
  -H "X-API-Key: psx_your_key"

# Option B: Token rotation (no auth needed!)
curl https://api.proxies.sx/v1/rotate/YOUR_ROTATION_TOKEN

Pool Gateway

One credential for every country with stock. Pool, country, rotation and filters go in the username. Live stock (public, counts per country only): GET /v1/gateway/pool/stock. Full guide: Pool Gateway.

# HTTP and HTTPS (CONNECT)
http://psx_<accountId>-<pool>-<country>[-<token>-<value> ...]:PROXY_PASSWORD@gw.proxies.sx:7000

# SOCKS5 (socks5h:// resolves DNS through the proxy)
socks5h://psx_<accountId>-<pool>-<country>:PROXY_PASSWORD@gw.proxies.sx:7001

# Example: sticky US peer session
curl -x http://psx_ACCOUNTID-peer-us-sid-job1-rot-sticky:PROXY_PASSWORD@gw.proxies.sx:7000 https://api.ipify.org

The password is your proxy password (GET /v1/account/proxy-password, set it with PATCH /v1/account/proxy-password) or a pak_ key. The gateway never accepts your account login password. Limits: 500 concurrent connections and 250 sessions per account.

Username tokens

TokenValuesNotes
poolmbl, peer, any, bestPosition 2. peer = residential and mobile network; mbl = our private 4G/5G devices in US, GB, FR, NL, PL and GE (Georgia). Omitted or unknown = any
country2-letter ISO code or anyPosition 3. ge is Georgia: for Germany use peer-de (mbl-de never works)
rotauto5, auto10, auto20, auto60, ondemand, sticky, hardDefault auto10. hard pins exactly like sticky; it is not a new IP per request
sid1-64 chars: a-z, 0-9, _Needed for sticky and auto* to persist across connections
carriername from /v1/gateway/pool/stock/carriersHard filter; prefer asn for network targeting
city, statename, 2-letter codeSoft preference, peer network only
iptypemobile, residential, datacenterHard filter; datacenter is served only when named
isp, asnbrand slug, numberHard match
failoversamecountry, samecarrier, samenode, any, strictDefault samecountry
ttl60-2592000 secondsSession TTL, default 3600 (not an IP guarantee)

Traps

  • • The username is lowercased and split on "-", so no token value may contain "-".
  • • Unknown tokens are skipped silently: -session-<id> is NOT -sid-<id> and creates no sticky session.
  • • sticky and the auto* modes only persist across connections when the username carries -sid-<id>.
  • • hard pins exactly like sticky; it does not give a new IP per request.
  • • Sticky pins the device, not the IP: a mobile carrier can still change a held device's exit IP. For a held address use a residential peer, a Reserved IP or a Private modem.
  • • The parser corrects or ignores a bad optional token instead of rejecting it. Only a missing or over-256-character username fails.

Error codes

Returned as CODE: message (req: uuid).

CodeHTTPMeaning
E_AUTH_REQUIRED407No proxy credentials sent
E_AUTH_INVALID407Bad credentials or key disabled
E_BALANCE_EXHAUSTED407Password accepted but no traffic left on the account: add GB
E_CAP_EXCEEDED407A pak_ key hit its GB cap
E_USERNAME_PARSE400Username missing or over 256 characters
E_WRONG_PORT400HTTP sent to the SOCKS5 port, or SOCKS5 to :7000
E_RATE_LIMITED_AUTH429Too many failed auth attempts
E_RATE_LIMITED_CONN429Over 500 concurrent connections for the account
E_SESSION_LIMIT429Over 250 concurrent sessions for the account
E_NO_STOCK_COUNTRY502No online endpoints for that pool, country and filters
E_STOCK_DEGRADED502Endpoint went offline mid-request
E_SSRF_BLOCKED403Target is private, localhost or cloud metadata
E_GATEWAY_CAPACITY503Shared gateway capacity reached (not an account limit): retry shortly
E_INTERNAL503Unexpected: open a ticket

Reference Data Endpoints

GET/v1/countries/with-devicesScope: ports:read

Get countries with available devices and free device count

Example Request
curl https://api.proxies.sx/v1/countries/with-devices \
  -H "X-API-Key: psx_your_key"
Response
[
  {
    "_id": "69276bf1f547dfc948699263",
    "name": "Poland",
    "code": "PL",
    "iso3": "POL",
    "phoneCode": "+48",
    "freeDeviceCount": 26
  },
  {
    "_id": "69276bf1f547dfc9486992b4",
    "name": "United Kingdom",
    "code": "GB",
    "iso3": "GBR",
    "phoneCode": "+44",
    "freeDeviceCount": 21
  }
]
GET/v1/carriers/country/:countryId?withDevice=trueScope: ports:read

Get carriers in a country with free device count

Example Request
curl "https://api.proxies.sx/v1/carriers/country/69276bf1f547dfc948699263?withDevice=true" \
  -H "X-API-Key: psx_your_key"
Response
[
  {
    "_id": "69276bf5f547dfc94869f2dc",
    "name": "T-Mobile Polska S.A.",
    "brand": "T-Mobile",
    "mcc": "260",
    "mnc": "02",
    "technology": "LTE",
    "freeDeviceCount": 19
  },
  {
    "_id": "69276bf5f547dfc94869f2df",
    "name": "Orange Polska S.A.",
    "brand": "Orange",
    "technology": "LTE",
    "freeDeviceCount": 7
  }
]
GET/v1/pricingScope: public

Public price list built from the same constants checkout uses: base price per GB, volume discounts, the 1 TB+ volume quote, country tiers and the Private modem plans in stock

Example Request
curl https://api.proxies.sx/v1/pricing
Response (abridged)
{
  "currency": "USD",
  "gb": {
    "pools": ["peer", "mbl"],
    "basePricePerGB": 4,
    "volumeDiscounts": [
      { "minGB": 1, "maxGB": 24, "discountPercent": 0, "pricePerGB": 4 },
      { "minGB": 250, "maxGB": null, "discountPercent": 40, "pricePerGB": 2.4 }
    ],
    "volumeQuote": { "minGB": 1000, "pricePerGBFrom": 0.5, "pool": "peer", "checkout": false },
    "countryTiers": {
      "live": true,
      "tiers": [
        { "tier": 1, "name": "Premium", "burnRate": 1, "pricePerGB": 4 },
        { "tier": 2, "name": "Plus", "burnRate": 0.375, "pricePerGB": 1.5 },
        { "tier": 3, "name": "Standard", "burnRate": 0.1875, "pricePerGB": 0.75 }
      ]
    }
  },
  "privateModems": { "available": true, "plans": [{ "countryCode": "GB", "period": "month", "priceUsd": 107 }] }
}

$4/GB on peer and mbl alike, down to $2.40/GB at 250 GB+ (25 GB+ 10%, 50 GB+ 20%, 100 GB+ 30%, 250 GB+ 40%). Country tiers: each GB of traffic uses balance by the exit country of the device that served it (Tier 1 $4.00, Tier 2 $1.50, Tier 3 $0.75 per GB, before volume discounts). From 1 TB on the peer pool: from $0.50/GB by quote. Duration is free; dedicated port slots are free and unlock with cumulative GB purchases.


Port Management Endpoints

GET/v1/portsScope: ports:read

List all your ports with connection details, device info, and traffic usage

Example Request
curl https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key"
Response
[
  {
    "_id": "6935a7065cb903907b750c64",
    "id": "6935a7065cb903907b750c64",
    "name": "psx_8cc33c_91vjml",
    "displayName": "Proxy #1",

    "httpPort": 8522,
    "socksPort": 5522,
    "serverIp": "203.0.113.10",
    "proxyLogin": "user_8cc33c91vjml",
    "proxyPassword": "gyQ4n6hP8R",

    "slotType": "shared",
    "exclusive": false,
    "osFingerprint": "windows:1",

    "suspended": false,
    "status": "active",
    "expiresAt": 1765210246994,
    "createdAt": 1733587846996,

    "rotationToken": "32c2144a26f1ff1a3a0b79c4e31b7369",
    "rotationSettings": {
      "enabled": true,
      "intervalMinutes": 30,
      "intervalSeconds": 1800,
      "lastRotatedAt": "2025-12-17T09:30:00.000Z",
      "rotationCount": 5
    },

    "usedTraffic": 1.5,
    "rotationLink": "https://api.proxies.sx/v1/rotate/32c2144a26f1ff1a3a0b79c4e31b7369",

    "device": {
      "_id": "69280411c01b1bb60efc4ab7",
      "country": { "name": "Poland", "code": "PL" },
      "carrier": { "name": "T-Mobile Polska S.A.", "brand": "T-Mobile" },
      "region": { "name": "Warsaw" }
    }
  }
]
POST/v1/portsScope: ports:write

Create a dedicated port (needs a free port slot; slots are free and unlock with cumulative GB purchases)

Request Body
{
  "countryId": "69276bf1f547dfc948699263",  // Required
  "expiresAt": 86400,                        // Required (seconds from now, 60 to 31536000)
  "carrierId": "carrier_id",                 // Optional
  "cityId": "city_id",                       // Optional
  "osFingerprint": "windows:1"               // Optional
}
Example Request
curl -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"countryId":"69276bf1f547dfc948699263","expiresAt":86400}'
Response
{
  "_id": "675123abc...",
  "displayName": "Proxy #1",
  "serverIp": "203.0.113.20",
  "httpPort": 8002,
  "socksPort": 5002,
  "proxyLogin": "auto_generated",
  "proxyPassword": "auto_generated",
  "expiresAt": 1702320967890
}
GET/v1/ports/:idScope: ports:read

Get full port details including device info and rotation settings

Example Request
curl https://api.proxies.sx/v1/ports/6935a7065cb903907b750c64 \
  -H "X-API-Key: psx_your_key"
GET/v1/ports/:id/statusScope: ports:read

Get port online/offline status

Response
{
  "status": "online",
  "isActive": true,
  "lastChecked": "2025-12-17T10:00:00.000Z",
  "expiresAt": 1765210246994
}
GET/v1/ports/:id/pingScope: ports:read

Test proxy connectivity and measure response time

Response
{
  "success": true,
  "ip": "198.51.100.23",
  "responseTime": 513,
  "testTime": "2025-12-17T10:37:36.621Z"
}
GET/v1/ports/:id/ipScope: ports:read

Get current public IP address of the port

Response
{
  "publicIp": "198.51.100.23",
  "serverIp": "203.0.113.10"
}
GET/v1/ports/:id/os-fingerprintsScope: ports:read

Get available OS fingerprint options for this port's server

Response
[
  { "value": "", "label": "None (Default)" },
  { "value": "windows:1", "label": "Windows 10" },
  { "value": "macosx:4", "label": "macOS / iPhone 13" },
  { "value": "ios:2", "label": "iOS (Real iPhone)" },
  { "value": "ios:1", "label": "iOS (p0f Compliant)" },
  { "value": "android:3", "label": "Android (Real)" },
  { "value": "android:1", "label": "Android (p0f Compliant)" },
  { "value": "macosx:3", "label": "macOS X" }
]
DELETE/v1/ports/:idScope: ports:write

Delete a port (removes it from the device and from your account)

Example Request
curl -X DELETE https://api.proxies.sx/v1/ports/675123abc... \
  -H "X-API-Key: psx_your_key"
Response
{
  "message": "Port deleted successfully"
}
POST/v1/ports/:id/reconfigureScope: ports:write

Change port location/carrier

Request Body
{
  "countryId": "new_country_id",  // Required
  "carrierId": "new_carrier_id"   // Optional
}
PUT/v1/ports/:id/credentialsScope: ports:write

Update port login/password credentials

Request Body
{
  "proxyLogin": "new_username",
  "proxyPassword": "new_password"
}
PATCH/v1/ports/:id/os-fingerprintScope: ports:write

Change OS fingerprint (p0f) for traffic spoofing

Request Body
{
  "osFingerprint": "windows:1"
}

// Available values:
// "", "windows:1", "macosx:3", "macosx:4",
// "ios:1", "ios:2", "android:1", "android:3"

IP Rotation Endpoints

POST/v1/ports/:id/rotateScope: ports:rotate

Rotate port to get a new IP (5-minute cooldown between rotations).

Example Request
curl -X POST https://api.proxies.sx/v1/ports/6935a7065cb903907b750c64/rotate \
  -H "X-API-Key: psx_your_key"
Response (Shared Device)
{
  "success": true,
  "portId": "6935a7065cb903907b750c64",
  "oldDeviceId": "69280411c01b1bb60efc4ab7",
  "newDeviceId": "69280412c01b1bb60efc4ab8",
  "oldIp": "198.51.100.23",
  "newIp": "198.51.100.57",
  "rotationDurationMs": 2450,
  "rotationCount": 5,
  "message": "Port rotated successfully"
}
GET/v1/ports/:id/can-rotateScope: ports:read

Check if port can be rotated and cooldown status

Response (Ready)
{
  "canRotate": true,
  "availableDevices": 26
}
Response (In Cooldown)
{
  "canRotate": false,
  "reason": "Rate limited. Must wait 180 seconds before next rotation.",
  "nextRotationAt": "2025-12-17T10:05:00.000Z",
  "cooldownRemaining": 180
}
PATCH/v1/ports/:id/rotation-settingsScope: ports:write

Enable/configure auto-rotation. Interval in SECONDS: 300-86400 (5 minutes to 24 hours)

Request Body
{
  "enabled": true,
  "intervalSeconds": 1800,  // 300-86400 (5 min to 24 h) - in SECONDS
  "matchCarrier": false,    // Keep same carrier when rotating
  "matchCity": false        // Keep same city/region when rotating
}
Example Request
curl -X PATCH https://api.proxies.sx/v1/ports/6935a7065cb903907b750c64/rotation-settings \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"intervalSeconds":1800}'
Response
{
  "_id": "6935a7065cb903907b750c64",
  "rotationSettings": {
    "enabled": true,
    "intervalMinutes": 30,
    "intervalSeconds": 1800,
    "rotationCount": 7,
    "matchCarrier": false,
    "matchCity": false,
    "excludedDeviceIds": []
  }
  // ... full port object
}

// Always use intervalSeconds; intervalMinutes is a legacy mirror.
GET/v1/ports/:id/rotation-historyScope: ports:read

Get rotation history for a port

Response
{
  "rotations": [
    {
      "_id": "6941a706...",
      "portId": "6935a7065cb903907b750c64",
      "fromDeviceId": "69280411c01b1bb60efc4ab7",
      "toDeviceId": "69280412c01b1bb60efc4ab8",
      "fromIp": "198.51.100.23",
      "toIp": "198.51.100.57",
      "triggerType": "api_token",
      "success": true,
      "rotationDurationMs": 2450,
      "country": "Poland",
      "carrier": "T-Mobile",
      "createdAt": "2025-12-17T09:55:00.000Z"
    }
  ],
  "total": 5
}

// triggerType values: "manual", "automatic", "api_token"

Account & Billing Endpoints

GET/v1/accountScope: account:read

Complete account details with wallet, subscriptions, ports, and status flags

Response
{
  "user": {
    "_id": "6935a45d04523391208cc33c",
    "email": "user@example.com",
    "role": "customer",
    "isActive": true
  },
  "wallet": {
    "totalDeposited": 100.00,
    "totalSpent": 50.00,
    "availableBalance": 50.00,
    "currency": "USD"
  },
  "subscription": {
    "shared": {
      "active": true,
      "slots": { "total": 10, "used": 2, "available": 8 },
      "traffic": { "purchasedGB": 10, "usedGB": 2.5, "availableGB": 7.5 },
      "expiresAt": null,
      "daysRemaining": null
    }
  },
  "status": {
    "hasActiveSubscription": true,
    "hasAvailableTraffic": true,
    "lowBalance": false,
    "lowTraffic": false
  }
}
GET/v1/account/summaryScope: account:read

Lightweight account summary for dashboard widgets and quick status checks

Response
{
  "balance": 50.00,
  "currency": "USD",
  "shared": {
    "slots": { "total": 10, "used": 2, "available": 8 },
    "trafficGB": { "total": 10, "used": 2.5, "available": 7.5 },
    "expiresAt": null,
    "daysRemaining": null
  },
  "alerts": [
    { "type": "low_traffic", "message": "Traffic is running low (< 5GB)", "severity": "info" }
  ]
}
GET/v1/account/usage?period=30dScope: traffic:read

Traffic usage breakdown by port (7d, 30d, or 90d period)

Response
{
  "period": "30d",
  "generatedAt": "2025-12-17T10:00:00.000Z",
  "traffic": {
    "shared": {
      "totalUsedGB": 2.5,
      "portCount": 2,
      "byPort": [
        { "portId": "6935a706...", "portName": "Proxy #1", "usedGB": 1.5 },
        { "portId": "6935a707...", "portName": "Proxy #2", "usedGB": 1.0 }
      ]
    },
    "combined": {
      "totalUsedGB": 2.5,
      "portCount": 2
    }
  }
}
GET/v1/traffic/balance-breakdownScope: traffic:read

Detailed traffic and billing breakdown with formula explanation

Response
{
  "totalPayments": 100.00,
  "totalPurchases": 50.00,
  "trafficUsedMB": 2560,
  "trafficUsedGB": 2.5,
  "purchasedTrafficGB": 10,
  "availableTrafficGB": 7.5,
  "pricePerGB": 4,
  "balance": 50.00,
  "currency": "USD",
  "formula": "balance = totalPayments - totalPurchases (traffic is pre-purchased!)"
}

Private Modems

A whole 4G/5G carrier modem rented to one customer by the day, week or month, with unlimited traffic, paid from the account balance (not through x402). Plans and prices are public at GET https://api.proxies.sx/v1/pricing under privateModems.plans. Buying, renewing and auto-renew need an API key with the modems:purchase scope. Full contract: agents.proxies.sx/modems/skill.md. Overview: Private modems.

GET/v1/private-modems/catalogScope: any API key

Plans in stock: tariffId, country, carrier, period (day, week or month), retail price in USD, OpenVPN and p0f support

curl https://api.proxies.sx/v1/private-modems/catalog \
  -H "X-API-Key: psx_YOUR_API_KEY"
POST/v1/private-modems/ordersScope: modems:purchase

Rent from the balance. Send the price you were shown as expectedPriceUsd: a changed price returns 409 price_changed and nothing is charged. One Idempotency-Key per checkout.

curl -X POST https://api.proxies.sx/v1/private-modems/orders \
  -H "X-API-Key: psx_YOUR_API_KEY" \
  -H "Idempotency-Key: 3f6c2a9e-order-1" \
  -H "Content-Type: application/json" \
  -d '{"tariffId": "pt_...", "expectedPriceUsd": 32}'
Manage a rental (every :id route is scoped to your account)
GET /v1/private-modems/mine - your modems with HTTP and SOCKS5 credentials, plus orders still settling
GET /v1/private-modems/:id/renewal-quote - renewal prices for a day, a week and a month
POST /v1/private-modems/:id/renew - {period, expectedPriceUsd}, modems:purchase scope
POST /v1/private-modems/:id/rotate - new IP now
PUT /v1/private-modems/:id/rotation-interval - {seconds}: 0 = off, otherwise at least 60
GET /v1/private-modems/:id/openvpn - OpenVPN profile (.ovpn)
GET /v1/private-modems/:id/p0f-options and PUT /v1/private-modems/:id/os - OS fingerprint (p0f) on lines that support it
PUT /v1/private-modems/:id/auto-renew - opt-in auto-renew, modems:purchase scope
POST /v1/private-modems/:id/rotation-token - new private rotation link; GET /v1/private-modems/rotate/:token rotates without a login
POST /v1/private-modems/:id/replace - move to another modem in the same country; new credentials

Complete Workflow Example

# 1. Check account status first
curl https://api.proxies.sx/v1/account/summary \
  -H "X-API-Key: psx_your_key"

# 2. Get countries where a dedicated port can be created
curl "https://api.proxies.sx/v1/countries/with-devices?pool=dedicated" \
  -H "X-API-Key: psx_your_key"

# 3. Get carriers for Poland
curl "https://api.proxies.sx/v1/carriers/country/69276bf1f547dfc948699263?withDevice=true" \
  -H "X-API-Key: psx_your_key"

# 4. Create a 24-hour port
curl -X POST https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"countryId":"69276bf1f547dfc948699263","expiresAt":86400}'

# 5. List your ports
curl https://api.proxies.sx/v1/ports \
  -H "X-API-Key: psx_your_key"

# 6. Rotate a port to new IP
curl -X POST https://api.proxies.sx/v1/ports/PORT_ID/rotate \
  -H "X-API-Key: psx_your_key"

# 7. Enable auto-rotation (every 30 min = 1800 seconds)
curl -X PATCH https://api.proxies.sx/v1/ports/PORT_ID/rotation-settings \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"intervalSeconds":1800}'

# 8. Check rotation history
curl https://api.proxies.sx/v1/ports/PORT_ID/rotation-history \
  -H "X-API-Key: psx_your_key"

# 9. Change OS fingerprint to Windows
curl -X PATCH https://api.proxies.sx/v1/ports/PORT_ID/os-fingerprint \
  -H "X-API-Key: psx_your_key" \
  -H "Content-Type: application/json" \
  -d '{"osFingerprint":"windows:1"}'

# 10. Get usage analytics
curl "https://api.proxies.sx/v1/account/usage?period=30d" \
  -H "X-API-Key: psx_your_key"

# 11. Delete a port when done
curl -X DELETE https://api.proxies.sx/v1/ports/PORT_ID \
  -H "X-API-Key: psx_your_key"

Proxy Connection Formats

HTTP Proxy
http://username:password@serverIp:httpPort
SOCKS5 Proxy
socks5://username:password@serverIp:socksPort
Example
http://user_abc123:pass456@203.0.113.10:8522
socks5://user_abc123:pass456@203.0.113.10:5522

Key Response Fields for Developers

Port Object Fields

  • status - "active" | "suspended" | "expired"
  • rotationToken - Token for no-auth rotation
  • trafficSummary - { usedMB, usedGB }
  • healthStatus - "healthy" | "degraded" | "offline"
  • osFingerprint - Current OS spoofing setting

Account Object Fields

  • wallet - Detailed balance breakdown
  • subscription.shared - Free port slots and traffic availability
  • status.hasAvailableTraffic - Boolean flag
  • status.lowTraffic - Boolean flag

MCP Server

AI-Controlled Proxy Management

@proxies-sx/mcp-server
Now available on NPM
View on NPM
Option 1: npx (recommended)
npx -y @proxies-sx/mcp-server
Option 2: Global install
npm i -g @proxies-sx/mcp-server
Option 3: Local project
npm i @proxies-sx/mcp-server
Package size: about 1.2 MB unpacked in v3.2.0, plus dependencies (MCP SDK, viem, zod)

The PROXIES.SX MCP Server allows AI assistants (Claude, Cursor, Cline) to manage your proxy infrastructure through natural language. Create ports, rotate IPs, monitor status, and purchase resources — all through conversation.

Two Authentication Modes

1
API Key Mode

Use your Proxies.sx account and API key to manage existing subscriptions.

Requires: PROXIES_API_KEY
2
x402 Payment Mode

AI agents autonomously purchase proxies using USDC on Base - no account needed!

Requires: AGENT_WALLET_KEY
101 Tools

20 listed by default, the rest with --toolset=full

Natural Language

No code needed

x402 Payments

Autonomous USDC

MIT License

Open source

MCP Setup

API Key Mode Configuration

For users with existing Proxies.sx accounts - manage your subscriptions with your API key:

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

x402 Payment Mode Configuration

For autonomous AI agents - the server pays with USDC on Base (no account needed):

{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": {
        "AGENT_WALLET_KEY": "0x_your_base_wallet_private_key"
      }
    }
  }
}
Requirements: Fund the wallet with USDC on Base ($4/GB, minimum 0.1 GB = $0.40; port time is free) plus a little ETH on Base for gas
Config locations: Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json | Cursor: .cursor/mcp.json | Claude Code: .mcp.json in the project root, or claude mcp add proxies-sx -e PROXIES_API_KEY=psx_... -- npx -y @proxies-sx/mcp-server
Hosted server: https://api.proxies.sx/mcp (Streamable HTTP) with the header Authorization: Bearer psx_...; without a key only the public tools are listed. Add ?toolset=full for every API-key tool. Wallet (x402) mode runs only locally.

Available Tools by Category

🌐Pool Gateway10 tools
pool_get_stock - Get live Pool Gateway stock, no account needed
pool_get_facets - List the cities, states, carriers (with ASN and class) and IP classes that have stock in one country, with counts, no account needed
pool_build_proxy_url - Build a ready-to-use Pool Gateway proxy URL (gw.proxies.sx, HTTP 7000 or SOCKS5 7001)
pool_explain_error - Explain a Pool Gateway error and say what to do about it
pool_get_my_credentials - Get your Pool Gateway proxy username and proxy password with ready HTTP and SOCKS5 URLs
pool_set_proxy_password - Set a new proxy password (at least 6 characters)
pool_get_my_stats - Get your own Pool Gateway traffic and open connections, plus the health score of the pool and how many devices are connected to it
pool_list_sessions - List your saved Pool Gateway sessions: pool, country, carrier, rotation mode, bytes and last activity
pool_close_session - Close one Pool Gateway session by the sessionKey from pool_list_sessions
pool_close_all_sessions - Close every saved Pool Gateway session of the account
📶Private modems6 tools
proxies_modem_catalog - List the Private modem plans for sale right now: country, carrier, period (day, week or month), price in USD, stock, OpenVPN and p0f support, regions
proxies_modem_quote - Price check before spending
proxies_modem_buy - Rent a Private modem (one dedicated 4G/5G modem, unlimited traffic) from the account balance
proxies_modem_renew - Extend the rental of one of your Private modems from the account balance
proxies_modem_rotate - Ask one of your Private modems for a new IP address
proxies_modem_mine - List your rented Private modems: status, expiry, online state, HTTP and SOCKS5 credentials, rotation settings, auto-renew, plus open orders and recent failures
🔒Private Pool and Reserved IPs10 tools
private_pool_list - List your Private Pools with their countries, status, gateway username, connection strings with the password masked (private_pool_reveal shows the key) and remaining GB
private_pool_build - Create a Private Pool paid from the account's existing GB balance: no purchase, traffic is metered from the same balance
private_pool_reveal - Show the gateway password (pak_ key) of a Private Pool
private_pool_usage - Get the traffic of a Private Pool per day, in MB
reserved_ip_list - List the Reserved IPs a Private Pool holds: country, class, carrier, city, rotation mode, whether the device is online, the exit IP last seen, and connection strings with the password masked
reserved_ip_reserve - Reserve one device for a Private Pool so no other customer is routed through it, and get its connection strings with the password masked
reserved_ip_rotate - Move a Reserved IP to a different device in the same country now
reserved_ip_extend - Change how long a Reserved IP is kept without traffic
reserved_ip_set_rotation - Set whether a Reserved IP moves to another device on a schedule: off (hold the device, the default) or every 5, 10, 20 or 60 minutes
reserved_ip_release - Give a Reserved IP back to the shared pool
👤Account2 tools
get_account_summary - Get the account balance, free port slots, traffic bought and left, and any account alerts
get_account_usage - Get traffic purchased, used and still available, split into Pool Gateway traffic and dedicated-port traffic
💳Billing6 tools
get_pricing - Get the live price per GB, the volume discounts, the free port-slot tiers and your current tier
calculate_price - Calculate what a GB amount costs with the volume discount applied
purchase_shared_traffic - Buy traffic in GB from the account balance
coupon_validate - Check whether a coupon code is valid for an order, without using it
coupon_redeem - Redeem a standalone coupon that grants free GB or port slots to the account
get_payment_history - List the account's past payments and crypto top-up orders
🪙Crypto payments7 tools
proxies_topup_checkout - Add money to the account balance by card: creates a Stripe Checkout page and returns its url and sessionId
proxies_topup_status - Check whether a card top-up started with proxies_topup_checkout was paid and credited to the balance
create_crypto_payment - Create a crypto order that tops up the account balance and return its hosted payment link
check_crypto_payment_status - Check whether a crypto order is still unpaid, confirming, paid, expired or cancelled, and whether the balance was credited
get_pending_crypto_payments - List the account's crypto orders that are not finished yet, with their payment links
cancel_crypto_payment - Cancel a crypto order that has not been paid yet
get_crypto_payment_info - Check whether crypto top-ups are available right now and which currencies the payment page accepts
🔌Dedicated ports9 tools
list_available_countries - List the countries where a dedicated port can be created right now, with the countryId create_port needs
list_ports - List your dedicated ports with status, country, carrier, expiry and port ids
get_port - Get one dedicated port with its location and ready-to-use HTTP and SOCKS5 connection strings (contains the port password)
create_port - Create a dedicated port on a carrier modem and return its connection strings
delete_port - Delete a dedicated port and free its slot
update_port_credentials - Change the login and/or password of a dedicated port
update_os_fingerprint - Set the OS fingerprint (TCP/IP signature) a dedicated port presents
reconfigure_port - Move a dedicated port to another country, carrier or city
extend_port - Add hours to a dedicated port's expiry
📡Port status4 tools
get_port_status - Check whether a dedicated port is online, offline or expired
get_port_ip - Get the server address a dedicated port listens on
ping_port - Test that a dedicated port answers and measure its latency
speed_test_port - Run a speed test through a dedicated port (download, upload, ping)
🔄Port rotation5 tools
rotate_port - Move a dedicated port to another modem in the same location
check_rotation_availability - Check whether a dedicated port can be rotated now, how long the cooldown still runs and how many other modems are free
configure_auto_rotation - Turn automatic rotation of a dedicated port on or off and set its interval
get_rotation_history - Get the past rotations of a dedicated port: when, how triggered, the location it moved to and whether it worked
get_rotation_token_url - Get the public rotation link of a dedicated port
🛠️Utilities4 tools
get_proxy_connection_string - Build the HTTP or SOCKS5 connection string of a dedicated port (contains the port password)
get_all_proxy_formats - Get a dedicated port in every common format: URLs, host:port, environment variables, curl, Python and Node.js snippets, and its public rotation link
get_service_status - Check whether Proxies.sx is healthy right now: open Pool Gateway incidents, the state of the API, gateway and relay, and recent uptime
get_os_fingerprint_options - List the OS fingerprint values create_port and update_os_fingerprint accept
🎫Support5 tools
create_support_ticket - Open a support ticket that a person at Proxies.sx reads and answers
list_my_tickets - List your support tickets with their status and IDs
get_ticket - Get one support ticket with the original message and every reply
reply_to_ticket - Add a reply to one of your support tickets
close_ticket - Close one of your support tickets once the problem is solved
🪪Pool access keys (reseller accounts)9 tools
pool_mint_key - Create a Pool Access Key (pak_) for one of your customers; it is used as the proxy password
pool_list_keys - List your Pool Access Keys with usage, cap and expiry; the key values are masked
pool_topup_key - Add GB to a Pool Access Key's cap and/or extend its expiry in one step
pool_update_key - Change a Pool Access Key's label, enabled flag, cap, expiry or quality tier
pool_regenerate_key - Replace the secret pak_ value of a Pool Access Key
pool_reveal_key - Show the full pak_ value of a Pool Access Key
pool_delete_key - Delete a Pool Access Key
pool_key_usage - Get the traffic of one Pool Access Key per day, in MB
pool_key_audit - Get the audit log of one Pool Access Key, newest first: created, changed, topped up, regenerated, revealed, deleted, and gateway logins that worked or failed
🔑x402 session management8 tools
get_x402_session - Get details of your x402 session including all ports
list_x402_ports - List all ports in your x402 session with connection strings and expiration times
get_x402_port_status - Get detailed status of a specific port including traffic usage and connection info
get_sessions_by_wallet - List all x402 sessions associated with your wallet address
get_session_status - Get quick status check for a session including traffic usage and expiration
replace_x402_port - Replace an offline port of an x402 session with a new port on another device, at no charge
calculate_x402_topup - Calculate what it costs to add traffic and/or time to an x402 session
topup_x402_session - Add traffic and/or time to an x402 session
🤖x402 wallet (optional, no account)16 tools
x402_get_proxy - Buy a dedicated mobile proxy on one carrier modem by paying USDC from the agent wallet; no account needed
x402_get_pricing - Get the live x402 price per GB, the smallest purchase, the allowed duration and the payment networks, and compare the cost of a purchase with the wallet balance
x402_list_sessions - List the active x402 proxy sessions this wallet bought from this machine, with location, expiry and proxy host
x402_check_session - Get status, time left, traffic used and the connection strings of an x402 proxy session
x402_wallet_balance - Get the agent wallet address and its USDC and ETH (gas) balance on the Base network
x402_rotate_ip - Move an x402 proxy to another modem so it gets a different exit IP
x402_list_countries - List the countries where x402_get_proxy can create a proxy right now, with the number of free modems
x402_extend_session - Add hours to an x402 proxy session
x402_service_status - Check that the x402 payment service is up, and show the wallet balance and how many sessions are active or about to expire
x402_get_pool_access - Buy Pool Gateway traffic by paying USDC from the agent wallet; no account needed
x402_pool_credit - Get the GB bought, used and left on an x402 pool session
x402_pool_topup - Add GB and/or time to an x402 pool session
x402_pool_regenerate - Replace the password of an x402 pool credential, for example after a leak
x402_pool_connection - Show the gateway host, port, username and password of an x402 pool session again
x402_pool_usage - Get the traffic of an x402 pool session per day, in MB
x402_pool_pricing - Get the Pool Gateway tiers that can be bought with x402 and their live price per GB and smallest purchase

x402 Protocol

Payment-Gated Proxy Access for AI Agents

x402 Protocol enables instant proxy access for AI agents using HTTP 402 Payment Required responses. No registration needed — just pay with USDC on Base or Solana and receive credentials instantly.

No Registration

Pay and receive credentials instantly

USDC Payments

On Base (L2) or Solana

AI-Native

Designed for autonomous agents

Dynamic Pricing & Availability

All x402 responses include live data:

  • • Available countries - Updated every 5 minutes from device inventory
  • • Pricing included - the live per-GB rate (one tier, shared)
  • • Stock levels - Real device counts per country

x402 Endpoints

GET/v1/x402/healthScope: public

Check if x402 integration is enabled

Response
{"enabled": true, "version": "1.0.0"}
GET/v1/x402/infoScope: public

Master endpoint - Get all config in one call (pricing, networks, limits)

Response
{
  "service": {"name": "Proxies.sx Mobile Proxy", ...},
  "pricing": {
    "shared": {"trafficPricePerGB": 4, "portPricePerHour": 0, ...},
    "networks": [{"network": "base", ...}, {"network": "solana", ...}],
    "minDurationSeconds": 3600,
    "maxDurationSeconds": 2592000,
    "minTrafficGB": 0.1
  },
  "countries": [{"code": "GB", "name": "United Kingdom", "availableDevices": 7, "tier": "both"}],
  "endpoints": {"purchase": "GET/POST https://api.proxies.sx/v1/x402/proxy", ...}
}
GET/v1/x402/countriesScope: public

Get available countries (dynamic, updated every 5 min)

Query Parameters
  • tier (optional) - "shared" (the only tier; private ports are retired)
Response
[
  {"code": "US", "name": "United States", "availableDevices": 88, "tier": "both"},
  {"code": "NL", "name": "Netherlands", "availableDevices": 27, "tier": "both"},
  {"code": "GB", "name": "United Kingdom", "availableDevices": 22, "tier": "both"},
  {"code": "PL", "name": "Poland", "availableDevices": 22, "tier": "both"}
]
Note: "tier" is a legacy field; dedicated ports exist only in US, GB, FR, NL, PL and GE (Georgia)
GET/v1/x402/pricingScope: public

Get current pricing and payment networks

Response
{
  "shared": {
    "tier": "shared",
    "portPriceMonthly": 0,
    "trafficPricePerGB": 4,
    "portPricePerHour": 0,
    "portPricePerDay": 0
  },
  "networks": [
    {
      "network": "base",
      "chainId": "eip155:8453",
      "enabled": true,
      "usdcAddress": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "recipientAddress": "0xF8cD900794245fc36CBE65be9afc23CDF5103042"
    },
    {
      "network": "solana",
      "chainId": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "enabled": true,
      "usdcAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "recipientAddress": "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv"
    }
  ],
  "minDurationSeconds": 3600,
  "maxDurationSeconds": 2592000,
  "minTrafficGB": 0.1
}
GET/v1/x402/calculate?tier=shared&duration=3600&traffic=1Scope: public

Calculate cost for specific duration and traffic

Parameters
  • tier - "shared"
  • duration - seconds (e.g., 3600 = 1 hour)
  • traffic - GB amount
Response
{"portCost": 0, "trafficCost": 4, "totalCost": 4, "totalCostMicro": "4000000", "breakdown": {...}}
GET/v1/x402/proxy?country=US&duration=3600&traffic=1Scope: public

Request proxy credentials (returns 402 Payment Required)

Parameters
  • country - ISO code (e.g., "US", "PL", "GB")
  • duration - seconds
  • traffic - GB amount
  • carrier (optional) - specific carrier
402 Response
{
  "x402Version": 1,
  "error": "Payment required to access this resource",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "4000000",
      "resource": "https://api.proxies.sx/v1/x402/proxy?country=US&duration=3600&traffic=1",
      "payTo": "0xF8cD900794245fc36CBE65be9afc23CDF5103042",
      "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "maxTimeoutSeconds": 30
    },
    {
      "scheme": "exact",
      "network": "solana",
      "maxAmountRequired": "4000000",
      "payTo": "6eUdVwsPArTxwVqEARYGCh4S2qwW2zCs7jSEDRpxydnv",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
  ]
}
POST/v1/x402/proxyScope: x402

Purchase proxy (POST method, same as GET)

Request Body
{
  "country": "US",
  "duration": 3600,
  "traffic": 1,
  "tier": "shared"
}
GET/v1/x402/pool/pricingScope: public

Pool Gateway tiers sold over x402 (mbl, peer) with the live price per GB, volume discounts and the username format

Buy Pool Gateway GB with GET or POST /v1/x402/pool?tier=mbl|peer&traffic=<GB>&country=<cc>: without payment it returns HTTP 402 with the USDC amount and payTo address; pay, then repeat the request with Payment-Signature: <tx_hash>. The answer carries gateway credentials (a pak_ password) and an X-Session-Token for /v1/x402/manage/pool/credit, /connection, /usage, /regenerate and /topup.

GET/v1/x402/.well-knownScope: public

Protocol discovery endpoint

Returns x402 protocol information and capabilities.

GET/v1/x402/manage/sessionScope: X-Session-Token

Get session details via session token

Headers
  • X-Session-Token: x402s_...
Response
{
  "sessionId": "...",
  "wallet": "0x...",
  "ports": [...],
  "traffic": {"allocated": 1, "used": 0.2, "remaining": 0.8},
  "expiresAt": "2025-01-15T10:00:00Z"
}
GET/v1/x402/manage/session/creditScope: X-Session-Token

Check remaining credit in session

Response
{
  "trafficGB": 0.8,
  "valueDollars": 3.20
}
GET/v1/x402/manage/portsScope: X-Session-Token

List all ports in session

Response
{
  "ports": [
    {
      "portId": "...",
      "status": "online",
      "country": "US",
      "proxy": {"http": "...", "socks5": "..."}
    }
  ]
}
GET/v1/x402/manage/ports/:portId/statusScope: X-Session-Token

Get status of specific port

Response
{
  "status": "online",
  "lastChecked": "2025-01-15T10:00:00Z",
  "trafficUsed": 0.2
}
POST/v1/x402/manage/ports/replaceScope: X-Session-Token

Replace offline port (free, max 3 per session)

Request Body
{
  "country": "US"
}

Maximum 3 replacements per session. Free of charge.

POST/v1/x402/manage/ports/recreateScope: X-Session-Token

Recreate deleted port using remaining credit

If you deleted a port but still have credit, recreate it in the same session.

GET/v1/x402/manage/session/topup/calculateScope: X-Session-Token

Preview cost of session top-up

Query Parameters
  • addTrafficGB - Additional traffic
  • addDurationSeconds - Additional duration
Response
{
  "cost": "8.00",
  "currency": "USDC"
}
POST/v1/x402/manage/session/topupScope: X-Session-Token + Payment-Signature

Pay to add traffic or duration to session

Headers
  • X-Session-Token: x402s_...
  • Payment-Signature: <tx_hash>
Request Body
{
  "addTrafficGB": 2,
  "addDurationSeconds": 86400
}
GET/v1/x402/session/:idScope: public

Get session by ID

Retrieve session details using session ID.

GET/v1/x402/session/tx/:txHashScope: public

Get session by transaction hash

Look up session using the blockchain transaction hash.

GET/v1/x402/sessions/wallet/:walletScope: public

Get all sessions for a wallet address

Response
{
  "sessions": [
    {
      "sessionId": "...",
      "created": "2025-01-15T10:00:00Z",
      "status": "active"
    }
  ]
}
GET/v1/x402/agents/:walletScope: public

Get agent details by wallet address

Retrieve agent information using wallet address.

GET/v1/rotate/:tokenScope: public

Rotate IP via public rotation token (no auth required)

Example
curl https://api.proxies.sx/v1/rotate/tok_abc123xyz

Rotation token provided in proxy credentials.

Payment Flow

1
Request Proxy
GET /v1/x402/proxy
→
2
Receive 402
Payment details
→
3
Send USDC
Base or Solana
→
4
Get Credentials
Retry with tx hash
# Step 1: Request proxy (get payment requirements)
curl "https://api.proxies.sx/v1/x402/proxy?country=US&duration=3600&traffic=1"

# Response: 402 Payment Required (x402Version 1)
# {
#   "x402Version": 1,
#   "error": "Payment required to access this resource",
#   "accepts": [
#     {
#       "scheme": "exact",
#       "network": "base",
#       "maxAmountRequired": "4000000",
#       "payTo": "0xF8cD900794245fc36CBE65be9afc23CDF5103042",
#       "asset": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"
#     }
#   ]
# }

# Step 2: Send USDC payment to the payTo address (Base or Solana)

# Step 3: Retry the SAME request with your tx hash
curl "https://api.proxies.sx/v1/x402/proxy?country=US&duration=3600&traffic=1" \
  -H "Payment-Signature: 0xYOUR_TX_HASH"

# Step 4: Receive proxy credentials
# {
#   "proxy": {
#     "http": "http://x402_user_abc:generated_pass@SERVER_IP:8080",
#     "socks5": "socks5://x402_user_abc:generated_pass@SERVER_IP:1080",
#     "server": "SERVER_IP",
#     "httpPort": 8080,
#     "socksPort": 1080,
#     "username": "x402_user_abc",
#     "password": "generated_pass",
#     "expiresAt": "2026-01-01T13:00:00Z"
#   },
#   "rotationUrl": "https://api.proxies.sx/v1/rotate/YOUR_ROTATION_TOKEN",
#   "management": { "sessionToken": "x402s_..." }
# }

Peer Marketplace - Earn USDC

Share your internet bandwidth and get paid in USDC on Solana. AI agents and humans connect via WebSocket and route traffic through your device; you earn for eligible customer traffic it serves.

Mobile IPs
Highest Tier
4G/5G carrier IPs — most valuable
Residential IPs
Mid Tier
Home ISP connections
Datacenter IPs
Base Tier
VPS & cloud provider IPs
Note: Earnings per GB are custom and returned upon registration based on IP type, location, and network quality. IP type is determined server-side via ASN lookup. Device withdrawal API minimum: $5 USDC. Before a device is admitted you need a farmer account and API key and a signed Partner Agreement 2.0 that we have approved (the relay closes with 1013 until then); a device goes on sale only after the automatic test (throughput floor 126 KiB/s on October 12, 2026). HTTP 429 means wait for Retry-After. No earnings or approval time is promised.

Peer API Endpoints

POST/v1/peer/agents/registerScope: public

Register as a peer in the network

Request Body
{
  "name": "my-agent",
  "type": "claude",
  "walletAddress": "YOUR_SOLANA_ADDRESS",
  "apiKey": "psx_YOUR_API_KEY"
}

Optional apiKey (format: psx_...) auto-links device to farmer dashboard. Also accepts X-API-Key header.

Response
{
  "deviceId": "agent_abc123",
  "jwt": "eyJ...",
  "refreshToken": "a1b2...",
  "relay": "wss://relay.proxies.sx",
  "earningsPerGB": {
    "mobile": "custom",
    "residential": "custom",
    "datacenter": "custom"
  }
}

Rate limit: up to 600 registrations per minute per source IP; on 429 honor Retry-After

POST/v1/peer/agents/:id/refreshScope: Refresh Token

Refresh JWT token (expires after 1 hour)

Request Body
{
  "refreshToken": "a1b2..."
}
Response
{
  "jwt": "eyJ...",
  "expiresAt": "2025-01-15T11:00:00Z"
}
GET/v1/peer/agents/:id/statusScope: JWT

Get peer status and connection info

Headers
  • Authorization: Bearer <jwt>
Response
{
  "status": "online",
  "connectedAt": "2025-01-15T10:00:00Z",
  "country": "US",
  "ipType": "mobile"
}
GET/v1/peer/agents/:id/earningsScope: JWT

Get earnings and traffic statistics

Response
{
  "totalEarned": 12.50,
  "pendingPayout": 3.25,
  "trafficGB": 50.2,
  "sessionsServed": 145
}
PUT/v1/peer/agents/:id/walletScope: JWT

Update Solana wallet address (7-day cooling period)

Request Body
{
  "walletAddress": "NEW_SOLANA_ADDRESS"
}

Cannot change wallet again for 7 days after update

POST/v1/peer/agents/:id/withdrawScope: JWT

Request payout to Solana wallet (min $5 USDC)

Response
{
  "success": true,
  "amount": 12.50,
  "txHash": "...",
  "processingTime": "24-48 hours"
}

Minimum withdrawal: $5 USDC

Marketplace Listing (Farmer)

PATCH/v1/peer/my-devices/:id/listingScope: JWT / API Key

Toggle device listing for sale in pool gateway

Request Body
{
  "listedForSale": true
}

Triggers automated verification. Device must pass quality checks before serving customer traffic.

GET/v1/peer/my-devices/:id/verificationScope: JWT / API Key

Get verification status, quality score, and check results

Response
{
  "status": "approved",
  "qualityScore": 85,
  "checks": {
    "ipType": { "passed": true, "value": "mobile" },
    "vpnDetection": { "passed": true },
    "hostingDetection": { "passed": true },
    "geoipMatch": { "passed": true, "claimed": "US", "detected": "US" },
    "minimumUptime": { "passed": true, "hours": 12.5 },
    "fraudFlags": { "passed": true }
  },
  "lastChecked": "2026-04-16T10:30:00Z"
}

Checks run every 10 minutes. Score ≥ 50 with all checks passed = auto-approved.

GET/v1/peer/my-devicesScope: JWT / API Key

List all farmer's devices with stats

Response
{
  "devices": [
    {
      "deviceId": "agent_abc123",
      "name": "my-agent",
      "status": "online",
      "listedForSale": true,
      "verified": true,
      "qualityScore": 85,
      "ipType": "mobile",
      "country": "US",
      "trafficGB": 12.5,
      "totalEarned": 3.75
    }
  ]
}

WebSocket — HTTPS Tunnel Support

The relay supports full TCP tunneling for HTTPS traffic alongside standard HTTP proxy requests. Connect at wss://relay.proxies.sx withSec-WebSocket-Protocol: token.YOUR_JWT.

Relay sends to Agent:
  • tunnel_connect — open TCP tunnel (host, port, sessionId)
  • tunnel_data — data to forward to target
  • tunnel_close — close tunnel
  • proxy_request — HTTP request (method, url, headers, body)
  • heartbeat — keepalive ping
Agent sends to Relay:
  • tunnel_connected — TCP tunnel established
  • tunnel_data — forward data from target
  • tunnel_closed — tunnel closed
  • proxy_response — HTTP response (requestId, statusCode, headers, body base64)
  • heartbeat_ack — keepalive response
  • device_info — metadata (country, carrier)

Gateway Integration

Verified + listed peer devices appear in the pool gateway alongside our network of mobile modems. Customers route traffic through peers using this username format:

# HTTP Gateway (port 7000)
{proxyUsername}-peer-{country}@gw.proxies.sx:7000

# SOCKS5 Gateway (port 7001)
{proxyUsername}-peer-{country}@gw.proxies.sx:7001

# Example: route through US peer
curl -x http://psx_YOUR_ID-peer-us:PROXY_PASSWORD@gw.proxies.sx:7000 https://httpbin.org/ip

Security Features

  • • JWT expiry: 1 hour (refresh via refresh token)
  • • Refresh token expiry: 7 days
  • • Max WebSocket connections: 2 per device
  • • Message rate limit: 100/min per device
  • • Registration rate limit: up to 600/min per source IP
  • • Wallet change cooling: 7 days
  • • IP classification: Server-side ASN lookup (cannot spoof)
  • • Wallet change rate limit: 1 per day
  • • Anomaly detection: Flags >$1000 earnings or >100GB/hour
  • • Token revocation: Server-side DB check on every request

AI Agent Discovery

This documentation is optimized for AI agent consumption. Access our machine-readable documentation with MCP Server (101 tools), x402 Protocol and complete API reference:

/llm.txt

SDK & Packages

6 npm packages

npm Packages

PackageDescription
@proxies-sx/mcp-serverMCP server - 101 tools for proxies, Private modems and x402 (v3.2.0)
@proxies-sx/x402-corex402 types, utilities, payment requirement builder
@proxies-sx/x402-honox402 Hono middleware for building paywall APIs
@proxies-sx/x402-solanaSolana transaction verification for x402
@proxies-sx/pool-sdkTyped SDK for the Pool Gateway reseller API - mint access keys, build proxy URLs
@proxies-sx/pool-portal-reactDrop-in React component + hooks for a Pool Gateway reseller dashboard

x402 SDK Example

import { createPaymentRequirement } from '@proxies-sx/x402-core';
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' }));

Discovery Files

FilePurpose
agents.proxies.sx/skill.mdMaster skill file — everything for AI agents in one read
proxies.sx/llms.txtLLM integration reference
agents.proxies.sx/.well-known/x402.jsonx402 protocol discovery
agents.proxies.sx/peer/skill.mdPeer marketplace detailed skill

Live Domains

api.proxies.sx
REST API + x402
client.proxies.sx
Customer portal
agents.proxies.sx
Agent hub
relay.proxies.sx
WebSocket relay
gw.proxies.sx
Proxy gateway

Ready to Integrate?

Get your API key from the dashboard or pay with USDC on-chain — no account needed.

PROXIES.SX (proxies.sx) is an independent brand and is not affiliated with, endorsed by, or connected to SX.ORG or the sx.org domain, and does not operate as SX.ORG. References to "$SX" or "SX" refer solely to PROXIES.SX and its own products and token, not to sx.org.