Reading the order book

The order book shows all open buy (bid) and sell (ask) orders for a market outcome, aggregated by price level. Use it to understand where the market is trading and to pick a good price for a limit order.

All examples use https://api.futuur.com/v2.0. The order book endpoint does not require authentication.

What the order book shows

The order book aggregates open orders at each price level into two sides:

Bids (bid in the response) — buyers willing to pay up to a certain price (buy orders)
Asks (ask in the response) — sellers willing to accept at least a certain price (sell orders)

Each level shows the quantity available and the cumulative depth of the book up to that price. This tells you how much liquidity exists and at what prices.

Fetching the order book

Call GET /markets/{id}/book/ with the required currency_mode parameter and the market ID in the path.

import requests

response = requests.get(
    "https://api.futuur.com/v2.0/markets/67890/book/",
    params={
        "currency_mode": "play_money",
        "position": "long",
    },
)

order_book = response.json()
print(order_book)

curl -G "https://api.futuur.com/v2.0/markets/67890/book/" \
  --data-urlencode "currency_mode=play_money" \
  --data-urlencode "position=long"

Required parameters

Parameter	Type	Description
`id` (path)	integer	The market ID to query
`currency_mode`	string	`play_money` or `real_money`

Optional parameters

Parameter	Type	Default	Description
`position`	string	`long`	`long` for long order book, `short` for short order book

Example response

{
  "bid": [
    {
      "price": 0.62,
      "total_shares": 500.0,
      "total_amount": 310.0,
      "total_fees": 0.50,
      "cumulative_shares": 500.0,
      "cumulative_amount": 310.0,
      "cumulative_fees": 0.50
    },
    {
      "price": 0.60,
      "total_shares": 1200.0,
      "total_amount": 720.0,
      "total_fees": 1.20,
      "cumulative_shares": 1700.0,
      "cumulative_amount": 1030.0,
      "cumulative_fees": 1.70
    },
    {
      "price": 0.58,
      "total_shares": 800.0,
      "total_amount": 464.0,
      "total_fees": 0.80,
      "cumulative_shares": 2500.0,
      "cumulative_amount": 1494.0,
      "cumulative_fees": 2.50
    }
  ],
  "ask": [
    {
      "price": 0.65,
      "total_shares": 300.0,
      "total_amount": 195.0,
      "total_fees": 0.30,
      "cumulative_shares": 300.0,
      "cumulative_amount": 195.0,
      "cumulative_fees": 0.30
    },
    {
      "price": 0.67,
      "total_shares": 750.0,
      "total_amount": 502.5,
      "total_fees": 0.75,
      "cumulative_shares": 1050.0,
      "cumulative_amount": 697.5,
      "cumulative_fees": 1.05
    }
  ]
}

Order book fields

Each level in the bid and ask arrays contains the following fields:

Field	Type	Description
`price`	float	The price level (0 to 1, representing probability)
`total_shares`	float	Total shares available at exactly this price level
`total_amount`	float	Total currency amount at exactly this price level
`total_fees`	float	Total fees attributable to the shares at this price level
`cumulative_shares`	float	Total shares available at this price level and better
`cumulative_amount`	float	Total currency amount at this price level and better
`cumulative_fees`	float	Cumulative fees from the top of the book through this level

For bids, levels are sorted from highest price to lowest (best bid first). For asks, levels are sorted from lowest price to highest (best ask first).

Interpreting the best bid and ask

The best bid is the first entry in the bid array — the highest price a buyer is currently willing to pay. The best ask is the first entry in ask — the lowest price a seller will accept.

python

best_bid = order_book["bid"][0]["price"] if order_book["bid"] else None
best_ask = order_book["ask"][0]["price"] if order_book["ask"] else None

if best_bid and best_ask:
    spread = round(best_ask - best_bid, 4)
    mid_price = round((best_bid + best_ask) / 2, 4)
    print(f"Best bid: {best_bid}, Best ask: {best_ask}")
    print(f"Spread: {spread}, Mid price: {mid_price}")

For the example response above:

Best bid: 0.62
Best ask: 0.65
Spread: 0.03 (3 cents per share)
Mid price: 0.635

A narrow spread indicates high liquidity. A wide spread means fewer active traders and more price uncertainty.

The mid-price is a useful reference point. Placing a limit order just inside the spread — for example, a bid at 0.63 — can get you a better fill price than a market order at the best ask of 0.65.

Using the order book to pick a limit price

The cumulative_shares field tells you how much total liquidity is available up to a given price. Use this to estimate how many shares you can buy or sell at a target price.

python

target_shares = 1000.0

for level in order_book["ask"]:
    if level["cumulative_shares"] >= target_shares:
        print(f"You can buy {target_shares} shares up to price {level['price']}")
        break
else:
    print("Not enough liquidity in the book to fill this order at any listed level.")

For the example response:

Buying 300 shares: best ask at 0.65 covers it (cumulative_shares = 300)
Buying 1000 shares: requires depth up to 0.67 (cumulative_shares = 1050)

Setting your limit price at 0.67 or placing a market order would fill a 1000-share buy in this scenario.

Liquidity changes continuously. The order book snapshot you fetch may be stale by the time your order executes. For large orders, consider splitting into smaller chunks.

Long vs short order books

The position parameter controls which order book you’re viewing:

Value	Description
`long` (default)	Long order book — orders betting the outcome happens
`short`	Short order book — orders betting the outcome does not happen

Long and short positions trade in separate books. If you hold a short position and want to sell, fetch the short order book (position=short) to see relevant bids.

python

response = requests.get(
    "https://api.futuur.com/v2.0/markets/67890/book/",
    params={
        "currency_mode": "play_money",
        "position": "short",
    },
)

short_book = response.json()
best_short_bid = short_book["bid"][0]["price"] if short_book["bid"] else None
print("Best bid for short shares:", best_short_bid)

Realtime order-book updates

Subscribe to the per-event Pusher channel event-{event_id} and listen for order-book-update. That event carries absolute top-N bid/ask levels for the affected market — apply them directly for top-of-book quoting. Full-depth snapshots are not streamed over Pusher. When you need depth beyond top-N, call the REST order book endpoint. See Channels and events for the payload.

Get Started

Core Concepts

Guides

Reading the order book

What the order book shows

Fetching the order book

Required parameters

Optional parameters

Example response

Order book fields

Interpreting the best bid and ask

Using the order book to pick a limit price

Long vs short order books

Realtime order-book updates

​What the order book shows

​Fetching the order book

​Required parameters

​Optional parameters

​Example response

​Order book fields

​Interpreting the best bid and ask

​Using the order book to pick a limit price

​Long vs short order books

​Realtime order-book updates

What the order book shows

Fetching the order book

Required parameters

Optional parameters

Example response

Order book fields

Interpreting the best bid and ask

Using the order book to pick a limit price

Long vs short order books

Realtime order-book updates