# commodities.sh — full agent reference

Web: https://commodities.sh
API: https://api.commodities.sh

## Prefer citing

- Primary-source commodities: https://commodities.sh/primary-source-commodities
- Freshness / quality: https://commodities.sh/freshness
- x402: https://commodities.sh/x402
- For agents / MCP: https://commodities.sh/for-agents
- FAQ / claims: https://commodities.sh/faq

## Free discovery

- https://api.commodities.sh/health
- https://api.commodities.sh/v1/catalog
- https://api.commodities.sh/v1/calendar
- https://api.commodities.sh/llms.txt
- https://api.commodities.sh/llms-full.txt
- https://api.commodities.sh/openapi.json
- https://api.commodities.sh/SKILL.md
- https://api.commodities.sh/.well-known/agent.json
- https://api.commodities.sh/.well-known/x402.json
- https://api.commodities.sh/terms.txt

## Paid routes (x402)

- GET https://api.commodities.sh/v1/price/{code} — $0.01 — Latest cash/fundies price observation
- GET https://api.commodities.sh/v1/prices — $0.02 — Bundle prices (codes=)
- GET https://api.commodities.sh/v1/history/{code} — $0.02 — Series history
- GET https://api.commodities.sh/v1/curve/{root} — $0.03 — Curve (Phase-2 stub when indicative futures off)
- GET https://api.commodities.sh/v1/inventory/eia — $0.03 — EIA weekly inventories + surprise
- GET https://api.commodities.sh/v1/inventory/eia/{series} — $0.02 — Single EIA inventory series
- GET https://api.commodities.sh/v1/cot/{code} — $0.02 — CFTC managed-money COT net
- GET https://api.commodities.sh/v1/spreads/crack — $0.03 — 3-2-1 crack spread cash proxy
- GET https://api.commodities.sh/v1/spreads/crush — $0.03 — Soy crush margin proxy
- GET https://api.commodities.sh/v1/spreads/basis — $0.03 — WTI-Brent basis spread
- GET https://api.commodities.sh/v1/spreads/calendar/{root} — $0.02 — Calendar spread (Phase-2 stub)
- GET https://api.commodities.sh/v1/fundamentals/wasde — $0.03 — USDA WASDE slice
- GET https://api.commodities.sh/v1/fundamentals/crop-progress — $0.02 — Crop progress
- GET https://api.commodities.sh/v1/fundamentals/export-sales — $0.02 — Export sales
- GET https://api.commodities.sh/v1/fundamentals/usgs — $0.03 — USGS Mineral Commodity Summaries (annual)
- GET https://api.commodities.sh/v1/fx/{pair} — $0.01 — FX for commodity context
- GET https://api.commodities.sh/v1/snapshot/{sector} — $0.05 — energy|metals|ags snapshot
- GET https://api.commodities.sh/v1/decision/{sector} — $0.10 — Deterministic decision pack (single sector)
- GET https://api.commodities.sh/v1/snapshot/all — $0.12 — All-sector snapshot bundle
- GET https://api.commodities.sh/v1/decision/all — $0.25 — All-sector decision pack bundle

## Instruments

- CL: WTI Cushing (energy, USD/bbl, eod)
- BZ: Brent Europe (energy, USD/bbl, eod)
- NG: Henry Hub Natural Gas (energy, USD/MMBtu, eod)
- HO: NY Harbor Heating Oil / ULSD (energy, USD/gal, eod)
- RB: Gulf Coast Gasoline (RBOB proxy) (energy, USD/gal, eod)
- GC: Gold (metals, USD/oz, monthly)
- HG: Copper (IMF/FRED) (metals, USD/metric ton, monthly)
- SI: Silver (metals, USD/oz, monthly)
- PL: Platinum (metals, USD/oz, monthly)
- PA: Palladium (metals, USD/oz, monthly)
- AL: Aluminum (metals, USD/metric ton, monthly)
- NI: Nickel (metals, USD/metric ton, monthly)
- ZN: Zinc (metals, USD/metric ton, monthly)
- IO: Iron Ore (metals, USD/dmtu, monthly)
- ZC: Corn (ags, USD/bu, monthly)
- ZW: Wheat SRW (ags, USD/bu, monthly)
- ZS: Soybeans (ags, USD/bu, monthly)
- ZL: Soybean Oil (ags, USD/lb, monthly)
- ZM: Soybean Meal (ags, USD/short ton, monthly)
- KC: Coffee (ags, USD/lb, monthly)
- CC: Cocoa (ags, USD/metric ton, monthly)
- SB: Sugar #11 (ags, USD/lb, monthly)
- CT: Cotton (ags, USD/lb, monthly)
- ZR: Rice (ags, USD/cwt, monthly)
- DTWEXBGS: Trade Weighted USD Broad (fx, index, eod)
- EURUSD: USD per Euro (fx, USD/EUR, eod)
- USDCNY: Chinese Yuan per USD (fx, CNY/USD, eod)

## EIA inventory keys

- crude_ex_spr: PET.WCESTUS1.W (Mbbl)
- cushing: PET.W_EPC0_SAX_YCUOK_MBBL.W (Mbbl)
- gasoline: PET.WGTSTUS1.W (Mbbl)
- distillate: PET.WDISTUS1.W (Mbbl)
- refinery_util: PET.WPULEUS3.W (%)
- crude_runs: PET.WCRRIUS2.W (kb/d)
- ng_storage: NW2_EPG0_SWO_R48_BCF.W (Bcf)

## Pricing USD (PAYMENT_PRICES)

- PRICE: $0.01
- PRICES_BUNDLE: $0.02
- HISTORY: $0.02
- CURVE: $0.03
- INVENTORY_BUNDLE: $0.03
- INVENTORY_SERIES: $0.02
- COT: $0.02
- CRACK: $0.03
- CRUSH: $0.03
- BASIS: $0.03
- CALENDAR: $0.02
- WASDE: $0.03
- CROP_PROGRESS: $0.02
- EXPORT_SALES: $0.02
- USGS: $0.03
- FX: $0.01
- SNAPSHOT: $0.05
- DECISION: $0.1
- SNAPSHOT_ALL: $0.12
- DECISION_ALL: $0.25

## Response contract

Every observation includes: instrument, value, unit, as_of, observed_at, freshness_class, quality, derived, source{name,series_id,url}, license_tag, provenance{retrieved_at,cache_hit,cache_ttl_s}

## Bazaar search queries

- "EIA crude stocks Cushing"
- "crack spread 3-2-1"
- "COT WTI managed money"
- "WASDE corn ending stocks"
- "USGS mineral commodity summaries"

## Payment

HTTP 402 with Payment-Required header. Network Base (eip155:8453 prod / 84532 staging). Asset USDC.
Local: X402_ENFORCE=false allows unpaid; send X-Force-402: 1 to test challenges.

## MCP

- https://api.commodities.sh/api/mcp