> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futuur.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reading the order book

> How to read and interpret the order book for a prediction market.

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.

<Note>
  All examples use the base URL `https://api.futuur.com`. The order book endpoint does not require authentication.
</Note>

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

<CodeGroup>
  ```python python theme={null}
  import requests

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

  order_book = response.json()
  print(order_book)
  ```

  ```bash curl theme={null}
  curl -G "https://api.futuur.com/markets/67890/book/" \
    --data-urlencode "currency_mode=play_money" \
    --data-urlencode "position=long"
  ```
</CodeGroup>

### 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

```json theme={null}
{
  "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 python theme={null}
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.

<Tip>
  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`.
</Tip>

## 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 python theme={null}
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.

<Warning>
  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.
</Warning>

## 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 python theme={null}
response = requests.get(
    "https://api.futuur.com/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)
```