Documentation

Macro Data API

REST and MCP. Values are decimal strings. Every data response carries source, as_of and, where known, next_release_at. Machine copies: OpenAPI, llms.txt, pricing JSON.

1. Get a key

curl -X POST https://macrodataapi.com/api/v1/auth/keys \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'
# -> {"api_key": "mdk_live_...", "tier": "free", "daily_limit": 500, ...}

Free: 10 requests a minute, 500 a day. Latest values, catalog, calendar, policy rates and yield curves. Pro adds history with as_of and vintages, at 60/min and 20,000/day.

2. Endpoints

Endpoint	What	Cadence	Per request	Tier
`GET /api/v1/series`	Catalog of every series with publisher, unit, frequency, latest period and next release.	Refreshes every 60 minutes.	$0.005	Free
`GET /api/v1/series/{series_id}`	Latest print for one series with the previous value, change, release time and next release.	Refreshes at each release; polled every 5 minutes on release days.	$0.010	Free
`GET /api/v1/series/{series_id}/history`	Full history of one series, optionally as it stood on a past date (as_of) for point-in-time backtests.	Refreshes at each release.	$0.020	Pro
`GET /api/v1/series/{series_id}/vintages`	Every revision of one period of one series: the initial print and each later value with its vintage date.	Refreshes at each release.	$0.020	Pro
`GET /api/v1/releases/upcoming`	Scheduled data releases for the next N days across every publisher, with the series each one updates.	Refreshes every 5 minutes.	$0.005	Free
`GET /api/v1/releases/latest`	The most recent releases observed, newest first, with the headline values that changed.	Refreshes every 60 seconds.	$0.010	Free
`GET /api/v1/rates/policy`	Current policy rates of the Fed, ECB, Bank of England and RBA with the last decision date and next meeting.	Refreshes every 5 minutes.	$0.005	Free
`GET /api/v1/yields/{country}`	Daily par yield curve for a country (US today), every tenor, with the previous session and the 2s10s spread.	Refreshes every 30 minutes.	$0.010	Free
`GET /api/v1/health`, `/api/v1/health/data`	Service and collection health	live	free	no key
`GET /api/v1/pricing`, `/api/v1/payments/plans`	Prices and networks	5 min	free	no key
`POST /api/v1/payments/agent-subscribe`	Buy a 1h, 1d or 7d pass with x402, get a key	live	plan price	x402

Series ids

Ids are country.topic.detail. Examples: us.cpi.all.sa, us.payrolls.total, us.gdp.real.qoq.saar, ea.hicp.annual, uk.cpi.annual, au.rba.cashrate. The full list with units is at GET /api/v1/series and on the series page.

Periods and values

Periods are YYYY-MM-DD (daily), YYYY-MM (monthly), YYYY-Qn (quarterly). Values are decimal strings exactly as published; parse them with a decimal type. Changes are computed in decimal arithmetic.

Point-in-time history

GET /api/v1/series/us.gdp.real.qoq.saar/history?as_of=2026-08-15&limit=8
# every period as it was known on 2026-08-15: the advance estimate of Q2, not the later revisions

GET /api/v1/series/us.gdp.real.qoq.saar/vintages?period=2026-Q2
# {"vintages": [{"vintage_date": "2026-07-30", "value": "3.0"}, {"vintage_date": "2026-08-28", "value": "3.3"}, ...]}

Vintages are recorded from the day this service first observed a series. Earlier revision history is not reconstructed.

Release calendar

GET /api/v1/releases/upcoming?days=7
GET /api/v1/releases/latest?limit=5

Times are UTC. BLS and BEA times come from the agencies' schedules, ONS from the series metadata, central banks from their published calendars. On a release day the affected series are polled every minute until the new period appears; released_at is the time we observed it.

3. Pay per request (x402)

curl -i https://macrodataapi.com/api/v1/series/us.cpi.all.sa
# HTTP/1.1 402 Payment Required
# Payment-Required: <base64>
# {"accepts": [{"scheme": "exact", "network": "eip155:8453", "amount": "10000", "payTo": "0x...", ...}],
#  "price_usd": 0.01, "alternatives": {...}}

# sign with an x402 client, then
curl https://macrodataapi.com/api/v1/series/us.cpi.all.sa -H "x-payment: <signed payload>"

Networks: Base (recommended), Ethereum and Solana USDC. Settlement runs through the Coinbase facilitator; you pay no gas. A per-request response is never cached. Passes go through POST /api/v1/payments/agent-subscribe with {"plan": "pass_1d"} and return a key once. There are no subscriptions; for steady use see RealtimeAPI.ai. Full table: agent pricing.

4. MCP

claude mcp add --transport http macrodataapi https://macrodataapi.com/mcp \
  --header 'X-API-Key: ${MACRODATA_API_KEY}'

Tools: list_capabilities, create_free_api_key, macro_search_series, macro_latest, macro_history, macro_vintages, macro_calendar, macro_latest_releases, macro_policy_rates, macro_yield_curve. Each is a loopback call to the REST endpoint, so tiers and limits are identical. Setup for other clients.

5. Errors and limits

Every refusal is JSON: {"detail": {"error": "...", "message": "...", ...}}. 401 carries mint_url; 403 carries upgrade with the x402 route; 429 carries Retry-After and scope (minute or day). Rate limit headers: X-RateLimit-Remaining-Minute, X-RateLimit-Remaining-Day. Payment and key-management routes never count against the daily cap.

6. Sources and licences

Publisher	Licence	Series
U.S. Bureau of Labor Statistics	US public domain	`us.cpi.all.sa` `us.cpi.all.nsa` `us.cpi.core.sa` `us.unemployment.rate` `us.payrolls.total` `us.earnings.hourly.private` `us.ppi.final_demand`
U.S. Bureau of Economic Analysis	US public domain	`us.gdp.real.qoq.saar` `us.pce.price.index` `us.pce.price.core`
U.S. Department of the Treasury	US public domain	`us.debt.total` `us.debt.public` `us.yield.10y` `us.yield.2y` `us.yield.3m` `us.yield.30y`
Board of Governors of the Federal Reserve System	US public domain	`us.fedfunds.effective`
European Central Bank	ECB data: free reuse with attribution	`ea.ecb.mrr` `ea.ecb.dfr` `ea.hicp.annual`
Eurostat	CC BY 4.0	`ea.unemployment.rate`
UK Office for National Statistics	Open Government Licence v3.0	`uk.cpi.annual` `uk.unemployment.rate` `uk.gdp.qoq`
Bank of England	Open Government Licence v3.0	`uk.boe.bankrate`
Australian Bureau of Statistics	CC BY 4.0	`au.cpi.index` `au.unemployment.rate`
Reserve Bank of Australia	CC BY 4.0	`au.rba.cashrate`

Attribution is included in the source array of every response, which satisfies CC BY and OGL and gives your agent provenance.

7. Through RealtimeAPI: 1,000 free calls a month

These endpoints are also listed on RealtimeAPI.ai under the feed macrodata. A free RealtimeAPI key gives 1,000 calls a month across every feed, one rta_live_ key for many feeds, x402 at the gateway, and edge caching with honest X-RTAPI-Data-Age headers.

curl -X POST https://api.realtimeapi.ai/keys/free -H "Content-Type: application/json" -d '{"email": "[email protected]"}'
curl https://api.realtimeapi.ai/v1/macrodata/series/us.cpi.all.sa -H "X-API-Key: rta_live_..."

Agents: paste the setup prompt (or fetch /realtimeapi/prompt.txt) and the agent adds the MCP server at https://mcp.realtimeapi.ai/mcp, mints the key and verifies with a CPI call.

8. Agent skill

A Claude Code style skill file describing this API, its endpoints, series ids and good habits: /skills/macrodataapi/SKILL.md. Install with mkdir -p ~/.claude/skills/macrodataapi && curl -fsSL https://macrodataapi.com/skills/macrodataapi/SKILL.md -o ~/.claude/skills/macrodataapi/SKILL.md, or append it to AGENTS.md.