CLOB Matching Engine

A high-performance Central Limit Order Book (CLOB) matching engine built with Rust and Axum.

Features

• Price-Time Priority Matching: Orders are matched based on best price first, then by arrival time (FIFO)
• Limit Orders: Support for buy and sell limit orders
• Real-time Matching: Immediate order matching against resting orders
• RESTful API: Simple HTTP API for order management
• Thread-safe: Concurrent access via RwLock for safe orderbook operations

Architecture

┌─────────────────────────────────────────────────────────┐
│                     ORDERBOOK                           │
│  ┌─────────────────────┐    ┌─────────────────────┐    │
│  │   BIDS (Buy Side)   │    │   ASKS (Sell Side)  │    │
│  │ Sorted by price     │    │ Sorted by price     │    │
│  │ (highest first)     │    │ (lowest first)      │    │
│  └─────────────────────┘    └─────────────────────┘    │
│           ↑                           ↑                 │
│           └─── SPREAD (gap) ──────────┘                 │
└─────────────────────────────────────────────────────────┘

Getting Started

Prerequisites

• Rust (edition 2024)
• Cargo

Installation

git clone <repository-url>
cd clob
cargo build --release

Running the Server

cargo run

Server starts at http://localhost:8080

API Endpoints

Health Check

GET /

Response:

{
  "status": "ok",
  "message": "Server is running on 8080"
}

---

Create Order

POST /create
Content-Type: application/json

Request Body:

{
  "price": 100,
  "quantity": 10,
  "user_id": 1,
  "side": "Buy"
}

Field	Type	Description
price	u32	Limit price
quantity	u32	Order quantity
user_id	u32	User identifier
side	string	"Buy" or "Sell"

Response:

{
  "order_id": 0,
  "filled_qty": 0,
  "remaining_qty": 10,
  "status": "open",
  "trades": []
}

Order Status:

• open - No matches, order resting in book
• partially_filled - Some quantity matched
• fully_filled - Entire order matched

---

Get Orderbook Depth

GET /depth

Response:

{
  "bids": [[99, 20], [98, 15]],
  "asks": [[100, 10], [101, 25]],
  "last_updated_id": "5"
}

Each entry is [price, total_quantity], sorted by best price first.

---

Delete Order (WIP)

DELETE /delete

Not yet implemented

Usage Examples

Create a Sell Order

curl -X POST http://localhost:8080/create \
  -H "Content-Type: application/json" \
  -d '{"price": 100, "quantity": 10, "user_id": 1, "side": "Sell"}'

Create a Matching Buy Order

curl -X POST http://localhost:8080/create \
  -H "Content-Type: application/json" \
  -d '{"price": 100, "quantity": 10, "user_id": 2, "side": "Buy"}'

View Orderbook Depth

curl http://localhost:8080/depth

Testing

Run the test suite:

cargo test

Run tests with output:

cargo test -- --nocapture

Project Structure

clob/
├── src/
│   ├── main.rs        # Application entry point, router setup
│   ├── orderbook.rs   # Matching engine logic
│   ├── routes.rs      # API route handlers
│   ├── input.rs       # Request DTOs
│   ├── output.rs      # Response DTOs
│   └── errors.rs      # Error handling
├── tests/
│   └── api_tests.rs   # Integration tests
└── Cargo.toml

License

MIT