API Reference

class odd_kernel.datasets.marketdata.DataType(value)

Available financial data fields.

ADJ_CLOSE = 'Adj Close'

CLOSE = 'Close'

HIGH = 'High'

LOW = 'Low'

OPEN = 'Open'

VOLUME = 'Volume'

classmethod parse(value: str)

Parses a string (case-insensitive) into a DataType. Raises ValueError if the string does not match any field.

class odd_kernel.datasets.marketdata.IndexType(value)

Supported index types for the output data.

DATETIME = 'datetime'

EPOCH = 'epoch'

INDEX = 'index'

STRING = 'string'

class odd_kernel.datasets.marketdata.MarketDataPeriod(value: int, unit: MarketDataTimeUnit)

Represents a time resolution with unit and magnitude.

to_pandas_freq() → str

Converts the period to a pandas-compatible frequency string.

class odd_kernel.datasets.marketdata.MarketDataProvider(max_cache_size=100, show_download_progress=False)

Module to fetch and manage financial time series from Yahoo Finance. Provides summary, raw data, and interpolated data methods.

get_available_tickers(max_count=None)

Returns all available tickers in the yahoo finance API

get_dataset(tickers: List[str], field: DataType, start: str, end: str, resolution: MarketDataPeriod, index_type: IndexType = IndexType.DATETIME) → Dict[str, DataFrame]

Returns interpolated data for the given tickers, field and resolution in a common time grid

get_interpolated(tickers: str | List[str], start: str, end: str, field: DataType, resolution: MarketDataPeriod = None, index_type: IndexType = IndexType.DATETIME, extrapolate_left=False) → tuple[Dict, Dict]

Returns interpolated data for a given ticker, field, and resolution. Performs flat extrapolation to the left and right of the original data range if required.

Parameters:

• tickers (Union[str, List[str]]) – Ticker symbols of the financial instrument.

• start (str) – Start date (inclusive) in ‘YYYY-MM-DD’ format.

• end (str) – End date (inclusive) in ‘YYYY-MM-DD’ format.

• field (DataType) – The financial data field to retrieve (e.g., CLOSE, OPEN).

• resolution (MarketDataPeriod, optional) – The target temporal resolution. If None no interpolation is performed. Defaults to None.

• index_type (IndexType, optional) – Defines the format of the time index in the output. Defaults to IndexType.DATETIME.

• extrapolate_left (bool, optional) – Whether to perform flat extrapolation to the left or not. Defaults to False.

Returns:

A tuple containing two dictionaries: one for the interpolated data and one for the metadata.

Return type:

tuple[Dict, Dict]

get_raw(tickers: str | List[str], field: DataType) → tuple[Dict, Dict]

Returns raw data for a given ticker and field.

get_summary(tickers: str | List[str]) → DataFrame

Returns a summary for each ticker: - name - min/max date - average resolution - available fields

get_ticker_metadata(tickers: str | List[str]) → Dict

Returns the metadata for a set of tickers.

class odd_kernel.datasets.marketdata.MarketDataTimeUnit(value)

Supported time units for interpolation resolution.

DAY = 'D'

MONTH = 'M'

YEAR = 'Y'

class odd_kernel.datasets.cryptocurrencies.BinanceClient(api_key: str | None = None, api_secret: str | None = None, verbose: bool = False)

Client for interacting with the Binance API.

get_all_tickers() → List[str]

Gets the list of all available tickers (symbols).

Returns:

List of available symbols.

Return type:

List[str]

get_exchange_info(symbol: str | None = None) → Dict

Gets exchange information including available symbols.

Parameters:

symbol (Optional[str], optional) – Specific symbol. Defaults to None.

Returns:

Dictionary with exchange information.

Return type:

Dict

get_historical_klines(symbol: str, period: CryptoCurrenciesPeriod, start_time: datetime, end_time: datetime | None = None, limit: int = 1000) → List[Dict]

Gets historical klines (OHLCV) data.

Parameters:

• symbol (str) – Trading pair (e.g., “BTCUSDT”).

• period (CryptoCurrenciesPeriod) – Data period/granularity.

• start_time (datetime) – Start date.

• end_time (Optional[datetime], optional) – End date. Defaults to now.

• limit (int, optional) – Maximum number of records per request (max 1000). Defaults to DEFAULT_HISTORICAL_LIMIT.

Returns:

List of dictionaries with OHLCV data.

Return type:

List[Dict]

get_historical_trades(symbol: str, start_time: datetime, end_time: datetime | None = None, limit: int = 1000) → List[Dict]

Gets historical aggregated trades.

Parameters:

• symbol (str) – Trading pair.

• start_time (datetime) – Start date.

• end_time (Optional[datetime], optional) – End date. Defaults to None.

• limit (int, optional) – Maximum number of records per request. Defaults to DEFAULT_HISTORICAL_LIMIT.

Returns:

List of dictionaries with trade data.

Return type:

List[Dict]

get_orderbook_snapshot(symbol: str, limit: int = 1000) → Dict

Gets an order book snapshot.

Parameters:

• symbol (str) – Trading pair.

• limit (int, optional) – Book depth (max 5000). Defaults to DEFAULT_SNAPSHOT_SIZE.

Returns:

Dictionary with bids and asks.

Return type:

Dict

get_trading_pairs_info() → List[Dict]

Gets detailed information for all trading pairs.

Returns:

List of dictionaries with information for each pair.

Return type:

List[Dict]

class odd_kernel.datasets.cryptocurrencies.CryptoCurrenciesPeriod(count: int, unit: CryptoCurrenciesTimeUnit)

Class for defining data granularity.

count

Number of units in the crypto currency period.

Type:

int

unit

Time unit for the crypto currency period.

Type:

CryptoCurrenciesTimeUnit

to_binance_interval() → str

Converts the period to Binance interval format.

Returns:

String with the interval in Binance format (e.g., “1m”, “1h”, “1d”).

Return type:

str

class odd_kernel.datasets.cryptocurrencies.CryptoCurrenciesTimeUnit(value)

Time units for defining periods.

DAY = 'd'

HOUR = 'h'

MINUTE = 'm'

MONTH = 'M'

SECOND = 's'

WEEK = 'w'

class odd_kernel.datasets.cryptocurrencies.DataType(value)

Data types available on Binance.

AGG_TRADES = 'aggTrades'

DEPTH = 'depth'

KLINES = 'klines'

TICKER_24HR = 'ticker24hr'

TRADES = 'trades'

class odd_kernel.datasets.cryptocurrencies.OrderBook(client: BinanceClient, symbol: str)

Maintains a real-time order book for a symbol.

asks: Dict[float, float]

bids: Dict[float, float]

buffer: List[Dict]

get_best_ask() → tuple[float, float] | None

Gets the best ask (lowest price).

get_best_bid() → tuple[float, float] | None

Gets the best bid (highest price).

get_orderbook_snapshot(depth: int = 10) → Dict

Gets a snapshot of the current order book.

Parameters:

depth (int, optional) – Number of levels to include. Defaults to 10.

Returns:

Dictionary with sorted bids and asks.

Return type:

Dict

get_spread() → float | None

Calculates the spread between bid and ask.

initialize_from_snapshot(limit: int = 1000)

Initializes the order book from a REST API snapshot.

Parameters:

limit (int, optional) – Snapshot depth. Defaults to DEFAULT_SNAPSHOT_SIZE.

last_update_id: int | None

process_buffered_events()

Processes events that were buffered before initialization.

process_depth_update(data: Dict)

Processes a depth stream update.

Parameters:

data (Dict) – Depth update data.

async start_stream()

Starts the depth update stream.