Unusual Whales API - Economy endpoints (EconomyController)

Unusual Whales API - Economy endpoints

Layer mapping: L1 (0DTE) load-bearing for event calendar. Macro release days (CPI, FOMC, NFP) are the single highest-impact 0DTE days. The SPY hunter has to know which day it is.

One endpoint, multiple indicators.

1. Base contract

Property	Value
Base URL	https://api.unusualwhales.com
Auth	Authorization: Bearer <token> header
Response envelope	{ "data": { ... } } (nested)
Status codes	200, 422, 500
Rate limits	Not specified

2. Endpoint

GET /api/economy/{indicator}

Time-series for one macro indicator.

Path parameter:

Param	Type	Required	Allowed values
indicator	string	yes	gdp, gdp-per-capita, treasury-yield, fed-funds, cpi, inflation, retail-sales, durables, unemployment, payrolls

Query parameters:

Param	Type	Required	Default	Allowed values
interval	string	no	varies	daily, weekly, monthly, quarterly, annual, semiannual
maturity	string	no	-	3month, 2year, 5year, 7year, 10year, 30year (only for treasury-yield)

Response:

{
  "data": {
    "name": "cpi",
    "interval": "monthly",
    "unit": "index_value",
    "data": [/* time-series rows */]
  }
}

The outer data envelope wraps an inner data array. Per-row shape is not detailed in docs - expect [{ date, value }]. Verify on first fetch.

3. MK3 use (L1)

Macro release days drive SPY 0DTE risk. The relevant ones for L1:

Release	Cadence	Typical print time (ET)	Impact
CPI	Monthly (~10th-15th)	08:30	High; defines Fed reaction function
FOMC rate decision	8x/yr	14:00	Highest single-print impact
FOMC minutes	8x/yr	14:00	Medium
NFP (payrolls)	Monthly (1st Fri)	08:30	High
Unemployment	Monthly	08:30	Bundled with NFP
Retail sales	Monthly	08:30	Medium
Durables	Monthly	08:30	Low-medium

Workflow. Run a daily pre-session task that builds an event calendar for the next 5 sessions:

1. Cross-reference today + next 4 trading dates against known release schedules (FOMC dates are on the Fed’s published calendar; CPI/NFP follow BLS release schedule).
2. Use these UW endpoints to confirm prior prints and surprise magnitudes (e.g. CPI YoY actual vs estimate from the prior month).
3. Build features:
   • is_release_day (bool, today)
   • release_in_session_window (release time in trading day)
   • prior_release_surprise_sign (last CPI surprise direction)
4. Strategy gate: the Setup Hunter can choose to flat-by-default into 08:30 prints, or trade them with a different sizing policy.

The actual release time and release dates probably aren’t in this endpoint - this endpoint gives historical series. The forward calendar likely lives elsewhere (UW’s economic_release alert noti_type, or an external calendar). Flag for future fetch.

4. Nautilus integration shape

• One-time daily pull at session start for each relevant indicator.
• Cache in memory.
• Publish a UWEconomyContext snapshot type to the bus once per day.
• The forward event calendar (release dates) needs a separate source
  • likely the UW alerts feed filtered to noti_type: economic_release, or an external macro calendar (Investing.com, Trading Economics).

5. Per-indicator notes

Indicator	What it returns	Default interval
gdp	US GDP level	quarterly
gdp-per-capita	US GDP/capita	annual
treasury-yield	Yield on tenor maturity	daily
fed-funds	Effective fed funds rate	daily
cpi	CPI index level	monthly
inflation	YoY inflation rate	monthly
retail-sales	Total retail sales	monthly
durables	Durable goods orders	monthly
unemployment	Unemployment rate	monthly
payrolls	Nonfarm payrolls level	monthly

For 0DTE, cpi, fed-funds, treasury-yield (esp. 2year and 10year) carry the most regime context. Long-end yields drive risk appetite; short-end drives Fed expectations.

6. Known gaps

• No release-date / release-time on the schema. This endpoint gives historical series, not the event calendar. For the calendar, use UW’s economic_release alert noti_type from uw-api-alerts, or pair with an external source.
• Per-row data shape not documented - first fetch should update.
• No surprise / expectation pairing on these rows (you get the actual, not the consensus that preceded it).
• No real-time push.

7. Source URL

• https://api.unusualwhales.com/docs/operations/PublicApi.EconomyController.show

cortana-north-star uw-api-alerts uw-api-earnings 2026-05-15-mk3-setup-hunter-architecture