# x402 Micropayments — Headless Oracle

Headless Oracle supports the x402 protocol for per-request USDC micropayments on Base mainnet.
Autonomous agents can pay for API access without a subscription or pre-registered API key.

Guide: https://headlessoracle.com/docs/x402-payments

## When x402 kicks in

Free tier keys (ho_free_*) have a 500 requests/day limit. After the limit:

1. If your account has prepaid credits → one credit is consumed automatically.
2. If X-Payment header is present with a valid Base mainnet USDC transaction → request is fulfilled.
3. Otherwise → HTTP 402 with machine-readable payment instruction.

## The 402 Response

```json
{
  "error": "PAYMENT_REQUIRED",
  "x402": {
    "version": "1",
    "scheme": "exact",
    "network": "base-mainnet",
    "chainId": 8453,
    "amount": "1000",
    "currency": "USDC",
    "decimals": 6,
    "paymentAddress": "0x26D4Ffe98017D2f160E2dAaE9d119e3d8b860AD3",
    "usdcContractAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "maxAge": 300
  }
}
```

## Paying with X-Payment header

1. Send 0.001 USDC (1000 units at 6 decimals) to paymentAddress on Base mainnet.
2. Retry the request with X-Payment header:

```
X-Payment: {"txHash":"0x...","network":"base-mainnet","amount":"1000","paymentAddress":"0x26D4...","memo":""}
```

## Prepaid Credits

POST /v5/credits/purchase — send X-Payment header with bulk USDC payment
GET /v5/credits/balance — check remaining credits

100 credits = 90000 USDC units (0.09 USDC)
1000 credits = 800000 USDC units (0.80 USDC)

## Security Notes

- Transactions expire after 300 seconds
- Each txHash can only be used once (replay protection, 600s TTL)
- Verify paymentAddress before sending funds