Economic Events Subscription
Overview
This guide provides detailed instructions on how to subscribe to economic events and indicators using the AiTrados WebSocket API. Economic events subscriptions allow you to receive real-time updates on key economic indicators such as inflation rates, unemployment figures, GDP data, and central bank decisions that can significantly impact financial markets.
Why Subscribe to Economic Events
- Market-Moving Data: Economic indicators often cause significant market movements
- Trading Opportunities: Identify potential trading opportunities based on economic releases
- Risk Management: Prepare for market volatility around key economic announcements
- Advance Notifications: Receive alerts before important economic data releases
- Cross-Market Analysis: Understand how economic data affects various asset classes
Economic Event Subscription
Basic Subscription
To subscribe to specific economic events, send the following message:
{
"message_type": "subscribe",
"params": {
"subscribe_type": "event",
"topics": [
"US:INFLATION_CPI_NSA:REAL_TIME",
"US:UNEMPLOYMENT_RATE:REAL_TIME"
]
}
}
Wildcard Subscription
To subscribe to all economic events for specific countries:
{
"message_type": "subscribe",
"params": {
"subscribe_type": "event",
"topics": ["US:*", "UK:*"]
}
}
Topic Format Specification
Each topic in the economic events subscription follows this format:
COUNTRY:EVENT_CODE:PREVIEW_INTERVAL
Parameters Explanation
Parameter | Description | Examples |
---|---|---|
COUNTRY |
ISO country code where the economic event occurs | US , UK , EU , JP , CN ,GLOBAL |
EVENT_CODE |
Unique identifier for the economic indicator | Economic Event Codes |
PREVIEW_INTERVAL |
When to receive the notification relative to the event | REAL_TIME , 30DAY , 2WEEK , 1WEEK , 1DAY , 60M , 15M , 5M |
Available Event Codes
A comprehensive list of economic event codes is available in the Economic Event Codes documentation. Some of the most frequently used event codes include:
Event Code | Description | Typical Impact |
---|---|---|
INFLATION_CPI_NSA |
Consumer Price Index (Non-Seasonally Adjusted) | High |
UNEMPLOYMENT_RATE |
Unemployment Rate | High |
GDP_QOQ |
Gross Domestic Product (Quarter over Quarter) | High |
INTEREST_RATE |
Central Bank Interest Rate Decision | Very High |
RETAIL_SALES_MOM |
Retail Sales (Month over Month) | Medium |
PMI_MANUFACTURING |
Purchasing Managers’ Index - Manufacturing | Medium |
NONFARM_PAYROLLS |
Non-Farm Payrolls (US) | Very High |
Preview Intervals
The PREVIEW_INTERVAL
parameter allows you to receive notifications at different times relative to the economic event:
Interval | Description |
---|---|
REAL_TIME |
Receive data immediately when published (default) |
30DAY |
Receive notification 30 days before the event |
2WEEK |
Receive notification 2 weeks before the event |
1WEEK |
Receive notification 1 week before the event |
1DAY |
Receive notification 1 day before the event |
60M |
Receive notification 60 minutes before the event |
15M |
Receive notification 15 minutes before the event |
5M |
Receive notification 5 minutes before the event |
Managing Subscriptions
Checking Current Subscriptions
To query all active subscriptions for the current connection:
{
"message_type": "show_subscribe"
}
The response will include all your active subscriptions, including economic event subscriptions:
{
"message_type": "show_subscribe",
"status": "ok",
"code": 200,
"message": "success",
"reference": null,
"result": {
"event": [
"US:INFLATION_CPI_NSA:REAL_TIME",
"US:UNEMPLOYMENT_RATE:REAL_TIME"
]
}
}
Unsubscribing from Events
To unsubscribe from specific economic events:
{
"message_type": "unsubscribe",
"params": {
"subscribe_type": "event",
"topics": [
"US:INFLATION_CPI_NSA:REAL_TIME",
"US:UNEMPLOYMENT_RATE:REAL_TIME"
]
}
}
Economic Event Data Structure
When an economic event occurs or is scheduled, you will receive data with the following structure:
{
"message_type": "event",
"status": "ok",
"code": 200,
"message": "success",
"reference": null,
"result": [
{
"country_iso_code": "US",
"event_code": "BUSINESS_PMI_NON_MANUFACTURING_ISM",
"event_name": "ISM Non-Manufacturing PMI",
"event_driven_type": "time_driven",
"importance": 3,
"impact": "high",
"event_timestamp": "2024-08-05T13:00:00Z",
"actual_value": 51.4,
"previous_value": 48.8,
"forecast_value": 51.4,
"change": 2.6,
"change_percent": 0.0,
"period": "Jul",
"unit": "N/A",
"source_id": "460b29c68f3590c1a6500b719cf9b4fc41f16b09d3ebb2a6c337fe41c1a75040",
"preview_interval": "REAL_TIME"
}
]
}
Python Implementation Example
The following example demonstrates how to subscribe to economic events using the AiTrados Python client library:
import os
import signal
from aitrados_api.common_lib.common import logger
from aitrados_api import SubscribeEndpoint
from aitrados_api import WebSocketClient
def handle_msg(client: WebSocketClient, message):
# Generic message handler
pass
def event_handle_msg(client: WebSocketClient, data_list):
# Handler for economic event messages
for record in data_list:
symbol = f"{record.get('country_iso_code')}:{record.get('event_code')}:{record.get('preview_interval')}"
string = f"event:{symbol} --> {record.get('event_timestamp')}"
logger.info(string)
def show_subscribe_handle_msg(client: WebSocketClient, message):
# Handler for subscription status messages
logger.info(f"✅ Subscription status: {message}")
print("subscriptions", client.all_subscribed_topics)
def auth_handle_msg(client: WebSocketClient, message):
# Handler for authentication messages
if not client.authorized:
return
# Subscribe to economic events after successful authentication
client.subscribe_event("US:INFLATION_CPI_NSA:REAL_TIME", "US:UNEMPLOYMENT_RATE:REAL_TIME")
# Initialize WebSocket client
client = WebSocketClient(
secret_key=os.getenv("AITRADOS_SECRET_KEY", "YOUR_SECRET_KEY"),
is_reconnect=True,
handle_msg=handle_msg,
event_handle_msg=event_handle_msg, # Specific handler for economic events
show_subscribe_handle_msg=show_subscribe_handle_msg,
auth_handle_msg=auth_handle_msg,
endpoint=SubscribeEndpoint.DELAYED, # Use DELAYED or REALTIME
debug=False
)
def signal_handler(sig, frame):
client.close()
if __name__ == "__main__":
signal.signal(signal.SIGINT, signal_handler)
client.run(is_thread=False)
# If running in a thread, you might need a loop:
# while True:
# sleep(2)
Subscription Strategies
High-Impact Events Only
To focus on market-moving events and reduce noise:
# Subscribe only to high-impact economic indicators
client.subscribe_event(
"US:NONFARM_PAYROLLS:REAL_TIME",
"US:INFLATION_CPI_NSA:REAL_TIME",
"US:INTEREST_RATE:REAL_TIME",
"US:GDP_QOQ:REAL_TIME"
)
Multi-Region Monitoring
To monitor key indicators across multiple regions:
# Monitor inflation across major economies
client.subscribe_event(
"US:INFLATION_CPI_NSA:REAL_TIME",
"EU:INFLATION_CPI_YOY:REAL_TIME",
"UK:INFLATION_CPI_YOY:REAL_TIME",
"JP:INFLATION_CPI_YOY:REAL_TIME"
)
Advance Notifications
To receive advance notifications before important releases:
# Get notifications at different intervals before NFP release
client.subscribe_event(
"US:NONFARM_PAYROLLS:1DAY", # 1 day before
"US:NONFARM_PAYROLLS:60M", # 60 minutes before
"US:NONFARM_PAYROLLS:15M", # 15 minutes before
"US:NONFARM_PAYROLLS:REAL_TIME" # Actual release
)
Best Practices
-
Strategic Subscriptions: Focus on economic events relevant to your trading strategy and asset classes.
-
Advance Planning: Use preview intervals to prepare for market volatility around major economic releases.
-
Complete Coverage: For critical indicators, consider subscribing to both advance notifications and real-time data.
-
Data Integration: Correlate economic data with price movements for comprehensive market analysis.
-
Automated Responses: Develop predefined responses to different economic scenarios based on deviation from forecasts.
-
Economic Calendar: Use economic event subscriptions to build a real-time economic calendar for your organization.