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 getLiquidity 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.

struct Liquidity {
  Tick tick;
  uint64 depth;
}

/**
 * @notice Returns the liquidity for a specific book
 * @param id The id of the book
 * @param from The starting tick
 * @param n The number of ticks to return
 * @return liquidity An array of liquidity data
 */
function getLiquidity(BookId id, Tick from, uint256 n) external view returns (Liquidity[] memory liquidity);

2.2 Query via Subgraph

Alternatively, you can use the Subgraph to fetch the liquidity and properties of the book.

query {
  books {
    id
    unitSize
    depths {
      id
      unitAmount
    }
  }
}

# Example Response
{
  "books": [
    {
      "id": "1029758694116366057286854058921974392175473815953576661397",
      "unitSize": "1000000000000",
      "depths": [
        {
          "id": "1029758694116366057286854058921974392175473815953576661397-388836",
          "unitAmount": "17692139"
        },
        {
          "id": "1029758694116366057286854058921974392175473815953576661397-390453",
          "unitAmount": "1000"
        }
      ]
    }
  ]
}

2.3 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:

  $$\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.

2.4 Fee Policy

Clober’s fee policy is divided into maker fees and taker fees. For order book integration, only the taker fee needs to be considered. The direction of fee collection is determined by a variable called useQuote. For example:

In the ETH/USDC market, the bid book (base: ETH, quote: USDC):

• If useQuote is true, the fee is charged in USDC.
• If useQuote is false, the fee is charged in ETH.

In the ask book (base: USDC, quote: ETH):

• If useQuote is true, the fee is charged in ETH.
• If useQuote is false, the fee is charged in USDC.

The fee rate is based on a scale of 1e6, so a maximum fee rate of 500000 represents 50%. Typically, Clober uses a taker fee of 1 basis point (1 bp).

The fee policy contract implementation can be found here: FeePolicy.sol And its TypeScript equivalent can be found here: fee-policy/model.ts