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.
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 the base URL https://api.futuur.com. Every request requires HMAC authentication headers. See the Authentication guide for how to generate them. 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 /events/{id}/order_book/ with the required currency_mode and market parameters.
import requests
response = requests.get(
"https://api.futuur.com/events/12345/order_book/",
params={
"currency_mode": "play_money",
"market": 67890,
"position": "long",
},
headers={
"Key": "YOUR_PUBLIC_KEY",
"Timestamp": "1712500000",
"HMAC": "YOUR_HMAC_SIGNATURE",
},
)
order_book = response.json()
print(order_book)
Required parameters
| Parameter | Type | Description |
|---|
currency_mode | string | play_money or real_money |
market | integer | The market ID to query |
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 |
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.
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}")
- 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.
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.")
- 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 |
position=short) to see relevant bids.
response = requests.get(
"https://api.futuur.com/events/12345/order_book/",
params={
"currency_mode": "play_money",
"market": 67890,
"position": "short",
},
headers={
"Key": "YOUR_PUBLIC_KEY",
"Timestamp": "1712500000",
"HMAC": "YOUR_HMAC_SIGNATURE",
},
)
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)
