Quickstart

All REST, MCP, and discovery routes are served from:

https://api.commodities.sh

No payment, no key. Returns instruments, inventory series, and pricing.

curl -s https://api.commodities.sh/v1/catalog | jq '.instruments | length'

Try catalog →

Shape: { service, phase, instruments[], inventory_series, pricing_usd, claims }

Full walkthrough: Getting started →

Every paid response is an Observation. Honesty fields are required — not optional marketing fluff.

• freshness_classeod | weekly | monthly | decree | …
• qualityofficial | indicative | derived | delayed
• license_tagRedistribution posture (fred_public, usgs_public, …)
• source{ name, series_id, url }
• provenanceretrieved_at, cache_hit, cache_ttl_s

See observation contract and claims for what Phase 1 does and does not sell.

Request a price. When enforce is on, expect HTTP 402, settle USDC on Base, retry with X-PAYMENT. Soft-GO demos may leave enforce off so the body returns without 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-PAYMENT

Sample 402 body

{
  "x402Version": 2,
  "error": "PAYMENT_REQUIRED",
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "10000",
    "resource": "/v1/price/CL",
    "description": "commodities.sh price"
  }]
}

Retry: same URL + header X-PAYMENT: <proof>. Details: Authentication →

Point your MCP host at the absolute HTTP endpoint on commodities.sh.

{
  "mcpServers": {
    "commodities": {
      "url": "https://api.commodities.sh/api/mcp"
    }
  }
}

Agent discovery stack: Agents guide →

Free surfaces agents and humans can scrape without paying — same host as the API.

• https://api.commodities.sh/llms.txt— Agent briefing
• https://api.commodities.sh/v1/catalog— Instruments JSON
• https://api.commodities.sh/openapi.json— Spec
• https://api.commodities.sh/SKILL.md— Agent skill
• https://api.commodities.sh/.well-known/agent.json— A2A
• https://api.commodities.sh/api/mcp— Tools
• https://api.commodities.sh/llms-full.txt— Full instrument + price dump
• https://api.commodities.sh/health— Status

Postman: import apps/web/postman/Commoditiesx402.postman_collection.json and set base_url to https://api.commodities.sh.