Skip to main content

Query the Pool

info

This documentation is for version 3 of DeepBook. For documentation on version 2 of DeepBook, see DeepBookV2 docs.

The Pool shared object represents a market, such as a SUI/USDC market. That Pool is the only one representing that unique pairing (SUI/USDC) and the pairing is the only member of that particular Pool. See DeepBook Design to learn more about the structure of pools.

To perform trades, you pass a BalanceManager and TradeProof into the relvant Pool. Unlike Pools, BalanceManager shared objects can contain any type of token, such that the same BalanceManager can access multiple Pools to interact with many different trade pairings. See BalanceManager to learn more.

API​

DeepBook exposes a set of endpoints that can be used to query any pool.

Check whitelist status​

Accessor to check whether the pool is whitelisted.

public fun whitelisted<BaseAsset, QuoteAsset>(self: &Pool<BaseAsset, QuoteAsset>): bool

Check quote quantity against base​

Dry run to determine the quote quantity out for a given base quantity.

public fun get_quote_quantity_out<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    base_quantity: u64,
    clock: &Clock,
): (u64, u64, u64)

Check quote quantity against quote​

Dry run to determine the base quantity out for a given quote quantity.

public fun get_base_quantity_out<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    quote_quantity: u64,
    clock: &Clock,
): (u64, u64, u64)

Check quote quantity against quote or base​

Dry run to determine the quantity out for a given base or quote quantity. Only one out of base or quote quantity should be non-zero. Returns the (base_quantity_out, quote_quantity_out, deep_quantity_required).

public fun get_quantity_out<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    base_quantity: u64,
    quote_quantity: u64,
    clock: &Clock,
): (u64, u64, u64)

Check fee required​

Returns the DEEP required for an order if it's a taker or maker given quantity and price (deep_required_taker, deep_required_maker).

public fun get_order_deep_required<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    base_quantity: u64,
    price: u64,
): (u64, u64)

Retrieve mid price for a pool​

Returns the mid price of the pool.

public fun mid_price<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    clock: &Clock,
): u64

Retrieve order IDs​

Returns the order_id for all open orders for the balance_manager in the pool.

public fun account_open_orders<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    balance_manager: ID,
): VecSet<u128>

Retrieve prices and quantities for an order book​

Returns vectors holding the prices (price_vec) and quantities (quantity_vec) for the level2 order book. The price_low and price_high are inclusive, all orders within the range are returned. is_bid is true for bids and false for asks.

public fun get_level2_range<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    price_low: u64,
    price_high: u64,
    is_bid: bool,
): (vector<u64>, vector<u64>)

Returns vectors holding the prices (price_vec) and quantities (quantity_vec) for the level2 order book. ticks are the maximum number of ticks to return starting from best bid and best ask. (bid_price, bid_quantity, ask_price, ask_quantity) are returned as four vectors. The price vectors are sorted in descending order for bids and ascending order for asks.

public fun get_level2_ticks_from_mid<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    ticks: u64,
): (vector<u64>, vector<u64>, vector<u64>, vector<u64>)

Retrieve balances​

Get all balances held in this pool.

public fun vault_balances<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64)

Retrieve pool ID​

Get the ID of the pool given the asset types.

public fun get_pool_id_by_asset<BaseAsset, QuoteAsset>(registry: &Registry): ID

Retrieve order information​

Returns the Order struct using the order ID.

public fun get_order<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    order_id: u128,
): Order

Returns a vector of Order structs using a vector of order IDs.

public fun get_orders<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    order_ids: vector<u128>,
): vector<Order>

Returns a vector of Order structs for all orders that belong to a BalanceManager in the pool.

public fun get_account_order_details<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    balance_manager: &BalanceManager,
): vector<Order>

Retrieve locked balance​

Returns the locked balance for a BalanceManager in the pool (base_quantity, quote_quantity, deep_quantity).

public fun locked_balance<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
    balance_manager: &BalanceManager,
): (u64, u64, u64)

Retrieve pool parameters​

Returns the trade parameters for the pool (taker_fee, maker_fee, stake_required).

public fun pool_trade_params<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64)

Returns the book parameters for the pool (tick_size, lot_size, min_size).

public fun pool_book_params<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
): (u64, u64, u64)

Returns the OrderDeepPrice struct for the pool, which determines the conversion for DEEP fees.

public fun get_order_deep_price<BaseAsset, QuoteAsset>(
    self: &Pool<BaseAsset, QuoteAsset>,
): OrderDeepPrice