quantpylib.wrappers.woox

quantpylib.wrappers.woox module is our official WooX wrapper SDK implementing the endpoints for trading. The library supports a fully asynchronous endpoint for efficiency and lightweight concurrency. The websocket manager handles reconnections and resubsriptions under network errors and upgrades.

We will demonstrate usage of the library. On top of the endpoints exposed by the exchange, we have added a variety of utility functions.

Examples

We would demonstrate some endpoints. Refer to full documentation for details.

import os
import pytz
import asyncio
from pprint import pprint
from datetime import datetime
from dotenv import load_dotenv
load_dotenv()

from quantpylib.wrappers.woox import Woox

async def print_handler(msg):
    print(msg)

async def main():
    """using the SDK"""
    woox = Woox(
        key=os.getenv("WOO_KEY"),
        secret=os.getenv("WOO_SECRET"),
        app_id=os.getenv("WOO_APP"),
    )
    """quantpylib.gateway endpoints"""
    await woox.init_client()
    print(woox.get_price_precision("PERP_BTC_USDT"))
    print(woox.get_lot_precision("PERP_BTC_USDT"))

    '''ACCOUNT ENDPOINTS'''
    pprint(await woox.account_balance())
    await woox.account_fill_subscribe(handler=print_handler)

    '''EXCHANGE ENDPOINTS'''
    pprint(await woox.contract_specifications())
    pprint(await woox.get_funding_info())

    '''EXECUTOR ENDPOINTS'''
    cloid = woox.rand_cloid()
    print(cloid)
    pprint(await woox.get_all_mids())
    pprint(await woox.get_all_marks())
    pprint(await woox.limit_order(ticker="PERP_SOL_USDT",amount=1,price=99.99,cloid=cloid))
    pprint(await woox.cancel_open_orders()) #or use ticker="PERP_SOL_USDT"
    pprint(await woox.cancel_order(ticker="PERP_SOL_USDT",cloid=cloid)) #or use oid
    pprint(await woox.market_order(ticker="PERP_SOL_USDT",amount=-0.5))
    pprint(await woox.l2_book_get(ticker="PERP_SOL_USDT"))
    await woox.l2_book_mirror(ticker="PERP_BTC_USDT",on_update=print_handler)
    await woox.l2_book_subscribe(ticker="PERP_BTC_USDT",handler=print_handler)
    await woox.trades_subscribe(ticker="PERP_BTC_USDT",handler=print_handler)
    await woox.all_mids_subscribe(handler=print_handler)

    '''ORDERS ENDPOINTS'''
    pprint(await woox.order_query(ticker='PERP_SOL_USDT',cloid='1234'))
    pprint(await woox.orders_get())
    await woox.orders_mirror(on_update=print_handler)
    await woox.order_updates_subscribe(handler=print_handler)

    '''POSITIONS ENDPOINTS'''
    pprint(await woox.positions_get())
    await woox.positions_mirror(on_update=print_handler)

    '''DATAPOLLER ENDPOINTS'''
    # pprint(await woox.get_trade_bars(
    #     ticker='PERP_BTC_USDT',
    #     start=datetime(2021,1,1, tzinfo=pytz.utc),
    #     end=datetime.now(pytz.utc),
    #     granularity=Period.HOURLY,
    #     granularity_multiplier=1,
    # ))

    '''raw exchange endpoints API - refer to docs for the other method implementations'''
    pprint(await woox.system_maintenance_status())
    pprint(await woox.exchange_info())
    pprint(await woox.market_trades(symbol="PERP_BTC_USDT"))
    #>... many more
    await asyncio.sleep(1e9)

if __name__ == "__main__":
    asyncio.run(main())

Woox

__init__(key=None, secret=None, app_id=None, environment=Environment.PROD)

Initializes the WooX instance.

Parameters:

Name	Type	Description	Default
key	str	API key for authentication.	None
secret	str	API secret for authentication.	None
app_id	str	Application ID for authentication.	None
environment	int	The environment to connect to. 1 for production, 2 for staging. Defaults to 1.	PROD

account_balance(**kwargs) async

Retrieve balance details of the user, such as equity, margin (total, maintenance) and pnl.

Returns:

Type	Description
dict	Balance details.

account_fill_subscribe(handler, **kwargs) async

Subscribe to order fill events.

Parameters:

Name	Type	Description	Default
handler	coroutine	A coroutine handler for the message received.	required
**kwargs		Exchange wrapper specific keyword arguments.	{}

account_fill_unsubscribe(**kwargs) async

Unsubscribe from order fill events.

all_mids_subscribe(handler, **kwargs) async

Subscribe to mid-price updates for all tickers.

Parameters:

Name	Type	Description	Default
handler	coroutine	A coroutine handler for the message received.	required
**kwargs		Exchange wrapper specific keyword arguments.	{}

all_mids_unsubscribe(**kwargs) async

Unsubscribe from mid-price updates for all tickers.

cancel_all_pending_orders() async

Cancel all pending orders.

cancel_open_orders(ticker=None, **kwargs) async

Cancel open orders on the exchange.

Parameters:

Name	Type	Description	Default
ticker	str	The coin symbol. Defaults to None, which means cancel all open orders.	None
**kwargs		Exchange wrapper specific keyword arguments.	{}

Returns:

Name	Type	Description
Any		The result of the cancellation request.

cancel_order(order_id, symbol) async

Cancel an order.

cancel_order_by_client_id(client_order_id, symbol) async

Cancel an order by client order ID.

cancel_orders(symbol) async

Cancel all orders for a specific ticker.

contract_specifications(contract_type='PERP', **kwargs) async

Retrieve the contract's trading rules from the exchange.

Returns:

Name	Type	Description
dict		A dictionary containing contract specifications for each asset with key-values: - SYMBOL_PRICE_PRECISION. - SYMBOL_QUANTITY_PRECISION. - SYMBOL_MIN_NOTIONAL - SYMBOL_BASE_ASSET - SYMBOL_QUOTE_ASSET

exchange_info(symbol=None) async

Retrieve the exchange information.

funding_rate_history(symbol, **kwargs) async

Retrieve the funding rate history for a specific contract.

futures_info(symbol=None) async

Retrieve the futures information.

get_account_information() async

Retrieve the account information.

get_all_marks(**kwargs) async

Retrieve the mark-price for all available tickers.

get_all_mids(**kwargs) async

Retrieve the mid-price for a specific ticker or all available tickers. NOTE: this endpoint is not available in WooX - it calls the get_all_marks endpoint instead.

Parameters:

Name	Type	Description	Default
**kwargs		Exchange wrapper specific keyword arguments.	{}

get_current_holding(**kwargs) async

Retrieve the current holding.

get_funding_info(**kwargs) async

Retrieve the funding rate and interval for all contracts.

get_futures_leverage_setting(symbol, margin_mode, position_mode) async

Retrieve the futures leverage setting.

get_lot_precision(ticker)

Retrieves the lot size precision for a specified ticker.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

Returns:

Name	Type	Description
int		The number of decimal places for lot size precision.

get_order(order_id) async

Retrieve an order by order ID.

get_order_by_client_id(client_order_id) async

Retrieve an order by client order ID.

get_orders(status='INCOMPLETE', **kwargs) async

Retrieve all orders.

get_position_info(symbol) async

Retrieve the position information for a specific ticker.

get_positions_info() async

Retrieve the position information for all tickers.

get_price_precision(ticker)

Retrieves the price precision for a specified ticker.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol.	required

Returns:

Name	Type	Description
int		The number of decimal places for price precision.

get_trade(trade_id) async

Retrieve a trade by trade ID.

get_trade_history(**kwargs) async

Retrieve the trade history.

get_trades(order_id) async

Retrieve all trades for an order.

init_client() async

Initializes the client by fetching contract specifications and setting up precision mappings.

l2_book_get(ticker, depth=100, standardize_schema=True, **kwargs) async

Retrieve the L2 Order Book for a specific ticker.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker symbol.	required
depth	int	Depth of the order book. Defaults to 100.	100
standardize_schema	bool	If True, returns the order book in a standardized schema. Defaults to True.	True
**kwargs		Additional keyword arguments specific to the exchange wrapper.	{}

l2_book_mirror(ticker, depth=50, buffer_size=100, as_dict=True, on_update=None, **kwargs) async

Keep a live, internal L2 Order Book representation using a l2-book subscription.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker symbol.	required
depth	int	Depth of the order-book representation. Defaults to 50.	50
buffer_size	int	Size of the order-book buffer, if as_dict is False.	100
as_dict	(bool, True)	If True, pass state as dictionary, otherwise as a quantpylib.hft.lob.LOB object into handlers.	True
on_update	coroutine	A coroutine handler when order book state is updated.	None
**kwargs		Exchange wrapper specific keyword arguments.	{}

l2_book_peek(ticker, as_dict=True, **kwargs)

Retrieve the mirrored, local internal L2 Order Book representation.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker symbol.	required
as_dict	(bool, True)	If True, return state as dictionary, otherwise as a quantpylib.hft.lob.LOB object.	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

l2_book_subscribe(ticker, handler, standardize_schema=True, speed_ms=200, **kwargs) async

Subscribe to L2 Order Book stream.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker symbol.	required
handler	coroutine	A coroutine handler for the message received.	required
speed_ms	int	Speed of the order book updates in milliseconds. Defaults to 200, which use orderbook delta subscriptions. Otherwise, subscriptions are to snapshots.	200
standardize_schema	(bool, True)	Processes the incoming message to {ts,b,a}	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

l2_book_subscriptions(**kwargs)

Retrieve the list of open l2 book subscriptions.

l2_book_unsubscribe(ticker, speed_ms=200, **kwargs) async

Unsubscribe from L2 Order Book.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker symbol.	required
speed_ms	int	Speed of the order book updates in milliseconds. Defaults to 200.	200
**kwargs		Exchange wrapper specific keyword arguments.	{}

limit_order(ticker, amount, price, tif='LIMIT', reduce_only=False, cloid=None, round_price=False, round_size=False, **kwargs) async

Submit a limit order.

Parameters:

Name	Type	Description	Default
ticker	str	The coin symbol.	required
amount	float or Decimal	The signed quantity of contracts to long or short.	required
price	float	The price at which to execute the order.	required
tif	str	The time in force for the order. Defaults to "LIMIT". Allowed values are: - "LIMIT" - "POST_ONLY" - "IOC" - "FOK"	'LIMIT'
reduce_only	bool	Whether the order should only reduce an existing position. Defaults to False.	False
cloid	int	Client order ID for order tracking. Defaults to None.	None
round_price	bool	Whether to round the price to a valid order specification. Defaults to False.	False
round_size	bool	Whether to round the price to a valid order specification. Defaults to False.	False
**kwargs		Additional keyword arguments for order customization.	{}

Returns:

Name	Type	Description
Any		The result of the order placement.

market_order(ticker, amount, reduce_only=False, cloid=None, round_size=False, **kwargs) async

Submit a market order.

Parameters:

Name	Type	Description	Default
ticker	str	The ticker symbol for the asset.	required
amount	float or Decimal	The signed quantity of contracts to long or short.	required
reduce_only	bool	Whether the order should only reduce an existing position. Defaults to False.	False
cloid	int	Client order ID for custom tracking. Defaults to None.	None
round_size	bool	Whether to round the price to a valid order specification. Defaults to False.	False
**kwargs		Additional keyword arguments specific to the exchange wrapper.	{}

Returns:

Name	Type	Description
Any		The result of the order placement. This typically includes a confirmation of the placed order, or an error message if the order could not be placed.

market_trades(symbol, **kwargs) async

Retrieve the trades for a specific ticker.

order_query(oid=None, cloid=None, as_dict=True, **kwargs) async

Get order details using client order ID.

Parameters:

Name	Type	Description	Default
oid	str	Order ID in exchange.	None
cloid	str	Client Order ID (used for actual query).	None
as_dict	bool	If True, return the order details as a dictionary. Defaults to True.	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

order_updates_subscribe(handler, **kwargs) async

Subscribe to creation, updation and deletion of account's orders.

Parameters:

Name	Type	Description	Default
handler	coroutine	A coroutine handler for the message received.	required
**kwargs		Exchange wrapper specific keyword arguments.	{}

order_updates_unsubscribe(**kwargs) async

Unsubscribe from order events.

orderbook_snapshot(symbol, **kwargs) async

Retrieve the order book snapshot for a specific ticker.

orders_get(**kwargs) async

Get all open orders. Automatically iterates the cursor if required to retrieve all orders.

Returns:

Name	Type	Description
dict		A dictionary containing order details.

orders_mirror(on_update=None, as_list=True, **kwargs) async

Keeps a local mirror copy of the account open orders.

Parameters:

Name	Type	Description	Default
on_update	coroutine	A coroutine handler for orders dictionary on order event.	None
as_list	bool	If True, pass state as list, otherwise as quantpylib.standards.Orders object into handlers.	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

orders_peek(as_dict=True, **kwargs)

Retrieves the local mirror copy of the account open orders.

Parameters:

Name	Type	Description	Default
as_dict	bool	If True, pass state as dictionary, otherwise as quantpylib.standards.Orders object.	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

positions_get(**kwargs) async

Get all open position details.

Parameters:

Name	Type	Description	Default
**kwargs		Exchange wrapper specific keyword arguments.	{}

positions_mirror(on_update=None, as_dict=True, **kwargs) async

Keeps a local mirror copy of the account open orders.

Parameters:

Name	Type	Description	Default
on_update	coroutine	A coroutine handler for positions dictionary on fill.	None
as_dict	bool	If True, the method returns positions as a dictionary, otherwise as a quantpylib.standards.Positions object. Defaults to True.	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

positions_peek(as_dict=True, **kwargs)

Retrieves the local mirror copy of the account open positions.

Parameters:

Name	Type	Description	Default
as_dict	bool	If True, the method returns positions as a dictionary, otherwise as a quantpylib.standards.Positions object. Defaults to True.	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

predicted_funding_rate(symbol) async

Retrieve the predicted funding rate for a specific contract.

predicted_funding_rate_all() async

Retrieve the predicted funding rate for all contracts.

rand_cloid(start='', end='', **kwargs)

Generate a random client order ID.

Parameters:

Name	Type	Description	Default
start	str	String representation of an integer between 0 and 9223372036854775807. Defaults to ''.	''
end	str	String representation of an integer between 0 and 9223372036854775807. Defaults to ''.	''

send_order(symbol, order_type, side, reduce_only=False, **kwargs) async

Send an order to the exchange.

system_maintenance_status() async

Retrieve the system maintenance status.

trades_subscribe(ticker, handler, standardize_schema=True, **kwargs) async

Subscribe to trade updates.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker symbol.	required
handler	coroutine	A coroutine handler for the message received.	required
standardize_schema	(bool, True)	Processes the incoming message to (ts,price,sz,dir)	True
**kwargs		Exchange wrapper specific keyword arguments.	{}

trades_unsubscribe(ticker, **kwargs) async

Unsubscribe from trade updates.

Parameters:

Name	Type	Description	Default
ticker	str	Ticker symbol.	required
**kwargs		Exchange wrapper specific keyword arguments.	{}

update_futures_leverage_setting(symbol, margin_mode, position_side, leverage) async

Update the futures leverage setting.

update_isolated_margin(**kwargs) async

Update the isolated margin.

update_leverage_setting(leverage) async

Update the leverage setting.