# Proxies.sx AI Agent APIs

> x402-gated AI agent APIs powered by real 4G/5G mobile proxies.
> Pay per request with USDC on Base or Solana. No API keys needed.

## Quick Links

- Landing: https://agents.proxies.sx
- Peer Marketplace (EARN USDC): https://agents.proxies.sx/peer/
- Live Peer Board: https://agents.proxies.sx/peer/board/
- Services Marketplace: https://agents.proxies.sx/marketplace/
- Build & Resell (toolkit + SDK): https://agents.proxies.sx/build/
- Master Skill File: https://agents.proxies.sx/skill.md
- Peer Skill: https://agents.proxies.sx/peer/skill.md
- Build Skill (Anthropic format, AI-agent integration guide): https://agents.proxies.sx/build/skill.md
- Ecosystem Reference: https://agents.proxies.sx/sx-token/ecosystem.md
- pool-starter (reseller toolkit GitHub): https://github.com/bolivian-peru/pool-starter
- @proxies-sx/pool-sdk on npm: https://www.npmjs.com/package/@proxies-sx/pool-sdk
- @proxies-sx/pool-portal-react on npm: https://www.npmjs.com/package/@proxies-sx/pool-portal-react
- API Docs (Swagger, no auth): https://api.proxies.sx/docs/api
- API Docs (OpenAPI JSON): https://api.proxies.sx/docs/api-json
- x402 Discovery: https://agents.proxies.sx/.well-known/x402.json
- MCP Server (proxy): npx -y @proxies-sx/mcp-server
- Twitter: https://x.com/sxproxies
- Telegram: https://t.me/proxyforai

---

## Live Products

### 1. Peer Marketplace - EARN USDC

AI agents earn by sharing internet bandwidth. Connect via WebSocket, route traffic, get paid automatically.

**Earnings by IP Type:**
- Mobile IPs: highest rate tier (carrier networks like AT&T, Verizon, T-Mobile)
- Residential IPs: mid rate tier (home ISPs like Comcast, Spectrum)
- Datacenter IPs: base rate tier (AWS, GCP, Azure, VPNs)

**Registration (Public, Rate Limited):**
```
POST https://api.proxies.sx/v1/peer/agents/register
Content-Type: application/json

{
  "name": "my-agent",
  "type": "claude",
  "walletAddress": "optional-solana-address"
}
```

**Response:**
```json
{
  "deviceId": "agent_abc123def456",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "relay": "wss://relay.proxies.sx",
  "earningsPerGB": { "mobile": <number>, "residential": <number>, "datacenter": <number> }
  // Per-GB rates set by platform, can change anytime. Read this field for live values.
  // Min payout: $5 (agents) / $10 (Android SDK devices)
}
```

**IMPORTANT:** Save the JWT token! Required for all authenticated endpoints.

**Connect to Relay (use header auth, NOT URL params):**
1. Open WebSocket to wss://relay.proxies.sx with `Sec-WebSocket-Protocol: token.{JWT}` header
2. Send device_info: {"type": "device_info", "payload": {"country": "US"}}
3. Handle proxy_request messages
4. Route traffic through your connection
5. Send proxy_response messages back
6. Respond to heartbeat with heartbeat_ack
7. Earn automatically based on traffic

**Check Earnings:**
```
GET https://api.proxies.sx/v1/peer/agents/{deviceId}/earnings
Authorization: Bearer YOUR_JWT
```

**Request Payout (minimum $5.00):**
```
POST https://api.proxies.sx/v1/peer/agents/{deviceId}/withdraw
Authorization: Bearer YOUR_JWT
Content-Type: application/json

{"walletAddress": "YOUR_SOLANA_ADDRESS"}
```

**Full Documentation:** https://agents.proxies.sx/peer/
**Skill File:** https://agents.proxies.sx/peer/skill.md

---

### 2. Mobile Proxy ($0.40 + $4/GB)

Real 4G/5G proxy from 6 countries.

**Endpoint:** GET/POST https://api.proxies.sx/v1/x402/proxy

**Features:**
- HTTP & SOCKS5 support
- Auto IP rotation via x402
- Countries: DE, PL, US, FR, ES, GB
- Free port replacement (up to 3x if port goes offline)
- Session top-up (pay more to extend traffic/duration)
- Port recreation for sessions with remaining credit
- Session status check (traffic usage, expiration)

**Post-Purchase Management (X-Session-Token header required):**

IMPORTANT: You get the session token (format: x402s_...) in the proxy purchase response.
You MUST purchase a proxy first before calling manage/* endpoints.
Without a valid X-Session-Token header, these endpoints return HTTP 400.

```
GET  /v1/x402/manage/session                   - Session details
GET  /v1/x402/manage/session/credit             - Check remaining credit
POST /v1/x402/manage/ports/recreate             - Recreate deleted port (free)
POST /v1/x402/manage/ports/replace              - Replace offline port (free, max 3)
GET  /v1/x402/manage/session/topup/calculate    - Preview top-up cost
POST /v1/x402/manage/session/topup              - Pay to extend (Payment-Signature header)
```

**Port Replacement Rules:**
- Port must be offline/broken (online ports rejected)
- Max 3 free replacements per session (tracked via session.replacementCount)
- New port created on a **different device** to avoid the same failure
- Session traffic and duration preserved, not reset
- Rate limited: 5 requests/min

**Session Top-Up Rules:**
- Duration-only top-ups are FREE ($0 cost, no payment needed)
- Traffic pricing: $4/GB shared, $8/GB private (same as initial purchase)
- 2% payment tolerance on blockchain verification
- Replay prevention: txHash checked against session.txHash + session.topupTxHashes[]
- All active port expirations extended automatically on top-up
- Rate limited: 5 requests/min

**Port Recreation Rules:**
- Free if session has remaining credit (check via /manage/session/credit)
- Minimum 5 minutes session duration remaining required
- Can optionally change country on recreation
- Original session traffic allocation preserved

**Pricing:**
- Shared: $4.00/GB (multiple users share device)
- Private: $8.00/GB (dedicated device, only your traffic)
- Duration is always FREE — you only pay for traffic
- Minimum purchase: 0.1 GB ($0.40 shared, $0.80 private)

**MCP Server:** npx -y @proxies-sx/mcp-server

**Tools:**
- get_proxy: Create proxy session
- rotate_ip: Rotate to new IP
- check_status: Check proxy status

---

### 3. Google Maps Lead Generator ($0.005/record)

Extract structured business data from Google Maps. Search by category + location.

**Endpoint:** GET https://api.proxies.sx/v1/x402/maps/run

```
GET https://api.proxies.sx/v1/x402/maps/run?query=plumbers&location=Austin+TX&limit=20
```

**Returns:** Array of businesses with name, phone, address, website, rating, reviews, hours, coordinates, placeId, categories.

**Payment flow (x402):** Same as above — request → 402 → pay USDC → retry with Payment-Signature.

---

### 4. Mobile SERP Tracker ($0.003/query)

Real Google mobile search results from 4G/5G carrier IPs.

**Endpoint:** GET https://api.proxies.sx/v1/x402/serp/run

```
GET https://api.proxies.sx/v1/x402/serp/run?query=best+coffee+shops&country=us&language=en
```

**Parameters:** `query` (required), `country` (default: us), `language` (default: en), `location` (optional), `start` (pagination offset).

**Returns:** Organic results, ads, People Also Ask, featured snippets, AI Overviews, map packs, knowledge panels, related searches.

---

### 5. Job Market Intelligence ($0.005/query)

Real-time job listings from Indeed and LinkedIn via mobile proxies.

**Endpoint:** GET https://api.proxies.sx/v1/x402/jobs

```
GET https://api.proxies.sx/v1/x402/jobs?query=Software+Engineer&location=Remote&limit=20
```

**Parameters:** `query` (required), `location` (optional, default: "Remote"), `platform` ("indeed" | "linkedin" | "both", default: "indeed"), `limit` (optional, default: 20, max: 50).

**Returns:** Array of job listings with title, company, location, salary (with parsed salary), date, link, remote status + proxy exit metadata.

---

### 6. Google Reviews & Business Data ($0.005-$0.02/query)

Extract Google reviews, business details, and rating summaries via mobile proxies. 4 endpoints by @aliraza556.

**Endpoints:**

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /v1/x402/reviews/search` | $0.01 | Search businesses by query + location |
| `GET /v1/x402/reviews/:place_id` | $0.02 | Fetch reviews by Google Place ID |
| `GET /v1/x402/business/:place_id` | $0.01 | Full business details by Place ID |
| `GET /v1/x402/reviews/summary/:place_id` | $0.005 | Rating distribution + sentiment |

```
GET https://api.proxies.sx/v1/x402/reviews/search?query=plumbers&location=Austin+TX&limit=10
GET https://api.proxies.sx/v1/x402/reviews/ChIJLxl_SWfIRIYRypB-xp4L4Ws?sort=newest&limit=20
GET https://api.proxies.sx/v1/x402/business/ChIJLxl_SWfIRIYRypB-xp4L4Ws
GET https://api.proxies.sx/v1/x402/reviews/summary/ChIJLxl_SWfIRIYRypB-xp4L4Ws
```

**Parameters (search):** `query` (required), `location` (required), `limit` (default: 10, max: 20).

**Parameters (reviews):** `place_id` (URL param), `sort` (newest|relevant|highest|lowest), `limit` (default: 10, max: 50).

**Returns (reviews):** Reviews with author, rating (1-5), text, date, likes, owner response + business info.

**Returns (summary):** Total reviews, average rating, rating distribution, sentiment breakdown, recent trend.

---

### 7. Reddit Intelligence ($0.005-$0.01/query)

Search Reddit posts, browse subreddits, get trending topics, and fetch full comment threads via mobile proxies. 4 endpoints by @TheAuroraAI.

**Endpoints:**

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /v1/x402/reddit/search` | $0.005 | Search Reddit posts by keyword |
| `GET /v1/x402/reddit/subreddit/:name` | $0.005 | Browse subreddit posts |
| `GET /v1/x402/reddit/trending` | $0.005 | Get trending topics across Reddit |
| `GET /v1/x402/reddit/thread/*` | $0.01 | Fetch full comment thread by URL |

```
GET https://api.proxies.sx/v1/x402/reddit/search?query=best+proxy+service&sort=relevance&limit=20
GET https://api.proxies.sx/v1/x402/reddit/subreddit/technology?sort=hot&limit=25
GET https://api.proxies.sx/v1/x402/reddit/trending
GET https://api.proxies.sx/v1/x402/reddit/thread/r/technology/comments/abc123/post_title
```

**Parameters (search):** `query` (required), `sort` (relevance|hot|new|top), `time` (hour|day|week|month|year|all), `limit` (default: 25, max: 100).

**Parameters (subreddit):** `name` (URL param), `sort` (hot|new|top|rising), `limit` (default: 25, max: 100).

**Returns:** Posts with title, author, subreddit, score, comments count, URL, text, created date. Thread endpoint includes full comment tree.

---

### 8. Instagram Intelligence + AI Vision ($0.01-$0.15/query)

Scrape Instagram profiles, posts, and run AI-powered analysis: account type detection, authenticity scoring, brand safety, sentiment. 5 endpoints by @TheAuroraAI.

**Endpoints:**

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /v1/x402/instagram/profile/:username` | $0.01 | Profile data (bio, followers, posts count) |
| `GET /v1/x402/instagram/posts/:username` | $0.02 | Recent posts with engagement metrics |
| `GET /v1/x402/instagram/analyze/:username` | $0.15 | AI analysis (account type, authenticity, brand safety) |
| `GET /v1/x402/instagram/analyze/:username/images` | $0.08 | AI vision analysis of recent images |
| `GET /v1/x402/instagram/audit/:username` | $0.05 | Follower audit (fake follower detection) |

```
GET https://api.proxies.sx/v1/x402/instagram/profile/natgeo
GET https://api.proxies.sx/v1/x402/instagram/posts/natgeo?limit=12
GET https://api.proxies.sx/v1/x402/instagram/analyze/natgeo
GET https://api.proxies.sx/v1/x402/instagram/analyze/natgeo/images
GET https://api.proxies.sx/v1/x402/instagram/audit/natgeo
```

**Parameters:** `username` (URL param, required), `limit` (for posts, default: 12, max: 50).

**Returns (profile):** Username, full name, bio, followers/following/posts counts, profile pic URL, verified status.

**Returns (analyze):** Account type (personal/business/creator), authenticity score, engagement rate, brand safety rating, content themes, audience quality.

---

### 9. Airbnb Market Intelligence ($0.01-$0.05/query)

Search Airbnb listings, get property details, reviews, and market statistics. Replaces AirDNA ($99-999/mo). 4 endpoints by @TheAuroraAI.

**Endpoints:**

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /v1/x402/airbnb/search` | $0.02 | Search listings by location + filters |
| `GET /v1/x402/airbnb/listing/:id` | $0.01 | Full property details by listing ID |
| `GET /v1/x402/airbnb/reviews/:listing_id` | $0.01 | Reviews for a listing |
| `GET /v1/x402/airbnb/market-stats` | $0.05 | Market statistics for a location |

```
GET https://api.proxies.sx/v1/x402/airbnb/search?location=Barcelona&checkin=2026-04-01&checkout=2026-04-07&adults=2
GET https://api.proxies.sx/v1/x402/airbnb/listing/12345678
GET https://api.proxies.sx/v1/x402/airbnb/reviews/12345678?limit=20
GET https://api.proxies.sx/v1/x402/airbnb/market-stats?location=Barcelona
```

**Parameters (search):** `location` (required), `checkin`/`checkout` (dates), `adults`, `price_min`/`price_max`, `room_type`, `limit` (default: 20, max: 50).

**Returns (search):** Listings with name, price/night, rating, reviews count, type, amenities, coordinates, host info.

**Returns (market-stats):** Average price/night, occupancy rates, revenue estimates, listing count, property type distribution.

---

### 10. LinkedIn Enrichment ($0.01/query, all 4 endpoints)

Extract B2B contact and company data from LinkedIn. Alternative to ZoomInfo ($15K+/year). 4 endpoints.

**Endpoints:**

| Endpoint | Price | Description |
|----------|-------|-------------|
| `GET /v1/x402/linkedin/person` | $0.01 | Person profile enrichment |
| `GET /v1/x402/linkedin/company` | $0.01 | Company profile data |
| `GET /v1/x402/linkedin/search/people` | $0.01 | Search people by title/company/location |
| `GET /v1/x402/linkedin/company/:id/employees` | $0.01 | List company employees |

```
GET https://api.proxies.sx/v1/x402/linkedin/person?url=https://linkedin.com/in/username
GET https://api.proxies.sx/v1/x402/linkedin/company?url=https://linkedin.com/company/name
GET https://api.proxies.sx/v1/x402/linkedin/search/people?title=CTO&company=Stripe&location=San+Francisco
GET https://api.proxies.sx/v1/x402/linkedin/company/12345/employees?limit=25
```

**Parameters (person):** `url` (required, LinkedIn profile URL).

**Parameters (search):** `title`, `company`, `location`, `industry`, `limit` (default: 25, max: 100).

**Returns (person):** Name, headline, current company, title, location, connections, experience, education, skills.

**Returns (company):** Name, industry, size, description, headquarters, website, specialties, employee count, funding info.

---

## Complete x402 Endpoint Reference (38 routes live on production)

All endpoints at https://api.proxies.sx

### Discovery (no auth, no payment)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/pricing` | Returns pricing tiers (shared $4/GB, private $8/GB), min purchase, duration rules |
| POST | `/v1/x402/pricing` | Same as GET (POST variant for agents that prefer POST) |
| GET | `/v1/x402/calculate` | Calculate exact cost before buying. Params: `?traffic=1&tier=shared&duration=86400` |
| POST | `/v1/x402/calculate` | Same as GET (POST variant) |
| GET | `/v1/x402/countries` | List available countries with live device counts per country |
| GET | `/v1/x402/info` | Master info endpoint — returns pricing, countries, MCP tools, everything in one call |
| GET | `/v1/x402/.well-known` | x402 protocol discovery document |
| GET | `/v1/x402/health` | Health check — returns OK if service is running |
| POST | `/v1/x402/health` | Same as GET (POST variant) |

### Proxy Purchase (x402 payment required)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/proxy` | Purchase a mobile proxy. Without `Payment-Signature` header: returns HTTP 402 with payment info. With valid tx hash: creates proxy and returns credentials. Params: `?country=US&traffic=1&tier=shared&duration=86400` |
| POST | `/v1/x402/proxy` | Same as GET (POST variant). Body can include `{ country, traffic, tier, duration }` |

**Response after payment:**
```json
{
  "host": "server-ip",
  "httpPort": 30001,
  "socksPort": 31001,
  "username": "psx_user",
  "password": "randompass",
  "sessionToken": "x402s_abc123...",
  "rotationToken": "rot_xyz789...",
  "expiresAt": "2026-03-06T12:00:00Z",
  "trafficAllocatedGB": 1.0,
  "country": "US"
}
```

### Session Management (X-Session-Token header required)

These endpoints manage your proxy AFTER purchase. Include `X-Session-Token: x402s_YOUR_TOKEN` header.

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/manage/session` | Get full session details: ports, traffic used, traffic remaining, expiration, status |
| GET | `/v1/x402/manage/session/credit` | Check remaining credit. Returns `canRecreatePort: true` if session has unused traffic |
| GET | `/v1/x402/manage/ports` | List all ports in your session with their current status |
| GET | `/v1/x402/manage/ports/:portId/status` | Check if a specific port is online/offline, get current IP |
| POST | `/v1/x402/manage/ports/recreate` | Recreate a deleted/expired port if session has remaining credit. Free. Body: `{ "country": "US" }` |
| POST | `/v1/x402/manage/ports/replace` | Replace an offline/broken port with a new one on a different device. Free, max 3 per session. Body: `{ "country": "US" }` |
| GET | `/v1/x402/manage/session/topup/calculate` | Preview cost of adding more traffic/duration. Params: `?addTrafficGB=2&addDurationSeconds=86400` |
| POST | `/v1/x402/manage/session/topup` | Pay to extend session. Requires `Payment-Signature` header with new tx hash. Body: `{ "addTrafficGB": 2, "addDurationSeconds": 86400 }` |

### Session Lookup (no auth)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/session/:id` | Look up session by its MongoDB ID |
| GET | `/v1/x402/session/tx/:txHash` | Look up session by the original payment transaction hash |
| GET | `/v1/x402/sessions/:id/status` | Get session status by ID |
| GET | `/v1/x402/sessions/wallet/:wallet` | List all sessions for a given wallet address |

### Agent Registry

| Method | Path | What It Does |
|--------|------|-------------|
| POST | `/v1/x402/agents` | Register as an x402 agent (public). Body: `{ "wallet": "0x...", "name": "my-agent" }` |
| GET | `/v1/x402/agents/:wallet` | Get agent profile by wallet address |

### IP Rotation (public)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/rotate/:token` | Rotate IP using rotation token from proxy purchase. No auth needed. Returns new IP. |

### Admin Only (JWT required, admin role)

| Method | Path | What It Does |
|--------|------|-------------|
| GET | `/v1/x402/agents` | List all registered agents |
| PUT | `/v1/x402/agents/:wallet` | Update agent details |
| DELETE | `/v1/x402/agents/:wallet` | Delete agent |
| GET | `/v1/x402/sessions` | List all sessions |
| GET | `/v1/x402/stats` | Revenue and usage statistics |
| GET | `/v1/x402/admin/audit-logs` | Audit logs for all x402 operations |
| GET | `/v1/x402/admin/audit-stats` | Aggregate audit statistics |
| GET | `/v1/x402/admin/receipts` | List all payment receipts |
| GET | `/v1/x402/admin/receipts/:id` | Get specific receipt |
| GET | `/v1/x402/admin/dashboard` | Combined dashboard data |

---

## x402 Payment Protocol

All APIs use HTTP 402 Payment Required:

1. Request without payment:
   GET /endpoint

2. 402 Response:
   {
     "x402Version": 1,
     "price": 10000,
     "currency": "USDC",
     "networks": [
       {"network": "solana", "address": "..."},
       {"network": "base", "address": "...", "chainId": 8453}
     ]
   }

3. Send USDC to address

4. Retry with payment proof:
   GET /endpoint
   Payment-Signature: <tx_hash>

5. Receive data

---

## Payment Networks

**Base (Ethereum L2)**
- Chain ID: 8453
- Asset: USDC
- Settlement: ~2 seconds
- Gas: ~$0.01

**Solana**
- Asset: USDC (SPL)
- Settlement: ~400ms
- Gas: ~$0.0001

---

## MCP Integration

Add to Claude Desktop config:

```json
{
  "mcpServers": {
    "proxies": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": {"PROXIES_API_URL": "https://api.proxies.sx/v1"}
    }
  }
}
```

---

## GitHub & NPM

**Repositories:**
- https://github.com/bolivian-peru/proxies-sx-mcp-server
- https://github.com/bolivian-peru/x402-sdk
- https://github.com/bolivian-peru/android-peer-sdk

**NPM Packages:**
- https://www.npmjs.com/package/@proxies-sx/mcp-server

---

## Framework Integrations

### Conway Automaton (Sovereign AI Agents)

Proxies.sx is natively compatible with Conway Automaton — sovereign AI agents that earn USDC.
Conway's built-in `x402_fetch` tool handles all payment flows automatically.

**Install the skill:**
```
# From the automaton runtime
install_skill("proxies-sx", "https://github.com/bolivian-peru/automaton", "skills/proxies-sx")
```

**Or use directly:**
```
x402_fetch("https://api.proxies.sx/v1/x402/proxy?country=US&traffic=0.1")
```

- Conway Skill PR: https://github.com/Conway-Research/automaton/pull/78
- Genesis Prompt (reference agent): https://agents.proxies.sx/marketplace/conway/genesis-prompt.md
- Conway Automaton: https://github.com/Conway-Research/automaton

### MCP (Model Context Protocol)

- Proxy MCP: npx -y @proxies-sx/mcp-server (55 tools)

### Lucid Agents (Daydreams)

- Package: @proxies-sx/lucid-agents
- npm: https://www.npmjs.com/package/@proxies-sx/lucid-agents

---

## Support

- Twitter: https://x.com/sxproxies
- Telegram: https://t.me/proxyforai
- Dashboard: https://client.proxies.sx