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 · LE · HE

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

Agents request, see HTTP 402 when enforce is on, pay USDC on Base, retry with proof. Soft-GO demos may leave enforce off.

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

catalog.listInstrument registry + metadata
price.latestLatest cash/fundies observation
inventory.getEIA weekly stocks + surprise
positioning.getCFTC managed-money COT
spread.getCrack, crush, calendar
price.historyHistorical time series for an instrument
fx.latestLatest FX rate observation
fundamentals.getWASDE, crop progress, ESR, USGS minerals
snapshot.getSector bundle
calendar.getRelease calendar
decision.getDeterministic 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. Production traffic pays with x402 USDC on Base when enforce is on (or Pro credits).

How do agents pay?

When X402_ENFORCE is on, paid routes return HTTP 402 with USDC payment requirements on Base; the agent settles and retries with an X-PAYMENT proof header. Soft-GO demos may leave enforce off. Free discovery — catalog, calendar, llms.txt, OpenAPI, SKILL.md, and the agent card — stays free. Pro operators may use credit keys.

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.