Orderbook

What is an Orderbook?

An orderbook is a real-time list of all outstanding buy (bid) and sell (ask) orders for a trading instrument. It shows the depth of the market and helps traders understand supply and demand at different price levels.

Structure

The orderbook consists of two sides:

Buy Orders (Bids)

Sorted by price in descending order (highest first):

Price    Size    Orders
-------------------------
1000     150     3 orders
999      200     5 orders
998      100     2 orders
995      300     4 orders

The top bid (highest price) is the best bid.

Sell Orders (Asks)

Sorted by price in ascending order (lowest first):

Price    Size    Orders
-------------------------
1005     100     2 orders
1008     250     4 orders
1010     150     3 orders
1015     200     2 orders

The top ask (lowest price) is the best ask.

Key Concepts

Best Bid and Best Ask

Best Bid: The highest price a buyer is willing to pay
Best Ask: The lowest price a seller is willing to accept

// Get best bid
GET /book/{market}/bid

// Get best ask
GET /book/{market}/ask

Bid-Ask Spread

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

Spread = Best Ask - Best Bid

A tighter spread indicates a more liquid market with better price discovery.

Example:

Best Ask: 1005
Best Bid: 1000
Spread: 5 (or 0.5%)

Market Depth

Market depth shows the quantity available at each price level. Deep markets have:

✅ Large quantities at multiple price levels
✅ Tight spreads
✅ Less price impact for large orders

Orderbook Operations

Adding Orders

When a limit order doesn't immediately match, it's added to the orderbook:

Determine Side

Bid orders go to the bid side
Ask orders go to the ask side

Find Price Level

Locate or create the appropriate price level in the sorted structure.

Append Order

Add the order to the queue at that price level (FIFO).

Update Volume

Increment the total volume at that price level.

Removing Orders

Orders are removed from the orderbook when:

Fully Matched: The order is completely filled
Cancelled: User cancels the order
Partially Filled: Part of the order is matched, remainder stays

Matching Orders

The orderbook facilitates matching by:

Maintaining sorted price levels
Providing O(1) access to best bid/ask
Supporting efficient traversal for multi-level matches

Price Levels

Each price level maintains:

type Limit struct {
    Price       float64      // Price of this level
    Orders      []*Order     // Queue of orders at this price
    TotalVolume int          // Total size across all orders
}

Example

At price level 1000:

{
  "Price": 1000,
  "TotalVolume": 150,
  "Orders": [
    {"ID": 1, "Size": 50, "UserID": 5},
    {"ID": 2, "Size": 75, "UserID": 7},
    {"ID": 3, "Size": 25, "UserID": 9}
  ]
}

Visualization

Here's how an orderbook might look:

┌─────────────────────────────────────┐
│           ORDERBOOK - INN           │
├─────────────────────────────────────┤
│                                     │
│  ASKS (Sell Orders)                 │
│  ─────────────────────              │
│  1015  │███████░░░│  200            │
│  1010  │██████████│  150            │
│  1008  │████████░░│  250            │
│  1005  │█████░░░░░│  100  ← Best Ask│
│                                     │
│  ──────────────── Spread: 5 ───────│
│                                     │
│  1000  │██████████│  150  ← Best Bid│
│   999  │████████░░│  200            │
│   998  │█████░░░░░│  100            │
│   995  │████████░░│  300            │
│  ─────────────────────              │
│  BIDS (Buy Orders)                  │
│                                     │
└─────────────────────────────────────┘

Implementation Details

Data Structure

The orderbook uses efficient data structures for fast operations:

type Orderbook struct {
    asks   []*Limit              // Sorted asks (ascending)
    bids   []*Limit              // Sorted bids (descending)
    Orders map[int64]*Order      // Fast order lookup
    Trades []*Trade              // Trade history
}

Adding an Order

func (ob *Orderbook) PlaceOrder(
    price float64,
    o *Order,
) []Trade {
    // Try to match first
    if matches := ob.match(o); len(matches) > 0 {
        return matches
    }
    
    // Add to appropriate side
    if o.Bid {
        ob.addBidOrder(price, o)
    } else {
        ob.addAskOrder(price, o)
    }
    
    return []Trade{}
}

Performance

Operation	Complexity
Get Best Bid/Ask	O(1)
Add Order	O(1) amortized
Match Order	O(k) where k = matches
Cancel Order	O(1)

Real-Time Updates

In a production system, orderbook changes trigger events:

Order added
Order matched
Order cancelled
Trade executed
Price level changed

These events can be streamed to clients via WebSocket for real-time updates.

Next Steps

Matching Engine

Learn how orders are matched

Market Maker

Understand automated market making

Examples

See orderbook operations in action

Orderbook

Matching Engine

Market Maker

Examples

On this page