Docs
Getting started
Two calls: free catalog to see what exists, then a paid price observation. Base URL is https://api.commodities.sh.
1. Free catalog
No payment, no key. Returns instruments, inventory series, and pricing.
curl -s https://api.commodities.sh/v1/catalog | jq '.instruments | length'2. Paid price ($0.01)
Request the latest cash/fundies print for an instrument (e.g. CL). When X402_ENFORCE=true, expect HTTP 402, settle USDC on Base, and retry with X-PAYMENT.
curl -i https://api.commodities.sh/v1/price/CL
# → HTTP 402 Payment Required (when X402_ENFORCE=true)
# Settle USDC on Base, retry with X-PAYMENTconst res = await fetch("https://api.commodities.sh/v1/price/CL");
// 402 → pay USDC on Base → retry with X-PAYMENT
const obs = await res.json();
console.log(obs.freshness_class, obs.value);What should I call first?
Always start with GET /v1/catalog. It is free, lists instruments and inventory series, and shows pricing_usd so agents know what each paid path costs before they settle USDC.
What do I get back from a paid price call?
An Observation: instrument, value, unit, as_of, freshness_class, quality, source (name + series_id), license_tag, and provenance. Honesty fields are required on every paid response.
Where do I go next?
Read Authentication for the 402 → pay → retry loop, Observation contract for field meanings, and Agents for llms.txt / SKILL.md / MCP discovery.