# 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://testnet.xapi.esoup.net
Chain: Base Sepolia (testnet)
Token: testnet USDC (free, no real value)
Docs: https://testnet.xapi.esoup.net/d/x402

## Quick Integration

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

### Account
POST /signup — Create account + API key (no auth, IP rate limited)

### Email & Recovery
POST /verify/email — Send verification email (API key required, body: {"email":"..."})
POST /verify/recover — Key recovery via email (no auth, body: {"email":"..."})

### Wallet
POST /wallet — Create custodial wallet (API key required)
GET /wallet — View wallet info + activation status (API key required)
GET /balance — USDC balance (API key required)

### Deposits
POST /deposit/check — Detect deposits, collect 1% fee, activate (API key required)
GET /deposit/history — Deposit history (API key required)

### Proxy (core product)
ANY /proxy/<url> — x402 proxy (API key required, wallet must be activated)
  Headers: X-Pay: true (authorize payment), X-Pay-Max: <amount> (consent gate)
  Response headers: X-XAPI-Amount, X-XAPI-Fee

### Keys
GET /keys — List all keys with status (API key required)
POST /keys/rotate — New key, old enters 24h grace period (API key required)
POST /keys/revoke — Revoke a key (API key required, body: {"token":"..."})

### Settings
GET /settings — View spending limits (API key required)
PATCH /settings — Update limits, max $100/tx $1000/day (API key required)

### Transactions
GET /transactions — Payment history (API key required)

### Refunds
POST /refund/request — Request refund via email (no auth, body: {"email":"..."})

## 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.10 processing fee after 30 days inactive

## Limits

- Request body: 100 MB max
- Upstream timeout: 30 seconds
- Proxy rate: 60 req/min per user
- Signup rate: 20/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://testnet.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.

## Testing

Test x402 endpoint: https://paywall.xapi.esoup.net/pay/testnet?amount=0.01
This charges $0.01 testnet USDC per call. Use it to verify your integration before production.

Production: https://xapi.esoup.net