x402 · Base USDC · MCP

EIA · FRED · CFTC · USDA · USGS

Primary-source commodities for agents

Inventories, cash, COT, and structure — with ruthless freshness labels.

Quickstart llms.txt →

GET api.commodities.sh/v1/price/CL · from $0.01 · freshness labeled

Not exchange real-time futures.

GET /v1/price/CL

observation

{
  "instrument": "CL",
  "name": "WTI Cushing",
  "value": 78.42,
  "unit": "USD/bbl",
  "as_of": "2026-07-09",
  "freshness_class": "eod",
  "quality": "official",
  "derived": false,
  "source": {
    "name": "FRED",
    "series_id": "DCOILWTICO"
  },
  "license_tag": "fred_public",
  "provenance": {
    "retrieved_at": "2026-07-09T14:02:11Z",
    "cache_hit": true,
    "cache_ttl_s": 300
  }
}

Free discovery

llms.txtAgent briefing CatalogInstruments JSON OpenAPISpec SKILL.mdAgent skill Agent cardA2A MCPTools

API host api.commodities.sh·loading catalog…

Coverage

What you get

Government cash and fundies across energy, metals, and ags — every observation carries freshness, quality, and license tags.

Energy

WTI, Brent, nat gas, heating oil, gasoline cash — plus EIA inventories.

CL · BZ · NG · HO · RB

Metals

Gold, copper, and precious metals from official series — COT where available.

GC · HG · SI · PL · PA · AL · NI · ZN · IO

Ags

Grains, softs, crush — WASDE, crop progress, and export sales.

ZC · ZW · ZS · ZL · ZM · KC · CC · SB · CT · ZR

Freshness labels

eod

End-of-day official cash

weekly

EIA / COT / USDA cadence

monthly

Decree and monthly prints

quality:derived

Crack, crush, decision packs

Payments

Pay per call with x402

No account required. Agents request, see HTTP 402, pay USDC on Base, retry with proof.

Request

GET api.commodities.sh/v1/inventory/eia — or any paid route. No API key.

402

Server returns HTTP 402 with USDC payment requirements on Base.

Pay & retry

Settle in USDC, attach the X-PAYMENT proof header, receive the observation.

request.sh

GET

curl -i https://api.commodities.sh/v1/price/CL

API

Endpoints that sell

Path-priced reference data. Pull what you need; leave the rest.

GET/v1/inventory/eia

Weekly EIA stocks with WoW and vs-5y surprise.

$0.03 / call

GET/v1/spreads/crack

3-2-1 crack from official cash legs.

$0.03 / call

GET/v1/cot/{code}

Managed-money COT nets from CFTC.

$0.02 / call

GET/v1/fundamentals/usgs

USGS Mineral Commodity Summaries — annual metals fundies.

$0.03 / call

GET/v1/snapshot/{sector}

Sector bundle: energy | metals | ags.

$0.05 / call

GET/v1/decision/{sector}

Deterministic decision pack for agents.

$0.10 / call

Agents

Built for agents

REST, MCP tools, and discovery files agents can find without a human in the loop.

bash

curl -i https://api.commodities.sh/v1/price/CL
# → HTTP 402 Payment Required (when X402_ENFORCE=true)
# Settle USDC on Base, retry with X-PAYMENT

MCP tools

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

list_instrumentsInstrument registry + metadata
get_priceLatest cash/fundies observation
get_inventoryEIA weekly stocks + surprise
get_positioningCFTC managed-money COT
get_spreadCrack, crush, calendar
get_fundamentalsWASDE, crop progress, ESR, USGS minerals
get_snapshotSector bundle
get_calendarRelease calendar
get_decision_packDeterministic decision pack

Pricing

USDC per call on Base. Free discovery stays free.

Endpoint	USDC
GET /v1/price/{code}	$0.01
GET /v1/prices?codes=	$0.02
GET /v1/history/{code}	$0.02
GET /v1/inventory/eia	$0.03
GET /v1/inventory/eia/{series}	$0.02
GET /v1/cot/{code}	$0.02
GET /v1/spreads/crack	$0.03
GET /v1/spreads/crush	$0.03
GET /v1/spreads/basis	$0.03
GET /v1/fundamentals/wasde	$0.03
GET /v1/fundamentals/crop-progress	$0.02
GET /v1/fundamentals/export-sales	$0.02
GET /v1/fundamentals/usgs	$0.03
GET /v1/fx/{pair}	$0.01
GET /v1/snapshot/{sector}	$0.05
GET /v1/decision/{sector}	$0.10
GET /v1/snapshot/all	$0.12
GET /v1/decision/all	$0.25

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

FAQ

Quick answers

What is commodities.sh?

commodities.sh is a primary-source commodities reference API for AI agents. It serves government cash, inventories, COT, USDA fundies, USGS minerals, and derived structure (crack, crush, basis) — each observation labeled with freshness, quality, license, and provenance. Agents discover it via llms.txt, SKILL.md, agent.json, OpenAPI, and MCP, then pay per call with x402 USDC on Base.

How do agents pay?

Paid routes use x402: the server returns HTTP 402 with USDC payment requirements on Base. The agent settles and retries with an X-PAYMENT proof header. Free discovery — catalog, calendar, llms.txt, OpenAPI, SKILL.md, and the agent card — stays free. No account or API key is required.

Does it sell real-time futures?

No. commodities.sh does not sell real-time CME/ICE/LME exchange futures. It serves cash, inventories, COT, USDA fundies, USGS minerals, and derived structure with explicit freshness and quality labels — not exchange real-time prints.

Get started

Ship the next commodities agent

Start with the catalog. Wire MCP. Pay only when you call.

Try with wallet Quickstart llms.txt

Does not sell real-time exchange futures. Cash, inventories, COT, USDA fundies (PSD/NASS/ESR when keyed), and derived structure. ZL/ZM oil/meal cash and crush oil/meal legs may be indicative until a licensed delayed futures feed is available. Precious metals are monthly indicative (Pink Sheet) — use /v1/fundamentals/usgs for metals fundies.