Prices and order book

Each market has one order book. Buyers and sellers of both outcomes trade in it, and Predict matches their orders off-chain and settles the matches on-chain.

Understanding the order book in the product docs explains the basics, such as limit and market orders and the spread. This page covers how the API sends the book.

Reading the bookCopy Anchor Link

The Get market orderbook endpoint returns the current book:

{
  "success": true,
  "data": {
    "marketId": 1,
    "updateTimestampMs": 1727910141000,
    "asks": [
      [0.492, 30192.26],
      [0.493, 20003]
    ],
    "bids": [
      [0.491, 303518.1],
      [0.49, 1365.44]
    ]
  }
}

Where:

Prices are in USDT per share, from 0 to 1, and read as probabilities: a Yes price of 0.62 means a 62% chance. A price never has more decimals than the market's decimalPrecision.

Only the best pricesCopy Anchor Link

When you only need the current price, use Get market quote instead of the whole book. It returns the best bid and the best ask, each with its price and size, priced in Yes like the book.

To follow many markets, Get quotes for multiple markets returns the quotes of up to 500 markets in one request, and Get orderbooks for multiple markets returns the whole books of up to 100. Pass the market IDs as ids, for example ?ids=123&ids=456.

To stream the best prices, subscribe to the top of book topic of the WebSocket API, predictTopOfBook/{marketId}. It sends the best bid and the best ask each time either changes. The topic sends each as a [price, shares] pair, like the order book, while the quote endpoints send an object with price and size.

Getting the No sideCopy Anchor Link

A Yes order and a No order at complementary prices are the same trade seen from the two sides. Buying No at 0.38 takes the same liquidity as selling Yes at 0.62. So the No book is the Yes book with its sides swapped and each price replaced by its complement:

• No bids come from the Yes asks. The best No bid, the most you can sell No for right now, is 1 − best Yes ask.
• No asks come from the Yes bids. The best No ask, the least you can buy No for right now, is 1 − best Yes bid.
• The share amounts stay the same.

Compute the complement at the market's decimalPrecision, so that the Yes and No prices add up to exactly 1. A plain 1 - price can give values such as 0.37999999999999995, which don't match the prices the backend uses.

type Level = [price: number, shares: number];

// The No price of a Yes price, at the market's decimal precision.
function getComplement(price: number, decimalPrecision = 2): number {
  const factor = 10 ** decimalPrecision;
  return (factor - Math.round(price * factor)) / factor;
}

// The No book from the Yes book the API sends.
function toNoBook(asks: Level[], bids: Level[], decimalPrecision: number) {
  const flip = ([price, shares]: Level): Level => [
    getComplement(price, decimalPrecision),
    shares,
  ];
  return { asks: bids.map(flip), bids: asks.map(flip) };
}

With the book above and a precision of 3, the best No bid is getComplement(0.492, 3) = 0.508 and the best No ask is getComplement(0.491, 3) = 0.509.

If one side of the Yes book is empty, the opposite side of the No book is empty too. Check for that before you read asks[0] or bids[0].

Live updatesCopy Anchor Link

For a live book, subscribe to the order book topic of the WebSocket API, predictOrderbook/{marketId}. The latest book usually arrives right after you subscribe, then a new copy every time it changes.

The WebSocket copy has a few more fields than the REST response:

Liquidity in settlementsPending is already matched. It can come back to the book if the settlement fails. See Order lifecycle.