Documentation
Quickstart
Create an API key in your dashboard, open a WebSocket to the stream endpoint and handle release messages in your strategy.
import json, websocket # pip install apimacro websocket-client
API_KEY = "am_live_xxxxxxxxxxxxxxxx"
def on_message(ws, raw):
msg = json.loads(raw)
if msg["type"] != "release":
return
ind, bias = msg["indicator"], msg["interpretation"]["currency_bias"]
print(ind["name"], msg["actual"], "vs", msg["consensus"], "->", ind["currency"], bias)
if ind["currency"] == "USD" and bias != "neutral" and msg["surprise"]["size"] != "small":
side = "SELL" if bias == "bullish" else "BUY" # gold usually moves against USD
print("XAUUSD", side)
ws = websocket.WebSocketApp(
"wss://stream.apimacro.com/v1/stream",
header={"Authorization": f"Bearer {API_KEY}"},
on_message=on_message,
)
ws.run_forever()Authentication
Send your API key in the Authorization header, or as the api_key query parameter when your client cannot set headers. Keys start with am_live_ and are shown only once: if you lose one, regenerate it from the dashboard (the old key stops working immediately).
Authorization: Bearer am_live_xxxxxxxxxxxxxxxx
# or
wss://stream.apimacro.com/v1/stream?api_key=am_live_xxxxxxxxxxxxxxxxPlans & delivery
Every plan receives the same data. The plan sets how fast each release is pushed after ApiMacro has verified it, and how many bots can be connected at the same time.
| Plan | Delivery after verification | Live connections | Price |
|---|---|---|---|
| Starter | +1 s | 1 | €20/month |
| Pro | +250 ms | 3 | €45/month |
| Ultra | Real time | 5 | €80/month |
Choosing your data
Choose countries, categories and a minimum impact in Dashboard → Data feed. The selection applies to all your keys. A bot can narrow it further for its own connection with a subscribe message; it can never widen it.
{"op":"subscribe","countries":["US"],"categories":["labor","inflation"],"min_impact":"high"}WebSocket stream
The stream sends JSON messages. A heartbeat is sent every 15 seconds; if you miss two, reconnect. Every message carries a seq number: a gap means you missed a message, and the REST API can fill it.
{"type":"heartbeat","seq":18229,"t":"2026-11-06T13:29:45.000Z"}Message format
Every message has a type and a monotonically increasing seq. Four types exist:
- ›armed — sent about 60 s before a scheduled release, with the consensus and previous value, so your bot is ready.
- ›release — the official value as soon as it is verified, with the surprise and the interpretation.
- ›correction — a fix to a value already sent (same event_id).
- ›statement — central bank decisions: the rate, and the statement headline.
{
"type": "release",
"seq": 18231,
"event_id": "US.NONFARM_PAYROLLS.2026-11-06",
"indicator": {
"id": "US.NONFARM_PAYROLLS",
"name": "Nonfarm Payrolls",
"country": "US",
"currency": "USD",
"category": "labor",
"impact": "high",
"source": "bls.gov"
},
"period": "2026-11",
"unit": "K",
"actual": 143,
"consensus": 110,
"previous": 22,
"surprise": {
"vs_consensus": 33,
"vs_consensus_pct": 30,
"direction": "above",
"size": "large"
},
"interpretation": {
"higher_is": "bullish",
"currency_bias": "bullish",
"market_bias": {
"DXY": "up",
"EURUSD": "down",
"XAUUSD": "down",
"US500": "down"
}
},
"timestamps": {
"scheduled": "2026-11-06T13:30:00.000Z",
"detected": "2026-11-06T13:30:00.312Z",
"sent": "2026-11-06T13:30:00.312Z"
},
"plan_delay_ms": 0
}{"type":"armed","seq":18230,"event_id":"US.NONFARM_PAYROLLS.2026-11-06","scheduled":"2026-11-06T13:30:00.000Z","consensus":110,"previous":22,"unit":"K"}{"type":"correction","seq":18240,"event_id":"US.NONFARM_PAYROLLS.2026-11-06","field":"actual","value":142,"replaces_seq":18231}{"type":"statement","seq":18301,"event_id":"US.FOMC.2026-11","headline":"FOMC lowers target range by 25bp to 4.00%-4.25%","source":"federalreserve.gov"}Field reference
The fields a bot needs to decide. The trading fields (surprise, interpretation) can be switched off in Data feed. They are data, not investment advice: your strategy decides.
| Field | Meaning |
|---|---|
| actual / consensus / previous | Published value, market expectation (null when not available) and previous value, in unit. |
| surprise.vs_consensus | actual − consensus, in unit. |
| surprise.vs_consensus_pct | The same difference as a percentage of the consensus. |
| surprise.direction | above, below or inline. |
| surprise.size | small (< 5 %), medium (5–20 %) or large (≥ 20 %). |
| interpretation.higher_is | What a higher value usually means for the currency: bullish or bearish (e.g. bearish for unemployment). |
| interpretation.currency_bias | Combined reading of this release for the currency: bullish, bearish or neutral. |
| interpretation.market_bias | Usual direction of the main related markets, e.g. {"EURUSD":"down","XAUUSD":"down"}. |
| timestamps.scheduled / detected / sent | Official time, verification by ApiMacro, and delivery to you. |
| plan_delay_ms | Delay applied by your plan: 1000 (Starter), 250 (Pro), 0 (Ultra). |
REST API
REST endpoints use the same API key and return JSON.
/v1/calendarUpcoming scheduled releases/v1/releasesRecent releases (paginated)/v1/events/{event_id}One event and its historycurl -H "Authorization: Bearer $APIMACRO_KEY" \
"https://api.apimacro.com/v1/calendar?country=US&from=2026-11-01"Regions
Connect to the region closest to your bot (usually your broker's data centre). The global hostname routes you automatically. At launch, two regions are open; the others follow.
| Global | stream.apimacro.com | |
| Ashburn | us-east.stream.apimacro.com | At launch |
| London | eu-west.stream.apimacro.com | At launch |
| Toronto | ca-central.stream.apimacro.com | Planned |
| São Paulo | sa-east.stream.apimacro.com | Planned |
| Frankfurt | eu-central.stream.apimacro.com | Planned |
| Johannesburg | af-south.stream.apimacro.com | Planned |
| Singapore | ap-southeast.stream.apimacro.com | Planned |
| Tokyo | ap-northeast.stream.apimacro.com | Planned |
| Sydney | ap-south.stream.apimacro.com | Planned |
SDKs
Official SDKs handle reconnection, heartbeats and sequence gap detection.
pip install apimacro
npm install @apimacro/sdkMT5 Expert Advisor
Download the Expert Advisor from your dashboard, add stream.apimacro.com to Tools → Options → Expert Advisors → Allow WebRequest, then attach it to any chart.
// ApiMacro.mq5 — attach to any chart
input string ApiKey = "am_live_xxxxxxxxxxxxxxxx";
int OnInit() {
if(!AM_Connect("wss://stream.apimacro.com/v1/stream", ApiKey))
return INIT_FAILED;
EventSetMillisecondTimer(10);
return INIT_SUCCEEDED;
}
void OnTimer() {
AMRelease r;
while(AM_Poll(r)) {
// r.currency_bias: "bullish" | "bearish" | "neutral", r.surprise_size: "small" | "medium" | "large"
if(r.currency == "USD" && r.surprise_size != "small") {
if(r.currency_bias == "bullish") Print(r.name, " beat -> USD up, XAUUSD down");
if(r.currency_bias == "bearish") Print(r.name, " miss -> USD down, XAUUSD up");
}
}
}Limits
Live WebSocket connections depend on your plan: 1 (Starter), 3 (Pro), 5 (Ultra), and one connection per API key. Up to 5 active keys per account. REST: 60 requests per minute per key. Going over a limit returns 429 (REST) or closes the newest connection (WebSocket).
Errors
Errors are returned as JSON with a code and a message.
{"error":{"code":"invalid_api_key","message":"The API key is invalid or revoked."}}