xapi PRODUCTION

x402 payment proxy for developers — Base (mainnet)

Base URL: https://xapi.esoup.net

We strongly recommend testing on testnet first. Testnet uses Base Sepolia with free testnet USDC. →

How it works

You call APIs through xapi. If the upstream returns 402 (payment required), xapi signs the USDC payment with your custodial wallet and retries. You never write crypto code.

Your App → xapi proxy → Upstream API
                           ← 402 Payment Required
           xapi pays from your balance
                           ← 200 + content
         ← Content returned to you

Pricing & fees

Honest pricing. No hidden fees.

Fee	Amount	When
Signup	Free	Create account + API key
Wallet creation	Free	Custodial wallet on Base
Deposit fee	1%	On every USDC deposit (non-refundable)
Minimum first deposit	$1.00	To activate wallet for proxy use
Minimum subsequent deposit	$0.10	After activation
Proxy requests	Free	You pay the upstream x402 price only
Key rotation	Free	24h grace period on old key
User-requested refund	Free	Balance returned minus deposit fee (already taken)
Abandonment refund	$0.50	Processing fee for idle wallet sweep (~2 years inactive)
Gas fees	$0	Facilitator pays all on-chain gas

Facilitator is currently Coinbase — they cover gas on Base. If facilitator fees change, refund amounts may be adjusted. We'll document any changes here.

Quick start

1. Sign up

curl -X POST https://xapi.esoup.net/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# Returns: user_id, api_key, next_steps

2. Verify your email (recommended)

curl -X POST https://xapi.esoup.net/verify/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# Check your inbox, click the link. Enables key recovery + refunds.

3. Create wallet

curl -X POST https://xapi.esoup.net/wallet \
  -H "Authorization: Bearer YOUR_API_KEY"

# Returns: wallet address on Base (mainnet). Fund this address with USDC.

4. Fund + activate

Send at least $1.02 USDC to your wallet address (covers $1.00 minimum + 1% fee). Then:

curl -X POST https://xapi.esoup.net/deposit/check \
  -H "Authorization: Bearer YOUR_API_KEY"

# Detects deposit, collects 1% fee, activates wallet.
# Returns: deposit_usdc, fee_usdc, wallet_activated

5. Proxy a request (Round 1 — see the price)

curl https://xapi.esoup.net/proxy/https://some-api.com/endpoint \
  -H "Authorization: Bearer YOUR_API_KEY"

# If upstream returns 402, you see payment requirements (price, payee).
# If upstream returns anything else, you get 404 (not an x402 endpoint).

6. Authorize payment (Round 2 — pay and get content)

curl https://xapi.esoup.net/proxy/https://some-api.com/endpoint \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Pay: true" \
  -H "X-Pay-Max: 0.05"

# X-Pay: true — authorize payment
# X-Pay-Max: 0.05 — consent gate, max USDC you'll pay (prevents price manipulation)
# Returns: upstream content + X-XAPI-Amount and X-XAPI-Fee response headers

API Reference

Click any endpoint to see request/response examples. All authenticated endpoints require Authorization: Bearer YOUR_API_KEY.

Account

POST/signupCreate account + API keyNo auth · IP rate limited

Email is optional but recommended — enables key recovery and refunds. Rate limited: 3/hour per IP.

curl -X POST https://xapi.esoup.net/signup \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# 200 OK
{
  "user_id": "abc123",
  "api_key": "eyJ0Ijoi...",
  "api_key_expires": "2027-03-23T00:00:00.000Z",
  "next_steps": [
    "1. Verify your email: POST /verify/email",
    "2. Create your wallet: POST /wallet",
    "3. Fund your wallet: send USDC on Base (mainnet)",
    "4. Set Authorization: Bearer <api_key>",
    "5. Probe any URL: GET /proxy/{url}",
    "6. On 402: re-send with X-Pay: true and X-Pay-Max"
  ]
}

Email Verification & Recovery

POST/verify/emailSend verification emailAPI key required

Links your email to your account. Enables key recovery via /verify/recover and refund requests.

curl -X POST https://xapi.esoup.net/verify/email \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# 200 OK
{"sent": true, "email": "you@example.com", "expires_in": "1 hour"}

POST/verify/recoverKey recovery via emailNo auth

Lost your API key? Sends a recovery email with a new key. Email must be previously verified.

curl -X POST https://xapi.esoup.net/verify/recover \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# 200 OK (always returns same response — anti-enumeration)
{"sent": true, "message": "If that email is verified, a recovery link has been sent."}

Wallet & Balance

POST/walletCreate custodial walletAPI key required

Creates a custodial USDC wallet on Base (mainnet). One wallet per user. No wallet = no private key = nothing at risk.

curl -X POST https://xapi.esoup.net/wallet \
  -H "Authorization: Bearer YOUR_API_KEY"

# 201 Created
{
  "address": "0x4C699957928C17B49c073956Bc75b11d79F502B7",
  "network": "Base (eip155:8453)",
  "token": "USDC",
  "fund_instructions": "Send USDC on Base (mainnet) to 0x4C69..."
}

# 409 Conflict (wallet already exists)
{"error": "Wallet already exists", "address": "0x4C69..."}

GET/walletView wallet infoAPI key required

curl https://xapi.esoup.net/wallet -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK
{
  "address": "0x4C69...",
  "network": "Base (eip155:8453)",
  "token": "USDC",
  "wallet_activated": true,
  "fund_instructions": "Send USDC on Base (mainnet) to 0x4C69..."
}

# 404 (no wallet yet)
{"error": "No wallet", "create_at": "POST /wallet"}

GET/balanceUSDC balanceAPI key required

curl https://xapi.esoup.net/balance -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK
{
  "address": "0x4C69...",
  "balance_usdc": "2.05",
  "wallet_activated": true,
  "refund_address": null,
  "network": "Base (eip155:8453)"
}

Deposits

POST/deposit/checkDetect deposit, collect fee, activateAPI key required

Call after sending USDC to your wallet address. Detects the on-chain balance increase, collects a 1% fee via x402, and activates your wallet at $1+.

curl -X POST https://xapi.esoup.net/deposit/check -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK — deposit found, wallet activated
{
  "status": "activated",
  "deposit_usdc": 2.08,
  "fee_usdc": 0.0208,
  "fee_percent": "1%",
  "fee_collected": true,
  "fee_tx_hash": "0x5a2f...",
  "net_deposit_usdc": 2.0592,
  "balance_after_usdc": 2.0592,
  "wallet_activated": true
}

# 200 OK — no new deposit
{"status": "no_new_deposit", "on_chain_usdc": 2.05, "wallet_activated": true}

# 400 — below minimum ($1.00 first deposit, $0.10 subsequent)
{"status": "deposit_below_minimum", "deposit_usdc": 0.50, "minimum_usdc": 1.00}

# 503 — fee collection failed (retry later)
{"status": "fee_collection_failed", "detail": "Call POST /deposit/check again to retry."}

GET/deposit/historyDeposit & fee historyAPI key required

curl https://xapi.esoup.net/deposit/history -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK
{
  "deposits": [{
    "deposit_usdc": 2.08,
    "fee_usdc": 0.0208,
    "fee_collected": true,
    "fee_tx_hash": "0x5a2f...",
    "net_deposit_usdc": 2.0592,
    "wallet_activated": true,
    "created_at": "2026-03-23T05:50:00.000Z"
  }]
}

Proxy — the core product

ANY/proxy/{url}x402 payment proxyAPI key required · wallet must be activated

Proxy any HTTP request. If the upstream returns 402, xapi handles the payment. Two-round flow:

Round 1 — Probe (see the price):

curl https://xapi.esoup.net/proxy/https://some-api.com/endpoint \
  -H "Authorization: Bearer YOUR_API_KEY"

# 402 — upstream is x402, price returned via Payment-Required header
# 404 — upstream is NOT an x402 endpoint
{"error": "Not an x402 endpoint", "upstream_status": 200}

Round 2 — Pay (authorize and get content):

curl https://xapi.esoup.net/proxy/https://some-api.com/endpoint \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Pay: true" \
  -H "X-Pay-Max: 0.05"

# 200 — payment settled, upstream content returned
# Response headers: X-XAPI-Amount: 0.05, X-XAPI-Fee: 0.0005

# 400 — X-Pay-Max missing or invalid
# 402 — insufficient USDC balance
# 403 — price > X-Pay-Max, spending limit hit, wallet not activated
# 404 — no wallet, or upstream not x402
# 502 — upstream unreachable or invalid x402 response

Headers:

X-Pay: true — authorize payment (required for Round 2)
X-Pay-Max: 0.05 — consent gate, max USDC you'll pay (required with X-Pay)
X-Pay-Override: true — accept a changed payTo address (use with caution)

Supports all HTTP methods. Request body forwarded (10 MB max). Authorization header stripped before forwarding to upstream.

API Keys

GET/keysList all keys with statusAPI key required

curl https://xapi.esoup.net/keys -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK
{
  "keys": [
    {"id": "abc", "tier": "M", "status": "active", "created_at": "2026-03-23T00:00:00Z", "grace_expires": null},
    {"id": "def", "tier": "M", "status": "grace", "created_at": "2026-03-22T00:00:00Z", "grace_expires": "2026-03-24T00:00:00Z"}
  ]
}
# Status values: active, grace, expired, revoked

POST/keys/rotateNew key, 24h grace on oldAPI key required

Issues a new key. Old key works for 24 more hours. Max 1 rotation per hour.

curl -X POST https://xapi.esoup.net/keys/rotate -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK
{
  "api_key": "eyJ0Ijoi...",
  "api_key_expires": "2027-03-23T00:00:00Z",
  "grace_period": {
    "old_key_valid_until": "2026-03-24T00:00:00Z",
    "message": "Your old key will continue working for 24 hours."
  }
}
# 400 — cannot rotate a key already in grace period
# 429 — max 1 rotation per hour

POST/keys/revokeRevoke a keyAPI key required

Permanently revoke an API key. You can only revoke your own keys.

curl -X POST https://xapi.esoup.net/keys/revoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token":"eyJ0Ijoi..."}'

# 200 OK — {"revoked": true}
# 403 — cannot revoke another user's key

Settings

GET/settingsView spending limitsAPI key required

curl https://xapi.esoup.net/settings -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK — {"max_tx_usdc": 5.00, "daily_cap_usdc": 50.00}

PATCH/settingsUpdate spending limitsAPI key required

Platform max: $100/transaction, $1000/day. Both fields optional.

curl -X PATCH https://xapi.esoup.net/settings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_tx_usdc": 10, "daily_cap_usdc": 100}'

# 200 OK — {"max_tx_usdc": 10.00, "daily_cap_usdc": 100.00}
# 400 — exceeds platform maximum

Transactions

GET/transactionsPayment historyAPI key required

curl https://xapi.esoup.net/transactions -H "Authorization: Bearer YOUR_API_KEY"

# 200 OK
{
  "transactions": [{
    "amount_usdc": 0.01,
    "fee_usdc": 0.0001,
    "target_url": "https://paywall.xapi.esoup.net/pay/mainnet",
    "payee": "0xB2E2...",
    "status": "settled",
    "tx_hash": "0xa8ef...",
    "created_at": "2026-03-23T06:20:00Z"
  }],
  "count": 1
}

Refunds

POST/refund/requestRequest refund via emailNo auth

Sends a refund confirmation email. Click the link to review funding sources and confirm. Refund executes immediately on-chain — USDC returned to the addresses that originally funded your wallet.

curl -X POST https://xapi.esoup.net/refund/request \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com"}'

# 200 OK (always — anti-enumeration)
{"sent": true, "message": "If that email is associated with an account, a refund link has been sent."}

Limits & timeouts

Limit	Value	Notes
Request body size	10 MB	Upstream API request body limit
Upstream timeout	30 seconds	Per upstream request (each round)
Proxy rate limit	60 req/min	Per user, across all proxy calls
Signup rate limit	3/hour	Per IP address
Key rotation	1/hour	Per user
Verify emails	3/day	Per user. 1/hour per address.
Recovery emails	1/day	Per email address
Refund emails	1/day	Per email address
Max per-transaction	$100 USDC	Platform max (user can set lower via /settings)
Max daily spend	$1,000 USDC	Platform max (user can set lower via /settings)
Grace period (key rotation)	24 hours	Old key works after rotation
Verify link expiry	1 hour	One-time use
Refund link expiry	24 hours	One-time use
Abandonment threshold	~2 years	No API calls for this period triggers sweep

Security

Wallet private keys encrypted at rest, decrypted only during signing
SSRF protection on proxy (HTTPS-only, IP blocklist)
PayTo address pinning per domain (detects upstream wallet changes)
X-Pay-Max consent gate (prevents upstream price manipulation)
Per-transaction + daily spending caps (user-configurable)
API-only — no browser/CORS access

Wallet lifecycle

1. POST /signup      → user + API key (no wallet yet)
2. POST /verify/email → verify email (enables recovery + refunds)
3. POST /wallet      → custodial wallet created at $0
4. Fund wallet       → send USDC to wallet address
5. POST /deposit/check → 1% fee collected, wallet activates at $1+
6. Use /proxy        → x402 payments from your balance
7. POST /keys/rotate → new key, old works 24h
8. POST /refund/request → email-based refund (immediate on-chain return)

Wallets are never deleted. Refunded wallets are marked as such and can be re-funded to reactivate. Unverified wallets with no email cannot recover keys or request refunds — verify your email.