x402 — pay per call

x402 lets clients — including agents with no account — pay for a single API call by sending USDC on Base. The server verifies the transfer on-chain, so there's no signup and no balance to manage.

The flow

1. Call a /api/v1/* endpoint with no auth.
2. The server replies 402 Payment Required with an x402 block — how much USDC to send, and where (pay_to).
3. Send that USDC amount on Base to pay_to (any wallet or web3 library).
4. Retry the same request with the transaction hash in the X-PAYMENT header.
5. The server verifies the transfer on-chain and returns the result.

Each payment transaction is single-use and pays for one request — send a fresh payment per call, for at least the quoted amount.

1. Make the request

Call any paid endpoint exactly as you normally would — no auth headers. If payment is needed you'll get the 402 below. (Request shapes are in the API reference.)

curl -X POST https://csds.blockchainrangers.com/api/v1/standard-report \
  -H "Content-Type: application/json" \
  -d '{"project_address":"0x6982508145454ce325ddbe47a25d4ec3d2311933","chain":"ethereum"}'

$body = @{ project_address = "0x6982508145454ce325ddbe47a25d4ec3d2311933"; chain = "ethereum" } | ConvertTo-Json
Invoke-RestMethod "https://csds.blockchainrangers.com/api/v1/standard-report" `
  -Method Post -Body $body -ContentType "application/json"

2. The 402 response

When payment is required, the response body is:

{
  "code": "payment_required",
  "error": "Payment required. Authenticate with an API key / web session, or pay per call via x402 (USDC on Base).",
  "x402": {
    "scheme": "exact",
    "network": "base-mainnet",
    "asset": "USDC",
    "asset_address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "decimals": 6,
    "amount": "0.10",
    "amount_units": "100000",
    "pay_to": "0xYourRecipient…",
    "instructions": "Send this USDC amount on Base to pay_to, then retry the request with header 'X-PAYMENT: '."
  }
}

amount is human-readable (USDC); amount_units is the same value in base units (6 decimals). Standard = $1.00, deep dive = $5.00 — see Pricing.

3. Pay, then retry

Send amount USDC (the token at asset_address) on Base to pay_to, then resend the request with the resulting transaction hash:

curl -X POST https://csds.blockchainrangers.com/api/v1/standard-report \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: 0xYOUR_BASE_TX_HASH" \
  -d '{"project_address":"0x6982508145454ce325ddbe47a25d4ec3d2311933","chain":"ethereum"}'

$body = @{ project_address = "0x6982508145454ce325ddbe47a25d4ec3d2311933"; chain = "ethereum" } | ConvertTo-Json
Invoke-RestMethod "https://csds.blockchainrangers.com/api/v1/standard-report" `
  -Method Post -Body $body -ContentType "application/json" `
  -Headers @{ "X-PAYMENT" = "0xYOUR_BASE_TX_HASH" }

If the payment is valid — correct token and recipient, at least the quoted amount, confirmed on Base, and not already used — the server runs the check and returns the result. Otherwise you get another 402:

Next