{"openapi":"3.1.0","info":{"title":"commodities.sh","version":"0.1.0","description":"Primary-source commodities API for agents. Every observation includes freshness_class, source, license_tag, provenance. Free discovery paths listed; paid routes use x402 USDC on Base.","x-free-paths":["/health","/v1/catalog","/v1/calendar","/llms.txt","/llms-full.txt","/openapi.json","/SKILL.md","/.well-known/agent.json","/.well-known/x402.json","/terms.txt"],"x-pricing":{"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}},"servers":[{"url":"https://api.commodities.sh"}],"paths":{"/health":{"get":{"summary":"Health + staleness","x-price":0}},"/v1/catalog":{"get":{"summary":"Instrument catalog","x-price":0}},"/v1/calendar":{"get":{"summary":"Release calendar","x-price":0}},"/llms.txt":{"get":{"summary":"Agent briefing (llms.txt)","x-price":0}},"/llms-full.txt":{"get":{"summary":"Full agent reference","x-price":0}},"/SKILL.md":{"get":{"summary":"Agent skill manifest","x-price":0}},"/.well-known/agent.json":{"get":{"summary":"A2A agent card","x-price":0}},"/.well-known/x402.json":{"get":{"summary":"x402 resource catalog","x-price":0}},"/v1/price/{code}":{"get":{"summary":"Latest price","description":"Latest cash/fundies price observation","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.01,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/prices":{"get":{"summary":"Bundle prices","description":"Bundle prices (codes=)","parameters":[{"name":"codes","in":"query","required":true,"schema":{"type":"string"}}],"x-price":0.02,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/history/{code}":{"get":{"summary":"Series history","description":"Series history","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.02,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/curve/{root}":{"get":{"summary":"Forward curve","description":"Curve (Phase-2 stub when indicative futures off)","parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.03,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/inventory/eia":{"get":{"summary":"EIA inventories + surprise","description":"EIA weekly inventories + surprise","x-price":0.03,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/inventory/eia/{series}":{"get":{"summary":"Single EIA inventory series","description":"Single EIA inventory series","parameters":[{"name":"series","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.02,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/cot/{code}":{"get":{"summary":"COT managed-money net","description":"CFTC managed-money COT net","parameters":[{"name":"code","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.02,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/spreads/crack":{"get":{"summary":"3-2-1 crack","description":"3-2-1 crack spread cash proxy","x-price":0.03,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/spreads/crush":{"get":{"summary":"Soy crush proxy","description":"Soy crush margin proxy","x-price":0.03,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/spreads/basis":{"get":{"summary":"WTI-Brent basis","description":"WTI-Brent basis spread","x-price":0.03,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/spreads/calendar/{root}":{"get":{"summary":"Calendar spread","description":"Calendar spread (Phase-2 stub)","parameters":[{"name":"root","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.02,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/fundamentals/wasde":{"get":{"summary":"USDA WASDE slice","description":"USDA WASDE slice","x-price":0.03,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/fundamentals/crop-progress":{"get":{"summary":"Crop progress","description":"Crop progress","x-price":0.02,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/fundamentals/export-sales":{"get":{"summary":"Export sales","description":"Export sales","x-price":0.02,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/fundamentals/usgs":{"get":{"summary":"USGS Mineral Commodity Summaries","description":"USGS Mineral Commodity Summaries (annual)","x-price":0.03,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/fx/{pair}":{"get":{"summary":"FX pair","description":"FX for commodity context","parameters":[{"name":"pair","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.01,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/snapshot/{sector}":{"get":{"summary":"Sector snapshot","description":"energy|metals|ags snapshot","parameters":[{"name":"sector","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.05,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/decision/{sector}":{"get":{"summary":"Decision pack","description":"Deterministic decision pack (single sector)","parameters":[{"name":"sector","in":"path","required":true,"schema":{"type":"string"}}],"x-price":0.1,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/snapshot/all":{"get":{"summary":"All-sector snapshot bundle","description":"All-sector snapshot bundle","x-price":0.12,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/v1/decision/all":{"get":{"summary":"All-sector decision pack bundle","description":"All-sector decision pack bundle","x-price":0.25,"responses":{"200":{"description":"Observation or bundle JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Observation"}}}},"402":{"description":"Payment Required (x402)"}}}},"/api/mcp":{"post":{"summary":"MCP streamable HTTP","x-price":"per-tool"},"get":{"summary":"MCP tool names (discovery)","x-price":0}}},"components":{"schemas":{"Observation":{"type":"object","required":["instrument","value","unit","as_of","freshness_class","source","license_tag","derived"],"properties":{"instrument":{"type":"string","example":"CL"},"value":{"type":"number","example":69.6},"unit":{"type":"string","example":"USD/bbl"},"as_of":{"type":"string","format":"date","example":"2026-07-06"},"observed_at":{"type":"string","format":"date-time"},"freshness_class":{"type":"string","enum":["eod","weekly","monthly","decree","intraday","delayed"]},"quality":{"type":"string","enum":["official","indicative","derived","delayed"]},"derived":{"type":"boolean"},"source":{"type":"object","properties":{"name":{"type":"string"},"series_id":{"type":"string"},"url":{"type":"string"}}},"license_tag":{"type":"string"},"provenance":{"type":"object","properties":{"retrieved_at":{"type":"string","format":"date-time"},"cache_hit":{"type":"boolean"},"cache_ttl_s":{"type":"number"}}}}}}}}