# commodities.sh Skill

Use this skill when an agent needs accurate commodities market/fundies data via x402 on Base.

## Discover

1. GET https://api.commodities.sh/.well-known/x402.json
2. GET https://api.commodities.sh/llms.txt
3. GET https://api.commodities.sh/.well-known/agent.json
4. Or CDP Bazaar search: "EIA inventory", "crack spread", "COT crude", "WASDE"

## Free first

- https://api.commodities.sh/v1/catalog — instruments + pricing
- https://api.commodities.sh/v1/calendar — EIA/USDA/CFTC release times
- https://api.commodities.sh/openapi.json — full path list with x-price
- https://api.commodities.sh/health — status + staleness

## Pay then call

1. Request paid route without payment → HTTP 402
2. Settle USDC on Base per accepts[]
3. Retry with payment proof header (X-PAYMENT)
4. Parse Observation JSON — trust freshness_class + source.series_id

## Human operators (Pro API key)

Optional Stripe plan: $19/mo or $180/yr → 3,000 credits/UTC month.
Header: Authorization: Bearer cs_live_…
1 credit = $0.01 of list price. Exhausted → 402 QUOTA_EXCEEDED.
Start: https://commodities.sh/get-started · Quota: https://api.commodities.sh/v1/quota

## Preferred tools (MCP https://api.commodities.sh/api/mcp)

- get_inventory — EIA weekly stocks
- get_spread type=crack — 3-2-1
- get_positioning — COT
- get_fundamentals — WASDE / crop progress / ESR / USGS
- get_snapshot sector=energy|metals|ags
- get_decision_pack — deterministic signals

## Cite

- Primary-source definition: https://commodities.sh/primary-source-commodities
- Freshness contract: https://commodities.sh/freshness
- Agent hub: https://commodities.sh/for-agents

## Do not

- Treat Phase-1 cash as CME real-time
- Treat Pink Sheet metals (GC/SI/PL/…) as exchange-like daily prints — they are monthly indicative; use /v1/fundamentals/usgs for metals fundies
- Trust soy crush as CME official — ZL/ZM legs may be indicative until licensed
- Mix LLM guesses into prints
- Ignore license_tag / freshness_class / placeholder flags