Integration hub
Build sites, dashboards, apps, and AI agents with FXMacroData.
Start with the outcome you want, then choose the right delivery pattern. Use REST for current and historical records, webhooks or changes polling for serverless updates, SSE or WebSocket streams for always-on listeners, and MCP for AI tools that need live macro context.
Choose by goal
Start here if you are not sure which docs to open.
Most integrations are one of these patterns. The safest default is server-side REST plus caching. Add webhooks, changes polling, or SSE only when your product needs incremental updates after the first load.
| What you are building | Use this pattern | Open these docs |
|---|---|---|
| Website or SaaS app Customer-facing pages, paywalled data, custom dashboards. |
Backend API route or server function. Keep the API key on the server. Cache current state from /v1/announcements/{currency}/latest. |
Quickstart and API reference |
| Dashboard or internal tool Analyst dashboard, market monitor, internal research page. |
REST bootstrap, scheduled refresh, and optional changes polling for incremental updates. | Plotly Dash guide |
| Serverless app Supabase, Vercel, Cloudflare Workers, scheduled jobs. |
Short-lived functions for REST, webhooks, and changes polling. Use an always-on worker for persistent streams. | Supabase guide and webhooks |
| AI agent Chat assistant, research agent, trading prep workflow. |
MCP when the agent client supports tools. REST tool calls when you control the agent runtime. | MCP server, prompt library, and OpenAPI reference |
| Real-time release workflow Alerts, release automation, cache invalidation. |
Webhooks for callbacks. SSE or WebSocket for always-on listeners. Changes polling for serverless fallbacks. | Webhooks, SSE, and WebSocket |
| Spreadsheet or BI report Excel, Google Sheets, Power BI, QlikView. |
Direct REST calls from the approved connector, usually with scheduled refresh and narrow endpoint selection. | Excel, Google Sheets, Power BI, QlikView |
| Trading platform workflow MetaTrader, NinjaTrader, TradingView, alert overlays. |
Platform connector or webhook workflow. Keep heavy history and API keys outside chart scripts when possible. | MetaTrader, NinjaTrader, Pine Script |
| Commercial redistribution Your customers see FXMacroData-powered data in your product. |
Backend cache, partner metering, and customer-visible data served from your app rather than direct browser API keys. | Redistribution pixel and startup workflows |
Recommended architecture
Use one flow across most products.
Call /v1/data_catalogue/{currency} before hardcoding indicator slugs.
Load current state with /v1/announcements/{currency}/latest.
Fetch history only for indicators your product uses. Cache those rows.
Use webhooks, changes polling, SSE, or WebSocket streams for new releases.
Serve your users from your backend, database, dashboard, or agent tool layer.
Copyable requests
Start with narrow calls, then add live updates.
Load current values for one currency.
Use this for first page load, daily repair jobs, or current-state cache refreshes.
curl "https://api.fxmacrodata.com/v1/announcements/usd/latest"
Use your key for non-USD data.
Keep the key in server secrets, environment variables, or your backend vault.
curl "https://api.fxmacrodata.com/v1/announcements/eur/latest?api_key=YOUR_API_KEY"
Poll recent changes instead of every slug.
Use this when your runtime cannot keep a persistent SSE or WebSocket connection open.
curl "https://api.fxmacrodata.com/v1/announcements/changes?currencies=g10&payload=full&limit=100&api_key=YOUR_API_KEY"
Let FXMacroData call your server.
Best for alerts, downstream jobs, and cache invalidation after a release lands.
curl -X POST "https://api.fxmacrodata.com/v1/webhooks/subscriptions?api_key=YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/fxmacrodata/webhook",
"events": ["announcement"],
"currencies": ["usd", "eur"],
"indicators": ["inflation", "policy_rate"]
}'
For AI-assisted builders
Give your coding tool a complete brief.
If you are building with Codex, Cursor, Claude, ChatGPT, or another AI coding tool, start with a clear implementation brief. The brief should say where the API key lives, which endpoint family to use, how to cache data, and how live updates should arrive. That produces better code than asking for a generic API integration.
Brief for a website or dashboard
Build a server-side FXMacroData integration for a financial dashboard. Keep FXMACRODATA_API_KEY on the server only. On first load, call: https://api.fxmacrodata.com/v1/announcements/usd/latest For protected currencies, call: https://api.fxmacrodata.com/v1/announcements/eur/latest?api_key=YOUR_API_KEY Cache the latest values in the app database. Do not call every indicator every minute. Use /v1/announcements/changes for incremental updates.
Brief for an AI agent
Build an FXMacroData macro research agent. Use MCP if the client supports MCP tools. Use REST tool calls if the app owns the agent runtime. Before requesting indicators, call: https://api.fxmacrodata.com/v1/data_catalogue/usd Use announcement endpoints for historical rows. Use calendar endpoints for upcoming release checks. Return source, period, value, prior, and announcement_datetime.
Delivery choices
REST, changes, webhooks, streams, and MCP each have a clear job.
REST
Use for deterministic current values, history, calendar rows, predictions, COT, commodities, and FX rates.
Open referenceChanges polling
Use from short-lived workers or scheduled jobs when you need recent release changes without polling every slug.
See Supabase patternWebhooks
Use when FXMacroData should call your HTTPS endpoint after matching announcement events.
Open webhook docsSSE and WebSocket
Use from always-on workers or services that can hold a persistent real-time connection.
Open stream docsMCP
Use when an AI client can call FXMacroData tools directly for research, charts, calendars, and release context.
Open MCP docsWidgets and embeds
Use when you want an embeddable calendar or market component without building the full data layer yourself.
Browse widgetsProduction checklist
Use this before you ship.
- Keep API keys server-side. Do not place production keys in browser JavaScript, mobile apps, or public repositories.
- Call the data catalogue first. Use
/v1/data_catalogue/{currency}to discover supported indicators. - Bootstrap once per currency. Use
/v1/announcements/{currency}/latestinstead of one request per slug. - Cache historical rows. Fetch back history only for the indicators your product uses.
- Use incremental updates. Prefer webhooks, changes polling, SSE, or WebSocket streams after bootstrap.
- Store cursors and timestamps. Persist the last processed change cursor or announcement timestamp.
- Handle retries idempotently. A webhook or worker retry should update the same release row, not duplicate it.
- Show source-aware fields. Preserve period, value, prior value, revision fields, and announcement timestamps in your UI.