Docs
Authentication
Two lanes: x402 for agents (default), and Pro API keys for operators who prefer Stripe credits.
How do agents authenticate?
Agents should use x402: probe a paid route, settle USDC on Base from the 402 challenge, retry with X-PAYMENT. No long-lived secret is required.
How do Pro API keys work?
Human operators buy Pro ($19/mo or $180/yr) at /get-started, receive a cs_live_… key once, and send Authorization: Bearer cs_live_… on paid routes. Each call debits credits (1 credit = $0.01 of list price). Exhausted quota returns HTTP 402 QUOTA_EXCEEDED.
A
x402 (agents)
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.
Example request
curl -i https://api.commodities.sh/v1/price/CL
# → HTTP 402 Payment Required (when X402_ENFORCE=true)
# Settle USDC on Base, retry with X-PAYMENTSample 402 body
{
"x402Version": 2,
"error": "PAYMENT_REQUIRED",
"accepts": [{
"scheme": "exact",
"network": "eip155:8453",
"maxAmountRequired": "10000",
"resource": "/v1/price/CL",
"description": "commodities.sh price"
}]
}Retry the same URL with header X-PAYMENT: <proof>.
Soft-GO note
When X402_ENFORCE is off (demo / Soft-GO), paid routes may return the observation body without a payment challenge. Treat that as a discovery convenience — production agent infrastructure should run with enforce on and a live facilitator.
Do I need an API key?
Agents do not. Prefer x402. Human operators can buy a Pro key at /get-started ($19/mo or $180/yr, 3,000 credits/month) and send Authorization: Bearer cs_live_….
Which network and asset for x402?
USDC on Base (eip155:8453). The 402 accepts array describes scheme, network, maxAmountRequired, and the resource path for the call you requested.
What if I get a 200 without paying?
Soft-GO demos may leave X402_ENFORCE off so agents can explore response shapes when no API key is present. Check /health and env posture before assuming payment is verified in production.