Order Book Depth

Get the current order book depth for a specific Deepbook pool. Returns all active bids and asks with their price levels, quantities, and order counts. This provides a snapshot of liquidity available at each price level.

Endpoint

GET /deepbook/{poolName}/order-book-depth

Use Cases

• Depth Charts — Visualize liquidity distribution across price levels
• Market Making — Analyze spread and depth to inform order placement strategies
• Trading Interfaces — Display the order book to users before trade execution
• Liquidity Analysis — Measure available liquidity for large orders and slippage estimation

Parameters

Path Parameters

Parameter	Type	Required	Description
poolName	string	Yes	The Deepbook pool name (e.g., "SUI_USDC")

Query Parameters

Parameter	Type	Required	Default	Description
limit	number	No	20	Maximum number of price levels to return for each side (bids/asks). Max 20.
api-key	string	Yes	—	Your Surflux API key for authentication

Response

Returns an object containing the pool ID and arrays of bid and ask price levels.

Field	Type	Description
pool_id	string	Unique identifier for the pool
bids	array	Array of bid price levels (buy orders), sorted highest to lowest
asks	array	Array of ask price levels (sell orders), sorted lowest to highest

Bid/Ask Object Structure

Each bid and ask object contains:

Field	Type	Description
price	number	Price level (in smallest units based on asset decimals)
total_quantity	number	Total quantity available at this price level
order_count	number	Number of individual orders at this price level

Example Response

{
  "pool_id": "0xe05dafb5133bcffb8d59f4e12465dc0e9faeaa05e3e342a08fe135800e3e4407",
  "bids": [
    {
      "price": 3380100,
      "total_quantity": 2957000000000,
      "order_count": 2
    },
    {
      "price": 3380000,
      "total_quantity": 2366000000000,
      "order_count": 1
    },
    {
      "price": 3379900,
      "total_quantity": 443800000000,
      "order_count": 1
    }
  ],
  "asks": [
    {
      "price": 3380500,
      "total_quantity": 443700000000,
      "order_count": 1
    },
    {
      "price": 3381200,
      "total_quantity": 11239000000000,
      "order_count": 4
    },
    {
      "price": 3383700,
      "total_quantity": 8000000000000,
      "order_count": 1
    }
  ]
}

Example Request

curl "https://api.surflux.dev/deepbook/SUI_USDC/order-book-depth?limit=20&api-key=YOUR_API_KEY"

const apiKey = 'YOUR_API_KEY';
const poolName = 'SUI_USDC';
const limit = 20;

const url = `https://api.surflux.dev/deepbook/${poolName}/order-book-depth?limit=${limit}&api-key=${apiKey}`;

const response = await fetch(url);
const orderBook = await response.json();

console.log(`Bids: ${orderBook.bids.length} levels`);
console.log(`Asks: ${orderBook.asks.length} levels`);

// Best bid and ask (spread)
const bestBid = orderBook.bids[0];
const bestAsk = orderBook.asks[0];
const spread = bestAsk.price - bestBid.price;

console.log(`Best bid: ${bestBid.price}, Best ask: ${bestAsk.price}`);
console.log(`Spread: ${spread}`);

Understanding Price and Quantity Values

Price and quantity values are returned in smallest units based on the asset's decimals.

Converting Prices

To convert prices to human-readable format, you need both the base and quote asset decimals from the Get Pools endpoint.

Example for SUI_USDC pool:

• Base asset (SUI): 9 decimals
• Quote asset (USDC): 6 decimals
• Raw price: 3380500

Human-readable price calculation:

price_per_sui = (raw_price / 10^quote_decimals) / (1 / 10^base_decimals)
             = (3380500 / 10^6) / (1 / 10^9)
             = 3.3805 USDC per SUI

Converting Quantities

Quantities represent the base asset and should be divided by 10^base_decimals.

Example:

• Raw quantity: 443700000000
• Base decimals: 9 (SUI)
• Human-readable: 443700000000 / 10^9 = 443.7 SUI

Best Practices

• Request Appropriate Depth — Use the limit parameter to request only the depth you need. Most trading UIs show 10-20 levels.
• Calculate Spread — The difference between bids[0].price and asks[0].price is the current bid-ask spread.
• Estimate Slippage — Sum quantities across price levels to estimate execution price for large orders.
• Combine with Live Stream — Use this endpoint for initial order book state, then maintain updates via Deepbook Flux Stream for real-time changes.
• Cache Pool Metadata — Fetch pool decimals once from Get Pools endpoint and reuse for all price conversions.