x402 payments
No account required. Agents request, see HTTP 402, pay USDC on Base, retry with proof. USDC per call on Base. Free discovery stays free.
What is the pay-per-call flow?
Request a paid path → server returns HTTP 402 with accepts[] payment requirements → settle the exact USDC amount on Base → retry the same request with an X-PAYMENT proof header → receive the labeled observation.
Do I need an account?
No. commodities.sh authenticates payment proof, not a user account. Discovery routes never require payment.
What does a 402 body look like?
The challenge includes x402Version, PAYMENT_REQUIRED error, and an accepts array with scheme exact, Base network, maxAmountRequired, and the resource path. Agents should parse accepts before settling.
Why does my wallet show a security warning before I sign?
x402's exact scheme signs an EIP-3009 transferWithAuthorization — a gasless, off-chain authorization that lets a relayer move funds on-chain later. That same primitive is also the one most wallet-drainer scams abuse, so wallet security tools like Blockaid flag it by default on domains without an established reputation. This is expected on a newer domain, not a sign of compromise: the signature only authorizes the exact bounded amount shown in the 402 challenge, sent to this service's payout address.
Flow steps
- 01
Request
GET api.commodities.sh/v1/inventory/eia — or any paid route. No API key.
- 02
402
Server returns HTTP 402 with USDC payment requirements on Base.
- 03
Pay & retry
Settle in USDC, attach the X-PAYMENT proof header, receive the observation.
Sample 402 challenge
{
"x402Version": 2,
"error": "PAYMENT_REQUIRED",
"accepts": [{
"scheme": "exact",
"network": "eip155:8453",
"maxAmountRequired": "10000",
"resource": "/v1/price/CL",
"description": "commodities.sh price"
}]
}curl -i https://api.commodities.sh/v1/price/CL
# → HTTP 402 Payment Required (when X402_ENFORCE=true)
# Settle USDC on Base, retry with X-PAYMENT