Kafka Events

This document provides comprehensive documentation of all Kafka events and topics used in the TradeX platform.

Event Schema Format

All events follow a common envelope structure:

{
  "event_id": "UUIDv7",
  "event_type": "topic.name.v1",
  "source_service": "service-name",
  "trace_id": "OpenTelemetry trace ID",
  "timestamp": "ISO8601 UTC timestamp",
  "version": "v1",
  "hmac": "optional HMAC signature",
  "data": { /* event-specific data */ }
}

Engine Events

engine.event.v1

Matching engine events including trades, order book deltas, and order status updates.

Event Types:

• TRADE - Trade execution
• BOOK_DELTA - Order book delta update
• ORDER_ACCEPTED - Order accepted by engine
• ORDER_FILLED - Order fully filled
• ORDER_CANCELED - Order canceled
• ORDER_REJECTED - Order rejected

Trade Data:

{
  "trade_id": "UUID",
  "price": 50000.0,
  "qty": 1.5,
  "taker_side": "BUY",
  "maker_order_id": "UUID",
  "taker_order_id": "UUID",
  "maker_user_id": "UUID",
  "taker_user_id": "UUID",
  "is_buyer_maker": true
}

Book Delta Data:

{
  "bids": [
    { "price": 50000.0, "qty": 1.5 }
  ],
  "asks": [
    { "price": 50001.0, "qty": 2.0 }
  ]
}

Consumers:

• Market Data Service
• Order Service
• Position Service

engine.snapshot.v1

Order book snapshots for full order book state.

Consumers:

• Market Data Service

engine.bookhash.v1

Order book hash events for integrity verification.

Consumers:

• Market Data Service

Market Data Events

md.trades.v1 (per symbol)

Normalized trade events published per symbol. The topic name follows the pattern md.trades.v1.{symbol} where {symbol} is the trading pair (e.g., BTCUSDT-PERP).

Data:

{
  "symbol": "BTCUSDT-PERP",
  "trade_id": "UUID",
  "price": 50000.0,
  "quantity": 1.5,
  "side": "BUY",
  "timestamp": 1234567890123
}

Publishers:

• Market Data Service

Consumers:

• Analytics services
• Reporting services

md.orderbook.delta.v1

Order book delta updates.

Publishers:

• Market Data Service

md.orderbook.snap.v1

Order book snapshots.

Publishers:

• Market Data Service

md.ohlcv.v1

OHLCV candlestick updates.

Publishers:

• Market Data Service

md.ticker24h.v1

24-hour ticker statistics.

Publishers:

• Market Data Service

md.mark.v1

Mark price updates.

Publishers:

• Market Data Service

md.index.v1

Index price updates.

Publishers:

• Market Data Service

md.funding.v1

Funding rate updates.

Publishers:

• Market Data Service

Metadata Events

md.instrument.created.v1

Instrument creation events.

Data:

{
  "symbol": "BTCUSDT-PERP",
  "instrument_id": "UUID",
  "status": "active",
  "created_at": "ISO8601 timestamp"
}

Publishers:

• Metadata Service

Consumers:

• All services (for instrument updates)

md.instrument.updated.v1

Instrument update events.

Publishers:

• Metadata Service

md.instrument.halt.v1

Instrument halt events.

Publishers:

• Metadata Service

md.instrument.resume.v1

Instrument resume events.

Publishers:

• Metadata Service

config.index_price.created.v1

Index price configuration created.

Publishers:

• Metadata Service

config.index_price.updated.v1

Index price configuration updated.

Publishers:

• Metadata Service

config.index_price.deleted.v1

Index price configuration deleted.

Publishers:

• Metadata Service

config.risk.updated.v1

Risk configuration updated.

Publishers:

• Metadata Service

config.funding.updated.v1

Funding configuration updated.

Publishers:

• Metadata Service

config.fees.updated.v1

Fee configuration updated.

Publishers:

• Metadata Service

Wallet Events

wallet.balance.changed.v1

Balance change events.

Data:

{
  "user_id": "UUID",
  "currency": "USDT",
  "balance_delta": {
    "available": 1000.0,
    "held": 100.0
  },
  "balance_snapshot": {
    "available": 5000.0,
    "held": 500.0,
    "total": 5500.0
  }
}

Publishers:

• Wallet Service

Consumers:

• All services (for balance updates)

wallet.deposit.confirmed.v1

Deposit confirmation events.

Publishers:

• Wallet Service

wallet.withdrawal.requested.v1

Withdrawal request events.

Publishers:

• Wallet Service

wallet.withdrawal.completed.v1

Withdrawal completion events.

Publishers:

• Wallet Service

wallet.withdrawal.failed.v1

Withdrawal failure events.

Publishers:

• Wallet Service

wallet.withdrawal.locked.v1

Withdrawal locked events.

Publishers:

• Wallet Service

wallet.hold.created.v1

Balance hold creation events.

Publishers:

• Wallet Service

wallet.hold_released.v1

Balance hold release events.

Publishers:

• Wallet Service

wallet.ledger_posted.v1

Ledger entry posted events.

Publishers:

• Wallet Service

wallet.admin_adjust.v1

Admin balance adjustment events.

Publishers:

• Wallet Service

Auth Events

auth.created.v1

Authentication creation events.

Publishers:

• Auth Service

auth.login.v1

User login events.

Publishers:

• Auth Service

Consumers:

• User Service

auth.account.created.v1

Account creation events.

Publishers:

• Auth Service

Consumers:

• User Service
• Wallet Service

auth.account.activated.v1

Account activation events.

Publishers:

• Auth Service

auth.account.deactivated.v1

Account deactivation events.

Publishers:

• Auth Service

auth.account.deleted.v1

Account deletion events.

Publishers:

• Auth Service

User Events

user.created.v1

User creation events.

Publishers:

• User Service

Consumers:

• Wallet Service (for initial wallet setup)

user.updated.v1

User update events.

Publishers:

• User Service

user.verified.v1

User verification events.

Publishers:

• User Service

user.frozen.v1

User frozen events.

Publishers:

• User Service

user.unfrozen.v1

User unfrozen events.

Publishers:

• User Service

user.kyc.initiated.v1

KYC initiation events.

Publishers:

• User Service

user.kyc.updated.v1

KYC update events.

Publishers:

• User Service

Order Events

order.command.v1

Order command events (order creation, cancellation, replacement).

Publishers:

• Order Service

Consumers:

• Matching Engine

Market Maker Events

mm.quote.simulated.v1

Simulated quote events (shadow mode only).

Data:

{
  "symbol": "BTCUSDT-PERP",
  "bid_price": 49995.0,
  "ask_price": 50005.0,
  "bid_qty": 1.0,
  "ask_qty": 1.0,
  "mid_price": 50000.0,
  "spread_bps": 10.0,
  "inventory_usdt": 500.0,
  "timestamp": 1234567890123
}

Publishers:

• Market Maker Service (shadow mode)

Consumers:

• Analytics services
• Testing/validation tools

mm.risk.triggered.v1

Risk event notifications (kill switch, limit breaches).

Data:

{
  "symbol": "BTCUSDT-PERP",
  "trigger_type": "EXPOSURE_BREACH",
  "reason": "Position exceeded max_position_usdt",
  "current_position_usdt": 10500.0,
  "max_position_usdt": 10000.0,
  "current_pnl_usdt": -450.0,
  "max_loss_usdt": 500.0,
  "timestamp": 1234567890123
}

Trigger Types:

• EXPOSURE_BREACH - Position exceeds max_position
• LOSS_BREACH - Total P&L exceeds max_loss
• MARKET_HALT - Exchange halted the symbol
• KAFKA_LAG - Consumer lag exceeds threshold
• REJECT_STORM - Too many order rejections
• RESPONSE_TIMEOUT - Order Service timeout

Publishers:

• Market Maker Service

Consumers:

• Monitoring systems
• Alerting services
• Risk management systems

mm.state.changed.v1

State transition events (ACTIVE ↔ PAUSED ↔ HALTED).

Data:

{
  "symbol": "BTCUSDT-PERP",
  "previous_state": "ACTIVE",
  "new_state": "HALTED",
  "reason": "Kill switch triggered: EXPOSURE_BREACH",
  "timestamp": 1234567890123
}

States:

• ACTIVE - Market making is active, placing and managing orders
• PAUSED - Market making is paused, no new orders placed
• HALTED - Market making is halted due to risk trigger, requires manual reset

Publishers:

• Market Maker Service

Consumers:

• Monitoring systems
• Operations dashboards
• Alerting services

Event Consumption Patterns

Consumer Groups

Each service uses a unique consumer group:

• marketdata-service - Market data events
• order-service - Order and trade events
• user-service - User and auth events
• wallet-service - Wallet events
• market-maker-service - Market data and engine events

Processing Guarantees

• At-least-once delivery: Events may be delivered multiple times
• Idempotent processing: Consumers should handle duplicate events
• Ordering: Events are ordered per partition

Schema Registry

All events use Avro schemas registered in the Schema Registry:

• Schema Location: shared/kafka-schema/
• Registry URL: Configured via SCHEMA_REGISTRY_URL
• Schema Evolution: Backward compatible changes supported

Related Documentation

• Kafka Integration Guide
• Schema Registry Guide
• Architecture Overview