unicorn_binance_local_depth_cache package

Submodules

unicorn_binance_local_depth_cache.unicorn_binance_local_depth_cache_manager module

class unicorn_binance_local_depth_cache.manager.BinanceLocalDepthCacheManager(exchange: str = 'binance.com', default_refresh_interval: int = None, depth_cache_update_interval: int = None, high_performance: bool = False, auto_data_cleanup_stopped_streams: bool = False, init_interval: float = 4.0, init_time_window: int = 5, on_restart=None, websocket_close_timeout: int = 2, websocket_ping_interval: int = 10, websocket_ping_timeout: int = 20, disable_colorama: bool = False, ubdcc_address: str = None, ubdcc_port: int = 80, ubra_manager: BinanceRestApiManager = None, warn_on_update: bool = True)

Bases: Thread

A Python SDK to access and manage multiple local Binance DepthCaches with Python in a simple, fast, flexible, robust and fully-featured way.

Binance API documentation:

• https://binance-docs.github.io/apidocs/spot/en/#how-to-manage-a-local-order-book-correctly

• https://binance-docs.github.io/apidocs/futures/en/#diff-book-depth-streams

Parameters:

• exchange (str) – Select binance.com, binance.com-testnet, binance.com-futures, binance.com-futures-testnet, binance.com-vanilla-options, binance.com-vanilla-options-testnet, binance.us, trbinance.com (default: binance.com)

• default_refresh_interval (int) – The default refresh interval in seconds, default is None. The DepthCache is reset and reinitialized at this interval.

• init_interval (float (seconds)) – Only one request to the Binance REST API is permitted to all DepthCaches.

• init_time_window (int (seconds)) – Only one request to the Binance REST API is permitted per DepthCache in this time window (specified in seconds).

• high_performance (bool) – If True, access to the depth snapshots via REST in the INIT process is not regulated. Be careful!

• auto_data_cleanup_stopped_streams (bool) – The parameter “auto_data_cleanup_stopped_streams=True” can be used to inform the UBWA instance that all remaining data of a stopped stream should be automatically and completely deleted.

• depth_cache_update_interval (int) – Update speed of the depth stream in milliseconds. More info: https://github.com/oliver-zehentleitner/unicorn-binance-local-depth-cache/wiki/update_intervals

• websocket_close_timeout (int) – The close_timeout parameter defines a maximum wait time in seconds for completing the closing handshake and terminating the TCP connection. This parameter is passed through to the websockets.client.connect()

• websocket_ping_interval (int) – Once the connection is open, a Ping frame is sent every ping_interval seconds. This serves as a keepalive. It helps keeping the connection open, especially in the presence of proxies with short timeouts on inactive connections. Set ping_interval to None to disable this behavior. This parameter is passed through to the websockets.client.connect()

• websocket_ping_timeout (int) – If the corresponding Pong frame isn’t received within ping_timeout seconds, the connection is considered unusable and is closed with code 1011. This ensures that the remote endpoint remains responsive. Set ping_timeout to None to disable this behavior. This parameter is passed through to the websockets.client.connect()

• disable_colorama (bool) – set to True to disable the use of colorama

• ubra_manager (BinanceRestApiManager) – Provide a shared unicorn_binance_rest_api.manager instance

• warn_on_update (bool) – set to False to disable the update warning

create_depth_cache(markets: str | list | None = None, refresh_interval: int = None) → bool

*Deprecated!* Please use ‘create_depthcache()’ instead!

create_depthcache(markets: str | List[str] | None = None, refresh_interval: int = None) → bool

Create one or more DepthCaches!

Parameters:

• markets (str or list) – Specify the market symbols for caches to be created

• refresh_interval (int) – The refresh interval in seconds, default is the default_refresh_interval of BinanceLocalDepthCache. The DepthCache is reset and reinitialized at this interval.

Returns:

bool

get_asks(market: str = None, limit_count: int = None, threshold_volume: float = None) → list

Get the current list of asks with price and quantity.

Parameters:

• market (str) – Specify the market symbol for the used DepthCache

• limit_count (int or None (0 is nothing, None is everything)) – List elements threshold to trim the result.

• threshold_volume (float or None (0 is nothing, None is everything)) – Volume threshold to trim the result.

Returns:

list

get_bids(market: str = None, limit_count: int = None, threshold_volume: float = None) → list

Get the current list of bids with price and quantity.

Parameters:

• market (str) – Specify the market symbol for the used DepthCache.

• limit_count (int or None (0 is nothing, None is everything)) – List elements threshold to trim the result.

• threshold_volume (float or None (0 is nothing, None is everything)) – Volume threshold to trim the result.

Returns:

list

get_dc_stream_id(market: str = None) → str | None

Get the stream_id of the corresponding stream.

Returns:

stream_id (str) or None

get_last_restart_time(market: str = None) → float | None

Get the Unix timestamp of the last restart of the underlying WebSocket stream serving this market.

Returns None if the stream has not restarted yet (fresh DepthCache, first connection).

A “restart” here means the WebSocket stream for this market had to reconnect and re-initialize the DepthCache (new REST snapshot + resync). High restart activity can indicate upstream instability on the exchange side.

Parameters:

market (str) – Specify the market symbol for the used DepthCache

Returns:

Unix timestamp (float seconds) or None

Raises:

DepthCacheNotFound – if the market is unknown

get_last_update_time(market: str = None) → int | None

Get the Unix timestamp in milliseconds of the last processed depth update for a market.

Returns None if the DepthCache exists but has not yet received its first update.

Parameters:

market (str) – Specify the market symbol for the used DepthCache

Returns:

Unix timestamp in milliseconds (int) or None

Raises:

DepthCacheNotFound – if the market is unknown

static get_latest_release_info() → dict | None

Get info about the latest available release

Returns:

dict or None

get_latest_version() → str | None

Get the version of the latest available release (cache time 1 hour)

Returns:

str or None

get_list_of_depth_caches() → list

*Deprecated!* Please use ‘get_list_of_depthcaches()’ instead!

get_list_of_depthcaches() → list

Get a list of active DepthCaches

Returns:

list

get_restart_count(market: str = None) → int

Get the number of restarts of the underlying WebSocket stream serving this market.

Returns 0 if the stream has not restarted yet.

A “restart” here means the WebSocket stream for this market had to reconnect and re-initialize the DepthCache. High restart activity can indicate upstream instability on the exchange side.

Parameters:

market (str) – Specify the market symbol for the used DepthCache

Returns:

Restart counter (int)

Raises:

DepthCacheNotFound – if the market is unknown

get_ubra_manager() → BinanceRestApiManager

Get the used BinanceRestApiManager() instance of BinanceLocalDepthCacheManager()

Returns:

BinanceRestApiManager

get_ubwa_manager() → BinanceWebSocketApiManager

Get the used BinanceWebSocketApiManager() instance of BinanceLocalDepthCacheManager()

Returns:

BinanceWebSocketApiManager

get_user_agent() → str

Get the user_agent string “lib name + lib version + python version”

Returns:

str

get_version() → str

Get the package/module version

Returns:

str

is_depth_cache_synchronized(market: str = None) → bool

Is a specific DepthCache synchronized?

Parameters:

market (str) – Specify the market symbol for the used DepthCache

Returns:

bool

is_stop_request(market: str = None) → bool

Is there a stop request?

Parameters:

market (str) – Specify the market symbol for the used DepthCache

Returns:

bool

is_update_available() → bool

Is a new release of this package available?

Returns:

bool

print_summary(add_string: str = None, footer: str = None, title: str = None) → None

Print an overview of all streams

Parameters:

• add_string (str) – text to add to the output

• footer (str) – footer of the output

• title (str) – title of the output

Returns:

None

print_summary_to_png(print_summary_export_path: str = None, height_per_row: float = 12.5, add_string: str = None, footer: str = None, title: str = None)

Create a PNG image file with the console output of print_summary()

LINUX ONLY It should not be hard to make it OS independent: https://github.com/oliver-zehentleitner/unicorn-binance-websocket-api/issues/61

Parameters:

• print_summary_export_path (str) – If you want to export the output of print_summary() to an image, please provide a path like “/var/www/html/”. View the Wiki!

• height_per_row (float) – set the height per row for the image height calculation

• add_string (str) – text to add to the output

• footer (str) – set a footer (last row) for print_summary output

• title (str) – set a title (first row) for print_summary output

Returns:

bool

set_credentials(api_key: str = None, api_secret: str = None) → None

Replace the internal BinanceRestApiManager with a fresh instance bound to the given credentials. Use this to rotate API keys at runtime without recreating the BinanceLocalDepthCacheManager or interrupting the WebSocket streams — the new credentials take effect from the next REST call (initial snapshot, resync).

Pass api_key=None and api_secret=None to drop credentials and fall back to the public rate limits.

Parameters:

• api_key (str) – Binance API key, or None to use public rate limits

• api_secret (str) – Binance API secret, or None to use public rate limits

set_refresh_request(markets: str | list | None = None) → bool

Set refresh requests for one or more DepthCaches!

Parameters:

markets (str or list) – Specify the market symbols for the DepthCaches to be refreshed

Returns:

bool

set_resync_request(market: str = None, unsubscribe: bool = True) → bool

This will set a DC out of sync and starts a new initialisation!

Parameters:

• market (str) – Specify the market for the used DepthCache

• unsubscribe (bool) – If True the market will get unsubscribed from the web stream.

Returns:

bool

stop_depth_cache(markets: str | list | None = None) → bool

*Deprecated!* Please use ‘stop_depthcache()’ instead!

stop_depthcache(markets: str | list | None = None) → bool

Stop and delete one or more DepthCaches!

Parameters:

markets (str or list) – Specify the market symbols for the DepthCaches to be stopped and deleted

Returns:

bool

stop_manager() → bool

Stop unicorn-binance-local-depth-cache with all sub routines

Returns:

bool

unicorn_binance_local_depth_cache.unicorn_binance_local_depth_cache_exceptions module

exception unicorn_binance_local_depth_cache.exceptions.DepthCacheAlreadyStopped(market=None)

Bases: Exception

Exception raised when an attempt is made to use a depth_cache that has already been stopped.

exception unicorn_binance_local_depth_cache.exceptions.DepthCacheClusterNotReachableError(url=None)

Bases: Exception

Exception raised when the UBDCC is not reachable.

exception unicorn_binance_local_depth_cache.exceptions.DepthCacheNotFound(market=None)

Bases: Exception

Exception raised when an attempt is made to use an instance that does not exist.

exception unicorn_binance_local_depth_cache.exceptions.DepthCacheOutOfSync(market=None)

Bases: Exception

Exception raised when an attempt is made to use a depth_cache that is out of sync.

unicorn_binance_local_depth_cache.unicorn_binance_local_depth_cache_cluster module

class unicorn_binance_local_depth_cache.cluster.Cluster(address: str = None, port: int = None)

Bases: object

create_depthcache(exchange: str = None, market: str = None, desired_quantity: int = None, update_interval: int = None, refresh_interval: int = None, debug: bool = False) → dict

async create_depthcache_async(exchange: str = None, market: str = None, desired_quantity: int = None, update_interval: int = None, refresh_interval: int = None, debug: bool = False) → dict

create_depthcaches(exchange: str = None, markets: list = None, desired_quantity: int = None, update_interval: int = None, refresh_interval: int = None, debug: bool = False) → dict

async create_depthcaches_async(exchange: str = None, markets: list = None, desired_quantity: int = None, update_interval: int = None, refresh_interval: int = None, debug: bool = False) → dict

get_asks(exchange: str = None, market: str = None, limit_count: int = None, threshold_volume: int = None, debug: bool = False) → dict

async get_asks_async(exchange: str = None, market: str = None, limit_count: int = None, threshold_volume: int = None, debug: bool = False) → dict

get_bids(exchange: str = None, market: str = None, limit_count: int = None, threshold_volume: int = None, debug: bool = False) → dict

async get_bids_async(exchange: str = None, market: str = None, limit_count: int = None, threshold_volume: int = None, debug: bool = False) → dict

get_cluster_info(debug: bool = False) → dict

async get_cluster_info_async(debug: bool = False) → dict

get_depthcache_info(exchange: str = None, market: str = None, debug: bool = False) → dict

async get_depthcache_info_async(exchange: str = None, market: str = None, debug: bool = False) → dict

get_depthcache_list(debug: bool = False) → dict

async get_depthcache_list_async(debug: bool = False) → dict

get_test() → dict

async get_test_async() → dict

stop_depthcache(exchange: str = None, market: str = None, debug: bool = False) → dict

async stop_depthcache_async(exchange: str = None, market: str = None, debug: bool = False) → dict

test_connection() → bool

async test_connection_async() → bool

ubdcc_add_credentials(account_group: str = None, api_key: str = None, api_secret: str = None, debug: bool = False) → dict

Store a Binance API key pair in the cluster for a given account group (binance.com, binance.com-testnet, binance.com-futures-testnet, binance.us, binance.tr). Multiple pairs per group are allowed and get load-balanced across DCNs. Returns the generated credential id.

async ubdcc_add_credentials_async(account_group: str = None, api_key: str = None, api_secret: str = None, debug: bool = False) → dict

ubdcc_get_credentials_list(debug: bool = False) → dict

List stored credentials. API keys are returned masked (preview only); api_secret is never returned. Each entry lists the DCN UIDs it is currently assigned to.

async ubdcc_get_credentials_list_async(debug: bool = False) → dict

ubdcc_remove_credentials(credential_id: str = None, debug: bool = False) → dict

Remove a stored API key pair by id.

async ubdcc_remove_credentials_async(credential_id: str = None, debug: bool = False) → dict

unicorn_binance_local_depth_cache.unicorn_binance_local_depth_cache_cluster_endpoints module

class unicorn_binance_local_depth_cache.cluster_endpoints.ClusterEndpoints

Bases: object

create_depthcache: str = 'create_depthcache'

create_depthcaches: str = 'create_depthcaches'

get_asks: str = 'get_asks'

get_bids: str = 'get_bids'

get_cluster_info: str = 'get_cluster_info'

get_depthcache_info: str = 'get_depthcache_info'

get_depthcache_list: str = 'get_depthcache_list'

stop_depthcache: str = 'stop_depthcache'

test: str = 'test'

ubdcc_add_credentials: str = 'ubdcc_add_credentials'

ubdcc_get_credentials_list: str = 'ubdcc_get_credentials_list'

ubdcc_remove_credentials: str = 'ubdcc_remove_credentials'

Module contents