Models Reference¶

Data models and types used throughout qldata.

Core Models¶

Bar¶

OHLCV candlestick data.

Bar `dataclass` ¶

Bar(
    timestamp: datetime,
    symbol: str,
    open: Decimal,
    high: Decimal,
    low: Decimal,
    close: Decimal,
    volume: Decimal,
)

OHLCV bar data model.

Represents aggregated price/volume data over a time period.

Attributes:

Name	Type	Description
`timestamp`	`datetime`	Bar start time
`symbol`	`str`	Symbol ticker
`open`	`Decimal`	Opening price
`high`	`Decimal`	Highest price
`low`	`Decimal`	Lowest price
`close`	`Decimal`	Closing price
`volume`	`Decimal`	Total volume

__post_init__ ¶

__post_init__() -> None

Validate OHLC consistency.

range ¶

range() -> Decimal

Calculate price range (high - low).

Returns:

Type	Description
`Decimal`	Price range

body ¶

body() -> Decimal

Calculate body size (abs(close - open)).

Returns:

Type	Description
`Decimal`	Absolute value of price change

is_bullish ¶

is_bullish() -> bool

Check if bar is bullish (close > open).

Returns:

Type	Description
`bool`	True if bullish, False otherwise

is_bearish ¶

is_bearish() -> bool

Check if bar is bearish (close < open).

Returns:

Type	Description
`bool`	True if bearish, False otherwise

DataFrame Columns:

Column	Type	Description
`open`	`float`	Opening price
`high`	`float`	Highest price
`low`	`float`	Lowest price
`close`	`float`	Closing price
`volume`	`float`	Trading volume

Index: timestamp (pandas DatetimeIndex, UTC)

Tick¶

Individual trade/tick data.

Tick `dataclass` ¶

Tick(
    timestamp: datetime,
    symbol: str,
    price: Decimal,
    volume: Decimal,
    bid: Decimal | None = None,
    ask: Decimal | None = None,
)

Tick (trade) data model.

Represents a single market trade.

Attributes:

Name	Type	Description
`timestamp`	`datetime`	Time of trade
`symbol`	`str`	Symbol ticker
`price`	`Decimal`	Trade price
`volume`	`Decimal`	Trade volume
`bid`	`Decimal \| None`	Best bid price (optional)
`ask`	`Decimal \| None`	Best ask price (optional)

__post_init__ ¶

__post_init__() -> None

Validate tick data.

spread ¶

spread() -> Decimal | None

Calculate bid-ask spread.

Returns:

Type	Description
`Decimal \| None`	Spread if both bid and ask are available, None otherwise

mid_price ¶

mid_price() -> Decimal | None

Calculate mid price (average of bid and ask).

Returns:

Type	Description
`Decimal \| None`	Mid price if both bid and ask are available, None otherwise

DataFrame Columns:

Column	Type	Description
`price`	`float`	Trade price
`quantity`	`float`	Trade quantity
`symbol`	`str`	Trading pair
`side`	`str`	`"buy"` or `"sell"`
`trade_id`	`int`	Unique trade identifier

Timeframe¶

Time intervals for bar data.

Timeframe ¶

Bases: Enum

Standard timeframe definitions for market data.

Supports common intervals from ticks to monthly bars.

from_string `classmethod` ¶

from_string(s: str) -> Timeframe

Parse string to Timeframe enum.

Parameters:

Name	Type	Description	Default
`s`	`str`	Timeframe string (e.g., "1h", "5m", "1d")	required

Returns:

Type	Description
`Timeframe`	Timeframe enum value

Raises:

Type	Description
`ValueError`	If timeframe string is not recognized

from_minutes `classmethod` ¶

from_minutes(minutes: int) -> Timeframe

Create timeframe from minutes.

Parameters:

Name	Type	Description	Default
`minutes`	`int`	Number of minutes (1, 2, 3, 5, 15, or 30)	required

Returns:

Type	Description
`Timeframe`	Timeframe enum

Raises:

Type	Description
`ValueError`	If minutes value not supported

Examples:

>>> Timeframe.from_minutes(5)
Timeframe.MIN_5

from_hours `classmethod` ¶

from_hours(hours: int) -> Timeframe

Create timeframe from hours.

Parameters:

Name	Type	Description	Default
`hours`	`int`	Number of hours (1, 2, 4, 6, 8, or 12)	required

Returns:

Type	Description
`Timeframe`	Timeframe enum

Raises:

Type	Description
`ValueError`	If hours value not supported

Examples:

>>> Timeframe.from_hours(4)
Timeframe.HOUR_4

from_days `classmethod` ¶

from_days(days: int) -> Timeframe

Create timeframe from days.

Parameters:

Name	Type	Description	Default
`days`	`int`	Number of days (1 or 3)	required

Returns:

Type	Description
`Timeframe`	Timeframe enum

Raises:

Type	Description
`ValueError`	If days value not supported

Examples:

>>> Timeframe.from_days(1)
Timeframe.DAY_1

minute `classmethod` ¶

minute() -> Timeframe

1-minute timeframe.

hour `classmethod` ¶

hour() -> Timeframe

1-hour timeframe.

day `classmethod` ¶

day() -> Timeframe

Daily timeframe.

week `classmethod` ¶

week() -> Timeframe

Weekly timeframe.

month `classmethod` ¶

month() -> Timeframe

Monthly timeframe.

to_pandas_rule ¶

to_pandas_rule() -> str | None

Convert to pandas resample rule.

Returns:

Type	Description
`str \| None`	Pandas resample rule string (e.g., "1h", "5T", "1D"), or None for tick data

to_seconds ¶

to_seconds() -> int

Convert timeframe to duration in seconds.

Returns:

Type	Description
`int`	Duration in seconds for this timeframe.
`int`	Returns 0 for TICK (no fixed interval).
`int`	Monthly (1M) returns approximate 30-day value (2592000 seconds).

Raises:

Type	Description
`ValueError`	If timeframe cannot be converted to seconds.

Examples:

>>> Timeframe.HOUR_1.to_seconds()
3600
>>> Timeframe.DAY_1.to_seconds()
86400

str ¶

__str__() -> str

String representation.

Available Timeframes:

Enum	String	Duration
`MINUTE_1`	`"1m"`	1 minute
`MINUTE_3`	`"3m"`	3 minutes
`MINUTE_5`	`"5m"`	5 minutes
`MINUTE_15`	`"15m"`	15 minutes
`MINUTE_30`	`"30m"`	30 minutes
`HOUR_1`	`"1h"`	1 hour
`HOUR_2`	`"2h"`	2 hours
`HOUR_4`	`"4h"`	4 hours
`HOUR_6`	`"6h"`	6 hours
`HOUR_8`	`"8h"`	8 hours
`HOUR_12`	`"12h"`	12 hours
`DAY_1`	`"1d"`	1 day
`DAY_3`	`"3d"`	3 days
`WEEK_1`	`"1w"`	1 week
`MONTH_1`	`"1M"`	1 month

from qldata import Timeframe

# Use enum
tf = Timeframe.HOUR_1

# Convert to string
print(tf.value)  # "1h"

# Parse from string
tf = Timeframe.from_string("4h")

Market Data Models¶

OrderBook¶

Order book snapshot.

OrderBook `dataclass` ¶

OrderBook(
    symbol: str,
    timestamp: datetime,
    bids: list[OrderBookLevel],
    asks: list[OrderBookLevel],
    sequence: int | None = None,
    source: str | None = None,
)

Order book snapshot with bids and asks.

Represents a point-in-time view of the order book.

Attributes:

Name	Type	Description
`symbol`	`str`	Trading pair symbol
`timestamp`	`datetime`	Time of snapshot
`bids`	`list[OrderBookLevel]`	List of bid levels (sorted descending by price)
`asks`	`list[OrderBookLevel]`	List of ask levels (sorted ascending by price)
`sequence`	`int \| None`	Sequence number for ordering updates (optional)
`source`	`str \| None`	Data source (e.g., "binance", "bybit")

best_bid `property` ¶

best_bid: OrderBookLevel | None

Get best (highest) bid price level.

best_ask `property` ¶

best_ask: OrderBookLevel | None

Get best (lowest) ask price level.

spread `property` ¶

spread: Decimal | None

Calculate bid-ask spread.

Returns:

Type	Description
`Decimal \| None`	Spread (ask - bid) if both sides exist, None otherwise

mid_price `property` ¶

mid_price: Decimal | None

Calculate mid price (average of best bid and ask).

Returns:

Type	Description
`Decimal \| None`	Mid price if both sides exist, None otherwise

__post_init__ ¶

__post_init__() -> None

Validate order book.

get_depth ¶

get_depth(side: str, depth: int) -> list[OrderBookLevel]

Get top N levels from one side of the book.

Parameters:

Name	Type	Description	Default
`side`	`str`	"bid" or "ask"	required
`depth`	`int`	Number of levels to return	required

Returns:

Type	Description
`list[OrderBookLevel]`	List of order book levels

total_volume ¶

total_volume(
    side: str, depth: int | None = None
) -> Decimal

Calculate total volume on one side of the book.

Parameters:

Name	Type	Description	Default
`side`	`str`	"bid" or "ask"	required
`depth`	`int \| None`	Optional depth limit (all levels if None)	`None`

Returns:

Type	Description
`Decimal`	Total volume

imbalance ¶

imbalance(depth: int | None = None) -> float

Calculate order book imbalance.

Imbalance = (bid_volume - ask_volume) / (bid_volume + ask_volume)

Parameters:

Name	Type	Description	Default
`depth`	`int \| None`	Optional depth limit	`None`

Returns:

Type	Description
`float`	Imbalance ratio (-1 to 1, positive = more bids)

Properties:

Property	Type	Description
`symbol`	`str`	Trading pair
`timestamp`	`datetime`	Snapshot time
`bids`	`list[OrderBookLevel]`	Buy orders (descending price)
`asks`	`list[OrderBookLevel]`	Sell orders (ascending price)

OrderBookLevel¶

Single price level in order book.

OrderBookLevel `dataclass` ¶

OrderBookLevel(price: Decimal, quantity: Decimal)

Single price level in an order book.

Attributes:

Name	Type	Description
`price`	`Decimal`	Price level
`quantity`	`Decimal`	Total quantity at this price level

__post_init__ ¶

__post_init__() -> None

Validate order book level.

Properties:

Property	Type	Description
`price`	`Decimal`	Price level
`quantity`	`Decimal`	Total quantity at level

FundingRate¶

Perpetual contract funding rate.

FundingRate `dataclass` ¶

FundingRate(
    symbol: str,
    timestamp: datetime,
    rate: Decimal,
    next_funding_time: datetime | None = None,
    mark_price: Decimal | None = None,
    source: str | None = None,
)

Funding rate for a perpetual contract.

Attributes:

Name	Type	Description
`symbol`	`str`	Trading pair symbol
`timestamp`	`datetime`	Time of funding rate
`rate`	`Decimal`	Funding rate (as decimal, e.g., 0.0001 = 0.01%)
`next_funding_time`	`datetime \| None`	When next funding will occur
`mark_price`	`Decimal \| None`	Mark price at funding time
`source`	`str \| None`	Data source

rate_bps `property` ¶

rate_bps: Decimal

Get funding rate in basis points (1 bps = 0.01%).

rate_percent `property` ¶

rate_percent: Decimal

Get funding rate as percentage.

__post_init__ ¶

__post_init__() -> None

Validate funding rate.

Properties:

Property	Type	Description
`symbol`	`str`	Trading pair
`rate`	`Decimal`	Funding rate
`timestamp`	`datetime`	Rate timestamp
`next_funding_time`	`datetime`	Next funding time

OpenInterest¶

Open interest data.

OpenInterest `dataclass` ¶

OpenInterest(
    symbol: str,
    timestamp: datetime,
    value: Decimal,
    value_usd: Decimal | None = None,
    unit: str = "contracts",
    source: str | None = None,
)

Open interest for a perpetual or futures contract.

Attributes:

Name	Type	Description
`symbol`	`str`	Trading pair symbol
`timestamp`	`datetime`	Time of measurement
`value`	`Decimal`	Open interest value
`value_usd`	`Decimal \| None`	Open interest in USD (if available)
`unit`	`str`	Unit of measurement ("contracts", "USD", "base_currency")
`source`	`str \| None`	Data source

__post_init__ ¶

__post_init__() -> None

Validate open interest.

Properties:

Property	Type	Description
`symbol`	`str`	Trading pair
`open_interest`	`Decimal`	Total open contracts
`timestamp`	`datetime`	Data timestamp

Symbol Models¶

SymbolInfo¶

Trading symbol metadata.

SymbolInfo `dataclass` ¶

SymbolInfo(
    symbol: str,
    base_asset: str,
    quote_asset: str,
    status: str = "TRADING",
    filters: SymbolFilters = SymbolFilters(),
    trading_hours: TradingHours = TradingHours(),
    contract_type: str | None = None,
    delivery_date: str | None = None,
    margin_asset: str | None = None,
    maker_fee: Decimal | None = None,
    taker_fee: Decimal | None = None,
    fee_tier: str | None = None,
    source: str | None = None,
    last_updated: str | None = None,
)

Complete symbol metadata and trading specifications.

Attributes:

Name	Type	Description
`symbol`	`str`	Trading pair symbol
`base_asset`	`str`	Base currency (e.g., "BTC" in "BTCUSDT")
`quote_asset`	`str`	Quote currency (e.g., "USDT" in "BTCUSDT")
`status`	`str`	Trading status ("TRADING", "HALT", "BREAK", etc.)
`filters`	`SymbolFilters`	Price/quantity filters
`trading_hours`	`TradingHours`	Market hours
`contract_type`	`str \| None`	For futures ("PERPETUAL", "CURRENT_QUARTER", etc.)
`delivery_date`	`str \| None`	For futures contracts
`margin_asset`	`str \| None`	Asset used for margin
`fee_tier`	`str \| None`	Fee tier or maker/taker fees
`source`	`str \| None`	Data source

is_spot `property` ¶

is_spot: bool

Check if this is a spot market.

is_perpetual `property` ¶

is_perpetual: bool

Check if this is a perpetual contract.

is_futures `property` ¶

is_futures: bool

Check if this is a dated futures contract.

is_active `property` ¶

is_active: bool

Check if symbol is actively trading.

validate_price ¶

validate_price(price: Decimal) -> bool

Check if price meets filter requirements.

Parameters:

Name	Type	Description	Default
`price`	`Decimal`	Price to validate	required

Returns:

Type	Description
`bool`	True if valid, False otherwise

validate_quantity ¶

validate_quantity(quantity: Decimal) -> bool

Check if quantity meets filter requirements.

Parameters:

Name	Type	Description	Default
`quantity`	`Decimal`	Quantity to validate	required

Returns:

Type	Description
`bool`	True if valid, False otherwise

validate_notional ¶

validate_notional(
    price: Decimal, quantity: Decimal
) -> bool

Check if notional value (price * quantity) meets requirements.

Parameters:

Name	Type	Description	Default
`price`	`Decimal`	Order price	required
`quantity`	`Decimal`	Order quantity	required

Returns:

Type	Description
`bool`	True if valid, False otherwise

Properties:

Property	Type	Description
`symbol`	`str`	Trading pair name
`base_asset`	`str`	Base currency (e.g., BTC)
`quote_asset`	`str`	Quote currency (e.g., USDT)
`status`	`str`	Trading status
`is_active`	`bool`	Currently tradeable
`is_spot`	`bool`	Spot market
`is_perpetual`	`bool`	Perpetual contract
`contract_type`	`str`	Contract type (perpetual, delivery)
`margin_asset`	`str`	Margin currency
`filters`	`TradingFilters`	Trading constraints

Methods:

Method	Returns	Description
`validate_price(price)`	`bool`	Check if price is valid
`validate_quantity(qty)`	`bool`	Check if quantity is valid

TradingFilters¶

Trading constraints for a symbol.

Property	Type	Description
`tick_size`	`Decimal`	Minimum price increment
`step_size`	`Decimal`	Minimum quantity increment
`min_quantity`	`Decimal`	Minimum order quantity
`max_quantity`	`Decimal`	Maximum order quantity
`min_notional`	`Decimal`	Minimum order value

Type Aliases¶

Common type aliases used in qldata:

from typing import Union, Dict
import pandas as pd

# Single or multi-symbol data
DataResult = Union[pd.DataFrame, Dict[str, pd.DataFrame]]

# Callback types
DataCallback = Callable[[pd.DataFrame], None]
ErrorCallback = Callable[[Exception], None]
CloseCallback = Callable[[], None]

Models Reference¶

Core Models¶

Bar¶

Bar dataclass ¶

__post_init__ ¶

range ¶

body ¶

is_bullish ¶

is_bearish ¶

Tick¶

Tick dataclass ¶

__post_init__ ¶

spread ¶

mid_price ¶

Timeframe¶

Timeframe ¶

from_string classmethod ¶

from_minutes classmethod ¶

from_hours classmethod ¶

from_days classmethod ¶

minute classmethod ¶

hour classmethod ¶

day classmethod ¶

week classmethod ¶

month classmethod ¶

to_pandas_rule ¶

to_seconds ¶

__str__ ¶

Market Data Models¶

OrderBook¶

OrderBook dataclass ¶

best_bid property ¶

best_ask property ¶

spread property ¶

mid_price property ¶

__post_init__ ¶

get_depth ¶

total_volume ¶

imbalance ¶

OrderBookLevel¶

OrderBookLevel dataclass ¶

__post_init__ ¶

FundingRate¶

FundingRate dataclass ¶

rate_bps property ¶

rate_percent property ¶

__post_init__ ¶

OpenInterest¶

OpenInterest dataclass ¶

__post_init__ ¶

Symbol Models¶

SymbolInfo¶

SymbolInfo dataclass ¶

is_spot property ¶

is_perpetual property ¶

is_futures property ¶

is_active property ¶

validate_price ¶

validate_quantity ¶

validate_notional ¶

TradingFilters¶

Type Aliases¶

See Also¶

Bar `dataclass` ¶

Tick `dataclass` ¶

from_string `classmethod` ¶

from_minutes `classmethod` ¶

from_hours `classmethod` ¶

from_days `classmethod` ¶

minute `classmethod` ¶

hour `classmethod` ¶

day `classmethod` ¶

week `classmethod` ¶

month `classmethod` ¶

str ¶

OrderBook `dataclass` ¶

best_bid `property` ¶

best_ask `property` ¶

spread `property` ¶

mid_price `property` ¶

OrderBookLevel `dataclass` ¶

FundingRate `dataclass` ¶

rate_bps `property` ¶

rate_percent `property` ¶

OpenInterest `dataclass` ¶

SymbolInfo `dataclass` ¶

is_spot `property` ¶

is_perpetual `property` ¶

is_futures `property` ¶

is_active `property` ¶