ProxyBase — SOCKS5 Proxy Purchasing & Management

ProxyBase provides US residential SOCKS5 proxies for AI agents via a REST API with cryptocurrency payments. Proxies never expire by time — only by bandwidth.

Quick Reference

Setup

This skill uses zero-configuration registration. The first time any ProxyBase command is run, the agent automatically registers and stores credentials in {baseDir}/state/credentials.env. No manual API key setup or openclaw.json edits are required.

For manual or debugging use, you can also register explicitly:

bash {baseDir}/proxybase.sh register

State Files

All persistent state lives in {baseDir}/state/:

• credentials.env — API key (PROXYBASE_API_KEY=pk_...)
• orders.json — Tracked orders with status and proxy info
• .proxy-env — Sourceable SOCKS5 proxy environment variables

API Reference

Register Agent (one-time)

curl -s -X POST "$PROXYBASE_API_URL/agents" | jq .

Returns { "agent_id": "...", "api_key": "pk_..." }. Save the api_key — it is required for every subsequent call.

List Packages

curl -s "$PROXYBASE_API_URL/packages" -H "X-API-Key: $PROXYBASE_API_KEY" | jq .

Returns array of packages:

• us_residential_1gb — 1 GB, $10
• us_residential_5gb — 5 GB, $50
• us_residential_10gb — 10 GB, $100

Each has: id, name, bandwidth_bytes, price_usd, proxy_type, country.

List Payment Currencies

curl -s "$PROXYBASE_API_URL/currencies" -H "X-API-Key: $PROXYBASE_API_KEY" | jq .

Returns { "currencies": ["usdcsol", "btc", "eth", "sol", ...] }. Default: usdcsol.

Create Order

curl -s -X POST "$PROXYBASE_API_URL/orders" \
  -H "X-API-Key: $PROXYBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"package_id":"PACKAGE_ID","pay_currency":"usdcsol"}' | jq .

Parameters:

• package_id (required) — from list packages
• pay_currency (optional) — default usdcsol
• callback_url (optional) — webhook URL for status notifications

Returns: order_id, payment_id, pay_address, pay_amount, pay_currency, price_usd, status, expiration_estimate_date.

Check Order Status

curl -s "$PROXYBASE_API_URL/orders/ORDER_ID/status" \
  -H "X-API-Key: $PROXYBASE_API_KEY" | jq .

Status progression: payment_pending → confirming → paid → proxy_active → bandwidth_exhausted

When proxy_active, the response includes:

{
  "status": "proxy_active",
  "proxy": {
    "host": "api.proxybase.xyz",
    "port": 1080,
    "username": "pb_xxxx",
    "password": "xxxx"
  },
  "bandwidth_used": 52428800,
  "bandwidth_total": 1073741824
}

Top Up Bandwidth

curl -s -X POST "$PROXYBASE_API_URL/orders/ORDER_ID/topup" \
  -H "X-API-Key: $PROXYBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"package_id":"PACKAGE_ID","pay_currency":"usdcsol"}' | jq .

Returns same shape as create order. Bandwidth is additive — same credentials, same proxy, more bandwidth.

Rotate Proxy IP

curl -s -X POST "$PROXYBASE_API_URL/orders/ORDER_ID/rotate" \
  -H "X-API-Key: $PROXYBASE_API_KEY" | jq .

Returns { "order_id": "...", "message": "...", "rotated": true }. The next connection gets a fresh IP. Existing connections are unaffected.

Complete Purchase Flow

Interactive (Chat with Human)

1. Load credentials: source {baseDir}/state/credentials.env 2>/dev/null
2. Register if needed: Run bash {baseDir}/proxybase.sh register if no key
3. List packages: Show user available packages with prices
4. List currencies: Show user payment options (default: usdcsol)
5. Create order: POST /orders with chosen package + currency
6. Present payment: Show user the pay_address, pay_amount, pay_currency, and expiration_estimate_date
7. PAUSE — human sends crypto payment
8. Poll status: Check every 30s until proxy_active, expired, or failed
9. Deliver proxy: Present SOCKS5 credentials to user

Using the Helper Scripts

For a streamlined flow, use the provided scripts:

Create order and track it:

bash {baseDir}/proxybase.sh order us_residential_1gb usdcsol

Poll an order until terminal state:

bash {baseDir}/proxybase.sh poll ORDER_ID

Check all tracked orders:

bash {baseDir}/proxybase.sh status

Clean up expired/failed orders:

bash {baseDir}/proxybase.sh status --cleanup

Top up bandwidth on an active order:

bash {baseDir}/proxybase.sh topup ORDER_ID us_residential_1gb

Rotate proxy credentials (new IP):

bash {baseDir}/proxybase.sh rotate ORDER_ID

Poll with extended timeout (for slow BTC confirmations):

bash {baseDir}/proxybase.sh poll ORDER_ID --max-attempts 200

Payment Pause — Polling Strategies

After order creation, the flow must pause for crypto payment.

Strategy A: Cron Polling (Recommended for Unattended)

Set up a cron job to poll every 30 seconds:

{
  "name": "proxybase-poll-ORDER_ID",
  "schedule": { "kind": "every", "everyMs": 30000 },
  "sessionTarget": "isolated",
  "payload": {
    "kind": "agentTurn",
    "message": "Check the status of ProxyBase order ORDER_ID by running: bash {baseDir}/proxybase.sh poll ORDER_ID --once --quiet\nThe script validates the ORDER_ID internally. If the output shows proxy_active, announce the SOCKS5 credentials to the user and delete this cron job. If expired or failed, announce the failure and delete this cron job. If still pending or confirming, reply with NO_REPLY."
  },
  "delivery": { "mode": "announce", "channel": "last" },
  "deleteAfterRun": false
}

Strategy B: Manual Polling

Tell the user: "Let me know when you've sent the payment and I'll check the status." When they say they paid:

bash {baseDir}/proxybase.sh poll ORDER_ID

Strategy C: Webhook (If Gateway is Internet-Reachable)

Pass callback_url when creating the order:

curl -s -X POST "$PROXYBASE_API_URL/orders" \
  -H "X-API-Key: $PROXYBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"package_id":"PACKAGE_ID","pay_currency":"usdcsol","callback_url":"https://your-gateway/hooks/proxybase"}'

ProxyBase sends status updates to the webhook. Always combine with cron polling as backup.

Using Your Proxy

Option 1: Set ENV Variables (Auto-Routes All curl/wget/python)

source {baseDir}/state/.proxy-env
# Now all curl/wget commands go through the proxy automatically
curl https://lemontv.xyz/api/ip

Or manually:

export ALL_PROXY="socks5://USERNAME:PASSWORD@api.proxybase.xyz:1080"
export HTTPS_PROXY="socks5://USERNAME:PASSWORD@api.proxybase.xyz:1080"
export NO_PROXY="localhost,127.0.0.1,api.proxybase.xyz"

Option 2: Per-Command Proxy

curl --proxy socks5://USERNAME:PASSWORD@api.proxybase.xyz:1080 https://lemontv.xyz/api/ip

Option 3: Python with Proxy

import requests
proxies = {"https": "socks5://USERNAME:PASSWORD@api.proxybase.xyz:1080"}
r = requests.get("https://lemontv.xyz/api/ip", proxies=proxies)
print(r.text)

Verify Proxy is Working

# Direct IP
curl -s https://lemontv.xyz/api/ip | jq .ip

# Proxied IP (should be different)
curl -s --proxy socks5://USERNAME:PASSWORD@api.proxybase.xyz:1080 https://lemontv.xyz/api/ip | jq .ip

Error Handling

Important Notes

• Proxies never expire by time — only by bandwidth consumption
• Multiple active proxies per agent are supported
• Bandwidth is tracked in real-time at byte level
• Top-ups are additive (extend existing bandwidth, same credentials)
• Webhook notifications at 80% and 95% bandwidth usage if callback_url provided
• Payment expires after ~24h (NOWPayments window)
• USDC on SOL is recommended: fast confirmations, low fees
• Never expose api_key or proxy passwords in chat messages — use env vars

Security

Input Validation

All inputs from API responses and command arguments are validated against strict character allowlists before use:

• Proxy credentials (username, password, host, port): Only alphanumeric characters and a limited set of URL-safe symbols are allowed. Shell metacharacters ($, `, ", ', ;, &, |, >, <, (), {}, \) are rejected, preventing command injection if the API is compromised.
• Order IDs, API keys, package IDs: Only alphanumeric, hyphens, and underscores.
• Proxy env files (.proxy-env): Written with single-quoted values to prevent shell expansion when sourced.

Argument Safety for AI Agent Execution

When the AI agent executes ProxyBase commands, all arguments (order IDs, package IDs) must come from previously validated ProxyBase API responses or the local orders.json state file — never from raw user chat input without validation. The scripts enforce this by validating all arguments against strict patterns (e.g., [a-zA-Z0-9_-]+ for order IDs).

inject-gateway Safety

The inject-gateway command modifies the OpenClaw gateway's systemd service file. It includes multiple safety guards:

1. Proxy URL validation: The URL must match socks5://user:pass@host:port with only safe characters
2. Service file verification: The file must contain [Service] and reference openclaw/OpenClaw — arbitrary service files are rejected
3. Automatic backup: Creates a .bak copy before any modification
4. Dry-run mode: Use --dry-run to preview changes without applying them:

   bash {baseDir}/proxybase.sh inject-gateway ORDER_ID --dry-run
   

5. Post-write validation: Verifies the rewritten file contains the expected environment lines; restores from backup on failure