PEER NETWORK

WHAT IS IT

The Proxies.sx Peer Network pays for bandwidth. Proxy customers route traffic through your device's connection; every routed GB accrues to your balance at the rate for your IP type. Payouts are USDC on Solana.

Three Ways to Participate

All methods speak the same relay protocol and earn at the same per-IP-type rates. Connect to the relay URL returned by registration (wss://relay.proxies.sx or a nearer regional relay - the register response's relay field is authoritative).

EARNINGS BREAKDOWN

Per-GB Rate Tiers

Your payout is a revenue share of the revenue actually collected on the traffic your device serves, set by Proxies.sx and customized per partner - there is no fixed public percentage; rates are configured by our team, can be tailored to you, and move with demand, paid NET with no platform fee taken on top. Get the current value by calling POST /v1/peer/agents/register and reading the earningsPerGB field, which shows live values for each tier at registration time. The same revenue-share model applies identically to AI agents, Android SDK devices, and modem farmers - a real mobile carrier IP earns the mobile tier regardless of how it joined the network. IP type is determined server-side via ASN lookup; device-reported type is ignored (cannot spoof).

How Your Earnings Are Calculated

Your payout is a revenue share of the revenue actually collected on the traffic your device serves - paid NET, with no platform fee taken on top. There is no fixed public percentage: it's set by Proxies.sx, customized per partner, and moves with demand and IP type - so read the live value in earningsPerGB at registration rather than assuming a fixed number.

There is no fixed monthly figure: your total = your revenue share x the GB actually routed through your device, which depends on demand, location, uptime, and carrier ASN reputation. Live per-GB rate at any moment: POST /v1/peer/agents/register -> the earningsPerGB field.

Rate Comparison vs Flat-Rate Platforms

Rates for real mobile IPs are tiered above residential and datacenter because AI agent and scraper demand concentrates on carrier IPs; flat-rate competitors pay one rate regardless of IP type. Earnings accumulate per-GB on every routed byte; payouts run weekly in USDC on Solana. Live rate at any moment: POST /v1/peer/agents/register -> check the earningsPerGB field in the response.

Payout Details

HOW IT WORKS

1. Register     POST /v1/peer/agents/register - get deviceId + JWT (1h) + refreshToken
                Pass apiKey="psx_..." so earnings auto-link to your account
2. Connect      to the relay URL from the register response (register.relay, geo-assigned)
                with Sec-WebSocket-Protocol: token.{JWT}
3. Heartbeat    Send {"type":"heartbeat"} every 30s - the relay replies heartbeat_ack
                (peers silent for 120s are force-closed by the zombie sweep)
4. Refresh      POST /v1/peer/agents/{id}/refresh - every ~50 min before JWT expires
5. Tunnel       Receive tunnel_connect -> open TCP to the target -> stream bytes both ways
                (the ready SDKs below do this for you; see the diagnostic note)
6. Earn         a revenue share of collected revenue - rate set by Proxies.sx,
                customized per partner, moves with demand - live per-GB rate in
                earningsPerGB field of the register response. Withdraw at
                $5+ (agents) / $10+ (SDK devices).

Architecture

+-----------------+     +------------------+     +------------------+
|   Your Device   |---->|   Relay Server   |<----|  Proxy Gateway   |
|  (Peer Node)    |     | (WebSocket Hub)  |     |  (HTTP Proxy)    |
+-----------------+     +------------------+     +------------------+
        |                       |                        |
        | Share bandwidth       | Match peers to         | Accept customer
        v                       | proxy requests         | connections
+-----------------+     +------------------+     +------------------+
| Earn by IP type:|     |  wss://relay     |     |  gw.proxies.sx   |
| Earn per GB     |     |  .proxies.sx     |     |  port 7000       |
| Auto-accumulate |     |                  |     |                  |
| USDC payouts    |     |                  |     |                  |
+-----------------+     +------------------+     +------------------+

Relay Server - WebSocket hub that manages peer connections and routes proxy traffic between customers and peers.

Gateway - HTTP proxy server that accepts customer connections (host:port with credentials) and forwards traffic through matched peers via the relay.

Backend API - Handles registration, authentication, earnings tracking, payouts, and IP classification.

QUICK START

1. Register

curl -s -X POST 'https://api.proxies.sx/v1/peer/agents/register' \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "type": "claude",
    "walletAddress": "YOUR_SOLANA_ADDRESS",
    "apiKey": "psx_YOUR_API_KEY"
  }'

# Response:
# {
#   "deviceId": "agent_abc123",
#   "jwt": "eyJ...",                          // 1-hour JWT
#   "refreshToken": "a1b2...",                // store this, used to refresh JWT
#   "relay": "wss://relay.proxies.sx",
#   "earningsPerGB": { "mobile": <CURRENT_RATE>, "residential": <CURRENT_RATE>, "datacenter": <CURRENT_RATE> }
#   (rates set by platform, can change anytime - read this field to know your live rate)
# }

apiKey is optional but strongly recommended. Without it the device registers as an orphan and earnings can't be credited to your account. Get an API key for free at client.proxies.sx -> API Keys -> New. SDK devices auto-link to the farmer/peer account that owns the API key.

JWT lifespan: 1 hour. To avoid disconnect, save the refreshToken and call POST /v1/peer/agents/{deviceId}/refresh with body {"refreshToken":"..."} before the JWT expires (rate limit: 10 refreshes per minute). The relay closes the WebSocket with code 4002 if the JWT is invalid/expired (4001 = you sent no token at all) - on a 4001/4002 close, refresh the JWT once for all sockets and reconnect.

2. Connect via WebSocket and Serve Tunnels

Current protocol: streaming TCP tunnels (tunnel_connect / tunnel_data / tunnel_close). The JWT goes in the Sec-WebSocket-Protocol header as token.<jwt>, never in the URL. Connect to the relay URL from your register response, not a hardcoded host.

const net = require('net');
const tunnels = new Map();  // sessionId -> TCP socket

const ws = new WebSocket(register.relay, [`token.${JWT}`]);  // JWT in Sec-WebSocket-Protocol

ws.on('open', () => {
  // REQUIRED: send a heartbeat every 30s; the relay replies heartbeat_ack.
  // The relay never pings you - peers silent for 120s are force-closed.
  const heartbeatTimer = setInterval(() => ws.send(JSON.stringify({ type: 'heartbeat', payload: {} })), 30000);
  ws.once('close', () => clearInterval(heartbeatTimer));

  ws.send(JSON.stringify({
    type: 'device_info',
    payload: {
      country: 'US',
      protocol: 'binary-v1',        // opt into binary tunnel frames (faster; see /peer/skill.md)
      supportsRelayRedirect: true   // honor server-driven nearest-relay routing
    }
  }));
});

ws.on('message', (raw, isBinary) => {
  if (isBinary) return handleBinaryFrame(raw);  // binary-v1 tunnel_data/tunnel_close - framing in /peer/skill.md
  const msg = JSON.parse(raw.toString());
  if (msg.type === 'tunnel_connect') {
    const { sessionId, host, port } = msg.payload;
    const sock = net.connect(port, host);         // open TCP to the target
    tunnels.set(sessionId, sock);
    sock.on('connect', () => ws.send(JSON.stringify({ type: 'tunnel_connected', payload: { sessionId } })));
    sock.on('data', (d) => ws.send(JSON.stringify({ type: 'tunnel_data', payload: { sessionId, data: d.toString('base64') } })));
    sock.on('close', () => { tunnels.delete(sessionId); ws.send(JSON.stringify({ type: 'tunnel_closed', payload: { sessionId } })); });
  }
  if (msg.type === 'tunnel_data')  { const s = tunnels.get(msg.payload.sessionId); if (s) s.write(Buffer.from(msg.payload.data, 'base64')); }
  if (msg.type === 'tunnel_close') { const s = tunnels.get(msg.payload.sessionId); if (s) s.destroy(); }
  if (msg.type === 'heartbeat_ack') { /* relay ack of your heartbeat - no action needed */ }
});

Sharp edge: after tunnel_connect, the first bytes must flow back within 5 seconds or the relay force-closes the tunnel (tunnel_open_timeout); repeated failures delist the device. The older proxy_request/proxy_response flow is legacy - do not build new clients on it. Full message reference: /peer/skill.md.

3. Refresh JWT Before It Expires (1h)

curl -s -X POST "https://api.proxies.sx/v1/peer/agents/${DEVICE_ID}/refresh" \
  -H "Content-Type: application/json" \
  -d "{\"refreshToken\":\"${REFRESH_TOKEN}\"}"

# Response:  { "jwt": "eyJ...new...", "expiresIn": "1h" }
#
# Run this every ~50 minutes to keep your WebSocket alive without re-registering.
# If the relay closes with code 4002 (invalid/expired JWT; 4001 = no token sent),
# refresh ONCE for all sockets and reconnect with the new JWT.
# Code 1013 = transient backend issue: retry with the SAME token, do not re-register.
# Rate limit: 10 refreshes / minute.

4. Check Earnings

curl -s "https://api.proxies.sx/v1/peer/agents/${DEVICE_ID}/earnings" \
  -H "Authorization: Bearer $JWT" | jq

# Response shows:
#   pendingPayoutCents      - earned but not yet paid (you'll see this grow per GB)
#   totalEarnedCents        - lifetime earnings
#   minimumPayoutCents      - 500 ($5) for agents, 1000 ($10) for SDK devices
#   canRequestPayout        - true once pending >= minimum
#   ipType                  - your detected IP class (sets your rate tier)
#   earningsPerGB           - live per-GB rates by tier (the authoritative rate)

5. Request Payout

curl -s -X POST "https://api.proxies.sx/v1/peer/agents/${DEVICE_ID}/withdraw" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"walletAddress":"YOUR_SOLANA_ADDRESS"}'

# Note: walletAddress is REQUIRED by validation (a valid 32-44 char base58
# Solana address; an empty body {} is rejected with 400) - but the payout
# wallet is ALWAYS the one you registered with (or set via
# /v1/peer/agents/:id/wallet). The body value is intentionally ignored if a
# wallet is already registered, to prevent siphoning.
# Wallet changes have a 7-day cooling period before withdrawals work again.
#
# Min payout: $5 for agents, $10 for SDK devices.
# Admin processes USDC payouts within 24-48 hours.

6. Docker One-Liner

# Runs the official tested SDK (reference-sdk.js). Just pass your API key.
#  - The -v volume PERSISTS the device identity, so a restart REUSES the same
#    device (token refresh) instead of registering a new one (no orphan devices,
#    no register 429s).
#  - No AGENT_NAME is set on purpose: the SDK defaults to the container's unique
#    hostname, so each container is its own stable device (setting the SAME name
#    on many containers would collapse them into ONE device - do not do that).
#  - The deps/download are guarded, so a restart is instant and never resets
#    docker's restart backoff.
docker run -d --name proxies-peer \
  -e API_KEY=psx_your_key \
  -e PEER_STATE_FILE=/state/id.json \
  -v proxies-peer-state:/state \
  --restart unless-stopped \
  node:20-alpine sh -c "[ -e node_modules/ws ] || npm i ws; [ -f reference-sdk.js ] || wget -qO reference-sdk.js https://agents.proxies.sx/peer/reference-sdk.js; node reference-sdk.js"

Getting 429 on register? You are starting many peers at once from ONE machine/IP. The Node SDK (v1.4.1) and the Go SDK (v1.3.3) already back off instead of crash-looping, and REGISTER_JITTER_MS spreads a fleet's first registration automatically - so a burst settles on its own within a minute. For a real fleet: one container per outbound IP (the network pays for the ACTUAL exit IP - 500 containers behind one VPS IP is ONE datacenter exit, not 500 residential ones), each with a unique AGENT_NAME and its own -v state volume.

ALL PEER API ENDPOINTS

Base URL: https://api.proxies.sx

Agent Management

Device Management

Routing customer traffic

Customers route traffic through the unified pool gateway at gw.proxies.sx:7000 (HTTP CONNECT) or gw.proxies.sx:7001 (SOCKS5), authenticated with a customer's psx_* username and proxy password - or a pool access key (pak_*). The peer-fleet composition, exit IPs, and per-device endpoints are not exposed publicly - doing so historically resulted in anti-bot vendors pre-blacklisting the entire inventory before any customer connected (DataDome t=bv ban pattern). The gateway's /v1/gateway/pool/availability returns coarse country counts only.

Peer Account (Portal) COMING SOON

These endpoints are not yet deployed. Use the Agent Management endpoints above.

Internal (Relay/Gateway Only)

Internal Key = internal service authentication (server-to-server only, not available to customers or peers). JWT = Authorization: Bearer <token>. API Key = X-API-Key header.

USE CASES

THE GOAL: AN HTTP PROXY ENDPOINT FROM A REAL IP

Everything on this page reduces to one contract: deliver an HTTP proxy endpoint from a device with a real mobile or residential IP, and get paid per GB routed.

The relay server, gateway, SDKs, Docker images, and API are provided paths - not the only paths. If you can expose an HTTP proxy from a mobile phone, a residential router, a 5G hotspot, or any device with a real-world IP by another method, that method is accepted.

What We Actually Need

Input:  A device with a real mobile/residential IP
Output: An HTTP proxy endpoint that routes traffic through that device
Result: We pay you per GB routed

The WebSocket relay is one path. The Android SDK is another. Docker is a third. A Raspberry Pi on a home network, a fleet of IoT devices, a custom SOCKS5-to-HTTP bridge, a mesh network, or something not yet on this list all qualify - the contract above is the only requirement.

Verify Your Peer Works (self-test)

Ready clients (Node.js, Go, Windows, Android) are listed once in Quick Start. All speak the identical relay protocol (register -> WebSocket -> binary tunnels -> nearest-relay redirect); each desktop/server client is a single file.

The real "is it working" signal is your device showing online + verified at farmer.proxies.sx - you don't need to curl-test it. The optional self-test below is a customer-side request: run with verbose logging and send a request through your own device (curl -x "http://psx_ACCOUNTID-peer-COUNTRY-pin-device-DEVICEID:PROXY_PASSWORD@gw.proxies.sx:7000" https://api.ipify.org) - you should see TUNNEL_CONNECT then TCP_OPEN_OK in your peer log. It needs a proxy password (set at client.proxies.sx/account) and a small traffic balance; a 407 means the curl's credentials are missing/wrong, not that your peer is broken. Porting to another language? The two things that bite hand-written ports: put the JWT in the Sec-WebSocket-Protocol header as token.<jwt> (never in the URL), and on an auth-failure close refresh the identity once for all sockets (do not relaunch your whole socket pool - that leaks connections and dials with stale tokens). The Go file documents both inline.

Freestyle Methods Welcome

The only hard requirements: the IP must be real (server-side ASN classification determines type and rate), traffic must actually flow through your device, and you connect via the relay protocol so traffic can be routed and metered. Everything else - language, runtime, hardware, architecture - is your choice.

If a detail is undocumented, build against the relay protocol in /peer/skill.md and verify with the self-test above. The peer system accepts any device that can handle HTTP traffic.

GROWING THE NETWORK

More peers = more diverse IPs = better success rates for proxy customers = more traffic routed = more earnings for everyone.

Telegram Bot Onboarding

The @proxies_sx Telegram channel provides onboarding for new peers. Share it with anyone interested in passive income.

AI Agent Self-Registration

AI agents can register in 2 API calls with no human intervention:

# 1. Register
curl -X POST 'https://api.proxies.sx/v1/peer/agents/register' \
  -H "Content-Type: application/json" \
  -d '{"name":"auto-agent","type":"custom","walletAddress":"SOLANA_WALLET"}'

# 2. Connect to relay with returned JWT
# (WebSocket connection - see Quick Start above)

Auto-Deploy Scripts

# Docker one-liner: see Quick Start step 6 (node:20-alpine + reference-sdk.js).
# The client takes -e API_KEY=psx_... - it registers itself and manages its
# own JWT lifecycle; there is no prebuilt "proxies-peer" image to pull.

# Fleets: run one container per device/IP. Each container already gets a unique
# stable identity (its hostname) - just give each its OWN state volume
# (-e PEER_STATE_FILE=/state/id.json -v peerNN:/state). Never set the SAME
# AGENT_NAME on multiple containers (same name + same key = ONE shared device).
#
# What earns residential rate: the peer's ACTUAL outbound IP is what we classify
# and pay (device-reported type is ignored). One container per residential line
# earns residential; many containers behind one VPS all exit that VPS's single
# datacenter IP - so they earn datacenter tier and share one register limit.
#
# The relay accepts ~50 sockets per source IP. The SDK opens WS_CONNECTIONS (4)
# each, so ~12 peers fit behind one IP. If you must share an IP, set
# WS_CONNECTIONS=1. For real scale, give each peer its own egress IP.
# docker-compose with one service per real egress IP works well.

Referral System (Technical Details)

Every peer account gets a unique referral code on creation. Share it with others - when they register with your code, you're linked permanently.

How Referrals Work (Step by Step)

1. You register as peer  ->  system generates your code (e.g. PEER_ABC123)
2. You share your code   ->  give it to humans, post it, embed in bots
3. New peer registers    ->  passes referralCode: "PEER_ABC123" in body (coming soon)
4. System links them     ->  your referralCount increments by 1 (coming soon)
5. They route traffic    ->  you earn 10% of their earnings for 30 days
6. Check your stats      ->  GET /v1/peer-account/referrals (coming soon)

How to Register With a Referral Code

# NOT YET DEPLOYED - this flow goes live with the Peer Account Portal (returns 404 today)
# New peer signs up with YOUR referral code
curl -s -X POST https://api.proxies.sx/v1/peer-auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newpeer@example.com",
    "password": "SecurePass123!",
    "name": "New Peer",
    "referralCode": "PEER_ABC123"
  }'

How to Check Your Referral Stats

# NOT YET DEPLOYED - this flow goes live with the Peer Account Portal (returns 404 today)
# Get your referral code and referred users
curl -s https://api.proxies.sx/v1/peer-account/referrals \
  -H "Authorization: Bearer $JWT"

# Response:
# {
#   "referralCode": "PEER_ABC123",
#   "referralCount": 5,
#   "referralEarningsCents": 1250,
#   "referredUsers": [
#     { "email": "ne***@example.com", "name": "New Peer", "joinedAt": "2026-02-05T..." }
#   ]
# }

Status: Referral linking ships with the Peer Account Portal and is not live yet - the current registration endpoints (POST /v1/peer/agents/register) do not accept a referralCode field, and POST /v1/peer-auth/register returns 404 today. Codes, tracking, and the 10% earnings bonus activate when the portal deploys.

Ways to Share Your Referral Code

Community Channels

SECURITY & TRUST

ANDROID SDK BETA

GitHub: github.com/bolivian-peru/android-peer-sdk

The Android SDK is currently in beta. API surface may change. Report issues on GitHub.

Installation

// build.gradle (app-level)
implementation("com.github.bolivian-peru:android-peer-sdk:1.3.1")

// settings.gradle - add JitPack
dependencyResolutionManagement {
    repositories {
        maven { url 'https://jitpack.io' }
    }
}

Usage

// Initialize
ProxiesPeerSDK.init(context, "api-key", config)

// Start sharing bandwidth
ProxiesPeerSDK.getInstance().start()

// Stop sharing
ProxiesPeerSDK.getInstance().stop()

IP Rotation PLANNED

SDK-side IP rotation (airplane-mode toggle on non-rooted Android) is on the roadmap but not in v1.1.x. Tracked under Phase 3b of the SDK production-readiness plan. The backend route POST /v1/peer/devices/:id/rotate exists but returns 501 for v1.1.x devices until the SDK ships an AirplaneModeAccessibilityService.

Developer Revenue Model

App developers integrate the SDK and earn a revenue share of the revenue collected on each GB routed through their users' devices, paid NET. Your payout is a revenue share set by Proxies.sx and customized per partner - there is no fixed public percentage; rates are configured by our team, can be tailored to you, and move with demand. Earnings accumulate automatically - the live per-GB rate is set by IP type (mobile > residential > datacenter), classified server-side via ASN lookup.

Contact us for custom SDK integration terms and revenue splits.

LINKS

Discovery Files

Live Domains

GitHub

Social

Twitter/X | Telegram | GitHub

Support

Email maya@proxies.sx or message https://t.me/proxies_sx. If a gateway error gave you a req: id, quote it.