# aitrados-dataset-api
[](https://badge.fury.io/py/aitrados-api)
[](https://pypi.org/project/aitrados-api/)
[](https://opensource.org/licenses/MIT)
`aitrados-dataset-api` is more than a Python client; it is a powerful framework engineered for professional, AI-driven quantitative trading. We move beyond simple data fetching to solve the most complex and time-consuming data management challenges, allowing you to focus exclusively on strategy development and alpha generation.
Our core philosophy is to provide a seamless data engine that elevates your analysis from a single asset to a panoramic view of the entire market ecosystem. By integrating **Effortless Real-Time OHLC Chart Flows**, **Professional-Grade Multi-Symbol, Multi-Timeframe (MSMTF) Time Alignment**, and **AI-Powered Fusion Analysis** (combining K-line, news, and economic events), `aitrados-dataset-api` provides an unprecedented data foundation for sophisticated algorithmic trading.
**Github**: [https://github.com/aitrados/aitrados-api](https://github.com/aitrados/aitrados-api)
**EXAMPLES**: [https://github.com/aitrados/aitrados-api/tree/main/examples](https://github.com/aitrados/aitrados-api/tree/main/examples)
**DOCS**: [https://docs.aitrados.com/en/docs/api/quickstart/](https://docs.aitrados.com/en/docs/api/quickstart/)
**OFFLINE DOCS**: [https://github.com/aitrados/aitrados-api/tree/main/docs/api](https://github.com/aitrados/aitrados-api/tree/main/docs/api)
**FREE GAIN SECRET KEY**:[https://www.aitrados.com/](https://www.aitrados.com/)
## Core Advantages: Redefining Your Trading Dataflow
In quantitative trading, data is the source of alpha, but data management is often the biggest obstacle. `aitrados-dataset-api` liberates you from the complex "data plumbing."
* 🚀 **Effortless Real-Time OHLC Chart Flow**
* **The Pain Point**: Maintaining a live, rolling, fixed-length OHLC chart (e.g., the latest 150 candles) is notoriously difficult. Developers wrestle with initial history loading, real-time WebSocket updates, managing the unclosed "live" candle, and handling the precise rollover logic—a process that is complex and highly prone to errors.
* **The AiTrados Solution**: Our `LatestOhlcChartFlowManager` completely automates this entire workflow. With a single command, you get a perfectly aligned, always-current rolling chart data stream. We handle all the underlying complexity, so you can immediately focus on strategy implementation.
* 🌐 **Professional-Grade Multi-Symbol, Multi-Timeframe (MSMTF) Alignment**
* **The Pain Point**: Advanced strategies like pairs trading, arbitrage, and hedging require analyzing multiple symbols across different timeframes simultaneously. Manually aligning OHLC data from these disparate sources to ensure perfect timestamp synchronization is a monumental challenge.
* **The AiTrados Solution**: Our MSMTF framework `LatestOhlcMultiTimeframeManager` is a philosophy built for professional trading. It doesn't just provide multi-symbol data; its core strength lies in ensuring **precise time alignment** across all datasets. This empowers you to build sophisticated cross-market models, identify leader-follower relationships, and capture fleeting arbitrage opportunities with confidence.
* 🧩 **Designed for AI-Powered Fusion Analysis**
* Seamlessly integrate naked K-line technical analysis, real-time news events, and macroeconomic data into a single, unified data source. This provides the clean, synchronized, and rich input required to train complex AI models and execute time-sensitive trading decisions.
## Feature Overview
* **Advanced Real-Time Capabilities via WebSocket:**
* Fully managed, real-time rolling OHLC chart flows.
* Time-aligned data streams for multiple symbols and timeframes.
* Real-time news feeds and economic event alerts.
* Economic event support preview_interval and realtime alerts.for example alert before 5/10/30/60 minutes 1 DAY,2 WEEKS.
* **Comprehensive Historical Data via HTTP API:**
* OHLCV data with extensive multi-timeframe support.
* Reference data for symbols (stocks, crypto, forex,option,futures , etc.).
* Options chains and expiration dates.
* Corporate actions (splits, dividends).
* Macroeconomic calendars and event history.
* Global trading holiday schedules.
* Vast archives of historical financial news.
## trade middleware (LOCAL RPC & SUB/PUB )
We introduce zeromq middleware, you can completely split complex strategies into modules and programs. Through the middleware to implement complex communication data calls
[SEE DOCS](https://docs.aitrados.com/en/docs/api/trade_middleware/overview/)
## Installation
You can install this library using pip:
```bash
pip install aitrados-api
```
## Usage
### HTTP API - Get Historical Data
You need to use your API key to initialize the `DatasetClient`.
```python
import asyncio
import os
from aitrados_api import DatasetClient
from aitrados_api import ClientConfig, RateLimitConfig
from aitrados_api import SchemaAsset, IntervalName
async def run_async_example():
config = ClientConfig(
secret_key=os.getenv("AITRADOS_SECRET_KEY", "YOUR_SECRET_KEY"),
timeout=30,
max_retries=1000,
rate_limit=RateLimitConfig(
daily_limit=100000,
requests_per_second=2,
requests_per_minute=30
),
debug=True
)
client = DatasetClient(config=config)
params = {
"schema_asset": SchemaAsset.CRYPTO,
"country_symbol": "GLOBAL:BTCUSD",
"interval": IntervalName.M60,
"from_date": "2025-07-18T00:00:00+00:00",
"to_date": "2025-10-05T23:59:59+00:00",
"format": "json",
"limit": 30
}
# ***************************************OHLC DATA***************************#
'''
# Get historical OHLC data asynchronously
async for ohlc in client.ohlc.a_ohlcs(**params):
print(ohlc)
'''
# Get latest OHLC data asynchronously. use for real-time data
ohlc_latest = await client.ohlc.a_ohlcs_latest(**params)
print(ohlc_latest)
# ***************************************symbol reference***************************#
'''
# Get symbol reference asynchronously
stock_reference = await client.reference.a_reference(schema_asset=SchemaAsset.STOCK, country_symbol="US:TSLA")
crypto_reference = await client.reference.a_reference(schema_asset=SchemaAsset.CRYPTO, country_symbol="GLOBAL:BTCUSD")
forex_reference = await client.reference.a_reference(schema_asset=SchemaAsset.FOREX, country_symbol="GLOBAL:EURUSD")
'''
# ***************************************OPTIONS INFORMATION***************************#
'''
# Get options information asynchronously
async for options in client.reference.a_search_option(schema_asset=SchemaAsset.STOCK, country_symbol="US:spy",
option_type="call", moneyness="in_the_money",
ref_asset_price=450.50, limit=100):
print(options)
'''
'''
# Get options expiration date list asynchronously
expiration_date_list = await client.reference.a_options_expiration_date_list(schema_asset=SchemaAsset.STOCK,
country_symbol="US:SPY")
print(expiration_date_list)
'''
# ***************************************stock corporate action***************************#
'''
# Get stock corporate action list asynchronously
async for actions in client.reference.a_stock_corporate_action_list(country_symbol="US:TSLA",
from_date="2020-08-18",
action_type="split", limit=100):
print(actions)
'''
# ***************************************economic event***************************#
'''
# Get economic event codes of all countries asynchronously
event_codes = await client.economic.a_event_codes(country_iso_code="US")
print(event_codes)
'''
'''
# Get economic event list asynchronously
async for event_list in client.economic.a_event_list(country_iso_code="US", limit=5):
print(event_list)
'''
'''
# Get economic event by date asynchronously
event = await client.economic.a_event()
print(event)
'''
'''
# Get economic latest event list asynchronously
latest_events = await client.economic.a_latest_events(country_iso_code="us",date_type="upcoming")
print(latest_events)
'''
# ***************************************holiday***************************#
'''
# Get holiday list asynchronously
async for holiday_list in client.holiday.a_holiday_list(full_symbol="stock:US:*", from_date="2023-01-01",
to_date="2026-12-31", limit=100):
print(holiday_list)
'''
'''
# Get holiday codes of all countries asynchronously
holiday_codes = await client.holiday.a_holiday_codes()
print(holiday_codes)
'''
# ***************************************news***************************#
'''
# Get news list asynchronously
async for news_list in client.news.a_news_list(full_symbol="stock:US:TSLA", from_date="2025-07-01",
to_date="2025-12-31", limit=100):
print(news_list)
'''
'''
# Get latest news asynchronously. use for real-time data
news_latest = await client.news.a_news_latest(full_symbol="stock:US:TSLA", limit=5)
print(news_latest)
'''
client.close()
if __name__ == "__main__":
asyncio.run(run_async_example())
```
### WebSocket API - Subscribe to Real-time Data
With the `WebSocketClient`, you can subscribe to various real-time data streams.
```python
import json
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):
# print("Received message:", message)
pass
def news_handle_msg(client: WebSocketClient, data_list):
for record in data_list:
symbol = f"{record.get('asset_schema')}:{record.get('country_iso_code')}:{record.get('underlying_name')}"
string = f"news:{symbol} --> {record.get('published_date')} --> {record.get('title')}"
logger.info(string)
def event_handle_msg(client: WebSocketClient, data_list):
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 ohlc_handle_msg(client: WebSocketClient, data_list):
count = len(data_list)
first_asset_schema = data_list[0].get('asset_schema', 'N/A')
logger.info(
f"Real-time data: Received 'ohlc_data' containing {count} records (asset type: {first_asset_schema}) {data_list[0].get('time_key_timestamp', 'N/A')}")
def show_subscribe_handle_msg(client: WebSocketClient, message):
#logger.info(f"✅ Subscription status: {message}")
print("subscriptions",json.dumps(client.all_subscribed_topics))
def auth_handle_msg(client: WebSocketClient, message):
if not client.authorized:
return
client.subscribe_news("STOCK:US:*", "CRYPTO:GLOBAL:*", "FOREX:GLOBAL:*")
client.subscribe_ohlc_1m("STOCK:US:*", "CRYPTO:GLOBAL:*", "FOREX:GLOBAL:*")
client.subscribe_event('US:*', 'CN:*', 'UK:*', 'EU:*', 'AU:*', 'CA:*', 'DE:*', 'FR:*', 'JP:*', 'CH:*')
client = WebSocketClient(
secret_key=os.getenv("AITRADOS_SECRET_KEY","YOUR_SECRET_KEY"),
is_reconnect=True,
handle_msg=handle_msg,
news_handle_msg=news_handle_msg,
event_handle_msg=event_handle_msg,
ohlc_handle_msg=ohlc_handle_msg,
show_subscribe_handle_msg=show_subscribe_handle_msg,
auth_handle_msg=auth_handle_msg,
endpoint=SubscribeEndpoint.DELAYED,
debug=True
)
def signal_handler(sig, frame):
client.close()
if __name__ == "__main__":
signal.signal(signal.SIGINT, signal_handler)
client.run(is_thread=False)
'''
while True:
sleep(2)
'''
```
### LATEST REAL-TIME OHLC PRICE CHART FLOW STREAMS EXAMPLE
With the `WebSocketClient` and `DatasetClient`, you can get the latest ohlc chart flow streams.
```python
import json
import os
import signal
from time import sleep
import pandas as pd
import polars as pl
from aitrados_api import SubscribeEndpoint, ChartDataFormat
from aitrados_api import ClientConfig
from aitrados_api import DatasetClient
from aitrados_api import WebSocketClient
from aitrados_api import LatestOhlcChartFlowManager
from aitrados_api.common_lib.contant import IntervalName
api_config = ClientConfig(
secret_key=os.getenv("AITRADOS_SECRET_KEY", "YOUR_SECRET_KEY"),
debug=True
)
api_client = DatasetClient(config=api_config)
def show_subscribe_handle_msg(client: WebSocketClient, message):
print("subscriptions", json.dumps(client.all_subscribed_topics))
ws_client = WebSocketClient(
secret_key=os.getenv("AITRADOS_SECRET_KEY", "YOUR_SECRET_KEY"),
show_subscribe_handle_msg=show_subscribe_handle_msg,
endpoint=SubscribeEndpoint.REALTIME,
debug=True
)
def latest_ohlc_chart_flow_callback(data: str | list | dict | pd.DataFrame | pl.DataFrame):
if isinstance(data, list):
print("Received data:", json.dumps(data[-2:], indent=2))
else:
print("Received data:", data)
latest_ohlc_chart_flow_manager = LatestOhlcChartFlowManager(
latest_ohlc_chart_flow_callback=latest_ohlc_chart_flow_callback,
api_client=api_client,
ws_client=ws_client,
limit=150,
data_format=ChartDataFormat.DICT
)
is_close = False
def signal_handler(sig, frame):
ws_client.close()
global is_close
is_close = True
if __name__ == "__main__":
signal.signal(signal.SIGINT, signal_handler)
ws_client.run(is_thread=True)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M1)
'''
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M3)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M5)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M10)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M15)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M60)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M120)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.M240)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.WEEK)
latest_ohlc_chart_flow_manager.add_item("crypto:global:btcusd", IntervalName.MON)
'''
while not is_close:
sleep(2)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M1)
'''
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M3)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M5)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M10)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M15)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M60)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M120)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.M240)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.WEEK)
latest_ohlc_chart_flow_manager.remove_item("crypto:global:btcusd", IntervalName.MON)
'''
```
### Example: Real-Time OHLC Price Chart Streams with MTF (Multiple-Timeframes) and MSMTF (Multiple-Symbols-Multiple-Timeframes) Alignment
Thanks to the unique time-series architecture used by AiTrados, we offer a distinct advantage in the precise temporal alignment of market data. This allows for the seamless implementation of both Multi-Timeframe (MTF) and Multi-Symbol, Multi-Timeframe (MSMTF) analysis.
Our framework fully supports the following configurations:
* **Single Symbol, Single Timeframe**: The classic, focused view.
* **Single Symbol, Multiple Timeframes (MTF)**: Analyze a single asset's trend and entry points across different time horizons.
* **Multiple Symbols, Multiple Timeframes (MSMTF)**: Conduct sophisticated cross-market analysis, such as pairs trading or arbitrage, with perfectly synchronized data.
```python
import datetime
import json
import os
import signal
from time import sleep
from typing import Dict, List
import pandas as pd
import polars as pl
from loguru import logger
from aitrados_api import SubscribeEndpoint, ChartDataFormat
from aitrados_api import ClientConfig
from aitrados_api import DatasetClient
from aitrados_api import WebSocketClient
from aitrados_api import LatestOhlcMultiTimeframeManager
from aitrados_api import IntervalName
api_config = ClientConfig(
secret_key=os.getenv("AITRADOS_SECRET_KEY", "YOUR_SECRET_KEY"),
debug=True
)
api_client = DatasetClient(config=api_config)
def show_subscribe_handle_msg(client: WebSocketClient, message):
print("subscriptions", json.dumps(client.all_subscribed_topics))
ws_client = WebSocketClient(
secret_key=os.getenv("AITRADOS_SECRET_KEY", "YOUR_SECRET_KEY"),
is_reconnect=True,
show_subscribe_handle_msg=show_subscribe_handle_msg,
endpoint=SubscribeEndpoint.REALTIME,
debug=True
)
def multi_timeframe_callback(name, data: Dict[str, List[str | list | pl.DataFrame | pd.DataFrame]], **kwargs):
print(f"==================Received data:{name}========================{datetime.datetime.now()}")
for full_symbol, tf_data_list in data.items():
for tf_data in tf_data_list:
if isinstance(tf_data, list):
print(json.dumps(tf_data[-2:], indent=2), "===len===", len(tf_data))
else:
print(tf_data)
latest_ohlc_multi_timeframe_manager = LatestOhlcMultiTimeframeManager(
api_client=api_client,
ws_client=ws_client,
multi_timeframe_callback=multi_timeframe_callback,
limit=150, # data length limit
works=10,
data_format=ChartDataFormat.DICT # multi_timeframe_callback return data format
)
is_close = False
def signal_handler(sig, frame):
ws_client.close()
global is_close
is_close = True
if __name__ == "__main__":
signal.signal(signal.SIGINT, signal_handler)
ws_client.run(is_thread=True)
# Add single symbol with single timeframe
latest_ohlc_multi_timeframe_manager.add_item(
item_data={
"CRYPTO:GLOBAL:BTCUSD": [IntervalName.M60],
},
name="single_timeframe"
)
# Add single symbol with multiple timeframes
latest_ohlc_multi_timeframe_manager.add_item(
item_data={
"CRYPTO:GLOBAL:BTCUSD": [IntervalName.M60, IntervalName.DAY],
},
name="multi_timeframe"
)
# Add multiple symbols with multiple timeframes
latest_ohlc_multi_timeframe_manager.add_item(
item_data={
"CRYPTO:GLOBAL:BTCUSD": [IntervalName.M15, IntervalName.M60, IntervalName.DAY],
"CRYPTO:GLOBAL:ETHUSD": [IntervalName.M15, IntervalName.M60, IntervalName.DAY]
},
name="multi_symbol_multi_timeframe"
)
# Add multiple stocks with multiple timeframes
latest_ohlc_multi_timeframe_manager.add_item(
item_data={
"stock:us:tsla": [IntervalName.M5, IntervalName.M60, IntervalName.DAY],
"stock:us:spy": [IntervalName.M5, IntervalName.M60, IntervalName.WEEK],
},
name="stock_multi_timeframe"
)
while not is_close:
sleep(2)
# Remove item example
# latest_ohlc_multi_timeframe_manager.remove_item(name="multi_symbol_multi_timeframe")
# latest_ohlc_multi_timeframe_manager.remove_item(name="multi_timeframe")
# latest_ohlc_multi_timeframe_manager.remove_item(name="single_timeframe")
# latest_ohlc_multi_timeframe_manager.remove_item(name="stock_multi_timeframe")
logger.info("Exited")
```
## Authorization
This project requires a `Secret Key` provided by the Aitrados platform (for WebSocket API). Please visit [www.aitrados.com](https://www.aitrados.com/) to obtain your key(Currently free).
In the code examples, be sure to replace `YOUR_SECRET_KEY` with your own valid key.
## Contributing
We welcome contributions from the community! If you have any suggestions for improvements or find bugs, please feel free to participate in the following ways:
* **Submit an Issue**: Report problems you encounter or suggest new features.
* **Create a Pull Request**: If you've fixed a bug or implemented a new feature, we welcome your PR.
## License
This project is licensed under the [MIT](LICENSE) License.
Raw data
{
"_id": null,
"home_page": null,
"name": "aitrados-api",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "AI, api, data, finance streaming, financial, market-data, ohlc, ohlcv, quantitative, real-time, streaming ohlc, trading, websockes ohlc, ws ohlc",
"author": null,
"author_email": "Alexander <support@aitrados.com>",
"download_url": "https://files.pythonhosted.org/packages/80/60/2e7478d6cb9760dba1ef23afcf9b12a50ffb69a60f73febb0dc6e169edbf/aitrados_api-0.1.91.tar.gz",
"platform": null,
"description": "# aitrados-dataset-api\n[](https://badge.fury.io/py/aitrados-api)\n[](https://pypi.org/project/aitrados-api/)\n[](https://opensource.org/licenses/MIT)\n\n`aitrados-dataset-api` is more than a Python client; it is a powerful framework engineered for professional, AI-driven quantitative trading. We move beyond simple data fetching to solve the most complex and time-consuming data management challenges, allowing you to focus exclusively on strategy development and alpha generation.\n\nOur core philosophy is to provide a seamless data engine that elevates your analysis from a single asset to a panoramic view of the entire market ecosystem. By integrating **Effortless Real-Time OHLC Chart Flows**, **Professional-Grade Multi-Symbol, Multi-Timeframe (MSMTF) Time Alignment**, and **AI-Powered Fusion Analysis** (combining K-line, news, and economic events), `aitrados-dataset-api` provides an unprecedented data foundation for sophisticated algorithmic trading.\n\n**Github**: [https://github.com/aitrados/aitrados-api](https://github.com/aitrados/aitrados-api)\n\n**EXAMPLES**: [https://github.com/aitrados/aitrados-api/tree/main/examples](https://github.com/aitrados/aitrados-api/tree/main/examples)\n\n**DOCS**: [https://docs.aitrados.com/en/docs/api/quickstart/](https://docs.aitrados.com/en/docs/api/quickstart/) \n\n**OFFLINE DOCS**: [https://github.com/aitrados/aitrados-api/tree/main/docs/api](https://github.com/aitrados/aitrados-api/tree/main/docs/api) \n\n**FREE GAIN SECRET KEY**:[https://www.aitrados.com/](https://www.aitrados.com/) \n\n\n## Core Advantages: Redefining Your Trading Dataflow\n\nIn quantitative trading, data is the source of alpha, but data management is often the biggest obstacle. `aitrados-dataset-api` liberates you from the complex \"data plumbing.\"\n\n* \ud83d\ude80 **Effortless Real-Time OHLC Chart Flow**\n * **The Pain Point**: Maintaining a live, rolling, fixed-length OHLC chart (e.g., the latest 150 candles) is notoriously difficult. Developers wrestle with initial history loading, real-time WebSocket updates, managing the unclosed \"live\" candle, and handling the precise rollover logic\u2014a process that is complex and highly prone to errors.\n * **The AiTrados Solution**: Our `LatestOhlcChartFlowManager` completely automates this entire workflow. With a single command, you get a perfectly aligned, always-current rolling chart data stream. We handle all the underlying complexity, so you can immediately focus on strategy implementation.\n\n* \ud83c\udf10 **Professional-Grade Multi-Symbol, Multi-Timeframe (MSMTF) Alignment**\n * **The Pain Point**: Advanced strategies like pairs trading, arbitrage, and hedging require analyzing multiple symbols across different timeframes simultaneously. Manually aligning OHLC data from these disparate sources to ensure perfect timestamp synchronization is a monumental challenge.\n * **The AiTrados Solution**: Our MSMTF framework `LatestOhlcMultiTimeframeManager` is a philosophy built for professional trading. It doesn't just provide multi-symbol data; its core strength lies in ensuring **precise time alignment** across all datasets. This empowers you to build sophisticated cross-market models, identify leader-follower relationships, and capture fleeting arbitrage opportunities with confidence.\n\n* \ud83e\udde9 **Designed for AI-Powered Fusion Analysis**\n * Seamlessly integrate naked K-line technical analysis, real-time news events, and macroeconomic data into a single, unified data source. This provides the clean, synchronized, and rich input required to train complex AI models and execute time-sensitive trading decisions.\n\n## Feature Overview\n\n* **Advanced Real-Time Capabilities via WebSocket:**\n * Fully managed, real-time rolling OHLC chart flows.\n * Time-aligned data streams for multiple symbols and timeframes.\n * Real-time news feeds and economic event alerts.\n * Economic event support preview_interval and realtime alerts.for example alert before 5/10/30/60 minutes 1 DAY,2 WEEKS.\n\n* **Comprehensive Historical Data via HTTP API:**\n * OHLCV data with extensive multi-timeframe support.\n * Reference data for symbols (stocks, crypto, forex,option,futures , etc.).\n * Options chains and expiration dates.\n * Corporate actions (splits, dividends).\n * Macroeconomic calendars and event history.\n * Global trading holiday schedules.\n * Vast archives of historical financial news.\n\n\n## trade middleware (LOCAL RPC & SUB/PUB )\n\nWe introduce zeromq middleware, you can completely split complex strategies into modules and programs. Through the middleware to implement complex communication data calls\n[SEE DOCS](https://docs.aitrados.com/en/docs/api/trade_middleware/overview/) \n\n## Installation\n\nYou can install this library using pip:\n```bash\npip install aitrados-api\n```\n\n## Usage\n\n### HTTP API - Get Historical Data\n\nYou need to use your API key to initialize the `DatasetClient`.\n\n```python\nimport asyncio\nimport os\n\nfrom aitrados_api import DatasetClient\nfrom aitrados_api import ClientConfig, RateLimitConfig\nfrom aitrados_api import SchemaAsset, IntervalName\n\n\nasync def run_async_example():\n config = ClientConfig(\n secret_key=os.getenv(\"AITRADOS_SECRET_KEY\", \"YOUR_SECRET_KEY\"),\n timeout=30,\n max_retries=1000,\n rate_limit=RateLimitConfig(\n daily_limit=100000,\n requests_per_second=2,\n requests_per_minute=30\n ),\n debug=True\n )\n\n client = DatasetClient(config=config)\n params = {\n \"schema_asset\": SchemaAsset.CRYPTO,\n \"country_symbol\": \"GLOBAL:BTCUSD\",\n \"interval\": IntervalName.M60,\n \"from_date\": \"2025-07-18T00:00:00+00:00\",\n \"to_date\": \"2025-10-05T23:59:59+00:00\",\n \"format\": \"json\",\n \"limit\": 30\n }\n # ***************************************OHLC DATA***************************#\n '''\n # Get historical OHLC data asynchronously\n async for ohlc in client.ohlc.a_ohlcs(**params):\n print(ohlc)\n '''\n\n # Get latest OHLC data asynchronously. use for real-time data\n ohlc_latest = await client.ohlc.a_ohlcs_latest(**params)\n print(ohlc_latest)\n\n # ***************************************symbol reference***************************#\n '''\n # Get symbol reference asynchronously\n stock_reference = await client.reference.a_reference(schema_asset=SchemaAsset.STOCK, country_symbol=\"US:TSLA\")\n crypto_reference = await client.reference.a_reference(schema_asset=SchemaAsset.CRYPTO, country_symbol=\"GLOBAL:BTCUSD\")\n forex_reference = await client.reference.a_reference(schema_asset=SchemaAsset.FOREX, country_symbol=\"GLOBAL:EURUSD\")\n '''\n # ***************************************OPTIONS INFORMATION***************************#\n '''\n # Get options information asynchronously\n async for options in client.reference.a_search_option(schema_asset=SchemaAsset.STOCK, country_symbol=\"US:spy\",\n option_type=\"call\", moneyness=\"in_the_money\",\n ref_asset_price=450.50, limit=100):\n print(options)\n '''\n\n '''\n # Get options expiration date list asynchronously\n expiration_date_list = await client.reference.a_options_expiration_date_list(schema_asset=SchemaAsset.STOCK,\n country_symbol=\"US:SPY\")\n print(expiration_date_list)\n '''\n # ***************************************stock corporate action***************************#\n '''\n # Get stock corporate action list asynchronously\n async for actions in client.reference.a_stock_corporate_action_list(country_symbol=\"US:TSLA\",\n from_date=\"2020-08-18\",\n action_type=\"split\", limit=100):\n print(actions)\n '''\n # ***************************************economic event***************************#\n '''\n # Get economic event codes of all countries asynchronously\n event_codes = await client.economic.a_event_codes(country_iso_code=\"US\")\n print(event_codes)\n '''\n\n '''\n # Get economic event list asynchronously\n async for event_list in client.economic.a_event_list(country_iso_code=\"US\", limit=5):\n print(event_list)\n '''\n '''\n # Get economic event by date asynchronously\n event = await client.economic.a_event()\n print(event)\n '''\n\n '''\n # Get economic latest event list asynchronously\n latest_events = await client.economic.a_latest_events(country_iso_code=\"us\",date_type=\"upcoming\")\n print(latest_events)\n '''\n\n # ***************************************holiday***************************#\n '''\n # Get holiday list asynchronously\n async for holiday_list in client.holiday.a_holiday_list(full_symbol=\"stock:US:*\", from_date=\"2023-01-01\",\n to_date=\"2026-12-31\", limit=100):\n print(holiday_list)\n '''\n '''\n # Get holiday codes of all countries asynchronously\n holiday_codes = await client.holiday.a_holiday_codes()\n print(holiday_codes)\n '''\n # ***************************************news***************************#\n '''\n # Get news list asynchronously\n async for news_list in client.news.a_news_list(full_symbol=\"stock:US:TSLA\", from_date=\"2025-07-01\",\n to_date=\"2025-12-31\", limit=100):\n print(news_list)\n '''\n\n '''\n # Get latest news asynchronously. use for real-time data\n news_latest = await client.news.a_news_latest(full_symbol=\"stock:US:TSLA\", limit=5)\n print(news_latest)\n '''\n client.close()\nif __name__ == \"__main__\":\n asyncio.run(run_async_example())\n```\n\n\n### WebSocket API - Subscribe to Real-time Data\n\nWith the `WebSocketClient`, you can subscribe to various real-time data streams.\n\n```python\nimport json\nimport os\nimport signal\n\n\nfrom aitrados_api.common_lib.common import logger\n\nfrom aitrados_api import SubscribeEndpoint\nfrom aitrados_api import WebSocketClient\n\n\ndef handle_msg(client: WebSocketClient, message):\n # print(\"Received message:\", message)\n pass\n\n\ndef news_handle_msg(client: WebSocketClient, data_list):\n for record in data_list:\n symbol = f\"{record.get('asset_schema')}:{record.get('country_iso_code')}:{record.get('underlying_name')}\"\n string = f\"news:{symbol} --> {record.get('published_date')} --> {record.get('title')}\"\n logger.info(string)\n\n\ndef event_handle_msg(client: WebSocketClient, data_list):\n for record in data_list:\n symbol = f\"{record.get('country_iso_code')}:{record.get('event_code')}:{record.get('preview_interval')}\"\n string = f\"event:{symbol} --> {record.get('event_timestamp')}\"\n logger.info(string)\n\n\ndef ohlc_handle_msg(client: WebSocketClient, data_list):\n count = len(data_list)\n first_asset_schema = data_list[0].get('asset_schema', 'N/A')\n\n logger.info(\n f\"Real-time data: Received 'ohlc_data' containing {count} records (asset type: {first_asset_schema}) {data_list[0].get('time_key_timestamp', 'N/A')}\")\n\n\ndef show_subscribe_handle_msg(client: WebSocketClient, message):\n #logger.info(f\"\u2705 Subscription status: {message}\")\n\n print(\"subscriptions\",json.dumps(client.all_subscribed_topics))\n\n\ndef auth_handle_msg(client: WebSocketClient, message):\n if not client.authorized:\n return\n\n client.subscribe_news(\"STOCK:US:*\", \"CRYPTO:GLOBAL:*\", \"FOREX:GLOBAL:*\")\n client.subscribe_ohlc_1m(\"STOCK:US:*\", \"CRYPTO:GLOBAL:*\", \"FOREX:GLOBAL:*\")\n client.subscribe_event('US:*', 'CN:*', 'UK:*', 'EU:*', 'AU:*', 'CA:*', 'DE:*', 'FR:*', 'JP:*', 'CH:*')\n\n\nclient = WebSocketClient(\n secret_key=os.getenv(\"AITRADOS_SECRET_KEY\",\"YOUR_SECRET_KEY\"),\n is_reconnect=True,\n\n handle_msg=handle_msg,\n news_handle_msg=news_handle_msg,\n event_handle_msg=event_handle_msg,\n ohlc_handle_msg=ohlc_handle_msg,\n show_subscribe_handle_msg=show_subscribe_handle_msg,\n auth_handle_msg=auth_handle_msg,\n endpoint=SubscribeEndpoint.DELAYED,\n debug=True\n)\n\n\ndef signal_handler(sig, frame):\n client.close()\n\n\nif __name__ == \"__main__\":\n signal.signal(signal.SIGINT, signal_handler)\n client.run(is_thread=False)\n '''\n while True:\n sleep(2)\n '''\n\n\n```\n\n### LATEST REAL-TIME OHLC PRICE CHART FLOW STREAMS EXAMPLE\n\nWith the `WebSocketClient` and `DatasetClient`, you can get the latest ohlc chart flow streams.\n```python\nimport json\nimport os\nimport signal\nfrom time import sleep\n\nimport pandas as pd\nimport polars as pl\nfrom aitrados_api import SubscribeEndpoint, ChartDataFormat\nfrom aitrados_api import ClientConfig\nfrom aitrados_api import DatasetClient\nfrom aitrados_api import WebSocketClient\nfrom aitrados_api import LatestOhlcChartFlowManager\nfrom aitrados_api.common_lib.contant import IntervalName\n\napi_config = ClientConfig(\n secret_key=os.getenv(\"AITRADOS_SECRET_KEY\", \"YOUR_SECRET_KEY\"),\n debug=True\n)\napi_client = DatasetClient(config=api_config)\n\n\ndef show_subscribe_handle_msg(client: WebSocketClient, message):\n print(\"subscriptions\", json.dumps(client.all_subscribed_topics))\n\n\nws_client = WebSocketClient(\n secret_key=os.getenv(\"AITRADOS_SECRET_KEY\", \"YOUR_SECRET_KEY\"),\n show_subscribe_handle_msg=show_subscribe_handle_msg,\n endpoint=SubscribeEndpoint.REALTIME,\n debug=True\n)\n\n\ndef latest_ohlc_chart_flow_callback(data: str | list | dict | pd.DataFrame | pl.DataFrame):\n if isinstance(data, list):\n print(\"Received data:\", json.dumps(data[-2:], indent=2))\n else:\n print(\"Received data:\", data)\n\n\nlatest_ohlc_chart_flow_manager = LatestOhlcChartFlowManager(\n latest_ohlc_chart_flow_callback=latest_ohlc_chart_flow_callback,\n api_client=api_client,\n ws_client=ws_client,\n limit=150,\n data_format=ChartDataFormat.DICT\n)\n\nis_close = False\n\n\ndef signal_handler(sig, frame):\n ws_client.close()\n global is_close\n is_close = True\n\n\nif __name__ == \"__main__\":\n signal.signal(signal.SIGINT, signal_handler)\n ws_client.run(is_thread=True)\n\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M1)\n '''\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M3)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M5)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M10)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M15)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M60)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M120)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.M240)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.WEEK)\n latest_ohlc_chart_flow_manager.add_item(\"crypto:global:btcusd\", IntervalName.MON)\n '''\n while not is_close:\n sleep(2)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M1)\n '''\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M3)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M5)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M10)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M15)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M60)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M120)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.M240)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.WEEK)\n latest_ohlc_chart_flow_manager.remove_item(\"crypto:global:btcusd\", IntervalName.MON)\n '''\n\n```\n### Example: Real-Time OHLC Price Chart Streams with MTF (Multiple-Timeframes) and MSMTF (Multiple-Symbols-Multiple-Timeframes) Alignment\n\nThanks to the unique time-series architecture used by AiTrados, we offer a distinct advantage in the precise temporal alignment of market data. This allows for the seamless implementation of both Multi-Timeframe (MTF) and Multi-Symbol, Multi-Timeframe (MSMTF) analysis.\n\nOur framework fully supports the following configurations:\n\n* **Single Symbol, Single Timeframe**: The classic, focused view.\n* **Single Symbol, Multiple Timeframes (MTF)**: Analyze a single asset's trend and entry points across different time horizons.\n* **Multiple Symbols, Multiple Timeframes (MSMTF)**: Conduct sophisticated cross-market analysis, such as pairs trading or arbitrage, with perfectly synchronized data.\n```python\nimport datetime\nimport json\nimport os\nimport signal\nfrom time import sleep\nfrom typing import Dict, List\n\nimport pandas as pd\nimport polars as pl\nfrom loguru import logger\n\nfrom aitrados_api import SubscribeEndpoint, ChartDataFormat\nfrom aitrados_api import ClientConfig\nfrom aitrados_api import DatasetClient\nfrom aitrados_api import WebSocketClient\nfrom aitrados_api import LatestOhlcMultiTimeframeManager\nfrom aitrados_api import IntervalName\n\napi_config = ClientConfig(\n secret_key=os.getenv(\"AITRADOS_SECRET_KEY\", \"YOUR_SECRET_KEY\"),\n debug=True\n)\napi_client = DatasetClient(config=api_config)\n\n\ndef show_subscribe_handle_msg(client: WebSocketClient, message):\n print(\"subscriptions\", json.dumps(client.all_subscribed_topics))\n\n\nws_client = WebSocketClient(\n secret_key=os.getenv(\"AITRADOS_SECRET_KEY\", \"YOUR_SECRET_KEY\"),\n is_reconnect=True,\n show_subscribe_handle_msg=show_subscribe_handle_msg,\n endpoint=SubscribeEndpoint.REALTIME,\n debug=True\n)\n\n\ndef multi_timeframe_callback(name, data: Dict[str, List[str | list | pl.DataFrame | pd.DataFrame]], **kwargs):\n print(f\"==================Received data:{name}========================{datetime.datetime.now()}\")\n\n for full_symbol, tf_data_list in data.items():\n for tf_data in tf_data_list:\n if isinstance(tf_data, list):\n print(json.dumps(tf_data[-2:], indent=2), \"===len===\", len(tf_data))\n else:\n print(tf_data)\n\n\nlatest_ohlc_multi_timeframe_manager = LatestOhlcMultiTimeframeManager(\n api_client=api_client,\n ws_client=ws_client,\n multi_timeframe_callback=multi_timeframe_callback,\n limit=150, # data length limit\n works=10,\n data_format=ChartDataFormat.DICT # multi_timeframe_callback return data format\n)\n\nis_close = False\n\n\ndef signal_handler(sig, frame):\n ws_client.close()\n global is_close\n is_close = True\n\n\nif __name__ == \"__main__\":\n signal.signal(signal.SIGINT, signal_handler)\n ws_client.run(is_thread=True)\n\n # Add single symbol with single timeframe\n latest_ohlc_multi_timeframe_manager.add_item(\n item_data={\n \"CRYPTO:GLOBAL:BTCUSD\": [IntervalName.M60],\n },\n name=\"single_timeframe\"\n )\n\n # Add single symbol with multiple timeframes\n latest_ohlc_multi_timeframe_manager.add_item(\n item_data={\n \"CRYPTO:GLOBAL:BTCUSD\": [IntervalName.M60, IntervalName.DAY],\n },\n name=\"multi_timeframe\"\n )\n\n # Add multiple symbols with multiple timeframes\n latest_ohlc_multi_timeframe_manager.add_item(\n item_data={\n \"CRYPTO:GLOBAL:BTCUSD\": [IntervalName.M15, IntervalName.M60, IntervalName.DAY],\n \"CRYPTO:GLOBAL:ETHUSD\": [IntervalName.M15, IntervalName.M60, IntervalName.DAY]\n },\n name=\"multi_symbol_multi_timeframe\"\n )\n\n # Add multiple stocks with multiple timeframes\n\n latest_ohlc_multi_timeframe_manager.add_item(\n item_data={\n \"stock:us:tsla\": [IntervalName.M5, IntervalName.M60, IntervalName.DAY],\n \"stock:us:spy\": [IntervalName.M5, IntervalName.M60, IntervalName.WEEK],\n },\n name=\"stock_multi_timeframe\"\n )\n\n while not is_close:\n sleep(2)\n # Remove item example\n # latest_ohlc_multi_timeframe_manager.remove_item(name=\"multi_symbol_multi_timeframe\")\n # latest_ohlc_multi_timeframe_manager.remove_item(name=\"multi_timeframe\")\n # latest_ohlc_multi_timeframe_manager.remove_item(name=\"single_timeframe\")\n # latest_ohlc_multi_timeframe_manager.remove_item(name=\"stock_multi_timeframe\")\n logger.info(\"Exited\")\n\n```\n\n\n## Authorization\n\nThis project requires a `Secret Key` provided by the Aitrados platform (for WebSocket API). Please visit [www.aitrados.com](https://www.aitrados.com/) to obtain your key(Currently free).\n\nIn the code examples, be sure to replace `YOUR_SECRET_KEY` with your own valid key.\n\n## Contributing\n\nWe welcome contributions from the community! If you have any suggestions for improvements or find bugs, please feel free to participate in the following ways:\n* **Submit an Issue**: Report problems you encounter or suggest new features.\n* **Create a Pull Request**: If you've fixed a bug or implemented a new feature, we welcome your PR.\n\n## License\n\nThis project is licensed under the [MIT](LICENSE) License.",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A client library for the Aitrados data platform, providing access to real-time and historical financial market data via HTTP and WebSocket APIs.specifically designed for AI quantitative trading/training.Multiple Timeframes,Multiple-Symbols-Multiple-Timeframes Alignment",
"version": "0.1.91",
"project_urls": {
"Bug Tracker": "https://github.com/aitrados/aitrados-api/issues",
"Documentation": "https://github.com/aitrados/aitrados-api",
"Homepage": "https://github.com/aitrados/aitrados-api",
"Repository": "https://github.com/aitrados/aitrados-api"
},
"split_keywords": [
"ai",
" api",
" data",
" finance streaming",
" financial",
" market-data",
" ohlc",
" ohlcv",
" quantitative",
" real-time",
" streaming ohlc",
" trading",
" websockes ohlc",
" ws ohlc"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "13e62264d9e10041597b58b170a2d761e075a19a82f09eb6567299926a5b1ca3",
"md5": "02e8c0b1fb2cd63af2f5fe0d040af9bd",
"sha256": "40292aecc33dadf96d4b3eaefd8889ecec8314e6c3dcbf602eda3ef1f7f57648"
},
"downloads": -1,
"filename": "aitrados_api-0.1.91-py3-none-any.whl",
"has_sig": false,
"md5_digest": "02e8c0b1fb2cd63af2f5fe0d040af9bd",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 84742,
"upload_time": "2025-10-22T16:25:49",
"upload_time_iso_8601": "2025-10-22T16:25:49.059042Z",
"url": "https://files.pythonhosted.org/packages/13/e6/2264d9e10041597b58b170a2d761e075a19a82f09eb6567299926a5b1ca3/aitrados_api-0.1.91-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "80602e7478d6cb9760dba1ef23afcf9b12a50ffb69a60f73febb0dc6e169edbf",
"md5": "2257e0757738aa0f619ff4314718e0aa",
"sha256": "6719926382c8630066c995f985daf0a7c8d0ea765219ec34b10bc839041fef94"
},
"downloads": -1,
"filename": "aitrados_api-0.1.91.tar.gz",
"has_sig": false,
"md5_digest": "2257e0757738aa0f619ff4314718e0aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 121475,
"upload_time": "2025-10-22T16:25:51",
"upload_time_iso_8601": "2025-10-22T16:25:51.129796Z",
"url": "https://files.pythonhosted.org/packages/80/60/2e7478d6cb9760dba1ef23afcf9b12a50ffb69a60f73febb0dc6e169edbf/aitrados_api-0.1.91.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 16:25:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aitrados",
"github_project": "aitrados-api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "aitrados-api"
}
JSON
