Payments

Every POST /services/* route is a paid resource. You are charged exactly the quoted price — $0.01 USDC — per successful request, settled on-chain at request time. There is no balance to top up, no invoice at month end, and no metering you have to reconcile: each response settles its own payment and carries the confirmation.

The quote is the contract

An unpaid request returns the terms:

curl -i -X POST http://localhost:3000/services/token-risk \
  -H "Content-Type: application/json" \
  -d '{"chain":"ethereum","tokenAddress":"0x6b175474e89094c44da98b954eedeac495271d0f"}'

# HTTP/1.1 402 Payment Required
# PAYMENT-REQUIRED: <base64 payment terms: scheme=exact, network, $0.01 USDC, payTo=...>

The PAYMENT-REQUIRED header is a machine-readable description of accepted terms: scheme (exact — a fixed price, never a range), network, asset, amount, and pay-to address. Your client signs a payment authorization for exactly that amount and retries with a PAYMENT-SIGNATURE header. Nothing else is ever drawn from your wallet.

Use @x402/fetch to automate the loop — hand-rolling signatures in curl is not practical.

Settlement and your receipt

The server verifies your signed payload and settles it through an x402 facilitator before running the service. The facilitator broadcasts your own signed authorization — it never custodies your funds, and neither does this API. The successful response attaches a PAYMENT-RESPONSE header with settlement confirmation you can store as a receipt, alongside the requestId that identifies the call in our records.

Payment is verified before any upstream work runs — you are never charged for a request that failed validation.

What happens when things fail

• Invalid input (400 validation_error) — rejected before payment; you pay nothing.
• Unsupported options (400 unsupported_options) — the request asked for an upstream mode outside the one-cent envelope; rejected before payment.
• Upstream trouble after settlement — a failed enrichment source degrades the response and says so in warnings (you still get the primary data you paid for). A failed primary source returns a provider_error / provider_timeout — see Error Codes for retry guidance.
• Cache hits (cache.hit: true) — some services cache public data for 1–10 minutes. Each request is priced identically either way; caching buys you latency, not a discount.

Check what a deployment enforces

GET /services and GET /services/:slug report the payment posture per service, so clients can tell what a deployment expects before calling:

"payment": {
  "protocol": "x402",
  "network": "eip155:84532",
  "enforced": true
}

When enforced is false the deployment is not accepting payments, and paid routes respond 402 payment_not_configured rather than serving content for free — the payment boundary fails closed in both directions.

Browser clients

For browser-based callers, the payment-flow headers (Payment-Required, Payment-Response, X-Request-Id) are exposed via CORS on allowed origins.