Docs
Agent integration
Discover commodities.sh without a human in the loop — then call REST or MCP with x402 when you need a paid observation.
Discovery stack
- llms.txt— Agent briefing
- Catalog— Instruments JSON
- OpenAPI— Spec
- SKILL.md— Agent skill
- Agent card— A2A
- MCP— Tools
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
Product hub: For agents →
MCP
Point your MCP host at the streamable HTTP endpoint:
json
{
"mcpServers": {
"commodities": {
"url": "https://api.commodities.sh/api/mcp"
}
}
}list_instrumentsInstrument registry + metadataget_priceLatest cash/fundies observationget_inventoryEIA weekly stocks + surpriseget_positioningCFTC managed-money COTget_spreadCrack, crush, calendarget_fundamentalsWASDE, crop progress, ESR, USGS mineralsget_snapshotSector bundleget_calendarRelease calendarget_decision_packDeterministic decision pack
Where should an agent start discovery?
Fetch /llms.txt for the briefing index, /SKILL.md for call patterns, /.well-known/agent.json for the A2A card, and /openapi.json for the machine schema. Catalog and calendar stay free.
How do agents connect MCP?
Add a server entry pointing at https://api.commodities.sh/api/mcp. Tools cover instruments, price, inventory, COT, spreads, fundies, snapshot, calendar, and decision packs.
Is discovery free?
Yes. FREE_DISCOVERY_PATHS — health, catalog, calendar, llms.txt, OpenAPI, SKILL.md, agent card, x402.json, terms — do not require payment. Paid observations still use x402.