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"
}
}
}catalog.listInstrument registry + metadataprice.latestLatest cash/fundies observationinventory.getEIA weekly stocks + surprisepositioning.getCFTC managed-money COTspread.getCrack, crush, calendarprice.historyHistorical time series for an instrumentfx.latestLatest FX rate observationfundamentals.getWASDE, crop progress, ESR, USGS mineralssnapshot.getSector bundlecalendar.getRelease calendardecision.getDeterministic 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.