Skip to main content

2. Querying Book Liquidity

There are two methods to query the liquidity of a book.

2.1 On-Chain Query​

If you have the book ID from step 1, you can query the book’s liquidity using the get_liquidity function from the BookViewer contract.

  • Pass the maximum value of 2^19 - 1 for the tick parameter to retrieve the liquidity. (minimum value is -(2^19 - 1))
  • The type Tick is int24.
#[derive(Copy, Drop, Serde)]
pub struct Liquidity {
  pub tick: Tick,
  pub depth: u64,
}

/**
 * @notice Returns the liquidity for a specific book
 * @param book_id The id of the book
 * @param tick The starting tick
 * @param n The number of ticks to return
 * @return liquidity An array of liquidity data
 */
fn get_liquidity(
  self: @TContractState, book_id: felt252, tick: Tick, n: u32
) -> Span<Liquidity>;

2.2 Converting Tick and Unit Amounts​

Once you have obtained the tick and unitAmount (or depth) list through method 2.1 or 2.2, you can convert them into human-readable values as follows:

  • Amount (in wei): unitAmount * unitSize

  • Human-readable price:

    price=toPrice(tick)×10baseDecimals296×10quoteDecimals\text{price} = \frac{\text{toPrice}( \text{tick} ) \times 10^{\text{baseDecimals}}}{2^{96} \times 10^{\text{quoteDecimals}}}
    • toPrice: A function that converts a tick into a price.
    • formatPrice: A function that converts a price into a human-readable value.

Note: Price has three layers: tick, price used in the contract (base 2⁹⁶), and human-readable price.

Example 1

In the case of the ETH/USDC bid book, when the tick value is -193379, the toPrice function calculates a price of 316924790063341364079. Using the above formula, the actual human-readable price becomes 4000.1532. (baseDecimals / quoteDecimals → 18 / 6)

Example 2

In the case of the USDC/ETH ask book, when the tick value is 193379, the toPrice function calculates a price of 19806281907237751425182398969079973056. Using the above formula, the actual human-readable price becomes 0.0002499904235904979. (baseDecimals / quoteDecimals → 6 / 18) It means ETH is asked at around 4000 ( = 1 / 0.0002499904235904979 ).

Note: Flipping the sign of the tick essentially produces the reciprocal of the human-readable price.