Retrievers

The retrievers handles the communication between an API, the user and a database. With each user’s request, it will try to search the response in a local database and if necessary will ask an API.

AbstractRetriever

This class is the base of all retrievers, it contains the main logic.

class CryptoPrice.retrievers.AbstractRetriever.AbstractRetriever(name: str)[source]
MAX_API_RETRY = 3
__init__(name: str)[source]
get_closest_price(asset: str, ref_asset: str, timestamp: int) → Optional[CryptoPrice.common.prices.Price][source]

Will get the closest price possible in time for a trading pair asset/ref asset. If no price is found, return None

Parameters

  • asset (str) – name of the asset in the trading pair (ex ‘BTC’ in ‘BTCUSDT’)

  • ref_asset (str) – name of the reference asset in the trading pair (ex ‘USDT’ in ‘BTCUSDT’)

  • timestamp (int) – time to fetch the price needed (in seconds)

Returns

the price closest in time found or None if no price found

Return type

Optional[Price]

abstract get_supported_pairs() → List[CryptoPrice.common.trade.TradingPair][source]

Return the list of trading pair supported by this retriever

Returns

list of trading pairs

Return type

List[TradingPair]

KlineRetriever

This class is specific for the retriever linked to an API with candle (ohlc) data, it implements the KlineDataBase for this kind of data.

class CryptoPrice.retrievers.KlineRetriever.KlineRetriever(name: str, kline_timeframe: CryptoPrice.utils.time.TIMEFRAME, closest_window: int = 120)[source]
__init__(name: str, kline_timeframe: CryptoPrice.utils.time.TIMEFRAME, closest_window: int = 120)[source]
get_klines_online(asset: str, ref_asset: str, timeframe: CryptoPrice.utils.time.TIMEFRAME, start_time: int, end_time: int, retry_count: int = 0) → List[CryptoPrice.common.prices.Kline][source]

This method handles RateAPIException and calls _get_klines_online which will effectively retrieve the online data

Parameters

  • asset (str) – asset of the trading pair

  • ref_asset (str) – reference asset of the trading pair

  • timeframe (TIMEFRAME) – timeframe for the kline

  • start_time (Optional[int]) – fetch only klines with an open time greater or equal than start_time

  • end_time (Optional[int]) – fetch only klines with an open time lower than end_time

  • retry_count (int) – internal use, number of recursive loops done on this method

Returns

list of klines

Return type

List[Kline]

Implemented Retrievers

Below are the retrievers implemented in this library.

class CryptoPrice.retrievers.BinanceRetriever.BinanceRetriever(kline_timeframe: CryptoPrice.utils.time.TIMEFRAME = TIMEFRAME.m1, closest_window: int = 310)[source]

This class is in charge of fetching klines from the Binance API

docs: https://python-binance.readthedocs.io/en/latest/binance.html

__init__(kline_timeframe: CryptoPrice.utils.time.TIMEFRAME = TIMEFRAME.m1, closest_window: int = 310)[source]
get_supported_pairs() → List[CryptoPrice.common.trade.TradingPair][source]

Return the list of trading pair supported by this retriever

Returns

list of trading pairs

Return type

List[TradingPair]

kline_translation = {TIMEFRAME.m1: '1m', TIMEFRAME.m3: '3m', TIMEFRAME.m5: '5m', TIMEFRAME.m15: '15m', TIMEFRAME.m30: '30m', TIMEFRAME.h1: '1h', TIMEFRAME.h2: '2h', TIMEFRAME.h4: '4h', TIMEFRAME.h6: '6h', TIMEFRAME.h8: '8h', TIMEFRAME.h12: '12h', TIMEFRAME.d1: '1d', TIMEFRAME.d3: '3d', TIMEFRAME.w1: '1w'}
class CryptoPrice.retrievers.KucoinRetriever.KucoinRetriever(kline_timeframe: CryptoPrice.utils.time.TIMEFRAME = TIMEFRAME.m1, closest_window: int = 310)[source]

docs: https://github.com/Kucoin/kucoin-python-sdk https://docs.kucoin.com

__init__(kline_timeframe: CryptoPrice.utils.time.TIMEFRAME = TIMEFRAME.m1, closest_window: int = 310)[source]
get_supported_pairs() → List[CryptoPrice.common.trade.TradingPair][source]

Return the list of trading pair supported by this retriever

Returns

list of trading pairs

Return type

List[TradingPair]

kline_translation = {TIMEFRAME.m1: '1min', TIMEFRAME.m3: '3min', TIMEFRAME.m5: '5min', TIMEFRAME.m15: '15min', TIMEFRAME.m30: '30min', TIMEFRAME.h1: '1hour', TIMEFRAME.h2: '2hour', TIMEFRAME.h4: '4hour', TIMEFRAME.h6: '6hour', TIMEFRAME.h8: '8hour', TIMEFRAME.h12: '12hour', TIMEFRAME.d1: '1day', TIMEFRAME.w1: '1week'}

MetaRetriever

This retriever is made above several specified retrievers. It allows to create price data across different exchanges / APIs.

class CryptoPrice.retrievers.MetaRetriever.MetaRetriever(retrievers: List[CryptoPrice.retrievers.AbstractRetriever.AbstractRetriever])[source]
__init__(retrievers: List[CryptoPrice.retrievers.AbstractRetriever.AbstractRetriever])[source]
construct_assets_neighbours(asset_subsets: List[str]) → Dict[source]

Construct a dictionary of neighbours assets, with the trading pairs needed to get from one asset to another

Parameters

asset_subsets (List[str]) – list of assets to use among supported assets

Returns

assets_neighbours

Return type

Dict

get_mean_price(asset: str, ref_asset: str, timestamp: int, preferred_assets: Optional[List[str]] = None, max_depth: int = 3, max_depth_range: int = 0) → Optional[CryptoPrice.common.prices.MetaPrice][source]

Will use the method get_path_prices and return the mean price of an asset compared to a reference asset on a given timestamp.

Parameters

  • asset (str) – name of the asset to get the price of

  • ref_asset (str) – name of the reference asset

  • timestamp (int) – time to fetch the price needed (in seconds)

  • preferred_assets (Optional[List[str]]) – list of assets to construct the price path from. If None, default value is [‘BTC’, ‘ETH’]

  • max_depth (int) – maximum number of trading pair to use, default 3

  • max_depth_range (int) – maximum length difference between different trading path. If the first trading path has a length of 1 and this parameter is equal to 2, trading_path with a length superior to 3 will be ignored

Returns

Metaprice reflecting the value calculated with a mean of trading path

Return type

Optional[MetaPrice]

get_path_prices(asset: str, ref_asset: str, timestamp: int, preferred_assets: Optional[List[str]] = None, max_depth: int = 2, max_depth_range: int = - 1) → Iterator[CryptoPrice.common.prices.MetaPrice][source]

Iterator that return MetaPrices that estimates the price of an asset compared to a reference asset. It will use the trading pair at its disposal to create trading path from the asset to the ref asset. It use a BFS algorithm, so the shortest path will be returned first. If no price is found, return None

Parameters

  • max_depth_range (int) –

  • asset (str) – name of the asset to get the price of

  • ref_asset (str) – name of the reference asset

  • timestamp (int) – time to fetch the price needed (in seconds)

  • preferred_assets (Optional[List[str]]) – list of assets to construct the price path from. If None, default value is [‘BTC’, ‘ETH’]

  • max_depth (int) – maximum number of trading pair to use, default 2

  • max_depth_range – maximum length difference between different trading path. If the first trading path has a length of 1 and this parameter is equal to 2, trading_path with a length superior to 3 will be ignored. Default -1 means that this parameter is ignored.

Returns

Metaprice reflecting the value calculated through a trading path

Return type

Optional[MetaPrice]

get_supported_pairs() → List[CryptoPrice.common.trade.TradingPair][source]

Return the list of trading pair supported by this retriever

Returns

list of trading pairs

Return type

List[TradingPair]