# xapi

> HTTP proxy that pays x402 so your code doesn't have to.

xapi is a payment proxy for developers calling x402-paywalled APIs. You fund a USDC balance, route your API calls through xapi, and it handles all crypto — wallets, signing, settlement. You never write payment code.

Base URL: https://xapi.esoup.net
Chain: Base (mainnet)
Token: USDC (real value)
Docs: https://xapi.esoup.net/d/x402

## Quick Integration

1. Sign up: POST https://xapi.esoup.net/signup with {"email":"you@example.com"} → returns api_key
2. Create wallet: POST https://xapi.esoup.net/wallet with Authorization: Bearer <api_key>
3. Fund wallet: send USDC on Base (mainnet) to the wallet address
4. Activate: POST https://xapi.esoup.net/deposit/check (detects deposit, collects 1% fee, activates at $1+)
5. Proxy: GET https://xapi.esoup.net/proxy/<target_url> with Authorization header

## Two-Round Proxy Flow

Round 1 (probe): Send request through /proxy/<url>. If upstream returns 402, xapi passes it back so you see the price.

Round 2 (pay): Re-send with X-Pay: true and X-Pay-Max: <max_usdc>. xapi signs the payment and retries. You get the content.

X-Pay-Max is required — it's your consent gate preventing upstream price manipulation.

## Endpoints

All authenticated endpoints require: Authorization: Bearer <api_key>

### POST /signup
No auth. Body: {"email":"you@example.com"} (email optional).
Returns: {user_id, api_key, api_key_expires, next_steps}.
Rate limited: 3/hour per IP.

### POST /verify/email
Auth required. Body: {"email":"you@example.com"}.
Sends verification email. Enables key recovery and refunds.
Returns: {sent, email, expires_in}.

### POST /verify/recover
No auth. Body: {"email":"you@example.com"}.
Sends key recovery email if email is verified.
Returns: {sent, message} (same response whether email exists or not).

### POST /wallet
Auth required. Creates custodial USDC wallet on Base (mainnet).
Returns: {address, network, token, fund_instructions}. Status 201.
Error 409 if wallet already exists.

### GET /wallet
Auth required. Returns: {address, network, token, wallet_activated, fund_instructions}.

### GET /balance
Auth required. Returns: {address, balance_usdc, wallet_activated, refund_address, network}.

### POST /deposit/check
Auth required. Detects new USDC at wallet address, collects 1% fee on-chain, activates wallet at $1+.
Returns: {status, deposit_usdc, fee_usdc, fee_collected, fee_tx_hash, balance_after_usdc, wallet_activated}.
Call after sending USDC to your wallet address.

### GET /deposit/history
Auth required. Returns: {deposits: [{deposit_usdc, fee_usdc, fee_collected, fee_tx_hash, net_deposit_usdc, wallet_activated, created_at}]}.

### ANY /proxy/<target_url>
Auth required. Wallet must be activated.

Round 1 (probe): GET https://xapi.esoup.net/proxy/https://api.example.com/endpoint
  If upstream returns 402: passes through the 402 with Payment-Required header so you see the price.
  If upstream returns anything else: returns 404 "Not an x402 endpoint".

Round 2 (pay): Same URL with headers X-Pay: true and X-Pay-Max: <max_usdc>.
  Signs USDC payment from your wallet, retries upstream, returns content.
  Response headers: X-XAPI-Amount (USDC paid), X-XAPI-Fee (platform fee).
  Errors: 400 (missing X-Pay-Max), 402 (insufficient balance), 403 (price > max, limit hit, wallet not activated), 502 (upstream error).

Optional header: X-Pay-Override: true to accept a changed payTo address from a domain you've paid before.

### GET /keys
Auth required. Returns: {keys: [{id, tier, status, created_at, grace_expires}]}.
Status values: active, grace, expired, revoked.

### POST /keys/rotate
Auth required. Issues new key, old key works for 24 more hours.
Returns: {api_key, api_key_expires, grace_period: {old_key_valid_until, message}}.
Rate limited: 1 rotation per hour.

### POST /keys/revoke
Auth required. Body: {"token":"the-key-to-revoke"}. You can only revoke your own keys.
Returns: {revoked: true}. Error 403 if token belongs to another user.

### GET /settings
Auth required. Returns: {max_tx_usdc, daily_cap_usdc}.
Defaults: $5/tx, $50/day. Platform max: $100/tx, $1000/day.

### PATCH /settings
Auth required. Body: {"max_tx_usdc": 10, "daily_cap_usdc": 100}.
Returns updated values. Error 400 if exceeds platform max.

### GET /transactions
Auth required. Returns: {transactions: [{amount_usdc, fee_usdc, target_url, payee, status, tx_hash, created_at}], count}.

### POST /refund/request
No auth. Body: {"email":"you@example.com"}.
Sends refund confirmation email if email is verified. Click the link to review and confirm.
Refund executes immediately on-chain — USDC returned to original funding sources.
Returns: {sent, message} (same response whether email exists or not).

## Pricing

- Signup: free
- Wallet creation: free
- Deposit fee: 1% on every deposit (non-refundable)
- Minimum first deposit: $1.00 to activate
- Minimum subsequent deposit: $0.10
- Proxy requests: free (you pay the upstream x402 price only)
- Gas fees: $0 (facilitator covers gas)
- User-requested refund: free (balance minus deposit fee already taken)
- Abandonment refund: $0.50 processing fee after ~2 years inactive

## Limits

- Request body: 10 MB max
- Upstream timeout: 30 seconds
- Proxy rate: 60 req/min per user
- Signup rate: 3/hour per IP
- Max per-transaction: $100 USDC (user-configurable lower)
- Max daily spend: $1,000 USDC (user-configurable lower)
- Key rotation: 1/hour
- Verify/recovery emails: 3/day per user, 1/hour per address

## Authentication

All authenticated endpoints use Bearer token in Authorization header:
Authorization: Bearer <api_key>

API keys are issued at signup and on email verification/recovery.
Keys are Tier M with 365-day TTL. Rotate before expiry via POST /keys/rotate.

## For AI Agents

If you are an AI agent that needs to call x402 APIs:
1. Your operator signs up and funds a wallet
2. You receive the API key
3. Route your API calls through https://xapi.esoup.net/proxy/<url>
4. Add Authorization: Bearer <key> and X-Pay: true + X-Pay-Max: <amount>
5. You never handle crypto, wallets, or payment signing

This is the "give your agent an allowance, not a wallet" pattern.

## Testnet

Test your integration first: https://testnet.xapi.esoup.net
Testnet docs: https://testnet.xapi.esoup.net/d/x402
Test x402 endpoint: https://paywall.xapi.esoup.net/pay/testnet?amount=0.01