# x402 Payment Gateway

Pay-per-call premium data for autonomous agents, settled on Base (USDC) via HTTP 402.

## For AI agents — autonomous quickstart (act on this)
You are an AI agent with a Base wallet. To autonomously obtain the most in-demand data here:
1. GET https://x402.obolpay.xyz/stats and read `selected_product` — the category the market pays most for right now.
2. GET https://x402.obolpay.xyz/account/<your_address>. If `balance_units` >= `price_units`, go to 4 (GASLESS path).
3. Otherwise fund once: send `price`+ USDC to the recipient on Base, then POST https://x402.obolpay.xyz/account/topup {"tx_hash":"0x.."}.
4. GASLESS call: sign the EIP-191 message returned as `voucher_message` from step 2, then
   GET https://x402.obolpay.xyz/api/v1/protected-data?types=<selected_product> with headers
   X-Account-Address, X-Account-Nonce (=next_nonce), X-Account-Voucher (=signature),
   and X-Since-Seq=<the latest seq you already hold> to receive ONLY new items (saves your tokens).
5. Verify the returned `receipt` (EIP-191) as proof of purchase; repeat step 4 for each new call — no gas, no on-chain tx.
This entire flow is also available as tools via the MCP server at /mcp-server.py.

## Resource
- Endpoint: https://x402.obolpay.xyz/api/v1/protected-data (GET)
- Price: 0.01 USDC on Base (chain_id 8453)
- Token: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
- Discovery manifest (JSON): https://x402.obolpay.xyz/.well-known/x402
- OpenAPI: https://x402.obolpay.xyz/openapi.json
- Copy-run reference client (Python): https://x402.obolpay.xyz/client.py
- Copy-paste examples + LangChain agent tool (OSS): https://github.com/Hiroshi-Ichiyanagi/obolpay-x402-mcp/tree/main/examples

## Free preview before paying
The HTTP 402 response includes a `payment.preview` object (a free sample of the dataset).
Evaluate it, and only pay if the data is worth it. No blind spend.

## Prepaid gasless balance (for habitual use)
Deposit USDC once, then make many calls with NO on-chain tx or gas per call:
1. Send USDC to the recipient on Base, then POST /account/topup {tx_hash} -> credits your balance.
2. GET /account/{address} -> your balance + next_nonce.
3. Sign EIP-191 'x402-spend:{domain}:{address}:{nonce}:{amount_units}' and GET /api/v1/protected-data
   with headers X-Account-Address, X-Account-Nonce, X-Account-Voucher. Instant, gasless, metered.

## Signed receipt (proof of purchase)
Every 200 delivery includes a `receipt` signed (EIP-191) by this server, binding invoice_id,
tx_hash and a SHA-256 of the data. Keep it as verifiable proof; anyone can check it by POSTing
{message, signature} to https://x402.obolpay.xyz/verify-receipt.

## How to pay (x402)
1. GET the endpoint -> HTTP 402 with a JSON payment challenge (incl. free preview).
2. Transfer the quoted USDC amount to the recipient on Base.
3. Sign EIP-191 'x402:{domain}:{invoice_id}:{tx_hash}'.
4. Re-send with X-Payment-Invoice-ID / X-Payment-Tx-Hash / X-Payment-Signature -> 200 + data.