Skip to main content

Orderbook Data

Each market on InTots maintains a live orderbook of resting limit orders. The orderbook endpoint provides a snapshot of all open bids and asks, which you can use to display depth, calculate spread, and estimate execution prices.

Endpoint​

GET /api/v1/market/orderbook/{market_id}

Path Parameters​

ParameterTypeDescription
market_idstringThe market ID to query.

Response​

{
  "market_id": "mkt_001",
  "bids": [
    { "price": 5500, "amount": 120000 },
    { "price": 5400, "amount": 85000 },
    { "price": 5200, "amount": 200000 }
  ],
  "asks": [
    { "price": 5700, "amount": 95000 },
    { "price": 5800, "amount": 150000 },
    { "price": 6000, "amount": 60000 }
  ]
}

Field Reference​

FieldTypeDescription
market_idstringThe market this orderbook belongs to.
bidsarrayBuy orders, sorted highest price first (descending).
asksarraySell orders, sorted lowest price first (ascending).
bids[].priceintegerBid price on the 0--10000 scale.
bids[].amountintegerTotal quantity available at this price level, in share cents.
asks[].priceintegerAsk price on the 0--10000 scale.
asks[].amountintegerTotal quantity available at this price level, in share cents.

Sort Order​

  • Bids are sorted from highest to lowest price. The first bid is the best bid (the highest price a buyer is willing to pay).
  • Asks are sorted from lowest to highest price. The first ask is the best ask (the lowest price a seller is willing to accept).

This ordering means the top of each array always represents the most competitive price.

Understanding Prices​

Prices are integers in the range 0 to 10000, representing a probability from 0% to 100% with two decimal places of precision.

Raw PriceDisplay
00.00%
250025.00%
550055.00%
10000100.00%

To convert to a human-readable percentage: price / 100.

Understanding Amounts​

Amounts are expressed in share cents. One full share equals 100 share cents. To display the number of whole shares at a price level:

shares = amount / 100

For example, an amount of 120000 means 1,200 shares are available at that price level.

Calculating the Spread​

The spread is the gap between the best ask and the best bid:

spread = best_ask.price - best_bid.price

Using the example response above:

spread = 5700 - 5500 = 200  (i.e. 2.00 percentage points)

A narrow spread indicates a liquid, actively traded market. A wide spread suggests thin liquidity or low trading activity.

Interpreting the Orderbook​

Depth​

The orderbook shows you how much liquidity is available at each price level. Summing the amounts across all bid levels gives you the total buy-side depth; summing the asks gives you the sell-side depth.

total_bid_depth = sum(bid.amount for each bid)
total_ask_depth = sum(ask.amount for each ask)

Estimated Execution Price​

To estimate the cost of a market buy of N shares, walk up the ask side:

  1. Start with the lowest ask.
  2. Consume shares at that price until the level is exhausted or your order is filled.
  3. Move to the next ask level if needed.
  4. The volume-weighted average price across consumed levels is your estimated execution price.

The same logic applies in reverse for market sells, walking down the bid side.

Hybrid Execution (Orderbook + AMM)​

InTots uses a hybrid model: incoming orders are first matched against resting limit orders in the orderbook. Any residual quantity that cannot be filled by the orderbook is routed to the LMSR automated market maker (AMM). This means:

  • The orderbook snapshot shows only the limit-order liquidity.
  • Additional liquidity is always available via the AMM, so orders will never fail to execute (though the AMM price may differ from the orderbook price).
  • For small orders in liquid markets, the orderbook typically provides better prices than the AMM.

Example: Fetching and Displaying the Orderbook​

curl "https://api.intots.com/api/v1/market/orderbook/mkt_001"
const res = await fetch('/api/v1/market/orderbook/mkt_001');
const book = await res.json();

const bestBid = book.bids[0];
const bestAsk = book.asks[0];
const spread = bestAsk.price - bestBid.price;

console.log(`Best Bid: ${bestBid.price / 100}% (${bestBid.amount / 100} shares)`);
console.log(`Best Ask: ${bestAsk.price / 100}% (${bestAsk.amount / 100} shares)`);
console.log(`Spread:   ${spread / 100} pp`);

Tips​

  • Poll periodically or combine with the WebSocket trades feed to keep your display current. The orderbook endpoint returns a point-in-time snapshot.
  • Empty arrays for bids or asks mean there are no resting limit orders on that side. The AMM still provides liquidity.
  • Price levels are aggregated. Each entry represents the total amount across all individual orders at that exact price.