xapi TESTNET

x402 payment proxy for developers — Base Sepolia (testnet)

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

This is the testnet environment (Base Sepolia, testnet USDC). Use paywall.xapi.esoup.net as a test x402 endpoint. Production docs →

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.10	Processing fee for idle wallet sweep (30 days inactive)
Gas fees	$0	Facilitator pays all on-chain gas (we are the facilitator on testnet)

On testnet, we run our own facilitator (sandbox wallet pays gas). Production uses Coinbase's facilitator which covers gas fees.

Quick start

1. Sign up

curl -X POST https://testnet.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://testnet.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://testnet.xapi.esoup.net/wallet \
  -H "Authorization: Bearer YOUR_API_KEY"

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

4. Fund + activate

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

curl -X POST https://testnet.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://testnet.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).

Test endpoint: Use https://paywall.xapi.esoup.net/pay/testnet?amount=0.01 as a real x402 endpoint that charges $0.01 testnet USDC per call.

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

curl https://testnet.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

All endpoints

Account

POST /signup Create account + API key IP rate limited

Email verification & recovery

POST /verify/email Send verification email API key required

POST /verify/recover Send key recovery email (lost your key?) No auth — email only

GET /verify/confirm?token=... Click from email — verifies + issues new key Token in URL

Wallet & balance

POST /wallet Create custodial wallet API key required

GET /wallet View wallet info + activation status API key required

GET /balance USDC balance on Base Sepolia (testnet) API key required

Deposits

POST /deposit/check Detect new deposits, collect fee, activate API key required

GET /deposit/history Deposit + fee history API key required

Proxy (the core product)

ANY /proxy/{url} x402 proxy — two-round flow API key required, wallet must be activated

Headers: X-Pay: true to authorize payment. X-Pay-Max: 0.05 consent gate (required with X-Pay). X-Pay-Override: true to accept changed payTo address.

API keys

GET /keys List all keys with status (active/grace/expired/revoked) API key required

POST /keys/rotate Issue new key, old enters 24h grace period API key required

POST /keys/revoke Revoke a specific key API key required

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 (sends email to verified address) No auth — email only

Limits & timeouts

Limit	Value	Notes
Request body size	100 MB	Upstream APIs may accept large payloads
Upstream timeout	30 seconds	Per upstream request (each round)
Proxy rate limit	60 req/min	Per user, across all proxy calls
Signup rate limit	20/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	30 days	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 testnet 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 (queued, processed async)

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.

Testnet testing guide

Use these endpoints to test the full x402 flow with testnet USDC:

# Test x402 endpoint (charges $0.01 testnet USDC)
https://paywall.xapi.esoup.net/pay/testnet?amount=0.01

# Round 1: See the price
curl https://testnet.xapi.esoup.net/proxy/https://paywall.xapi.esoup.net/pay/testnet?amount=0.01 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Round 2: Pay and get content
curl "https://testnet.xapi.esoup.net/proxy/https://paywall.xapi.esoup.net/pay/testnet?amount=0.01" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Pay: true" \
  -H "X-Pay-Max: 0.01"