Live and historical prices, CFTC Commitment of Traders positioning, EIA/USDA/FRED fundamentals, news, sentiment, your own alerts — plus curve analytics you won't find on any other commodity API. Free key, no card required.
Sign in, open Data & exports, and create a key. Any signed-in account can create one free key — no subscription and no card. Keys look like ch_live_… and are shown once.
Every response is JSON, wraps its payload in data, and carries a generated_at ISO timestamp.
Pass your key as a bearer token on every request. There are no other auth schemes, and keys are not accepted as query parameters.
Rate limits are applied per key, not per IP — so a team hitting the API from one server address is not throttled as a single client.
One endpoint, selected with the resource query parameter. The base URL is https://kcxhsmlqqyarhlmcapmj.supabase.co/functions/v1/data-api.
| Resource | Tier | Parameters | Returns |
|---|---|---|---|
| prices | Free | commodity, timeframe | No parameters returns the full live catalogue. With commodity, the current price. Add timeframe — one of 1d 1m 3m 6m 1y 2y — for a historical series. |
| cot | Free | commodity (required), limit | Weekly CFTC positioning — managed money and commercial longs/shorts, net position, open interest. limit defaults to 52 weeks, maximum 520. |
| fundamentals | Free | series_id, dataset | EIA, USDA and FRED series with latest value, week-on-week and year-on-year change, and a five-year average. A series_id returns the full observation history; without one you get the list. |
| sentiment | Free | commodity | Community bullish/bearish votes per commodity — the same aggregate the in-app sentiment page shows. Omit commodity for every commodity's aggregate. |
| news | Premium+ | category, limit | The RSS-based news feed. category filters to one of energy, metals, grains, livestock, softs, economic, geopolitical, general. limit defaults to 20, maximum 100. |
| vol_cone | Pro | commodity (required) | Historical realized volatility — annualized, over rolling 10/20/60/120-day windows, with percentile rank against the last ~5 years. Reads a cache; see the note below. |
| roll_scanner | Pro | — | Roll yield across every covered contract, ranked contango-to-backwardation, in one call. Always the full universe — no commodity param. Reads a cache; see the note below. |
| term_structure | Pro | commodity (required), months_ahead | The forward curve, plus the same contracts priced 1 week and 1 month ago, so you can see how the shape shifted. months_ahead is 3–18, default 12. Reads a cache; see the note below. |
| portfolio | Free | — | Your own positions — commodity, quantity, entry price and date, notes. |
| watchlists | Free | — | Your own watchlists and their items. |
| alerts | Free | — | Your own price alerts — condition, target price, whether it's active, when it last fired. Read-only for now. |
portfolio, watchlists and alerts are scoped to the account that owns the key. news needs an active Premium or Pro subscription on that account — the same gate the in-app news page uses, re-checked on every request. vol_cone, roll_scanner and term_structure need Pro. Everything else is market data, identical for everyone, on the free tier.
vol_cone / roll_scanner / term_structure take a short product slug — wti brent gold silver copper platinum palladium corn wheat soybeans cattle hogs lumber — not the full display name ("WTI Crude Oil") that prices and cot use. They also never compute on demand: each one reads a cache the app itself keeps warm, refreshed roughly every 6 hours by real usage. That means a product nobody has opened in the app recently can return 404 snapshot_not_available — open the equivalent page in the app once to seed it — and a successful response can carry "stale": true if the cache is older than 6 hours. This is deliberate: it keeps a public API key from being able to trigger cost on our paid market-data provider just by being polled.
| Free | Pro | |
|---|---|---|
| Keys | 1 | Unlimited |
| Daily requests | 50 | No cap |
| Per-minute | 60 | 60 |
| Card required | No | — |
Every response carries rate-limit headers so you can back off before being throttled. The per-minute ceiling is the same on both tiers; Pro removes the daily cap and the single-key limit.
Errors return the appropriate HTTP status with a machine-readable error string.
| Status | Error | Meaning |
|---|---|---|
| 401 | api_key_required | No bearer token, or it does not start with ch_live_. |
| 401 | invalid_api_key | The key is not recognised or has been revoked. |
| 400 | commodity_required | cot, vol_cone, or term_structure was called without a commodity. |
| 400 | invalid_commodity | vol_cone/term_structure commodity wasn't one of the short slugs — the response lists the valid ones. |
| 400 | invalid_months_ahead | term_structure months_ahead must be an integer from 3 to 18. |
| 400 | invalid_timeframe | Unsupported timeframe; the response lists the valid values. |
| 403 | premium_required | news needs an active Premium or Pro subscription. |
| 403 | pro_required | vol_cone, roll_scanner or term_structure needs an active Pro subscription. |
| 404 | commodity_not_found | No live price for that commodity name. |
| 404 | series_not_found | No fundamentals series with that series_id. |
| 404 | snapshot_not_available | No cached value exists yet for that vol_cone/roll_scanner/term_structure request — see the Resources note above. |
| 404 | unknown_resource | The resource parameter did not match a known value. |
| 429 | rate_limited | More than 60 requests in the current 60-second window for this key. |
| 429 | trial_daily_limit_exceeded | A free key passed 50 requests today. Upgrade to remove the cap. |
| 500 | data_unavailable | Upstream data problem on our side. Retry. |
No per-request billing at either tier. The price is flat — you will never receive a surprise invoice for a backfill.
The news resource is the one exception to the two tiers above: it needs an active Premium subscription on the account, not just a paid API key — Premium is the app's $6.99/mo tier, sold separately from API access. See the Resources table for exactly which resource needs which tier.
This page covers the whole surface. For per-resource request and response examples, field-level schemas, and the machine-readable OpenAPI description, see the developer reference in the app.
Commodity Hub is a data and analytics service. It does not execute trades, hold funds, or provide investment advice. Market data is sourced from CME, CBOT, COMEX and NYMEX, positioning from the CFTC, and fundamentals from the EIA, USDA and FRED — always check the generated_at timestamp before citing a number as current.