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.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

Position Events

Position Service v2 (live since 2026-05-10) does not store mark prices and is event-sourced from position_ledger. Mark-to-market unrealized P&L is computed caller-side.

position.updated.v1

Emitted after every ledger append (trade, funding, or liquidation).

Data (selected fields):

{
  "ledger_seq": 12345,
  "user_id": "UUID",
  "symbol": "BTCUSDT-PERP",
  "qty": "1.5",
  "entry_price": "50000.0",
  "cum_trade_pnl": "120.5",
  "cum_funding_pnl": "-3.2",
  "cum_fees_paid": "1.8",
  "trigger_kind": "TRADE",
  "trigger_event_id": "UUID",
  "occurred_at": "RFC3339Nano",
  "trace_id": "string"
}

Partition key: user_id.

Publishers: Position Service. Consumers: Frontend, risk dashboards, analytics.

position.closed.v1

Emitted only when a position transitions from non-zero to zero quantity.

Data:

{
  "ledger_seq": 12345,
  "user_id": "UUID",
  "symbol": "BTCUSDT-PERP",
  "final_cum_trade_pnl": "120.5",
  "final_cum_funding_pnl": "-3.2",
  "final_cum_fees_paid": "1.8",
  "close_reason": "USER",
  "opened_at": "RFC3339Nano",
  "closed_at": "RFC3339Nano",
  "trace_id": "string"
}

close_reason is USER or LIQUIDATION. Partition key: user_id.

Publishers: Position Service. Consumers: Settlement Service, frontend, analytics.

settlement.v1

Envelope-wrapped event emitted by Position Service whenever a monetary delta touches a position (trade P&L, funding P&L, or fees). This is the canonical settlement signal consumed by Wallet Service for account ledger postings and margin updates.

Envelope (Kafka Governance v1.0):

{
  "event_id": "UUID",
  "event_type": "settlement.v1",
  "source_service": "position-service",
  "trace_id": "string",
  "timestamp": "RFC3339Nano",
  "version": "v1",
  "data": {
    "settlement_id": "<ledger_seq>",
    "user_id": "UUID",
    "symbol": "BTCUSDT-PERP",
    "kind": "TRADE",
    "trade_pnl":   "12.50",
    "funding_pnl": "0",
    "fee":         "-0.05",
    "currency": "USDT",
    "source_event": "trade:<event_id>",
    "order_id":   "UUID",
    "trade_id":   "UUID",
    "filled_qty": "0.5",
    "is_maker":   false,
    "occurred_at": "RFC3339Nano"
  }
}

kind is TRADE (also used for liquidations) or FUNDING. Partition key: user_id.

Publishers: Position Service. Consumers: Wallet Service.

risk.exposure.v2

Per-user aggregate exposure snapshot emitted by the debounced exposure aggregator after position changes.

Data:

{
  "user_id": "UUID",
  "long_notional_usdt": 60000.0,
  "short_notional_usdt": 15000.0,
  "total_notional_usdt": 75000.0,
  "open_position_count": 3,
  "as_of_ledger_seq": 12345,
  "timestamp": 1234567890123
}

Partition key: user_id.

Publishers: Position Service. Consumers: Risk Service.

Funding Events

Funding Service is scheduler-driven — md.funding.v1 is consumed only for rate-cache warming, not as a settlement trigger.

position.funding.v1

Per-user funding deltas published by Funding Service (optional fanout, gated by env). Consumed by Position Service, which folds the funding delta into the ledger and emits settlement.v1 for the Wallet Service.

Data (selected fields):

{
  "cycle_id": "UUID",
  "user_id": "UUID",
  "symbol": "BTCUSDT-PERP",
  "position_side": "LONG",
  "position_size": "1.5",
  "funding_rate": "0.0001",
  "mark_price": "50000.0",
  "funding_amount": "-7.5",
  "settled_at": "RFC3339Nano",
  "trace_id": "string"
}

Idempotent on (event_source, event_id). Partition key: user_id.

Publishers: Funding Service. Consumers: Position Service.

funding.payment.settled.v1

Public audit event emitted after every successful settlement (APPLIED → APPLIED_PUBLISHED transition).

Data:

{
  "payment_id": "UUID",
  "cycle_id": "UUID",
  "user_id": "UUID",
  "symbol": "BTCUSDT-PERP",
  "position_side": "LONG",
  "position_size": "1.5",
  "funding_rate": "0.0001",
  "mark_price": "50000.0",
  "funding_amount": "-7.5",
  "settled_at": "RFC3339Nano",
  "trace_id": "string"
}

funding_amount sign convention: negative = user pays, positive = user receives.

Publishers: Funding Service. Consumers: Analytics, audit, frontend.

Risk Events

risk.pretrade_decision.v1

Audit log event emitted for every PreTradeCheck call that publishes to Kafka (same paths as the service’s decision stream). Payload is Avro; envelope includes event_id, event_type, source_service, trace_id, timestamp, version, optional hmac, and nested data.

data (summary — see shared/kafka-schema/risk-service/risk.pretrade_decision.v1.avsc):

{
  "user_id": "UUID",
  "symbol": "BTCUSDT-PERP",
  "side": "BUY",
  "decision": "APPROVED",
  "reason": null,
  "rule_id": null,
  "rule_version": null,
  "rule_hash": null,
  "projected_notional": "15000.0",
  "projected_leverage": "3.0",
  "projected_margin_ratio": "0.25",
  "equity": "50000.0",
  "maintenance_margin": "1200.0",
  "request_id": "order-or-idempotency-key",
  "ts_evaluated": "2026-04-09T12:00:00Z"
}

Decision values: APPROVED, REJECTED

Publishers:

• Risk Service

Consumers:

• Compliance / audit systems

For what projected_notional, projected_leverage, projected_margin_ratio, equity, and maintenance_margin mean (and reduce-only rules), see Pre-trade risk concepts.

risk.exposure_snapshot.v1

Emitted alongside the pretrade decision when projected notional math ran (non-empty projected_notional). Symbol-scoped row for analytics (warehouses, dashboards); not the same as portfolio risk.exposure.v2 from position-service.

data (summary — see shared/kafka-schema/risk-service/risk.exposure_snapshot.v1.avsc):

Includes account_id, request_id, trace_id, allowed, optional reject_reason, projected notional / leverage / margin ratio, equity, maintenance_margin, required_initial_margin, liquidation_risk, optional policy fields (requested_leverage, exposure_limit_usdt, effective_max_leverage, instrument_max_leverage), optional margin tier hints (tier_id, tier_ordinal, lookup_symbol_key), and ts_evaluated.

Publishers:

• Risk Service

Consumers:

• Analytics pipelines (e.g. ClickHouse, data lake)

risk.violation.v1

Emitted by Risk Service when a dynamic risk rule rejects a pre-trade check (RISK_RULE_VIOLATION). Avro envelope + data with user/account/symbol/side, rule identity (rule_id, rule_version), metric, operator, threshold, provided_value, action, reject_reason, request_id, projected notional / leverage / margin ratio, equity, maintenance margin, and ts_evaluated.

Schema: shared/kafka-schema/risk-service/risk.violation.v1.avsc

Publishers: Risk Service

Consumers: Monitoring, compliance, analytics (as needed)

risk.margin_call.v1

Emitted by Risk Service when a configured margin-ratio rule fires during pre-trade evaluation (warning path). data includes rule fields, projected_margin_ratio, equity, maintenance margin, request_id, optional tier hints and maintenance_margin_pct.

Schema: shared/kafka-schema/risk-service/risk.margin_call.v1.avsc

Publishers: Risk Service

Consumers: Notifications, risk ops, analytics

risk.liquidation.v1

Emitted by Risk Service when pre-trade evaluation hits liquidation risk (LIQUIDATION_RISK). Not the same topic as risk.liquidation.trigger.v1 (position-service → settlement). data includes liquidation_threshold, projected_margin_ratio, equity, maintenance margin, request_id, optional tier and maintenance pct fields.

Schema: shared/kafka-schema/risk-service/risk.liquidation.v1.avsc

Publishers: Risk Service

Consumers: Risk ops, analytics, downstream automation (as configured)

Settlement Events

settlement.initiated.v1

Settlement process started for a user position.

Publishers:

• Settlement Service

settlement.completed.v1

Settlement completed — position closed out.

Data:

{
  "settlement_id": "UUID",
  "user_id": "UUID",
  "symbol": "BTCUSDT-PERP",
  "settlement_type": "liquidation",
  "fill_price": 49500.0,
  "filled_qty": 1.5,
  "shortfall": 0.0,
  "insurance_fund_used": 0.0,
  "adl_triggered": false,
  "timestamp": 1234567890123
}

Publishers:

• Settlement Service

settlement.failed.v1

Settlement failed and requires manual intervention.

Publishers:

• Settlement Service

settlement.adl.triggered.v1

Auto-deleveraging activated to cover a liquidation shortfall.

Publishers:

• Settlement Service

settlement.insurance.used.v1

Insurance fund drawn to cover a liquidation shortfall.

Publishers:

• Settlement Service

risk.liquidation.trigger.v1

Liquidation threshold crossed for a user’s position; consumed by Settlement Service to begin the liquidation flow.

Publishers:

• Position Service

Consumers:

• Settlement Service

Event Consumption Patterns

Consumer Groups

Each service uses a unique consumer group:

• marketdata-service - Market data and engine events
• order-service - Order and engine events
• position-service - Engine and funding events
• user-service - Auth events
• wallet-service - User events
• risk-service - Order, engine, wallet, position, and user events
• funding-service - Funding rate events
• market-maker-service - Market data and engine events
• matching-engine - Order command events
• settlement-service - Risk 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