Skip to content

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, logger=None)

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, standardize_schema=1, **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 the user-facing order fill consumer.

account_fills_get(start_ms=None, end_ms=None, **kwargs) async

Retrieve normalized fills over the half-open range [start_ms, end_ms).

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

Keeps a local mirror copy of account fills.

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.

bba_subscribe(ticker, handler, standardize_schema=1, **kwargs) async

Subscribe to best bid/ask updates.

Parameters:

Name Type Description Default
ticker str

Ticker symbol.

 required
handler coroutine

Callback invoked for each best bid/ask update.

 required
standardize_schema int

Payload schema mode. 0 passes the raw provider payload, 1 emits the legacy {ts,bid,ask,bid_sz,ask_sz} dictionary, and 2 emits quantpylib.standards.models.BBAUpdate. Defaults to 1.

 1
**kwargs

Exchange wrapper specific keyword arguments.

 {}

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(ticker, oid=None, cloid=None, **kwargs) async

Cancel an order.

Parameters:

Name Type Description Default
ticker str

Ticker symbol.

 required
oid int

Order ID to cancel.

 None
cloid int

Client Order ID to cancel.

 None
**kwargs

Exchange wrapper specific keyword arguments.

 {}

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.

cancel_wire(ticker, oid=None, cloid=None, **kwargs) async

Build an exchange-native cancel wire.

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=1, **kwargs) async

Retrieve an L2 order-book snapshot.

Parameters:

Name Type Description Default
ticker str

Ticker symbol.

 required
depth int

WooX order-book depth limit. Defaults to 100.

 100
standardize_schema int

Payload schema mode. 0 returns the raw provider payload, 1 returns the legacy {ts,b,a} dictionary, and 2 returns quantpylib.standards.models.BookUpdate. Defaults to 1.

 1
**kwargs

Exchange wrapper specific keyword arguments.

 {}

Returns:

Type Description
dict | BookUpdate

Order book data in the selected schema.

l2_book_mirror(ticker, depth=50, buffer_size=100, as_dict=True, on_update=None, apply_shadow_depth=False, **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 local order-book representation. Defaults to 50.

 50
buffer_size int

Size of the local order-book buffer. Defaults to 100.

 100
as_dict bool

If True, pass state as a {ts,b,a} dictionary; otherwise pass the local LOB object into handlers. Defaults to True.

 True
on_update coroutine

Callback invoked after local mirror updates. Defaults to None.

 None
apply_shadow_depth bool

Whether to maintain additional book levels inside the LOB. Defaults to False.

 False
**kwargs

Exchange wrapper specific keyword arguments.

 {}

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

Return the local L2 order-book mirror created by l2_book_mirror().

Parameters:

Name Type Description Default
ticker str

Ticker symbol.

 required
as_dict bool

If True, return the mirror as a {ts,b,a} dictionary; otherwise return the local LOB object. Defaults to True.

 True
**kwargs

Exchange wrapper specific keyword arguments.

 {}

Returns:

Type Description
dict | LOB

Current mirrored order-book state.

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

Subscribe to L2 order-book updates.

Parameters:

Name Type Description Default
ticker str

Ticker symbol.

 required
handler coroutine

Callback invoked for each order-book update.

 required
speed_ms int

WooX stream cadence in milliseconds. Defaults to 200.

 200
standardize_schema (int, 1)

Payload schema mode. 0 passes the raw provider payload, 1 emits the legacy {ts,b,a} dictionary, and 2 emits quantpylib.standards.models.BookUpdate.

 1
**kwargs

Exchange wrapper specific keyword arguments.

 {}

l2_book_subscriptions(**kwargs)

Return active L2 order-book subscription identifiers.

Returns:

Type Description
list

Open L2 order-book subscription identifiers.

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

Unsubscribe from L2 order-book updates.

Parameters:

Name Type Description Default
ticker str

Ticker symbol.

 required
speed_ms int

WooX stream cadence used for the subscription. 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 the user-facing order event consumer.

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, woo_only=True, **kwargs) async

Subscribe to public trade updates.

Parameters:

Name Type Description Default
ticker str

Ticker symbol.

 required
handler coroutine

Callback invoked for each trade update.

 required
standardize_schema int

Payload schema mode. 0 passes the raw provider payload, 1 emits the legacy normalized (ts,price,sz,dir) tuple, and 2 emits quantpylib.standards.models.TradeUpdate. Defaults to True (1).

 True
woo_only bool

If True, only emit trades executed on WooX. Defaults to True.

 True
**kwargs

Exchange wrapper specific keyword arguments.

 {}

trades_unsubscribe(ticker, **kwargs) async

Unsubscribe from public 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.