TitaniumBOE-Sim

Simulator of Cboe's BOE binary protocol with a matching engine, trading bots, REST API, WebSocket feed, and dashboard — all packaged in a single deployable JAR.

  • Java 21
  • Virtual Threads
  • Javalin
  • RocksDB
  • Docker
  • JUnit 5
GitHub ↗ DeepWiki ↗

The Problem

Cboe's BOE (Binary Order Entry) protocol is the binary standard used by institutional traders to send orders to U.S. options exchanges. It is not human-readable text: each message is an exact sequence of bytes in Little Endian format, with fixed-size fields, prices encoded with 4 implicit decimal places, and optional fields controlled by bitfields negotiated at session start.

Understanding how it works internally — and being able to experiment with it — is practically impossible without access to real trading systems.

The Solution

A full simulator that speaks the same language as Cboe, byte by byte, following the official spec v2.11.90. Any real BOE client can connect as if it were the actual exchange.

The system includes:

  • Matching engine with price-time priority — orders are matched by price and, within the same price, by arrival order (FIFO)
  • 3 trading bots that maintain constant market activity: Market Maker (provides liquidity on both sides), Trend Follower (follows momentum) and Random Trader (simulates market noise)
  • REST API + WebSocket for real-time market data and operations from any HTTP client
  • Web dashboard (Astro + Tailwind) served directly from the JAR — no extra server or build step
  • Interactive CLI to connect, submit orders and monitor the order book from the terminal
  • Full persistence with RocksDB: orders, trades and sessions survive restarts

Under the Hood

Each TCP connection runs on its own Java 21 Virtual Thread — the simplest model (blocking I/O) without the cost of real OS threads. Result: over 500 concurrent sessions with P99 Order Acknowledgment latency under 5ms.

The matching engine synchronizes per symbol instead of globally: AAPL and SPX can run matching in parallel without blocking each other. Writes to RocksDB go through an async queue — the client receives its confirmation before anything touches disk.

Protocol messages are modeled as Java 21 sealed classes, enabling exhaustive dispatch verified at compile time: adding a new message type without handling it is a compile error, not a silent bug.

Ti
TitaniumBOE-Sim · Arquitectura
Cboe Titanium U.S. Options BOE v2.11.90 · Java 21 · Virtual Threads
▶ Pruébalo — arrastra nodos · click para inspeccionar
clienteedgecoredatasim
HTTP / WSTCP binarydispatchprocessOrder()saveAsync()tradesREST looptrade eventsBrowser / DashboardAstro 5 · TailwindCLI · BOE Client SDKexternal integrationsRestApiServerJavalin 6.7 · :9091RESTWS /ws/feedScalar UICboeServerNIO · TCP :8081VThread/connLoginHeartbeatClientConnectionHandler1 sesión = 1 VThreadOrderManagervalida · enruta · respondeOrderValidatorack/rejectMatchingEnginelock por símbolo · FIFOOrderBook<sym>TreeMap<BigDecimal,List<Order>>price-time priorityPersistence LayerRocksDB 9.11 · write-behindOrderRepositoryTradeRepository6 column familiesBotManagerVThreads paralelosMarketMakerTrendFollowerRandomTrader
lanza hasta 50 órdenes BOE concurrentes recorriendo el sistema
Architecture diagram of TitaniumBOE-Sim

By the Numbers

  • 131 Java classes · 319 automated tests
  • 11 BOE message types with exact wire format per spec
  • P99 < 5ms Order Acknowledgment latency under sustained load
  • 500+ simultaneous TCP connections without drops
  • 10 implementation phases — from typed enums to per-session optional field negotiation
DOCUMENTATION

Technical Architecture — TitaniumBOE-Sim

Document version: 2.0
Reference protocol: Cboe Titanium U.S. Options BOE Specification v2.11.90
Runtime: Java 21 · Maven 3.9 · Virtual Threads

1. Problem Context

The Binary Order Entry (BOE) protocol from Cboe is a low-latency binary protocol used to submit options orders on institutional exchanges. Its complexity stems from:

  • Little Endian binary format — each field has a fixed offset, exact size, and its own type (Binary, Alpha, Text, Binary Price with 4 implicit decimals, DateTime in nanoseconds).
  • Optional fields controlled by bitfields — the presence of each field is negotiated per session via a Return Bitfields Parameter Group in the Login Request. Each message is self-describing.
  • Multiple protocol versions — switching from BOEv2.11 to BOEv3.x requires manually rewriting the parser, serialization, and all tests.
  • Strict session flow — Login required before any order; sequences per matching unit; heartbeats in both directions.

TitaniumBOE-Sim solves this in Java 21 with a complete, testable implementation of the protocol, a real matching engine, and a persistence layer, REST API, and dashboard all in a single JAR.

2. System Overview

┌──────────────────────────────────────────────────────────────────────────┐
│                           External Clients                               │
│  Browser ─────────── REST / WebSocket ─────────── CLI / BOE Client SDK   │
└────────────┬─────────────────────────────────────────────────────┬───────┘
             │ HTTP/WS (port 9091)                                 │ TCP (port 8081)
             ▼                                                     ▼
┌────────────────────────────┐              ┌────────────────────────────────┐
│      RestApiServer         │              │       CboeServer               │
│  Javalin 6.7 + Scalar UI   │              │  ServerSocketChannel           │
│  ┌──────────┬───────────┐  │              │  VirtualThread per connection  │
│  │ REST     │ WebSocket │  │              │  ┌──────────────────────────┐  │
│  │ endpoints│ /ws/feed  │  │              │  │ ClientConnectionHandler  │  │
│  └──────────┴───────────┘  │              │  │  - Login / Logout / HB   │  │
└────────────┬───────────────┘              │  │  - New/Cancel/Modify Ord │  │
             │                              │  └────────────┬─────────────┘  │
             │                              └───────────────┼────────────────┘
             │                                              │
             └──────────────────────┬───────────────────────┘
                                    │
                    ┌───────────────▼──────────────────┐
                    │           OrderManager           │
                    │  Validates, routes, responds     │
                    └───────────────┬──────────────────┘
                                    │
               ┌────────────────────┼─────────────────────┐
               │                    │                     │
    ┌──────────▼───────┐  ┌─────────▼────────┐  ┌─────────▼──────────┐
    │  MatchingEngine  │  │  OrderRepository │  │  TradeRepository   │
    │  synchronized    │  │  (RocksDB async) │  │  (RocksDB async)   │
    │  per symbol      │  └──────────────────┘  └────────────────────┘
    │  ┌────────────┐  │
    │  │ OrderBook  │  │  ── TreeMap<BigDecimal, List<Order>>
    │  │ (per sym.) │  │  ── price-time (FIFO per level)
    │  └────────────┘  │
    └──────────────────┘
               │
    ┌──────────▼──────────┐
    │   BotManager        │
    │  MarketMaker        │
    │  TrendFollower      │
    │  RandomTrader       │
    └─────────────────────┘

3. Technology Stack

Layer Technology Rationale
Runtime Java 21, Virtual Threads One VThread per TCP connection without OS thread overhead; >500 concurrent connections
Build Maven 3.9, frontend-maven-plugin Compiles Astro and bundles the frontend into the JAR — a single deployable artifact
BOE Server NIO ServerSocketChannel Non-blocking accept; each client runs in its own VThread
REST / WebSocket Javalin 6.7 Lightweight, no reflection on the hot path, compatible with VThreads
Frontend Astro 5 + Tailwind CSS Static generation at build time; served from classpath
Persistence RocksDB 9.11 Async write-behind queue, high throughput for orders
Security JBCrypt Password hashing with configurable work factor
Testing JUnit 5 + Awaitility 319 tests; wire format tests against the spec

4. BOE Protocol Layer

4.1 Message Hierarchy (Java 21 Sealed Classes)

BoeProtocolMessage (sealed abstract)
├── SessionMessage (sealed abstract)
│   ├── LoginRequestMessage       (0x37) ← Member → Cboe
│   ├── LoginResponseMessage      (0x24) ← Cboe → Member
│   ├── LogoutRequestMessage      (0x02) ← Member → Cboe
│   ├── LogoutResponseMessage     (0x08) ← Cboe → Member
│   ├── ClientHeartbeatMessage    (0x03) ← Member → Cboe
│   ├── ServerHeartbeatMessage    (0x09) ← Cboe → Member
│   └── ReplayCompleteMessage     (0x13) ← Cboe → Member
│
└── ApplicationMessage (sealed abstract)
    ├── NewOrderMessage           (0x38) ← Member → Cboe
    ├── CancelOrderMessage        (0x39) ← Member → Cboe
    ├── ModifyOrderMessage        (0x3A) ← Member → Cboe
    ├── OrderAcknowledgmentMessage(0x25) ← Cboe → Member
    ├── OrderRejectedMessage      (0x26) ← Cboe → Member
    ├── OrderModifiedMessage      (0x27) ← Cboe → Member
    ├── UserModifyRejectedMessage (0x29) ← Cboe → Member
    ├── OrderCancelledMessage     (0x2A) ← Cboe → Member
    ├── CancelRejectedMessage     (0x2B) ← Cboe → Member
    ├── OrderExecutedMessage      (0x2C) ← Cboe → Member
    └── OrderRestatedMessage      (0x28) ← Cboe → Member

Sealed classes allow exhaustive pattern matching in the dispatcher:

switch (message) {
    case NewOrderMessage m    -> handleNewOrder(m);
    case CancelOrderMessage m -> handleCancelOrder(m);
    case ModifyOrderMessage m -> handleModifyOrder(m);
    // Compiler verifies exhaustiveness
}

4.2 Message Header (10 bytes — all messages)

Offset  Len  Field            Notes
------  ---  ---------------  -------------------------------------------------
0       2    StartOfMessage   Always 0xBA 0xBA
2       2    MessageLength    Bytes of message including this field, excl. SOM
4       1    MessageType      1-byte message type identifier
5       1    MatchingUnit     Always 0 in inbound messages
6       4    SequenceNumber   32-bit LE counter per application stream

Formula: MessageLength = total_bytes - 2
Endianness: Little Endian on all binary fields (Intel x86 byte order)

4.3 Protocol Data Types

Type Size Representation Example
Binary variable LE unsigned 64 00 00 00 = 100
Binary Price 8 bytes LE signed, 4 implicit decimals 08 E2 01 00... = 12.34 (= 123400 / 10000)
Short Binary Price 4 bytes LE signed, 4 implicit decimals 0C 30 00 00 = 1.23
DateTime 8 bytes Nanoseconds since Unix epoch
Text variable ASCII, NUL (0x00) padded "ABC\x00\x00"
Alpha variable ASCII, NUL (0x00) padded "MSFT\x00\x00\x00\x00"

4.4 Optional Fields and Bitfields

Messages such as New Order and Modify Order include optional fields controlled by bitfield bytes:

[Fixed Header (10B)] [Fixed fields...] [NumBitfields (1B)] [Bitfield₁] ... [BitfieldN] [opt_field₁] [opt_field₂] ...

Rule: optional fields appear in order — first bitfield first, least significant bit first within each byte.

Login negotiation: the client declares via the Return Bitfields Parameter Group (0x81) which fields it wants to receive in each response message type. The server respects that negotiation for the entire session and each response message is self-describing (it includes its own bitfield bytes).

public class ReturnBitfields {
    private final Map<Byte, byte[]> masksByMessageType;

    public byte[] maskFor(byte messageType) { ... }
}

4.5 Binary Price: Implementation

public record BinaryPrice(long rawValue) {
    private static final long SCALE = 10_000L;  // 4 implicit decimals

    public BigDecimal toPrice() {
        return BigDecimal.valueOf(rawValue, 4);  // scale=4
    }

    public static BinaryPrice fromPrice(BigDecimal price) {
        long raw = price.scaleByPowerOfTen(4).longValueExact();
        return new BinaryPrice(raw);
    }
}

12.3400 → rawValue 123400 → wire 08 E2 01 00 00 00 00 00

5. BOE Server Layer

5.1 Concurrency Model

CboeServer
  └── ServerSocketChannel (non-blocking accept)
        └── For each accepted connection:
              Thread.ofVirtual().start(() -> {
                  ClientConnectionHandler handler = new ClientConnectionHandler(socket, ...);
                  handler.run();  // Blocking loop — VThread manages blocking
              })

Java 21 Virtual Threads allow the simplest programming model (blocking I/O) without the overhead of real OS threads. Each connection has its own VThread; >500 simultaneous connections with minimal footprint.

5.2 ClientConnectionHandler — Session Flow

                     ┌─ TCP connection established ─┐
                     │                              │
                     ▼                              │
              [Read LoginRequest]                   │
                     │                              │
          ┌──────────▼────────────┐                 │
          │  AuthenticationService│                 │
          │  - Look up user in DB │                 │
          │  - BCrypt.checkpw()   │                 │
          └──────────┬────────────┘                 │
                     │ OK / FAIL                    │
          ┌──────────▼────────────┐                 │
          │  Send LoginResponse   │                 │
          │  Negotiate ReturnBFlds│                 │
          └──────────┬────────────┘                 │
                     │                              │
         ┌───────────▼─────────────┐                │
         │   Message loop          │◄───────────────┘
         │   (HeartbeatMonitor)    │
         │  switch(message) {      │
         │    NewOrder    → ...    │
         │    CancelOrder → ...    │
         │    ModifyOrder → ...    │
         │    ClientHB    → ...    │
         │    LogoutReq   → ...    │
         │  }                      │
         └───────────┬─────────────┘
                     │
              [LogoutRequest / timeout]
              Send Logout → close socket

5.3 Sequences and Heartbeats

  • Session messages (Login, Logout, Heartbeat): SequenceNumber = 0 always
  • Application messages Member→Cboe: single stream per session, client increments
  • Application messages Cboe→Member: per matching unit (independent per unit)
  • Heartbeat: if no data arrives within 1 second, the server sends ServerHeartbeat
  • Timeout: 5 seconds with no data → server sends Logout and closes connection

6. Matching Engine

6.1 Data Structure — OrderBook

// One OrderBook per symbol, created on demand
class OrderBook {
    private final TreeMap<BigDecimal, List<Order>> bids;  // descending (best price first)
    private final TreeMap<BigDecimal, List<Order>> asks;  // ascending  (best price first)
}

Within each price level: orders are kept in a List<Order> in arrival order — FIFO (price-time priority).

6.2 Matching Cycle — processOrder

processOrder(Order incoming)
    │
    ├── Can it cross? (canMatch)
    │    ├── MARKET → always yes
    │    ├── BUY LIMIT → yes if price >= bestAsk
    │    └── SELL LIMIT → yes if price <= bestBid
    │
    ├── YES → executeMatching (loop):
    │         ├── Get best counterpart (FIFO at that level)
    │         ├── Check self-trade (same username → cancel passive)
    │         ├── fillQty = min(aggressiveLeavesQty, passiveLeavesQty)
    │         ├── execPrice = passive order price (price-time priority)
    │         ├── Create Trade, update leavesQty on both orders
    │         ├── If passive filled → removeOrder(passive)
    │         └── Notify listeners (WebSocket broadcast)
    │
    └── If leavesQty > 0 and order.isLive() → addOrder(book)

6.3 Synchronization

// Lock per symbol — no contention between AAPL and SPX
private final Map<String, Object> symbolLocks = new ConcurrentHashMap<>();

public List<Trade> processOrder(Order order) {
    Object lock = symbolLocks.computeIfAbsent(order.getSymbol(), k -> new Object());
    synchronized (lock) {
        // ... complete matching under the symbol lock
    }
}

6.4 Modify Order — Spec Logic (p.77)

Modify Order requires a specific sequence to maintain OrderBook integrity:

1. removeOrder(book)        // BEFORE changing the price (TreeMap key)
2. Calculate delta:
     delta        = newOrderQty - order.getEffectiveOrderQty()
     newLeavesQty = order.getLeavesQty() + delta
3. If newLeavesQty <= 0 → order.cancel() → return []
4. order.modify(newClOrdID, newPrice, newOrdType, newOrderQty, newLeavesQty)
5. Attempt matching at new price
6. If leavesQty > 0 → addOrder(book) at new price

Why this order: OrderBook uses TreeMap<BigDecimal, List<Order>> where price is the key. If the price were updated before removing the order, removeOrder would look in the new price level and not find the order (it's still at the old level).

6.5 Shadow Fields in Order (supporting modify without breaking TreeMap)

public class Order {
    private final BigDecimal price;      // original price (immutable)

    // Mutable overrides applied by Modify Order
    private volatile BigDecimal modifiedPrice;
    private volatile String modifiedClOrdID;
    private volatile OrdType modifiedOrdType;
    private volatile int modifiedOrderQty;  // 0 = not modified

    public BigDecimal getPrice() {
        return modifiedPrice != null ? modifiedPrice : price;
    }
    public int getEffectiveOrderQty() {
        return modifiedOrderQty > 0 ? modifiedOrderQty : orderQty;
    }
}

7. Order Lifecycle

                          [New Order received]
                                  │
                    ┌─────────────▼────────────┐
                    │      OrderValidator      │
                    │  - ClOrdID unique?       │
                    │  - Side, Symbol, Qty OK? │
                    │  - Price for LIMIT?      │
                    └──────┬──────────┬────────┘
                      OK   │          │ Error
                           │          ▼
                           │   OrderRejected (0x26)
                           │
              ┌────────────▼────────────────┐
              │  order.state = PENDING_NEW  │
              │ orderRepository.saveAsync() │
              └────────────┬────────────────┘
                           │
              ┌────────────▼────────────────┐
              │   matchingEngine.process()  │
              └────────────┬────────────────┘
                           │
               ┌───────────▼───────────────┐
               │ order.acknowledge()       │
               │ order.state = LIVE        │
               │ Send OrderAck (0x25)      │
               └───────────┬───────────────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
      Partial fill    Full fill       No fill
           │               │               │
   PARTIALLY_FILLED    FILLED           LIVE
     ┌─────┘               │            ┌──┘
     │   Send              │            │  Stays in
     │   OrderExec         │            │  OrderBook
     │   (0x2C)       OrderExec         │
     │                (0x2C)            │
     │                                  │
     └──── Modify/Cancel possible ──────┘
                           │
              [Cancel] → OrderCancelled (0x2A)
              [Modify] → OrderModified  (0x27)

OrderState values:

State isActive() isCancellable() isLive()
PENDING_NEW true false false
LIVE true true true
PARTIALLY_FILLED true true true
FILLED false false false
CANCELLED false false false
REJECTED false false false
EXPIRED false false false

8. Persistence — RocksDB

8.1 Write-Behind Architecture

OrderManager / TradeService
       │
       │  orderRepository.saveAsync(order)
       │
       ▼
┌──────────────────────┐
│  OrderRepository     │
│  LinkedBlockingQueue │  ← hot path never blocked
│  (write-behind)      │
└──────────────────────┘
       │ background thread
       ▼
┌──────────────────────┐
│  RocksDBManager      │
│  - orders CF         │
│  - trades CF         │
│  - sessions CF       │
│  - users CF          │
│  - audit CF          │
│  - statistics CF     │
└──────────────────────┘

Advantage: the matching engine and dispatcher never wait for disk I/O. The confirmation goes to the client (OrderAck) before persistence completes.

8.2 Column Families

Column Family Key Value
orders clOrdID (String) Order serialized (Jackson CBOR)
trades tradeId (Long → bytes) Trade serialized
sessions username+subID PersistedSession
users username PersistedUser (BCrypt password hash)
audit timestamp + UUID AuditEvent
statistics stats PersistedStatistics

9. REST API and WebSocket

9.1 Endpoints

Port: 9091

Group Method Path Auth Description
System GET /api/health No Server status
Symbols GET /api/symbols No Available symbols
Symbols GET /api/symbols/{symbol} No Market data for a symbol
Auth POST /api/auth/register No Register user
Auth POST /api/auth/login Basic Validate credentials
Orders POST /api/orders Basic Create order
Orders GET /api/orders/active Basic User's active orders
Orders GET /api/orders/{clOrdID} Basic Order detail
Orders DELETE /api/orders/{clOrdID} Basic Cancel order
Positions GET /api/positions Basic User positions
Positions GET /api/positions/{symbol} Basic Position by symbol
Trades GET /api/trades/my Basic My trades
Trades GET /api/trades/recent Basic Recent market trades
Trades GET /api/trades/symbol/{symbol} Basic Trades by symbol
Simulator GET /api/simulator/status No Simulator status
Simulator GET /api/simulator/bots No Bot list
Simulator POST /api/simulator/bots/{id}/start Basic Start bot
Simulator POST /api/simulator/bots/{id}/stop Basic Stop bot
Docs GET /api/docs No Scalar UI (OpenAPI)

9.2 WebSocket Feed

Endpoint: ws://localhost:9091/ws/feed

Events emitted in real time:

// Executed trade
{ "type": "TRADE", "symbol": "AAPL", "price": 150.50, "qty": 100, "timestamp": 1234567890 }

// Order book update
{ "type": "ORDER_BOOK", "symbol": "AAPL", "bids": [...], "asks": [...] }

// Order status change
{ "type": "ORDER_STATUS", "clOrdID": "ABC123", "status": "FILLED" }

9.3 Authentication

HTTP Basic Auth on all authenticated endpoints:

Authorization: Basic base64(username:password)

Demo credentials (with DEMO_MODE=true):

  • TRD1 / Pass1234!
  • TRD2 / Pass5678!

10. Trading Bots

Three strategies run on parallel virtual threads:

Bot Strategy Description
MarketMakerStrategy Liquidity provision Places bids and asks within the spread; adjusts based on P&L
TrendFollowerStrategy Trend following Detects price momentum; buys on uptrend, sells on downtrend
RandomTraderStrategy Random noise Random orders to simulate active market

Each bot operates via the internal REST API, generating continuous activity in the matching engine. With DEMO_MODE=true all three start automatically.

11. Key Design Decisions

11.1 Java 21 Virtual Threads

Decision: one VThread per TCP connection, blocking I/O.
Alternative considered: NIO non-blocking with Selector loop (Netty style).
Why VThreads: simpler and more readable code, no callback hell, no CompletableFuture chains. Java 21 guarantees the scheduler maps VThreads to OS threads efficiently. In tests: >500 simultaneous connections with P99 latency < 5ms.

11.2 Sealed Class Hierarchy + Pattern Matching

Decision: BoeProtocolMessage as a sealed class with two branches: SessionMessage and ApplicationMessage.
Why: the compiler verifies switch exhaustiveness. Adding a new message type without handling it is a compile-time error, not a silent runtime bug.

11.3 Per-Symbol Synchronization in MatchingEngine

Decision: ConcurrentHashMap<String, Object> of locks, one per symbol.
Why: AAPL and SPX share no state; there's no reason to serialize their matching. This enables parallel matching across symbols with zero contention between them.

11.4 TreeMap for OrderBook

Decision: TreeMap<BigDecimal, List<Order>> sorted by price.
Why: getBestBid() = firstKey() and getBestAsk() = firstKey() are O(log n). Inserting a new level is also O(log n). The alternative (PriorityQueue) doesn't allow efficient access to an already-existing level.

11.5 Write-Behind Queue for Persistence

Decision: LinkedBlockingQueue consumed by a background thread into RocksDB.
Why: the hot path (matching + ACK to client) never waits for disk. The trade-off: in an abrupt crash, the last writes in the queue may be lost. Acceptable in a simulator; in production a WAL + fsync would be used.

11.6 Shadow Fields in Order for Modify

Decision: modifiedPrice, modifiedClOrdID, etc. fields instead of mutating final fields.
Why: the original fields are final to guarantee the OrderBook can remove the order at the correct price. The effective getter returns the modified field if present, the original otherwise. This makes Modify Order safe with respect to the TreeMap.

12. Testing

12.1 Coverage

319 tests across 30 classes:

Area Tests Focus
Wire format (protocol) ~150 Byte-by-byte parsing against the spec
Matching engine ~20 Price-time priority, self-trade, Modify delta logic
Session layer ~40 Login, logout, heartbeat, sequences
Order management ~30 Validation, lifecycle, states
Persistence ~15 RocksDB CRUD, serialization
REST / auth ~20 Endpoints, authentication, errors
Load test manual LoadTestRunner (5 phases, not in CI suite)

12.2 Load Test Runner (Phase 10)

mvn test-compile
java -cp "target/test-classes:target/classes:$(mvn -q dependency:build-classpath \
    -DincludeScope=test -Dmdep.outputFile=/dev/stdout)" \
    com.boe.simulator.load.LoadTestRunner \
    --tcp=500 --logins=100 --rest=5000 --ack-sessions=10 --ack-orders=100
Phase Metric Criterion
1 — TCP Capacity Accepted connections ≥ 500 simultaneous
2 — BOE Login Login rate ≥ 200 logins/sec
3 — REST API Throughput ≥ 800 req/sec
4 — Order Ack Latency P99 < 5ms (using spec-compliant NewOrderMessage)
5 — Memory Stability Heap growth < 200 MB per 10,000 orders

13. Project Structure

TitaniumBOE-Sim/
├── src/main/java/com/boe/simulator/
│   ├── protocol/
│   │   ├── message/          # 20 BOE message classes (sealed hierarchy)
│   │   ├── types/            # Domain enums (Side, OrdType, Capacity…)
│   │   └── serialization/    # BoeMessageSerializer
│   ├── server/
│   │   ├── CboeServer.java           # Main TCP server
│   │   ├── connection/               # ClientConnectionHandler per session
│   │   ├── matching/                 # MatchingEngine, OrderBook, Trade
│   │   ├── order/                    # OrderManager, Order, OrderValidator
│   │   ├── auth/                     # AuthenticationService (BCrypt)
│   │   ├── session/                  # ClientSession, ClientSessionManager
│   │   ├── heartbeat/                # HeartbeatMonitor
│   │   ├── ratelimit/                # RateLimiter
│   │   └── persistence/              # RocksDB (repos + services + models)
│   ├── api/
│   │   ├── RestApiServer.java        # Javalin setup + OpenAPI
│   │   ├── controller/               # REST controllers
│   │   ├── service/                  # Application services
│   │   ├── websocket/                # WebSocketHandler + WebSocketService
│   │   ├── dto/                      # Request/Response DTOs
│   │   └── middleware/               # Auth, CORS, Error filters
│   └── bot/
│       ├── BotManager.java
│       └── strategy/                 # MarketMaker, TrendFollower, Random
├── src/test/
│   └── java/com/boe/simulator/
│       ├── protocol/                 # Wire format tests
│       ├── server/                   # Engine, auth, session tests
│       └── load/                     # LoadTestRunner (manual)
├── frontend/                         # Astro 5 + Tailwind (compiled into JAR)
├── docs/
│   ├── ARCHITECTURE.md               # This document
│   ├── API_DOCUMENTATION.md          # Full REST reference
│   └── BOE Protocol Specification - Quick Reference.md
├── Dockerfile
├── docker-compose.yml
└── pom.xml

Document maintained alongside the code — if behavior changes, update this description.

REST API Documentation — TitaniumBOE-Sim

Port: 9091
Base URL: http://localhost:9091
Authentication: HTTP Basic Auth
Format: JSON (UTF-8)

Interactive Documentation Access

Once the server is running:

Interface URL Description
Scalar UI http://localhost:9091/api/docs Recommended — modern UI with code examples
Swagger UI http://localhost:9091/api/swagger Classic alternative
OpenAPI JSON http://localhost:9091/openapi Raw specification

Starting the Server

# Quick build and start (demo mode — users and market data pre-loaded)
mvn clean package -DskipTests
DEMO_MODE=true java -jar target/boe-simulator-*.jar

Demo credentials:

  • TRD1 / Pass1234!
  • TRD2 / Pass5678!

Authentication

All endpoints marked with 🔐 require credentials via HTTP Basic Auth:

# Manual header
curl -H "Authorization: Basic $(echo -n 'TRD1:Pass1234!' | base64)" \
     http://localhost:9091/api/orders/active

# Shorthand with curl
curl -u TRD1:Pass1234! http://localhost:9091/api/orders/active

Endpoints

System

GET /api/health

Server status. No authentication required.

curl http://localhost:9091/api/health

{
  "status": "UP",
  "uptime": "00:03:42",
  "activeConnections": 2,
  "totalOrders": 847,
  "totalTrades": 312
}

Authentication

POST /api/auth/register

Registers a new user.

curl -X POST http://localhost:9091/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "TRD3", "password": "MiPass123!"}'

{ "success": true, "message": "User registered successfully" }
Code Meaning
201 User created
409 Username already exists
400 Invalid data

POST /api/auth/login 🔐

Validates credentials (returns 200 if correct, 401 if not).

curl -u TRD1:Pass1234! -X POST http://localhost:9091/api/auth/login

Symbols and Market Data

GET /api/symbols

Lists all symbols with activity in the simulator.

curl http://localhost:9091/api/symbols

["AAPL", "MSFT", "SPX", "SPXW", "TSLA"]

GET /api/symbols/{symbol}

Market data for a symbol: best bid/ask, last price, volume.

curl http://localhost:9091/api/symbols/AAPL

{
  "symbol": "AAPL",
  "bestBid": 149.75,
  "bestAsk": 150.25,
  "lastTradePrice": 150.00,
  "volume": 2400
}

Orders

POST /api/orders 🔐

Submits a new order. The server processes it through the matching engine and returns the initial state.

curl -X POST http://localhost:9091/api/orders \
  -u TRD1:Pass1234! \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "AAPL",
    "side": "BUY",
    "orderQty": 100,
    "price": 150.50,
    "orderType": "LIMIT",
    "capacity": "CUSTOMER"
  }'

Body — fields:

Field Type Required Values
symbol string Yes Asset symbol
side string Yes BUY, SELL
orderQty int Yes 1 – 999,999
price decimal For LIMIT Limit price
orderType string Yes LIMIT, MARKET
capacity string Yes CUSTOMER, AGENCY, MARKET_MAKER, PRINCIPAL
account string No Client account

Response:

{
  "success": true,
  "data": {
    "clOrdID": "ORD-1714500000001",
    "symbol": "AAPL",
    "side": "BUY",
    "orderQty": 100,
    "leavesQty": 100,
    "price": 150.50,
    "orderType": "LIMIT",
    "status": "LIVE",
    "createdAt": 1714500000001
  }
}

GET /api/orders/active 🔐

Live orders (LIVE, PARTIALLY_FILLED) of the authenticated user.

curl -u TRD1:Pass1234! http://localhost:9091/api/orders/active

GET /api/orders/{clOrdID} 🔐

Order detail by client ID.

curl -u TRD1:Pass1234! http://localhost:9091/api/orders/ORD-1714500000001

DELETE /api/orders/{clOrdID} 🔐

Cancels a live order. Returns 404 if it doesn't exist or doesn't belong to the authenticated user.

curl -X DELETE -u TRD1:Pass1234! \
     http://localhost:9091/api/orders/ORD-1714500000001

{ "success": true, "message": "Order cancelled" }

Positions

GET /api/positions 🔐

All user positions (net per symbol after fills).

curl -u TRD1:Pass1234! http://localhost:9091/api/positions

[
  { "symbol": "AAPL", "quantity": 200, "avgPrice": 150.25, "unrealizedPnL": 50.00 },
  { "symbol": "MSFT", "quantity": -100, "avgPrice": 310.00, "unrealizedPnL": -30.00 }
]

GET /api/positions/{symbol} 🔐

Net position in a specific symbol.

curl -u TRD1:Pass1234! http://localhost:9091/api/positions/AAPL

Trades

GET /api/trades/my 🔐

Trades executed by the authenticated user (as buyer or seller).

curl -u TRD1:Pass1234! http://localhost:9091/api/trades/my

[
  {
    "tradeId": 1000042,
    "symbol": "AAPL",
    "side": "BUY",
    "quantity": 100,
    "price": 150.25,
    "clOrdID": "ORD-1714500000001",
    "timestamp": 1714500001234
  }
]

GET /api/trades/recent

Latest market trades (all users). No authentication required.

curl http://localhost:9091/api/trades/recent

GET /api/trades/symbol/{symbol}

Trades for a specific symbol (full market).

curl http://localhost:9091/api/trades/symbol/AAPL

Simulator (Admin)

GET /api/simulator/status

General simulator status: uptime, total orders, matches.

curl http://localhost:9091/api/simulator/status

GET /api/simulator/bots

List of configured bots and their status.

curl http://localhost:9091/api/simulator/bots

[
  { "id": "market-maker", "status": "RUNNING", "ordersPlaced": 1240, "fills": 87 },
  { "id": "trend-follower", "status": "RUNNING", "ordersPlaced": 430, "fills": 23 },
  { "id": "random-trader", "status": "STOPPED", "ordersPlaced": 0, "fills": 0 }
]

POST /api/simulator/bots/{botId}/start 🔐

POST /api/simulator/bots/{botId}/stop 🔐

curl -X POST -u TRD1:Pass1234! http://localhost:9091/api/simulator/bots/random-trader/start
curl -X POST -u TRD1:Pass1234! http://localhost:9091/api/simulator/bots/market-maker/stop

WebSocket Feed

Endpoint: ws://localhost:9091/ws/feed

Connect to receive real-time market events.

const ws = new WebSocket('ws://localhost:9091/ws/feed');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'TRADE':
      console.log(`Trade: ${msg.symbol} ${msg.qty} @ ${msg.price}`);
      break;
    case 'ORDER_BOOK':
      console.log(`Book update: ${msg.symbol}`, msg.bids, msg.asks);
      break;
    case 'ORDER_STATUS':
      console.log(`Order ${msg.clOrdID} → ${msg.status}`);
      break;
  }
};

Event types:

Type Fields Description
TRADE symbol, price, qty, timestamp Trade executed in the market
ORDER_BOOK symbol, bids[], asks[] Order book update
ORDER_STATUS clOrdID, status Order status change

Response Codes

Code Meaning
200 OK
201 Resource created
400 Invalid request (missing or malformed fields)
401 Unauthenticated (credentials required)
403 Unauthorized (order does not belong to user)
404 Resource not found
409 Conflict (duplicate username, duplicate ClOrdID)
500 Internal server error

Error Format

{
  "success": false,
  "error": "Order not found: ORD-9999999",
  "timestamp": 1714500005000
}

Environment Variables

Variable Default Description
DEMO_MODE true Pre-loads demo users and market data
BOE_PORT 8081 BOE binary protocol port (TCP)
API_PORT 9091 REST API + dashboard port
LOG_LEVEL INFO Log verbosity (FINE, INFO, WARNING)
ADMIN_USERNAME — Admin user in non-demo mode
ADMIN_PASSWORD — Admin password

Native BOE Protocol Reference

To interact directly over TCP (port 8081) using the binary BOE protocol, see:

  • docs/BOE Protocol Specification - Quick Reference.md — complete wire format reference
  • docs/ARCHITECTURE.md — parser and serialization design

BOE Protocol Specification — Quick Reference

Source: Cboe Titanium U.S. Options Binary Order Entry Specification
Version: 2.11.90 · October 3, 2025

1. Protocol Fundamentals

  • All communication is via standard TCP/IP.
  • All binary values are Little Endian (Intel x86 byte order), not network byte order.
  • Each message is identified by a unique 1-byte MessageType.
  • Terminology mirrors FIX protocol (Side, TimeInForce, OrdType, etc.) for familiarity.

2. Message Header (10 bytes — every message)

Offset  Len  Field            Notes
------  ---  ---------------  -------------------------------------------------
0       2    StartOfMessage   Always 0xBA 0xBA
2       2    MessageLength    Bytes for message incl. this field, excl. StartOfMessage
4       1    MessageType      1-byte message identifier (see §5)
5       1    MatchingUnit     Unit that created the message (see notes below)
6       4    SequenceNumber   32-bit LE sequence counter (see §6)

MatchingUnit rules:

  • Session-level messages → always 0 in both directions.
  • Member-to-Cboe (inbound) application messages → always 0.
  • Cboe-to-Member (outbound) application messages → set by Cboe to the matching unit.

MessageLength formula:

MessageLength = (total message bytes) - 2
             = MessageType(1) + MatchingUnit(1) + SequenceNumber(4) + body + 2

Does not include the two StartOfMessage bytes.

3. Data Types

Type Byte Order Size Description
Binary LE unsigned context FE = 254; 64 00 00 00 = 100
Signed Binary LE signed two's complement context DF = -33; 64 00 00 00 = +100
Binary Price LE signed 8 bytes 4 implied decimal places. 08 E2 01 00 00 00 00 00 = 123,400/10,000 = 12.34. Negative prices supported (complex instruments).
Short Binary Price LE signed 4 bytes 4 implied decimal places. 0C 30 00 00 = 12,300/10,000 = 1.23
Signed Binary Fee LE signed 8 bytes 5 implied decimal places.
Alpha — context Uppercase A-Z and lowercase a-z only. NUL (0x00) padded right.
Alphanumeric — context A-Z, a-z, 0-9. NUL (0x00) padded right.
Text — context Printable ASCII. NUL (0x00) padded right.
DateTime LE unsigned 8 bytes Nanoseconds past Unix epoch (UTC). 1,294,909,373,757,324,000 = 2011-01-13 09:02:53.757324 UTC
Date LE unsigned 4 bytes YYYYMMDD expressed as integer.

All string/text fields are NUL-padded (0x00), left-aligned.

4. Optional Fields and Bitfields

Messages such as New Order and Modify Order append optional fields after the required fields. Presence is controlled by bitfield bytes:

  • A count byte (NumberOfBitfields) declares how many bitfield bytes follow.
  • Each bit in a bitfield byte enables one optional field.
  • Optional fields are appended in order: first bitfield first, lowest-order bit first.
  • If an optional field is irrelevant in a given context, it is still present but with all bytes set to 0x00.
  • The set of optional fields that Cboe returns is negotiated at login time via the Return Bitfields Parameter Group in the Login Request.
  • Each Cboe-to-Member message includes the bitfields echo so each message is self-describing (no need to reference the login).

See Input Bitfields Per Message (p. 171) and Return Bitfields Per Message (p. 179) in the spec.

5. Message Type Codes

5.1 Session Messages

Message Type Code Direction Description
Login Request 0x37 Member → Cboe First message on connect
Logout Request 0x02 Member → Cboe Graceful session close
Client Heartbeat 0x03 Member → Cboe Keep-alive
Login Response 0x24 Cboe → Member Login accept/reject
Logout 0x08 Cboe → Member Session termination
Server Heartbeat 0x09 Cboe → Member Keep-alive
Replay Complete 0x13 Cboe → Member End of missed-message replay

5.2 Application Messages — Member to Cboe

Message Type Code Description
New Order 0x38 Submit a new order
New Order (Short) 0x39 Abbreviated new order
New Order Cross 0x3A Cross order (C1/EDGX)
New Complex Instrument 0x3C Define complex instrument (C1/C2/EDGX)
New Complex Order 0x3D Multi-leg order (C1/EDGX/C2)
New Complex Order Short 0x3E Abbreviated complex order
New Order Cross Multileg 0x3F Cross multileg (C1/EDGX)
Cancel Order 0x45 Cancel a live order
Mass Cancel Order 0x46 Cancel multiple orders
Modify Order 0x4A Modify a live order
Quote Update 0x59 Quote update
Purge Orders 0x62 Purge orders by criteria
Reset Risk 0x63 Risk reset

5.3 Application Messages — Cboe to Member

Message Type Code Description
Order Acknowledgment 0x25 Order accepted and working
Order Rejected 0x26 Order rejected with reason
Order Modified 0x27 Modification confirmed
Order Restated 0x28 Order restated (e.g., done-for-day)
User Modify Rejected 0x29 Modification rejected
Order Cancelled 0x2A Cancellation confirmed
Cancel Rejected 0x2B Cancellation rejected
Order Execution 0x2C Trade fill
Trade Cancel or Correct 0x2D Trade bust/correction
Mass Cancel Acknowledgment 0x99 Mass cancel confirmed
Purge Notification 0x9B Purge confirmed

6. Session Protocol

6.1 Login and Sequencing

  • Session messages (Login, Logout, Heartbeat) are unsequenced — SequenceNumber = 0 in both directions.
  • Member → Cboe application messages are sequenced using a single sequence stream across all matching units.
  • Cboe → Member application messages are sequenced per matching unit (distinct counter per unit).
  • A Login Request must be the first message sent after TCP connect.
  • Session identified by (username + SessionSubID); only one concurrent connection per pair.
  • On reconnect, Member sends last received sequence number per unit; Cboe replays missed messages.
  • Gaps forward (sequence ahead) are ignored. Gaps backward → Cboe sends Logout.
  • Replay Complete is sent immediately after Login Response if no messages need replaying.
  • Cboe rejects all orders during replay.

6.2 Sequence Reset

No formal reset command. To reset: send Login Request with NoUnspecifiedUnitReplay = 0x01 and NumberOfUnits = 0. Use LastReceivedSequenceNumber from the Login Response as the new starting sequence.

6.3 Heartbeats

  • Trigger: if no data has been sent in either direction for 1 second.
  • Timeout: if Cboe receives no inbound data or heartbeats for 5 seconds → sends Logout and closes.
  • Heartbeats from Cboe do not increment the sequence number.
  • Members are encouraged to have a 1-second heartbeat interval and similar staleness logic.

6.4 Logging Out

  1. Member sends Logout Request.
  2. Cboe drains any queued outbound data.
  3. Cboe replies with Logout and closes the connection.
  4. After receiving a Logout Request, Cboe ignores all inbound messages except Client Heartbeat.
  5. A member may close TCP without logging out, but may lose queued messages.

6.5 Exchange Shutdown

Cboe sends Logout (reason = E = End of Day) to all connected ports at approximately 17:30 ET daily without waiting for a logout request.

7. Session Message Field Tables

7.1 Login Request (0x37) — Member to Cboe

Table 11 — Login Request Message Fields

Offset  Len  Type          Field                 Notes
------  ---  ------------  --------------------  ----------------------------------
0       2    Binary        StartOfMessage        0xBA 0xBA
2       2    Binary        MessageLength         Incl. this field, excl. SOM
4       1    Binary        MessageType           0x37
5       1    Binary        MatchingUnit          Always 0 inbound
6       4    Binary        SequenceNumber        Always 0 for session messages
10      4    Alphanumeric  SessionSubID          Session Sub ID supplied by Cboe
14      4    Alphanumeric  Username              Username supplied by Cboe
18      10   Alphanumeric  Password              Password supplied by Cboe
28      1    Binary        NumberOfParamGroups   Number of parameter groups (n ≥ 0)
         …   —             ParamGroup₁..ₙ        See §7.1.1 and §7.1.2

Wire size: Variable (minimum 29 total bytes with 0 param groups)
MessageLength = 27 + param groups byte count

Login Request Example (Table 14):

BA BA           StartOfMessage
3D 00           MessageLength = 61 bytes
37              MessageType = Login Request
00              MatchingUnit = 0
00 00 00 00     SequenceNumber = 0
30 30 30 31     SessionSubID = "0001"
54 45 53 54     Username = "TEST"
54 45 53 54 49 4E 47 00 00 00   Password = "TESTING"
03              NumberOfParamGroups = 3
…               (param groups)

7.1.1 Unit Sequences Parameter Group (0x80)

Carries the last consumed outbound sequence number per matching unit, so Cboe can replay any missed messages.

Offset  Len  Field               Notes
------  ---  ------------------  -----------------------------------------
0       2    ParamGroupLength    Bytes for this group, including this field
2       1    ParamGroupType      0x80
3       1    NoUnspecifiedUnitReplay  0x00 = replay unspecified; 0x01 = suppress
4       1    NumberOfUnits       Unit/sequence pairs to follow
—       1    UnitNumber₁         Unit number
—       4    UnitSequence₁       Last received sequence for unit
…

7.1.2 Return Bitfields Parameter Group (0x81)

Declares which optional fields Cboe should include in each outbound message type for the remainder of the session.

Offset  Len  Field                  Notes
------  ---  ---------------------  -------------------------------------------
0       2    ParamGroupLength       Bytes for this group, including this field
2       1    ParamGroupType         0x81
3       1    MessageType            Return message type (e.g., 0x25 = Order Ack)
4       1    NumberOfReturnBitfields  Bitfield count
5       1    ReturnBitfield₁..ₙ    One byte per bitfield

Multiple instances allowed (one per Cboe-to-Member message type you want configured).

7.2 Logout Request (0x02) — Member to Cboe

Table 15 — Logout Request Message Fields

Offset  Len  Type    Field            Notes
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x02
5       1    Binary  MatchingUnit     Always 0
6       4    Binary  SequenceNumber   Always 0

Total: 10 bytes. MessageLength = 8. SequenceNumber = always 0 for session messages.

7.3 Client Heartbeat (0x03) — Member to Cboe

Table 17 — Client Heartbeat Message Fields

Offset  Len  Type    Field            Notes
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x03
5       1    Binary  MatchingUnit     Always 0
6       4    Binary  SequenceNumber   Always 0

Total: 10 bytes. Identical layout to Logout Request, different MessageType.

7.4 Login Response (0x24) — Cboe to Member

Table 19 — Login Response Message Fields

Offset  Len   Type          Field                    Notes
------  ----  ------------  -----------------------  ----------------------------------
0       2     Binary        StartOfMessage           0xBA 0xBA
2       2     Binary        MessageLength            Variable (≥ 136 on success)
4       1     Binary        MessageType              0x24
5       1     Binary        MatchingUnit             Always 0
6       4     Binary        SequenceNumber           Always 0
10      1     Alphanumeric  LoginResponseStatus      See codes below
11      60    Text          LoginResponseText        Human-readable description (NUL padded)
71      1     Binary        NoUnspecifiedUnitReplay  Echo of Login Request flag
72      4     Binary        LastReceivedSequenceNumber  Last inbound seq processed by Cboe
76      1     Binary        NumberOfUnits            Unit/sequence pairs to follow
—       1     Binary        UnitNumber₁              A unit number
—       4     Binary        UnitSequence₁            Highest available Cboe→Member seq
…
—       1     Binary        NumberOfParamGroups      Echo of Login Request param groups
—       …     —             ParamGroup₁..ₙ           Echo of Login Request param groups

LoginResponseStatus values:

Code Meaning
A Login Accepted
N Not authorized (invalid username/password)
D Session is disabled
B Session in use (already connected)
S Invalid session
Q Sequence ahead in Login message
I Invalid unit given in Login message
F Invalid return bit field in login message
M Invalid Login Request message structure

Note: Response length is variable. Cboe always returns sequence numbers for all units (even those not in the Login Request). Prepare to handle variable-length Login Response messages.

7.5 Logout (0x08) — Cboe to Member

Table 21 — Logout Message Fields

Offset  Len  Type          Field                     Notes
------  ---  ------------  ------------------------  ----------------------------------
0       2    Binary        StartOfMessage            0xBA 0xBA
2       2    Binary        MessageLength             Variable
4       1    Binary        MessageType               0x08
5       1    Binary        MatchingUnit              Always 0
6       4    Binary        SequenceNumber            Always 0
10      1    Alphanumeric  LogoutReason              See codes below
11      60   Text          LogoutReasonText          Human-readable description
71      4    Binary        LastReceivedSequenceNumber  Last inbound seq processed by Cboe
75      1    Binary        NumberOfUnits             Unit/sequence pairs to follow
—       1    Binary        UnitNumber₁
—       4    Binary        UnitSequence₁             Highest available sequence for unit
…

LogoutReason values:

Code Meaning
U User Requested
E End of Day
A Administrative
! Protocol Violation

7.6 Server Heartbeat (0x09) — Cboe to Member

Table 23 — Server Heartbeat Message Fields

Offset  Len  Type    Field            Notes
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x09
5       1    Binary  MatchingUnit     Always 0
6       4    Binary  SequenceNumber   Always 0

Total: 10 bytes. Does not increment the outbound sequence number.

7.7 Replay Complete (0x13) — Cboe to Member

Table 25 — Replay Complete Message Fields

Offset  Len  Type    Field            Notes
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x13
5       1    Binary  MatchingUnit     Always 0
6       4    Binary  SequenceNumber   Always 0

Sent immediately after Login Response when there are no messages to replay, or after all replayed messages when there are.

8. Application Messages — Member to Cboe

8.1 New Order (0x38)

Table 27 — New Order Message Fields

Offset  Len   Type          Field                       Notes
------  ----  ------------  --------------------------  ----------------------------------
0       2     Binary        StartOfMessage              0xBA 0xBA
2       2     Binary        MessageLength               Variable
4       1     Binary        MessageType                 0x38
5       1     Binary        MatchingUnit                Always 0
6       4     Binary        SequenceNumber              Incremental application sequence
10      20    Text          ClOrdID                     ASCII 33–126 except , ; | @ "
                                                         NUL-padded. Unique among live orders.
30      1     Alphanumeric  Side                        1 = Buy ('1' = 0x31)
                                                         2 = Sell ('2' = 0x32)
31      4     Binary        OrderQty                    Max 999,999 contracts
35      1     Binary        NumberOfNewOrderBitfields   Count of bitfield bytes following
36      1     Binary        NewOrderBitfield₁           Identifies optional fields present
…       1     Binary        NewOrderBitfieldₙ           Last bitfield
—       …     —             Optional fields…            Per enabled bits, lowest bit first

Required optional fields (must always be present via bitfield):

Field Type Size Notes
Symbol Alphanumeric 8 Required (some form of symbology)
Price Binary Price 8 Required for limit orders. Non-negative.
OrdType Alphanumeric 1 Required for market/stop orders. Default = Limit.
Capacity Alphanumeric 1 Always required

New Order Example (Table 28):

BA BA             StartOfMessage
59 00             MessageLength = 89 bytes
38                MessageType = New Order
00                MatchingUnit = 0
64 00 00 00       SequenceNumber = 100
41 42 43 31 32 33 00…(pad)  ClOrdID = "ABC123"
31                Side = Buy (ASCII '1')
64 00 00 00       OrderQty = 100
04                NumberOfBitfields = 4
04                Bitfield1: Price
C1                Bitfield2: Symbol, Capacity, RoutingInst
01                Bitfield3: Account
17                Bitfield4: MaturityDate, StrikePrice, PutOrCall, OpenClose
70 17 00 00 00 00 00 00   Price = 0.60 (6000/10000)
4D 53 46 54 00…   Symbol = "MSFT"
43                Capacity = 'C' (Customer)
52 00 00 00       RoutingInst = 'R' (Routable)
44 45 46 47 00…   Account = "DEFG"
EF DB 32 01       MaturityDate = 2011-03-19
98 AB 02 00 00 00 00 00   StrikePrice = 17.50
31                PutOrCall = '1' (Call)
4F                OpenClose = 'O' (Open)

9. Field Value Reference

9.1 Side (New Order, offset 30)

Wire Value ASCII Meaning
0x31 '1' Buy
0x32 '2' Sell

9.2 OrdType

Wire Value ASCII Meaning
0x31 '1' Market
0x32 '2' Limit
0x33 '3' Stop
0x34 '4' Stop Limit

9.3 Capacity

Wire Value ASCII Meaning
0x41 'A' Agency
0x43 'C' Customer
0x4D 'M' Market Maker
0x50 'P' Principal
0x46 'F' Firm
0x4A 'J' Joint Back Office

9.4 OpenClose

Wire Value ASCII Meaning
0x4F 'O' Open
0x43 'C' Close
0x00 — None / default

9.5 PutOrCall

Wire Value ASCII Meaning
0x31 '1' Call
0x30 '0' Put

9.6 LoginResponseStatus

See §7.4 table above.

9.7 LogoutReason

See §7.5 table above.

10. Sequencing Rules Summary

Direction Message Category Sequencing
Member → Cboe Session (Login, Logout, Heartbeat) Unsequenced (SequenceNumber = 0)
Member → Cboe Application (orders, cancels) Single stream across all matching units
Cboe → Member Session Unsequenced (SequenceNumber = 0)
Cboe → Member Application Per matching unit (independent counter per unit)
  • Cboe recommends (but does not require) Members send sequence numbers on inbound.
  • A gap forward in Member's sequence is ignored by Cboe.
  • A gap backward (duplicate or reused sequence) → Cboe sends Logout.

11. MessageLength Calculation Examples

Session messages (Logout Request, Client Heartbeat, Server Heartbeat, Replay Complete)

Payload = MessageType(1) + MatchingUnit(1) + SequenceNumber(4) = 6 bytes
MessageLength = 6 + 2 = 8
Total wire size = 2 (StartOfMessage) + 8 = 10 bytes

Login Request (minimal — no param groups)

Payload = Type(1) + MU(1) + Seq(4) + SessionSubID(4) + Username(4) + Password(10) + NumParamGroups(1)
        = 25 bytes
MessageLength = 25 + 2 = 27
Total = 2 + 27 = 29 bytes

12. Hours of Operation (Eastern Time)

Exchange Order Acceptance Start GTH RTH
C1 8:00 pm (prev day) SPX/VIX/XSP; 7:30 am all products 8:15–9:25 am (SPX/VIX/XSP) 9:30 am – 4:00 pm (4:15 pm ETFs/ETNs)
C2 7:30 am N/A 9:30 am – 4:00 pm (4:15 pm)
EDGX 7:30 am N/A 9:30 am – 4:00 pm (4:15 pm)
  • C1 also supports a Curb session: 4:30–5:00 pm (SPX/VIX/XSP).
  • Exchange shuts down ~17:30 ET daily (sends Logout with reason E).
  • Orders remaining after Regular Trading Session that are not eligible for Extended Trading are automatically cancelled.

13. Protocol Features — Key Notes

Messages in Flight

  • Max messages in flight between order handler and matching engine: 128.
  • If unacknowledged messages exceed 1,024, BOE order handler stops reading from the member TCP socket (flow control).
  • Reading resumes when unacknowledged messages fall below 960.

GTC/GTD Order Persistence

  • GTC and GTD orders persist between sessions. On EDGX/C2, GTC/GTD cancellation deadline is 4:45 pm ET; on C1, 5:15 pm ET.

Market Order NBBO Width Protection

  • Market orders rejected if NBBO width > 100% of midpoint (min $5.00, max $10.00).

Stale NBBO

  • If Cboe detects a stale NBBO, new orders are rejected for the affected class(es). Existing orders remain on the book but cannot be updated.

14. Common Pitfalls

Correct Incorrect
StartOfMessage = 0xBA 0xBA Using 0xB0 0xE3 or other values
MessageLength = payload + 2 MessageLength = payload only
StartOfMessage excluded from MessageLength Including StartOfMessage in length
String fields NUL-padded (0x00) Space-padded (0x20)
Side wire value = ASCII '1'/'2' (0x31/0x32) Side wire value = binary 1/2
Session messages: SequenceNumber = 0 Incrementing sequence on session messages
Inbound MatchingUnit = always 0 Setting MatchingUnit on outbound orders
Atomic sequence counter Hardcoded or non-thread-safe counter
Login Request must be first message Sending orders before login

15. Simulator Delta (Spec vs. Current Implementation)

Discrepancies between this spec and the current TitaniumBOE-Sim implementation to be addressed in Phase 2+:

Area Spec (v2.11.90) Simulator (current) Phase
Side wire values '1' = Buy, '2' = Sell (ASCII) fromByte(1/2) legacy path covers this Review
Capacity 'C' Customer (0x43) is a valid value Not in Capacity enum Phase 2
OrdType wire values '1'=Market, '2'=Limit (ASCII) fromByte(1/2) legacy path covers this Review
MessageType codes (session) 0x37/0x24/0x09/0x13 etc. Enum has 0x0001/0x01F5/0x01F8 (website values) Phase 2
MessageType codes (app) 0x38=NewOrder, 0x45=Cancel Enum has 0x07D1/0x07DA (website values) Phase 2
String padding NUL (0x00) Space (0x20) in OrderAcknowledgmentMessage Phase 2
OrderAcknowledgmentMessage MessageType = 0x25 (1 byte) Uses 0x25 but encodes as 1-byte ✅ OK

16. References

  • Spec PDF: docs/US_Options_BOE_Specification.pdf (v2.11.90, Oct 3, 2025)
  • Relevant sections:
    • §10 "Data Types" (p. 10) — complete type definitions
    • §11 "Optional Fields and Bit Fields" (p. 11)
    • §43 "Session — Message Header Fields" (p. 43) — header layout
    • §44 "Login, Replay and Sequencing" (p. 44)
    • §46 "Heartbeats" (p. 46)
    • §48 "Session Messages — Member to Cboe" (p. 48)
    • §53 "Session Messages — Cboe to Member" (p. 53)
    • §60 "Application Messages — New Order" (p. 60)
    • §196 "List of Optional Fields" (p. 196) — complete optional field directory
    • §216 "List of Message Types" (p. 216) — complete code table
Architecture diagram of TitaniumBOE-Sim
IMAGES