TitaniumBOE-Sim

Simulador del protocolo binario BOE de Cboe con matching engine, bots de trading, REST API, WebSocket y dashboard — todo en un único JAR deployable.

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

El Problema

El protocolo BOE (Binary Order Entry) de Cboe es el estándar binario que usan los traders institucionales para enviar órdenes a los exchanges de opciones de EE.UU. No es texto legible: cada mensaje es una secuencia exacta de bytes en Little Endian, con campos de tamaño fijo, precios codificados con 4 decimales implícitos y campos opcionales controlados por bitfields negociados al inicio de la sesión.

Entender cómo funciona por dentro — y poder experimentar con él — es prácticamente imposible sin acceso a sistemas reales de trading.

La Solución

Un simulador completo que habla el mismo lenguaje que Cboe, byte a byte, siguiendo la especificación oficial v2.11.90. Cualquier cliente BOE real puede conectarse como si fuera el exchange.

El sistema incluye:

  • Motor de matching con prioridad precio-tiempo — las órdenes se emparejan en orden de precio y, dentro del mismo precio, por orden de llegada (FIFO)
  • 3 bots de trading que mantienen actividad constante en el mercado: Market Maker (provee liquidez en ambos lados), Trend Follower (sigue el momentum) y Random Trader (simula ruido de mercado)
  • REST API + WebSocket para market data en tiempo real y operaciones desde cualquier cliente HTTP
  • Dashboard web (Astro + Tailwind) servido directamente desde el JAR — sin servidor ni build step extra
  • CLI interactivo para conectarse, enviar órdenes y monitorear el libro desde la terminal
  • Persistencia completa con RocksDB: órdenes, trades y sesiones sobreviven reinicios

Por Dentro

Cada conexión TCP corre en su propio Virtual Thread de Java 21 — el modelo más simple (I/O bloqueante) sin el costo de OS threads reales. Resultado: más de 500 sesiones concurrentes con latencia P99 de Order Acknowledgment por debajo de 5ms.

El matching engine sincroniza por símbolo en lugar de globalmente: AAPL y SPX pueden ejecutar matching en paralelo sin bloquearse entre sí. Las escrituras a RocksDB van a una cola asíncrona — el cliente recibe su confirmación antes de que nada toque disco.

Los mensajes del protocolo están modelados como sealed classes de Java 21, lo que permite un dispatch exhaustivo verificado en tiempo de compilación: agregar un nuevo tipo de mensaje sin manejarlo es un error de compilación, no un bug silencioso.

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
Diagrama de TitaniumBOE-Sim

En Números

  • 131 clases Java · 319 tests automatizados
  • 11 tipos de mensaje BOE con wire format exacto al spec
  • P99 < 5ms de latencia Order Acknowledgment bajo carga sostenida
  • 500+ conexiones TCP simultáneas sin drops
  • 10 fases de implementación — desde enums tipados hasta negociación de campos opcionales por sesión
DOCUMENTACIÓN

Arquitectura Técnica — TitaniumBOE-Sim

Versión del documento: 2.0
Protocolo de referencia: Cboe Titanium U.S. Options BOE Specification v2.11.90
Runtime: Java 21 · Maven 3.9 · Virtual Threads

1. Contexto del Problema

El protocolo Binary Order Entry (BOE) de Cboe es un protocolo binario de baja latencia usado para enviar órdenes de opciones en exchanges institucionales. Su complejidad radica en:

  • Formato binario Little Endian — cada campo tiene un offset fijo, tamaño exacto y tipo propio (Binary, Alpha, Text, Binary Price con 4 decimales implícitos, DateTime en nanosegundos).
  • Campos opcionales controlados por bitfields — la presencia de cada campo se negocia por sesión mediante un Return Bitfields Parameter Group en el Login Request. Cada mensaje es auto-descriptivo.
  • Múltiples versiones del protocolo — cambiar de BOEv2.11 a BOEv3.x requiere reescribir manualmente todo el parser, la serialización y las pruebas.
  • Flujo de sesión estricto — Login obligatorio antes de cualquier orden; secuencias por matching unit; heartbeats en ambas direcciones.

TitaniumBOE-Sim resuelve esto en Java 21 con una implementación completa y testeable del protocolo, un motor de matching real, y una capa de persistencia, REST API y dashboard todo en un único JAR.

2. Visión General del Sistema

┌──────────────────────────────────────────────────────────────────────────┐
│                        Clientes Externos                                 │
│   Browser ─────────── REST / WebSocket ─────────── CLI / BOE Client SDK  │
└────────────┬─────────────────────────────────────────────────────┬───────┘
             │ HTTP/WS (puerto 9091)                               │ TCP (puerto 8081)
             ▼                                                     ▼
┌────────────────────────────┐              ┌────────────────────────────────┐
│      RestApiServer         │              │       CboeServer               │
│  Javalin 6.7 + Scalar UI   │              │  ServerSocketChannel           │
│  ┌──────────┬───────────┐  │              │  VirtualThread por conexión    │
│  │ REST     │ WebSocket │  │              │  ┌──────────────────────────┐  │
│  │ endpoints│ /ws/feed  │  │              │  │ ClientConnectionHandler  │  │
│  └──────────┴───────────┘  │              │  │  - Login / Logout / HB   │  │
└────────────┬───────────────┘              │  │  - New/Cancel/Modify Ord │  │
             │                              │  └────────────┬─────────────┘  │
             │                              └───────────────┼────────────────┘
             │                                              │
             └──────────────────────┬───────────────────────┘
                                    │
                    ┌───────────────▼──────────────────┐
                    │           OrderManager           │
                    │  Valida, enruta, responde        │
                    └───────────────┬──────────────────┘
                                    │
               ┌────────────────────┼─────────────────────┐
               │                    │                     │
    ┌──────────▼───────┐  ┌─────────▼────────┐  ┌─────────▼──────────┐
    │  MatchingEngine  │  │  OrderRepository │  │  TradeRepository   │
    │  synchronized    │  │  (RocksDB async) │  │  (RocksDB async)   │
    │  por símbolo     │  └──────────────────┘  └────────────────────┘
    │  ┌────────────┐  │
    │  │ OrderBook  │  │  ── TreeMap<BigDecimal, List<Order>>
    │  │ (por sym.) │  │  ── precio-tiempo (FIFO por nivel)
    │  └────────────┘  │
    └──────────────────┘
               │
    ┌──────────▼──────────┐
    │   BotManager        │
    │  MarketMaker        │
    │  TrendFollower      │
    │  RandomTrader       │
    └─────────────────────┘

3. Stack Tecnológico

Capa Tecnología Justificación
Runtime Java 21, Virtual Threads Un VThread por conexión TCP sin overhead de OS threads; >500 conexiones concurrentes
Build Maven 3.9, frontend-maven-plugin Compila Astro y empaqueta el frontend en el JAR — un solo artefacto deployable
Servidor BOE NIO ServerSocketChannel No bloqueante en el accept; cada cliente corre en su propio VThread
REST / WebSocket Javalin 6.7 Ligero, sin reflection en el hot path, compatible con VThreads
Frontend Astro 5 + Tailwind CSS Generación estática en build time; servido desde classpath
Persistencia RocksDB 9.11 Escritura asíncrona (write-behind queue), alta throughput para órdenes
Seguridad JBCrypt Hash de contraseñas con work factor configurable
Testing JUnit 5 + Awaitility 319 tests; pruebas de wire format contra la spec

4. Capa de Protocolo BOE

4.1 Jerarquía de Mensajes (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

Las sealed classes permiten pattern matching exhaustivo en el dispatcher:

switch (message) {
    case NewOrderMessage m    -> handleNewOrder(m);
    case CancelOrderMessage m -> handleCancelOrder(m);
    case ModifyOrderMessage m -> handleModifyOrder(m);
    // El compilador verifica exhaustividad
}

4.2 Header de Mensajes (10 bytes — todos los mensajes)

Offset  Len  Campo            Notas
------  ---  ---------------  -------------------------------------------------
0       2    StartOfMessage   Siempre 0xBA 0xBA
2       2    MessageLength    Bytes del mensaje incluyendo este campo, sin SOM
4       1    MessageType      Identificador 1 byte del tipo de mensaje
5       1    MatchingUnit     Siempre 0 en mensajes inbound
6       4    SequenceNumber   Contador LE 32-bit por stream de aplicación

Fórmula: MessageLength = total_bytes - 2
Endianness: Little Endian en todos los campos binarios (Intel x86 byte order)

4.3 Tipos de Datos del Protocolo

Tipo Tamaño Representación Ejemplo
Binary variable LE unsigned 64 00 00 00 = 100
Binary Price 8 bytes LE signed, 4 decimales implícitos 08 E2 01 00... = 12.34 (= 123400 / 10000)
Short Binary Price 4 bytes LE signed, 4 decimales implícitos 0C 30 00 00 = 1.23
DateTime 8 bytes Nanosegundos desde Unix epoch
Text variable ASCII, relleno con NUL (0x00) "ABC\x00\x00"
Alpha variable ASCII, relleno con NUL (0x00) "MSFT\x00\x00\x00\x00"

4.4 Campos Opcionales y Bitfields

Los mensajes como New Order y Modify Order incluyen campos opcionales controlados por bytes de bitfield:

[Fixed Header (10B)] [Campo fijo...] [NumBitfields (1B)] [Bitfield₁] ... [BitfieldN] [Campo_opt₁] [Campo_opt₂] ...

Regla: los campos opcionales aparecen en orden — primer bitfield primero, bit menos significativo primero dentro de cada byte.

Negociación en login: el cliente declara via el Return Bitfields Parameter Group (0x81) qué campos quiere recibir en cada tipo de mensaje de respuesta. El servidor respeta esa negociación durante toda la sesión y cada mensaje de respuesta es auto-descriptivo (incluye sus propios bitfield bytes).

// Clase ReturnBitfields encapsula la negociación por tipo de mensaje
public class ReturnBitfields {
    private final Map<Byte, byte[]> masksByMessageType;

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

4.5 Binary Price: Implementación

public record BinaryPrice(long rawValue) {
    private static final long SCALE = 10_000L;  // 4 decimales implícitos

    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. Capa del Servidor BOE

5.1 Modelo de Concurrencia

CboeServer
  └── ServerSocketChannel (non-blocking accept)
        └── Por cada conexión aceptada:
              Thread.ofVirtual().start(() -> {
                  ClientConnectionHandler handler = new ClientConnectionHandler(socket, ...);
                  handler.run();  // Bucle bloqueante — el VThread gestiona el bloqueo
              })

Java 21 Virtual Threads permiten el modelo de programación más simple (blocking I/O) sin el overhead de OS threads reales. Cada conexión tiene su propio VThread; >500 conexiones simultáneas con footprint mínimo.

5.2 ClientConnectionHandler — Flujo de Sesión

                     ┌─ Conexión TCP establecida ─┐
                     │                            │
                     ▼                            │
              [Lee LoginRequest]                  │
                     │                            │
          ┌──────────▼────────────┐               │
          │  AuthenticationService│               │
          │  - Busca usuario BD   │               │
          │  - BCrypt.checkpw()   │               │
          └──────────┬────────────┘               │
                     │ OK / FAIL                  │
          ┌──────────▼────────────┐               │
          │  Envía LoginResponse  │               │
          │  Negocia ReturnBFlds  │               │
          └──────────┬────────────┘               │
                     │                            │
         ┌───────────▼─────────────┐              │
         │   Bucle de mensajes     │◄─────────────┘
         │   (HeartbeatMonitor)    │
         │  switch(message) {      │
         │    NewOrder    → ...    │
         │    CancelOrder → ...    │
         │    ModifyOrder → ...    │
         │    ClientHB    → ...    │
         │    LogoutReq   → ...    │
         │  }                      │
         └───────────┬─────────────┘
                     │
              [LogoutRequest / timeout]
              Envía Logout → cierra socket

5.3 Secuencias y Heartbeats

  • Mensajes de sesión (Login, Logout, Heartbeat): SequenceNumber = 0 siempre
  • Mensajes de aplicación Member→Cboe: stream único por sesión, incrementa el cliente
  • Mensajes de aplicación Cboe→Member: por matching unit (independiente por unidad)
  • Heartbeat: si no llega ningún dato en 1 segundo, el servidor envía ServerHeartbeat
  • Timeout: 5 segundos sin dato → el servidor envía Logout y cierra conexión

6. Motor de Matching

6.1 Estructura de Datos — OrderBook

// Un OrderBook por símbolo, creado bajo demanda
class OrderBook {
    private final TreeMap<BigDecimal, List<Order>> bids;  // descendente (mejor precio primero)
    private final TreeMap<BigDecimal, List<Order>> asks;  // ascendente  (mejor precio primero)
}

Dentro de cada nivel de precio: las órdenes se mantienen en una List<Order> en orden de llegada — FIFO (price-time priority).

6.2 Ciclo de Matching — processOrder

processOrder(Order incoming)
    │
    ├── ¿Puede cruzar? (canMatch)
    │    ├── MARKET → siempre sí
    │    ├── BUY LIMIT → sí si price >= bestAsk
    │    └── SELL LIMIT → sí si price <= bestBid
    │
    ├── SÍ → executeMatching (loop):
    │         ├── Obtiene la mejor contrapartida (FIFO en ese nivel)
    │         ├── Verifica self-trade (misma username → cancela pasiva)
    │         ├── fillQty = min(aggressiveLeavesQty, passiveLeavesQty)
    │         ├── execPrice = precio de la pasiva (price-time priority)
    │         ├── Crea Trade, actualiza leavesQty en ambas órdenes
    │         ├── Si pasiva completada → removeOrder(passive)
    │         └── Notifica listeners (WebSocket broadcast)
    │
    └── Si leavesQty > 0 y order.isLive() → addOrder(book)

6.3 Sincronización

// Lock por símbolo — no hay contención entre AAPL y 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) {
        // ... matching completo bajo el lock del símbolo
    }
}

6.4 Modify Order — Lógica Spec (p.77)

El Modify Order requiere un orden específico para mantener la integridad del OrderBook:

1. removeOrder(book)        // ANTES de cambiar el precio (TreeMap key)
2. Calcular delta:
     delta        = newOrderQty - order.getEffectiveOrderQty()
     newLeavesQty = order.getLeavesQty() + delta
3. Si newLeavesQty <= 0 → order.cancel() → retorna []
4. order.modify(newClOrdID, newPrice, newOrdType, newOrderQty, newLeavesQty)
5. Intentar matching al nuevo precio
6. Si leavesQty > 0 → addOrder(book) al nuevo precio

Por qué este orden: OrderBook usa TreeMap<BigDecimal, List<Order>> donde el precio es la clave. Si se actualizara el precio antes de remover la orden, el removeOrder buscaría en el nivel de precio nuevo y no encontraría la orden (todavía está en el nivel viejo).

6.5 Shadow Fields en Order (soporte a modify sin romper TreeMap)

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

    // Mutable overrides aplicados por Modify Order
    private volatile BigDecimal modifiedPrice;
    private volatile String modifiedClOrdID;
    private volatile OrdType modifiedOrdType;
    private volatile int modifiedOrderQty;  // 0 = no modificado

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

7. Ciclo de Vida de una Orden

                          [New Order recibida]
                                  │
                    ┌──────────────▼────────────┐
                    │      OrderValidator       │
                    │  - ClOrdID único?         │
                    │  - Side, Symbol, Qty OK?  │
                    │  - Precio para LIMIT?     │
                    └──────┬──────────┬─────────┘
                      OK   │          │ Error
                           │          ▼
                           │   OrderRejected (0x26)
                           │
              ┌────────────▼────────────────┐
              │ order.state = PENDING_NEW   │
              │ orderRepository.saveAsync() │
              └────────────┬────────────────┘
                           │
              ┌────────────▼────────────────┐
              │   matchingEngine.process()  │
              └────────────┬────────────────┘
                           │
               ┌───────────▼───────────────┐
               │ order.acknowledge()       │
               │ order.state = LIVE        │
               │ Envía OrderAck (0x25)     │
               └───────────┬───────────────┘
                           │
           ┌───────────────┼───────────────┐
           │               │               │
      FILL parcial    FILL completo   Sin fill
           │               │               │
   PARTIALLY_FILLED    FILLED           LIVE
     ┌─────┘               │            ┌──┘
     │   Envía             │            │  Permanece en
     │   OrderExec         │            │  OrderBook
     │   (0x2C)       OrderExec         │
     │                (0x2C)            │
     │                                  │
     └──── Modify/Cancel posibles ──────┘
                           │
              [Cancel] → OrderCancelled (0x2A)
              [Modify] → OrderModified  (0x27)

Estados de OrderState:

Estado 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. Persistencia — RocksDB

8.1 Arquitectura Write-Behind

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

Ventaja: el matching engine y el dispatcher nunca esperan I/O de disco. La confirmación va al cliente (OrderAck) antes de que la persistencia se complete.

8.2 Column Families

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

9. REST API y WebSocket

9.1 Endpoints

Puerto: 9091

Grupo Método Path Auth Descripción
Sistema GET /api/health No Estado del servidor
Símbolos GET /api/symbols No Símbolos disponibles
Símbolos GET /api/symbols/{symbol} No Market data de un símbolo
Auth POST /api/auth/register No Registrar usuario
Auth POST /api/auth/login Basic Validar credenciales
Órdenes POST /api/orders Basic Crear orden
Órdenes GET /api/orders/active Basic Órdenes activas del usuario
Órdenes GET /api/orders/{clOrdID} Basic Detalle de una orden
Órdenes DELETE /api/orders/{clOrdID} Basic Cancelar orden
Posiciones GET /api/positions Basic Posiciones del usuario
Posiciones GET /api/positions/{symbol} Basic Posición por símbolo
Trades GET /api/trades/my Basic Mis trades
Trades GET /api/trades/recent Basic Trades recientes (mercado)
Trades GET /api/trades/symbol/{symbol} Basic Trades por símbolo
Simulador GET /api/simulator/status No Estado del simulador
Simulador GET /api/simulator/bots No Lista de bots
Simulador POST /api/simulator/bots/{id}/start Basic Iniciar bot
Simulador POST /api/simulator/bots/{id}/stop Basic Detener bot
Docs GET /api/docs No Scalar UI (OpenAPI)

9.2 WebSocket Feed

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

Eventos emitidos en tiempo real:

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

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

// Cambio de estado de orden
{ "type": "ORDER_STATUS", "clOrdID": "ABC123", "status": "FILLED" }

9.3 Autenticación

HTTP Basic Auth en todos los endpoints autenticados:

Authorization: Basic base64(username:password)

Credenciales demo (modo DEMO_MODE=true):

  • TRD1 / Pass1234!
  • TRD2 / Pass5678!

10. Bots de Trading

Tres estrategias ejecutan en hilos virtuales paralelos:

Bot Estrategia Descripción
MarketMakerStrategy Provee liquidez Coloca bids y asks dentro del spread; ajusta según P&L
TrendFollowerStrategy Sigue tendencia Detecta momentum de precio; compra en uptrend, vende en downtrend
RandomTraderStrategy Ruido aleatorio Órdenes aleatorias para simular mercado activo

Cada bot opera via la REST API interna, generando actividad continua en el matching engine. En DEMO_MODE=true los tres arrancan automáticamente.

11. Decisiones de Diseño Clave

11.1 Java 21 Virtual Threads

Decisión: un VThread por conexión TCP, I/O bloqueante.
Alternativa considerada: NIO non-blocking con Selector loop (Netty style).
Por qué VThreads: código más simple y legible, sin callback hell, sin CompletableFuture chains. Java 21 garantiza que el scheduler mapea VThreads a OS threads eficientemente. En pruebas: >500 conexiones simultáneas con latencia P99 < 5ms.

11.2 Sealed Class Hierarchy + Pattern Matching

Decisión: BoeProtocolMessage como sealed class con dos ramas: SessionMessage y ApplicationMessage.
Por qué: el compilador verifica exhaustividad del switch. Agregar un nuevo tipo de mensaje requiere actualizar el switch — la omisión es un error de compilación, no un bug silencioso en runtime.

11.3 Synchronization por Símbolo en MatchingEngine

Decisión: ConcurrentHashMap<String, Object> de locks, uno por símbolo.
Por qué: AAPL y SPX no comparten estado; no tiene sentido serializar su matching. Esto permite matching paralelo entre símbolos con zero contención entre ellos.

11.4 TreeMap para OrderBook

Decisión: TreeMap<BigDecimal, List<Order>> ordenado por precio.
Por qué: getBestBid() = firstKey() y getBestAsk() = firstKey() son O(log n). Insertar un nivel nuevo también es O(log n). La alternativa (PriorityQueue) no permite acceso eficiente a un nivel ya existente.

11.5 Write-Behind Queue para Persistencia

Decisión: LinkedBlockingQueue consumida por un thread background hacia RocksDB.
Por qué: el hot path (matching + ACK al cliente) nunca espera disco. El trade-off: en un crash abrupto se pueden perder las últimas escrituras en cola. Aceptable en un simulador; en producción se usaría WAL + fsync.

11.6 Shadow Fields en Order para Modify

Decisión: campos modifiedPrice, modifiedClOrdID, etc. en vez de mutar los campos final.
Por qué: los campos originales son final para garantizar que el OrderBook puede remover la orden al precio correcto. El getter efectivo devuelve el campo modificado si existe, el original si no. Esto hace el Modify Order seguro respecto al TreeMap.

12. Testing

12.1 Cobertura

319 tests distribuidos en 30 clases:

Área Tests Enfoque
Wire format (protocol) ~150 Parseo byte a byte contra la spec
Matching engine ~20 Price-time priority, self-trade, Modify delta logic
Session layer ~40 Login, logout, heartbeat, secuencias
Order management ~30 Validación, ciclo de vida, estados
Persistencia ~15 RocksDB CRUD, serialización
REST / auth ~20 Endpoints, autenticación, errores
Load test manual LoadTestRunner (5 fases, no en el suite de CI)

12.2 Load Test Runner (Fase 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
Fase Métrica Criterio
1 — TCP Capacity Conexiones aceptadas ≥ 500 simultáneas
2 — BOE Login Login rate ≥ 200 logins/seg
3 — REST API Throughput ≥ 800 req/seg
4 — Order Ack Latency P99 < 5ms (usando NewOrderMessage spec-compliant)
5 — Memory Stability Heap growth < 200 MB por 10,000 órdenes

13. Estructura del Proyecto

TitaniumBOE-Sim/
├── src/main/java/com/boe/simulator/
│   ├── protocol/
│   │   ├── message/          # 20 clases de mensajes BOE (sealed hierarchy)
│   │   ├── types/            # Enums de dominio (Side, OrdType, Capacity…)
│   │   └── serialization/    # BoeMessageSerializer
│   ├── server/
│   │   ├── CboeServer.java           # Servidor TCP principal
│   │   ├── connection/               # ClientConnectionHandler por sesión
│   │   ├── 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/               # Controladores REST
│   │   ├── service/                  # Servicios de aplicación
│   │   ├── 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 (compilado en el JAR)
├── docs/
│   ├── ARCHITECTURE.md               # Este documento
│   ├── API_DOCUMENTATION.md          # Referencia REST completa
│   └── BOE Protocol Specification - Quick Reference.md
├── Dockerfile
├── docker-compose.yml
└── pom.xml

Documento mantenido junto al código — si el comportamiento cambia, actualizar esta descripción.

Documentación REST API — TitaniumBOE-Sim

Puerto: 9091
Base URL: http://localhost:9091
Autenticación: HTTP Basic Auth
Formato: JSON (UTF-8)

Acceso a Documentación Interactiva

Una vez que el servidor esté corriendo:

Interfaz URL Descripción
Scalar UI http://localhost:9091/api/docs Recomendada — UI moderna con ejemplos de código
Swagger UI http://localhost:9091/api/swagger Alternativa clásica
OpenAPI JSON http://localhost:9091/openapi Especificación cruda

Iniciar el Servidor

# Build y arranque rápido (modo demo — usuarios y datos precargados)
mvn clean package -DskipTests
DEMO_MODE=true java -jar target/boe-simulator-*.jar

Credenciales demo:

  • TRD1 / Pass1234!
  • TRD2 / Pass5678!

Autenticación

Todos los endpoints marcados con 🔐 requieren credenciales via HTTP Basic Auth:

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

# Forma abreviada con curl
curl -u TRD1:Pass1234! http://localhost:9091/api/orders/active

Endpoints

Sistema

GET /api/health

Estado del servidor. No requiere autenticación.

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

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

Autenticación

POST /api/auth/register

Registra un nuevo usuario.

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

{ "success": true, "message": "Usuario registrado correctamente" }
Código Significado
201 Usuario creado
409 Username ya existe
400 Datos inválidos

POST /api/auth/login 🔐

Valida credenciales (retorna 200 si son correctas, 401 si no).

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

Símbolos y Market Data

GET /api/symbols

Lista todos los símbolos con actividad en el simulador.

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

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

GET /api/symbols/{symbol}

Market data de un símbolo: best bid/ask, último precio, volumen.

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

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

Órdenes

POST /api/orders 🔐

Envía una nueva orden. El servidor la procesa a través del matching engine y retorna el estado inicial.

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 — campos:

Campo Tipo Requerido Valores
symbol string Sí Símbolo del activo
side string Sí BUY, SELL
orderQty int Sí 1 – 999,999
price decimal Para LIMIT Precio límite
orderType string Sí LIMIT, MARKET
capacity string Sí CUSTOMER, AGENCY, MARKET_MAKER, PRINCIPAL
account string No Cuenta del cliente

Respuesta:

{
  "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 🔐

Órdenes vivas (LIVE, PARTIALLY_FILLED) del usuario autenticado.

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

GET /api/orders/{clOrdID} 🔐

Detalle de una orden por su ID de cliente.

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

DELETE /api/orders/{clOrdID} 🔐

Cancela una orden viva. Retorna 404 si no existe o no pertenece al usuario autenticado.

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

{ "success": true, "message": "Orden cancelada" }

Posiciones

GET /api/positions 🔐

Todas las posiciones del usuario (netas por símbolo tras 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} 🔐

Posición neta en un símbolo específico.

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

Trades

GET /api/trades/my 🔐

Trades ejecutados por el usuario autenticado (como comprador o vendedor).

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

Últimos trades del mercado (todos los usuarios). No requiere autenticación.

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

GET /api/trades/symbol/{symbol}

Trades de un símbolo específico (mercado completo).

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

Simulador (Admin)

GET /api/simulator/status

Estado general del simulador: uptime, órdenes totales, matches.

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

GET /api/simulator/bots

Lista de bots configurados y su estado.

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

Conecta para recibir eventos en tiempo real del mercado.

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;
  }
};

Tipos de eventos:

Tipo Campos Descripción
TRADE symbol, price, qty, timestamp Trade ejecutado en el mercado
ORDER_BOOK symbol, bids[], asks[] Actualización del libro de órdenes
ORDER_STATUS clOrdID, status Cambio de estado de una orden

Códigos de Respuesta

Código Significado
200 OK
201 Recurso creado
400 Request inválido (campos faltantes o malformados)
401 No autenticado (credenciales requeridas)
403 No autorizado (la orden no pertenece al usuario)
404 Recurso no encontrado
409 Conflicto (username duplicado, ClOrdID duplicado)
500 Error interno del servidor

Formato de Error

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

Variables de Entorno

Variable Default Descripción
DEMO_MODE true Pre-carga usuarios demo y datos de mercado
BOE_PORT 8081 Puerto del protocolo BOE binario (TCP)
API_PORT 9091 Puerto REST API + dashboard
LOG_LEVEL INFO Verbosidad de logs (FINE, INFO, WARNING)
ADMIN_USERNAME — Usuario admin en modo no-demo
ADMIN_PASSWORD — Contraseña admin

Referencia del Protocolo BOE Nativo

Para interactuar directamente por TCP (puerto 8081) usando el protocolo BOE binario, ver:

Especificación del Protocolo BOE — Referencia Rápida

Fuente: Cboe Titanium U.S. Options Binary Order Entry Specification
Versión: 2.11.90 · 3 de octubre de 2025

1. Fundamentos del Protocolo

  • Toda comunicación es por TCP/IP estándar.
  • Todos los valores binarios son Little Endian (orden de bytes Intel x86), no network byte order.
  • Cada mensaje se identifica con un MessageType de 1 byte único.
  • La terminología refleja el protocolo FIX (Side, TimeInForce, OrdType, etc.) para mayor familiaridad.

2. Cabecera de Mensaje (10 bytes — en todos los mensajes)

Offset  Len  Campo             Notas
------  ---  ----------------  -------------------------------------------------
0       2    StartOfMessage    Siempre 0xBA 0xBA
2       2    MessageLength     Bytes del mensaje incl. este campo, excl. StartOfMessage
4       1    MessageType       Identificador de mensaje de 1 byte (ver §5)
5       1    MatchingUnit      Unidad que creó el mensaje (ver notas abajo)
6       4    SequenceNumber    Contador secuencial LE de 32 bits (ver §6)

Reglas de MatchingUnit:

  • Mensajes de sesión → siempre 0 en ambas direcciones.
  • Mensajes de aplicación del miembro a Cboe (entrantes) → siempre 0.
  • Mensajes de aplicación de Cboe al miembro (salientes) → asignado por Cboe a la unidad de matching.

Fórmula de MessageLength:

MessageLength = (bytes totales del mensaje) - 2
             = MessageType(1) + MatchingUnit(1) + SequenceNumber(4) + cuerpo + 2

No incluye los dos bytes de StartOfMessage.

3. Tipos de Datos

Tipo Byte Order Tamaño Descripción
Binary LE sin signo contexto FE = 254; 64 00 00 00 = 100
Signed Binary LE con signo (complemento a dos) contexto DF = -33; 64 00 00 00 = +100
Binary Price LE con signo 8 bytes 4 decimales implícitos. 08 E2 01 00 00 00 00 00 = 123.400/10.000 = 12,34. Precios negativos soportados (instrumentos complejos).
Short Binary Price LE con signo 4 bytes 4 decimales implícitos. 0C 30 00 00 = 12.300/10.000 = 1,23
Signed Binary Fee LE con signo 8 bytes 5 decimales implícitos.
Alpha — contexto Solo mayúsculas A-Z y minúsculas a-z. Relleno con NUL (0x00) a la derecha.
Alphanumeric — contexto A-Z, a-z, 0-9. Relleno con NUL (0x00) a la derecha.
Text — contexto ASCII imprimible. Relleno con NUL (0x00) a la derecha.
DateTime LE sin signo 8 bytes Nanosegundos desde Unix epoch (UTC). 1.294.909.373.757.324.000 = 2011-01-13 09:02:53.757324 UTC
Date LE sin signo 4 bytes YYYYMMDD expresado como entero.

Todos los campos de texto/cadena son relleno NUL (0x00), alineados a la izquierda.

4. Campos Opcionales y Bitfields

Mensajes como New Order y Modify Order agregan campos opcionales después de los campos requeridos. La presencia se controla mediante bytes de bitfield:

  • Un byte de conteo (NumberOfBitfields) declara cuántos bytes de bitfield siguen.
  • Cada bit en un byte de bitfield habilita un campo opcional.
  • Los campos opcionales se agregan en orden: primer bitfield primero, bit de menor orden primero.
  • Si un campo opcional es irrelevante en un contexto dado, sigue presente pero con todos los bytes en 0x00.
  • El conjunto de campos opcionales que Cboe retorna se negocia en el momento del login mediante el Return Bitfields Parameter Group en el Login Request.
  • Cada mensaje de Cboe al miembro incluye el eco de bitfields para que cada mensaje sea auto-descriptivo (sin necesidad de referenciar el login).

Ver Input Bitfields Per Message (p. 171) y Return Bitfields Per Message (p. 179) en la especificación.

5. Códigos de Tipo de Mensaje

5.1 Mensajes de Sesión

Tipo de Mensaje Código Dirección Descripción
Login Request 0x37 Miembro → Cboe Primer mensaje al conectar
Logout Request 0x02 Miembro → Cboe Cierre de sesión ordenado
Client Heartbeat 0x03 Miembro → Cboe Keep-alive
Login Response 0x24 Cboe → Miembro Aceptación/rechazo de login
Logout 0x08 Cboe → Miembro Terminación de sesión
Server Heartbeat 0x09 Cboe → Miembro Keep-alive
Replay Complete 0x13 Cboe → Miembro Fin de la reproducción de mensajes perdidos

5.2 Mensajes de Aplicación — Miembro a Cboe

Tipo de Mensaje Código Descripción
New Order 0x38 Enviar una nueva orden
New Order (Short) 0x39 Nueva orden abreviada
New Order Cross 0x3A Orden cruzada (C1/EDGX)
New Complex Instrument 0x3C Definir instrumento complejo (C1/C2/EDGX)
New Complex Order 0x3D Orden multi-pata (C1/EDGX/C2)
New Complex Order Short 0x3E Orden compleja abreviada
New Order Cross Multileg 0x3F Cruce multi-pata (C1/EDGX)
Cancel Order 0x45 Cancelar una orden activa
Mass Cancel Order 0x46 Cancelar múltiples órdenes
Modify Order 0x4A Modificar una orden activa
Quote Update 0x59 Actualización de cotización
Purge Orders 0x62 Purgar órdenes por criterio
Reset Risk 0x63 Reinicio de riesgo

5.3 Mensajes de Aplicación — Cboe a Miembro

Tipo de Mensaje Código Descripción
Order Acknowledgment 0x25 Orden aceptada y activa
Order Rejected 0x26 Orden rechazada con motivo
Order Modified 0x27 Modificación confirmada
Order Restated 0x28 Orden re-declarada (p.ej., done-for-day)
User Modify Rejected 0x29 Modificación rechazada
Order Cancelled 0x2A Cancelación confirmada
Cancel Rejected 0x2B Cancelación rechazada
Order Execution 0x2C Ejecución de trade (fill)
Trade Cancel or Correct 0x2D Anulación/corrección de trade
Mass Cancel Acknowledgment 0x99 Cancelación masiva confirmada
Purge Notification 0x9B Purga confirmada

6. Protocolo de Sesión

6.1 Login y Secuenciamiento

  • Los mensajes de sesión (Login, Logout, Heartbeat) no están secuenciados — SequenceNumber = 0 en ambas direcciones.
  • Los mensajes de aplicación Miembro → Cboe están secuenciados con un único flujo de secuencia para todas las unidades de matching.
  • Los mensajes de aplicación Cboe → Miembro están secuenciados por unidad de matching (contador independiente por unidad).
  • Un Login Request debe ser el primer mensaje enviado después de la conexión TCP.
  • La sesión se identifica por (username + SessionSubID); solo una conexión concurrente por par.
  • Al reconectar, el miembro envía el último número de secuencia recibido por unidad; Cboe reproduce los mensajes perdidos.
  • Saltos hacia adelante (secuencia mayor a la esperada) se ignoran. Saltos hacia atrás → Cboe envía Logout.
  • Replay Complete se envía inmediatamente después del Login Response si no hay mensajes que reproducir.
  • Cboe rechaza todas las órdenes durante la reproducción.

6.2 Reset de Secuencia

No hay comando de reset formal. Para resetear: enviar Login Request con NoUnspecifiedUnitReplay = 0x01 y NumberOfUnits = 0. Usar LastReceivedSequenceNumber del Login Response como nueva secuencia de inicio.

6.3 Heartbeats

  • Disparador: si no se han enviado datos en ninguna dirección durante 1 segundo.
  • Tiempo de espera: si Cboe no recibe datos entrantes o heartbeats durante 5 segundos → envía Logout y cierra la conexión.
  • Los heartbeats de Cboe no incrementan el número de secuencia.
  • Se recomienda a los miembros tener un intervalo de heartbeat de 1 segundo y lógica de obsolescencia similar.

6.4 Cierre de Sesión

  1. El miembro envía Logout Request.
  2. Cboe drena cualquier dato saliente en cola.
  3. Cboe responde con Logout y cierra la conexión.
  4. Después de recibir un Logout Request, Cboe ignora todos los mensajes entrantes excepto Client Heartbeat.
  5. Un miembro puede cerrar TCP sin cerrar sesión, pero puede perder mensajes en cola.

6.5 Cierre del Exchange

Cboe envía Logout (razón = E = End of Day) a todos los puertos conectados aproximadamente a las 17:30 ET diariamente, sin esperar una solicitud de logout.

7. Tablas de Campos de Mensajes de Sesión

7.1 Login Request (0x37) — Miembro a Cboe

Tabla 11 — Campos del Mensaje Login Request

Offset  Len  Tipo          Campo                 Notas
------  ---  ------------  --------------------  ----------------------------------
0       2    Binary        StartOfMessage        0xBA 0xBA
2       2    Binary        MessageLength         Incl. este campo, excl. SOM
4       1    Binary        MessageType           0x37
5       1    Binary        MatchingUnit          Siempre 0 (entrante)
6       4    Binary        SequenceNumber        Siempre 0 para mensajes de sesión
10      4    Alphanumeric  SessionSubID          ID de sub-sesión suministrado por Cboe
14      4    Alphanumeric  Username              Nombre de usuario suministrado por Cboe
18      10   Alphanumeric  Password              Contraseña suministrada por Cboe
28      1    Binary        NumberOfParamGroups   Número de grupos de parámetros (n ≥ 0)
         …   —             ParamGroup₁..ₙ        Ver §7.1.1 y §7.1.2

Tamaño en cable: Variable (mínimo 29 bytes totales con 0 grupos de parámetros)
MessageLength = 27 + bytes de grupos de parámetros

Ejemplo de Login Request (Tabla 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
…               (grupos de parámetros)

7.1.1 Grupo de Parámetros Unit Sequences (0x80)

Transporta el último número de secuencia saliente consumido por unidad de matching, para que Cboe pueda reproducir los mensajes perdidos.

Offset  Len  Campo               Notas
------  ---  ------------------  -----------------------------------------
0       2    ParamGroupLength    Bytes de este grupo, incluyendo este campo
2       1    ParamGroupType      0x80
3       1    NoUnspecifiedUnitReplay  0x00 = reproducir no especificados; 0x01 = suprimir
4       1    NumberOfUnits       Pares unidad/secuencia a continuación
—       1    UnitNumber₁         Número de unidad
—       4    UnitSequence₁       Última secuencia recibida para la unidad
…

7.1.2 Grupo de Parámetros Return Bitfields (0x81)

Declara qué campos opcionales debe incluir Cboe en cada tipo de mensaje saliente durante el resto de la sesión.

Offset  Len  Campo                  Notas
------  ---  ---------------------  -------------------------------------------
0       2    ParamGroupLength       Bytes de este grupo, incluyendo este campo
2       1    ParamGroupType         0x81
3       1    MessageType            Tipo de mensaje de retorno (p.ej., 0x25 = Order Ack)
4       1    NumberOfReturnBitfields  Cantidad de bitfields
5       1    ReturnBitfield₁..ₙ    Un byte por bitfield

Se permiten múltiples instancias (una por tipo de mensaje Cboe→Miembro que desees configurar).

7.2 Logout Request (0x02) — Miembro a Cboe

Tabla 15 — Campos del Mensaje Logout Request

Offset  Len  Tipo    Campo            Notas
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x02
5       1    Binary  MatchingUnit     Siempre 0
6       4    Binary  SequenceNumber   Siempre 0

Total: 10 bytes. MessageLength = 8. SequenceNumber = siempre 0 en mensajes de sesión.

7.3 Client Heartbeat (0x03) — Miembro a Cboe

Tabla 17 — Campos del Mensaje Client Heartbeat

Offset  Len  Tipo    Campo            Notas
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x03
5       1    Binary  MatchingUnit     Siempre 0
6       4    Binary  SequenceNumber   Siempre 0

Total: 10 bytes. Estructura idéntica a Logout Request, diferente MessageType.

7.4 Login Response (0x24) — Cboe a Miembro

Tabla 19 — Campos del Mensaje Login Response

Offset  Len   Tipo          Campo                    Notas
------  ----  ------------  -----------------------  ----------------------------------
0       2     Binary        StartOfMessage           0xBA 0xBA
2       2     Binary        MessageLength            Variable (≥ 136 en caso de éxito)
4       1     Binary        MessageType              0x24
5       1     Binary        MatchingUnit             Siempre 0
6       4     Binary        SequenceNumber           Siempre 0
10      1     Alphanumeric  LoginResponseStatus      Ver códigos abajo
11      60    Text          LoginResponseText        Descripción legible (relleno NUL)
71      1     Binary        NoUnspecifiedUnitReplay  Eco del campo del Login Request
72      4     Binary        LastReceivedSequenceNumber  Última secuencia entrante procesada por Cboe
76      1     Binary        NumberOfUnits            Pares unidad/secuencia a continuación
—       1     Binary        UnitNumber₁              Número de unidad
—       4     Binary        UnitSequence₁            Mayor secuencia disponible Cboe→Miembro
…
—       1     Binary        NumberOfParamGroups      Eco de los grupos del Login Request
—       …     —             ParamGroup₁..ₙ           Eco de los grupos del Login Request

Valores de LoginResponseStatus:

Código Significado
A Login Aceptado
N No autorizado (usuario/contraseña inválidos)
D Sesión deshabilitada
B Sesión en uso (ya conectado)
S Sesión inválida
Q Secuencia adelantada en el mensaje de login
I Unidad inválida en el mensaje de login
F Campo de bitfield de retorno inválido en el login
M Estructura de Login Request inválida

Nota: La longitud de la respuesta es variable. Cboe siempre retorna números de secuencia para todas las unidades (incluso las no incluidas en el Login Request). Prepárate para manejar mensajes Login Response de longitud variable.

7.5 Logout (0x08) — Cboe a Miembro

Tabla 21 — Campos del Mensaje Logout

Offset  Len  Tipo          Campo                     Notas
------  ---  ------------  ------------------------  ----------------------------------
0       2    Binary        StartOfMessage            0xBA 0xBA
2       2    Binary        MessageLength             Variable
4       1    Binary        MessageType               0x08
5       1    Binary        MatchingUnit              Siempre 0
6       4    Binary        SequenceNumber            Siempre 0
10      1    Alphanumeric  LogoutReason              Ver códigos abajo
11      60   Text          LogoutReasonText          Descripción legible
71      4    Binary        LastReceivedSequenceNumber  Última secuencia entrante procesada por Cboe
75      1    Binary        NumberOfUnits             Pares unidad/secuencia a continuación
—       1    Binary        UnitNumber₁
—       4    Binary        UnitSequence₁             Mayor secuencia disponible para la unidad
…

Valores de LogoutReason:

Código Significado
U Solicitado por el usuario
E Fin del día
A Administrativo
! Violación de protocolo

7.6 Server Heartbeat (0x09) — Cboe a Miembro

Tabla 23 — Campos del Mensaje Server Heartbeat

Offset  Len  Tipo    Campo            Notas
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x09
5       1    Binary  MatchingUnit     Siempre 0
6       4    Binary  SequenceNumber   Siempre 0

Total: 10 bytes. No incrementa el número de secuencia saliente.

7.7 Replay Complete (0x13) — Cboe a Miembro

Tabla 25 — Campos del Mensaje Replay Complete

Offset  Len  Tipo    Campo            Notas
------  ---  ------  ---------------  --------------------------
0       2    Binary  StartOfMessage   0xBA 0xBA
2       2    Binary  MessageLength    8 bytes
4       1    Binary  MessageType      0x13
5       1    Binary  MatchingUnit     Siempre 0
6       4    Binary  SequenceNumber   Siempre 0

Se envía inmediatamente después del Login Response cuando no hay mensajes que reproducir, o después de todos los mensajes reproducidos cuando los hay.

8. Mensajes de Aplicación — Miembro a Cboe

8.1 New Order (0x38)

Tabla 27 — Campos del Mensaje New Order

Offset  Len   Tipo          Campo                       Notas
------  ----  ------------  --------------------------  ----------------------------------
0       2     Binary        StartOfMessage              0xBA 0xBA
2       2     Binary        MessageLength               Variable
4       1     Binary        MessageType                 0x38
5       1     Binary        MatchingUnit                Siempre 0
6       4     Binary        SequenceNumber              Secuencia de aplicación incremental
10      20    Text          ClOrdID                     ASCII 33–126 excepto , ; | @ "
                                                         Relleno NUL. Único entre órdenes activas.
30      1     Alphanumeric  Side                        1 = Buy ('1' = 0x31)
                                                         2 = Sell ('2' = 0x32)
31      4     Binary        OrderQty                    Máx 999.999 contratos
35      1     Binary        NumberOfNewOrderBitfields   Cantidad de bytes de bitfield siguientes
36      1     Binary        NewOrderBitfield₁           Identifica los campos opcionales presentes
…       1     Binary        NewOrderBitfieldₙ           Último bitfield
—       …     —             Campos opcionales…          Por bits habilitados, bit menor primero

Campos opcionales requeridos (deben estar siempre presentes vía bitfield):

Campo Tipo Tamaño Notas
Symbol Alphanumeric 8 Requerido (alguna forma de simbología)
Price Binary Price 8 Requerido para órdenes límite. No negativo.
OrdType Alphanumeric 1 Requerido para órdenes de mercado/stop. Por defecto = Limit.
Capacity Alphanumeric 1 Siempre requerido

Ejemplo de New Order (Tabla 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…(relleno)  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. Referencia de Valores de Campo

9.1 Side (New Order, offset 30)

Valor en cable ASCII Significado
0x31 '1' Compra (Buy)
0x32 '2' Venta (Sell)

9.2 OrdType

Valor en cable ASCII Significado
0x31 '1' Mercado (Market)
0x32 '2' Límite (Limit)
0x33 '3' Stop
0x34 '4' Stop Limit

9.3 Capacity

Valor en cable ASCII Significado
0x41 'A' Agency (Agencia)
0x43 'C' Customer (Cliente)
0x4D 'M' Market Maker
0x50 'P' Principal
0x46 'F' Firm (Firma)
0x4A 'J' Joint Back Office

9.4 OpenClose

Valor en cable ASCII Significado
0x4F 'O' Apertura (Open)
0x43 'C' Cierre (Close)
0x00 — Ninguno / por defecto

9.5 PutOrCall

Valor en cable ASCII Significado
0x31 '1' Call (Opción de compra)
0x30 '0' Put (Opción de venta)

9.6 LoginResponseStatus

Ver tabla en §7.4.

9.7 LogoutReason

Ver tabla en §7.5.

10. Resumen de Reglas de Secuenciamiento

Dirección Categoría de Mensaje Secuenciamiento
Miembro → Cboe Sesión (Login, Logout, Heartbeat) Sin secuencia (SequenceNumber = 0)
Miembro → Cboe Aplicación (órdenes, cancelaciones) Flujo único para todas las unidades de matching
Cboe → Miembro Sesión Sin secuencia (SequenceNumber = 0)
Cboe → Miembro Aplicación Por unidad de matching (contador independiente por unidad)
  • Cboe recomienda (pero no requiere) que los miembros envíen números de secuencia en los mensajes entrantes.
  • Un salto hacia adelante en la secuencia del miembro es ignorado por Cboe.
  • Un salto hacia atrás (secuencia duplicada o reutilizada) → Cboe envía Logout.

11. Ejemplos de Cálculo de MessageLength

Mensajes de sesión (Logout Request, Client Heartbeat, Server Heartbeat, Replay Complete)

Carga útil = MessageType(1) + MatchingUnit(1) + SequenceNumber(4) = 6 bytes
MessageLength = 6 + 2 = 8
Tamaño total en cable = 2 (StartOfMessage) + 8 = 10 bytes

Login Request (mínimo — sin grupos de parámetros)

Carga útil = 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. Horarios de Operación (Hora del Este — ET)

Exchange Inicio Aceptación de Órdenes GTH RTH
C1 8:00 pm (día anterior) SPX/VIX/XSP; 7:30 am todos los productos 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 también soporta una sesión Curb: 4:30–5:00 pm (SPX/VIX/XSP).
  • El exchange cierra ~17:30 ET diariamente (envía Logout con razón E).
  • Las órdenes que permanecen después de la Sesión de Negociación Regular y que no son elegibles para Trading Extendido son canceladas automáticamente.

13. Características del Protocolo — Notas Clave

Mensajes en Vuelo

  • Máximo de mensajes en vuelo entre el manejador de órdenes y el motor de matching: 128.
  • Si los mensajes no reconocidos superan 1.024, el manejador de órdenes BOE deja de leer del socket TCP del miembro (control de flujo).
  • La lectura se reanuda cuando los mensajes no reconocidos caen por debajo de 960.

Persistencia de Órdenes GTC/GTD

  • Las órdenes GTC y GTD persisten entre sesiones. En EDGX/C2, el plazo de cancelación de GTC/GTD es a las 4:45 pm ET; en C1, a las 5:15 pm ET.

Protección de Amplitud NBBO para Órdenes de Mercado

  • Las órdenes de mercado son rechazadas si la amplitud del NBBO supera el 100% del punto medio (mín $5,00, máx $10,00).

NBBO Desactualizado

  • Si Cboe detecta un NBBO desactualizado, las nuevas órdenes son rechazadas para las clases afectadas. Las órdenes existentes permanecen en el libro pero no pueden actualizarse.

14. Errores Comunes

Correcto Incorrecto
StartOfMessage = 0xBA 0xBA Usar 0xB0 0xE3 u otros valores
MessageLength = carga útil + 2 MessageLength = solo carga útil
StartOfMessage excluido del MessageLength Incluir StartOfMessage en la longitud
Campos de texto/cadena rellenos con NUL (0x00) Relleno con espacios (0x20)
Valor de Side en cable = ASCII '1'/'2' (0x31/0x32) Valor de Side en cable = binario 1/2
Mensajes de sesión: SequenceNumber = 0 Incrementar secuencia en mensajes de sesión
MatchingUnit entrante = siempre 0 Asignar MatchingUnit en órdenes salientes
Contador de secuencia atómico Contador hardcodeado o no thread-safe
Login Request debe ser el primer mensaje Enviar órdenes antes del login

15. Delta del Simulador (Spec vs. Implementación Actual)

Discrepancias entre esta especificación y la implementación actual de TitaniumBOE-Sim a resolver en Fase 2+:

Área Spec (v2.11.90) Simulador (actual) Fase
Valores de Side en cable '1' = Buy, '2' = Sell (ASCII) Ruta legacy fromByte(1/2) lo cubre Revisar
Capacity 'C' Customer (0x43) es un valor válido No está en el enum Capacity Fase 2
Valores de OrdType en cable '1'=Market, '2'=Limit (ASCII) Ruta legacy fromByte(1/2) lo cubre Revisar
Códigos MessageType (sesión) 0x37/0x24/0x09/0x13 etc. Enum tiene 0x0001/0x01F5/0x01F8 (valores del sitio web) Fase 2
Códigos MessageType (app) 0x38=NewOrder, 0x45=Cancel Enum tiene 0x07D1/0x07DA (valores del sitio web) Fase 2
Relleno de cadenas NUL (0x00) Espacio (0x20) en OrderAcknowledgmentMessage Fase 2
OrderAcknowledgmentMessage MessageType = 0x25 (1 byte) Usa 0x25 y lo codifica como 1 byte ✅ OK

16. Referencias

  • PDF de la especificación: docs/US_Options_BOE_Specification.pdf (v2.11.90, 3 oct. 2025)
  • Secciones relevantes:
    • §10 "Data Types" (p. 10) — definiciones completas de tipos
    • §11 "Optional Fields and Bit Fields" (p. 11)
    • §43 "Session — Message Header Fields" (p. 43) — estructura del encabezado
    • §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) — directorio completo de campos opcionales
    • §216 "List of Message Types" (p. 216) — tabla completa de códigos
Diagrama de TitaniumBOE-Sim
IMÁGENES