unified-data 0.3.4

Add your description here

unified-data

Unified Kline Data Interface

unified-data allows you to pull standardized kline (candlestick) data from various financial markets (Crypto, Stocks, Futures) through a single, unified interface. It handles the complexity of exchange-specific API differences, so you can focus on analysis.

Features

• Unified Interface: Single pull_kline function for all market types.
• Polars Integration: Returns high-performance polars.DataFrame objects.
• Smart Routing: Automatically routes requests to the appropriate data source (ccxt, yfinance, akshare) based on market type.
• Standardized Inputs: Use a common ticker format regardless of the underlying exchange.
• AI-Ready: Designed with clear typing and schemas to be easily used by AI Agents and LLMs.

Installation

pip install unified-data

Quick Start

import polars as pl
from unified_data import pull_kline, MarketType

# 1. Pull Crypto Data (BTC/USDT)
df_crypto = pull_kline(
    ticker="BTC_USDT",
    market_type=MarketType.CRYPTO,
    period="1d",
    limit=200
)
print(df_crypto.head())

# 2. Pull US Stock Data (Apple)
df_stock = pull_kline(
    ticker="AAPL",
    market_type=MarketType.STOCK,
    period="1h",
    limit=50
)
print(df_stock.head())

Standardized Tickers

unified-data uses a strictly standardized format for input tickers. The library handles translation to exchange-specific symbols internally.

Market Type	Format Pattern	Example	Description
Crypto	[SYMBOL]_[QUOTE]	BTC_USDT	Standard pair with underscore separator.
Stocks	[SYMBOL]	AAPL	Common ticker symbol.
Futures (Front)	[SYMBOL]=F	GC=F	Continuous/Front month contract.
Futures (Specific)	[SYMBOL][MONTH][YY]	GCU26	Specific expiry (e.g., Gold September 2026).

Futures Month Codes

Code	Month	Code	Month	Code	Month
F	Jan	K	May	U	Sep
G	Feb	M	Jun	V	Oct
H	Mar	N	Jul	X	Nov
J	Apr	Q	Aug	Z	Dec

Supported Timeframes

The period argument supports a standardized set of intervals across all adapters:

Period	Description
1d	Daily
1w	Weekly
1M	Monthly (Note the capital M to distinguish from minute)

You can import these constants for type safety:

from unified_data import TimeFramePeriod

# Use standard constants
period = TimeFramePeriod.D1  # "1d"
period = TimeFramePeriod.M1  # "1M"

Note: While intraday periods like 1m, 5m, 1h are supported by some adapters (crypto/stocks), availability varies. The standard set above is guaranteed.

Usage Reference

pull_kline

The main entry point for the library.

def pull_kline(
    ticker: str, 
    market_type: str, 
    period: str, 
    start_date: datetime | str | None = None, 
    end_date: datetime | str | None = None, 
    limit: int = 200,
    exchange: str | None = None
) -> pl.DataFrame

Parameters:

• ticker (str): The asset symbol in the standardized format (e.g., BTC_USDT, AAPL).
• market_type (str): The type of market. Use unified_data.models.enums.MarketType constants:
  • "crypto"
  • "stock"
  • "futures"
• period (str): Timeframe interval (e.g., 1m, 1h, 1d).
• start_date (datetime | str, optional): Start time for data.
• end_date (datetime | str, optional): End time for data.
• limit (int): Number of candles to retrieve (default: 200).
• exchange (str, optional): Force a specific exchange backend (e.g., ccxt, yfinance, akshare).

Returns: A polars.DataFrame with the following columns:

• ts: Timestamp (Unix ms)
• open: Open price
• high: High price
• low: Low price
• close: Close price
• vol: Volume
• symbol: The ticker symbol
• exchange: The exchange/source name (e.g., ccxt, yfinance)

---

AI Agent Integration

This package is designed to be easily used by Large Language Models (LLMs) and AI Agents using tool calling (function calling).

Tool Definition

When providing this library as a tool to an AI, you can use the following definition:

{
  "name": "pull_kline",
  "description": "Retrieve historical candlestick (OHLCV) data for financial assets (Crypto, Stocks, Futures). Returns a Polars DataFrame.",
  "parameters": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "Standardized symbol. Crypto: 'BTC_USDT', Stock: 'AAPL', Futures: 'GC=F'."
      },
      "market_type": {
        "type": "string",
        "enum": ["crypto", "stock", "futures"],
        "description": "Class of the asset."
      },
      "period": {
        "type": "string",
        "description": "Timeframe, e.g., '1h', '4h', '1d'."
      },
      "limit": {
        "type": "integer",
        "description": "Number of data points to retrieve."
      },
      "start_date": {
        "type": "string",
        "description": "ISO 8601 start date (optional)."
      }
    },
    "required": ["ticker", "market_type", "period"]
  }
}

System Prompt Recommendation

If you are instructing an AI to use this library, include the following in its system prompt:

You have access to the unified_data library. When asked for market data, ALWAYS use the pull_kline tool. Ensure you convert user requests into the standardized ticker format:

• Crypto pairs must use underscores: "Bitcoin to USDT" -> BTC_USDT
• Stocks use their symbol: "Apple" -> AAPL
• Futures use the Month Code standard: "Gold Dec 2025" -> GCZ25

Configuration

Supported Data Sources (Backends):

• Crypto: ccxt (Binance default)
• Stocks (US): yfinance
• Stocks (China): akshare
• Futures: yfinance / akshare

No API keys are required for the default public endpoints.