Unusual Whales API - Commodities endpoints
Single endpoint, single controller. Historical pricing/metric series for the major commodities. Macro context only - not in the SPY hunter hot path, but useful for cross-asset/regime narratives.
1. Base contract
| Property | Value |
|---|---|
| Base URL | https://api.unusualwhales.com |
| Auth | Authorization: Bearer <token> header |
| Response envelope | { "data": { ... } } |
| Status codes | 200, 422, 500 |
| Rate limits | Not specified |
2. Endpoint
GET /api/commodities/{name}
Time-series for one commodity (or all-commodities for the full set).
Path parameter:
| Param | Type | Required | Allowed values |
|---|---|---|---|
name | string | yes | wti, brent, natural-gas, copper, aluminum, wheat, corn, cotton, sugar, coffee, all-commodities |
Query parameter:
| Param | Type | Required | Default | Allowed values |
|---|---|---|---|---|
interval | string | no | monthly | daily, weekly, monthly, quarterly, annual |
Response:
{
"data": {
"name": "wti",
"interval": "monthly",
"unit": "USD per barrel",
"data": [/* time series values */]
}
}The outer data envelope wraps an inner data array of time-series
values. unit is human-readable (e.g. "USD per barrel", "USD per million BTU").
3. MK3 use
Not part of the SPY hunter hot path. Plausible uses:
- Macro regime overlay. WTI spikes correlate with risk-off in equities; copper falls correlate with growth-slowdown narratives. Useful as a low-frequency context feature, not a gate.
- Cross-asset divergence postmortems. When SPY rips while WTI/copper diverge, note it in the postmortem corpus.
- News-event framing. OPEC/refining shocks → WTI prints, then energy-sector flow alerts. Match alert clusters to commodity moves.
Polling cadence: daily at most. This is reference data, not signal.
4. Nautilus integration shape
Optional UWCommodityActor that pulls daily at session start, caches
in memory or writes to Postgres. Probably not even worth a custom
data class until a strategy needs it - just an HTTP fetch + parse.
5. Known gaps
- No realtime / intraday endpoint here. This is historical series only.
- Response example uses null-placeholder, so the actual
data[]shape (per-row schema) is undocumented - probably[{ date, value }]but verify on first real fetch.
6. Source URL
https://api.unusualwhales.com/docs/operations/PublicApi.CommoditiesController.show