Last Updated: 2026-05-03 Owner: Process-Dev Summary: Event and Redis stream contract reference for producers, consumers, envelopes, and idempotency rules.

QuantMatrix Event Contract Reference¶

This document defines the internal event contracts used across QuantMatrix.

Its purpose is to: - make event-driven flows explicit - align producers and consumers - reduce ambiguity in Redis stream payloads - support replay, recovery, analytics, and testing

Use this document together with: - the API Reference Document - the Data Dictionary and Schema Reference - the Implementation Specification - the Trade Analytics Specification

1. Event Design Principles¶

QuantMatrix events should follow these rules: - every event must have a stable type - event payloads should be normalized, not raw broker-specific blobs - timestamps should be ISO 8601 UTC - important identifiers should always be present - events should be versionable without ambiguity - consumers should be able to process events idempotently

2. Standard Event Envelope¶

Recommended common envelope:

{
  "type": "MARKET_TICK",
  "version": "1.0",
  "event_id": "evt_001",
  "session_id": "2026-05-03",
  "timestamp": "2026-05-03T09:31:04Z",
  "source": "alpaca_market_data",
  "payload": {}
}

Required Envelope Fields¶

type
version
event_id
session_id
timestamp
source
payload

Optional Envelope Fields¶

correlation_id
causation_id
mode
partition_key

3. Event Categories¶

Primary event categories: - market data events - radar and scanner events - strategy events - risk events - order and execution events - position and pnl events - health and operational events - analytics events

4. Redis Stream Reference¶

Suggested streams:

`stream:market_ticks`¶

Purpose: normalized incoming market ticks
Producers: market data ingestion service
Consumers: Momentum Radar, analytics, optional live caches

`stream:top_gainer_scans`¶

Purpose: periodic radar scan outputs
Producers: Momentum Radar service
Consumers: Opportunity Scanner, UI cache updater, analytics

`stream:watchlist_events`¶

Purpose: candidate creation and watchlist lifecycle transitions
Producers: Opportunity Scanner, UI manual actions, Strategy Allocator
Consumers: watchlist state manager, UI cache, analytics

`stream:strategy_events`¶

Purpose: strategy assignments, entry signals, exit signals, strategy health updates
Producers: Strategy Allocator, strategy engine
Consumers: risk manager, OMS, analytics

`stream:risk_events`¶

Purpose: risk violations, blocks, halt actions
Producers: Global Risk Manager
Consumers: UI, OMS, analytics, alerting

`stream:order_events`¶

Purpose: order commands, acknowledgments, cancels, rejections
Producers: OMS, broker adapter
Consumers: positions service, UI, analytics, reconciliation

`stream:execution_events`¶

Purpose: fills and partial fills
Producers: broker adapter, execution handler
Consumers: positions service, pnl service, analytics

`stream:health_events`¶

Purpose: component health and connectivity changes
Producers: all major services
Consumers: UI, alerting, operations tooling

`stream:analytics_events`¶

Purpose: trade close, feature extraction, explanation, recommendation workflows
Producers: execution handler, analytics pipeline
Consumers: trade journal, recommendation engine, review tooling

5. Market Data Events¶

`MARKET_TICK`¶

Purpose: - normalized tick for one symbol

Payload fields: - symbol - price - bid - ask - volume - provider

Example:

{
  "type": "MARKET_TICK",
  "version": "1.0",
  "event_id": "evt_tick_001",
  "session_id": "2026-05-03",
  "timestamp": "2026-05-03T09:31:04Z",
  "source": "alpaca_market_data",
  "payload": {
    "symbol": "AAPL",
    "price": 189.23,
    "bid": 189.22,
    "ask": 189.24,
    "volume": 1200345,
    "provider": "alpaca"
  }
}

`MARKET_BAR_1M`¶

Purpose: - normalized one-minute bar if bar-based logic is used

Payload fields: - symbol - open - high - low - close - volume - bar_start - bar_end

6. Radar and Scanner Events¶

`TOP_GAINER_SCAN_RESULT`¶

Purpose: - current top gainer set captured by Momentum Radar

Payload fields: - top_n - leaders

Each leaders item: - symbol - price - percentage_gain - change_1m - change_5m - sector - float - volume - average_volume - captured_at

`MOMENTUM_SNAPSHOT_WRITTEN`¶

Purpose: - confirms minute snapshot was written to Redis cache

Payload fields: - symbol - minute_ts - cache_key

`WATCHLIST_CANDIDATE_CREATED`¶

Purpose: - scanner or manual UI created a new watchlist candidate

Payload fields: - symbol - source - initial_status - time_added

`WATCHLIST_STATUS_CHANGED`¶

Purpose: - lifecycle transition for a watchlist item

Payload fields: - symbol - previous_status - new_status - strategy_id - reason

7. Strategy Events¶

`STRATEGY_ASSIGNED`¶

Purpose: - a strategy has been assigned to a watchlist candidate

Payload fields: - symbol - strategy_id - strategy_version - assigned_at

`ENTRY_SIGNAL_GENERATED`¶

Purpose: - one strategy generated a buy signal

Payload fields: - signal_id - symbol - strategy_id - strategy_version - action - confidence - signal_price - explanation

`EXIT_SIGNAL_GENERATED`¶

Purpose: - active position generated an exit signal

Payload fields: - signal_id - symbol - strategy_id - action - exit_reason - signal_price - explanation

`STRATEGY_HEALTH_CHANGED`¶

Purpose: - strategy polling/health status changed

Payload fields: - symbol - strategy_id - previous_health - new_health - detail

8. Risk Events¶

`RISK_VIOLATION`¶

Purpose: - a risk rule blocked or halted activity

Payload fields: - rule - symbol - client_order_id - severity - detail

`RISK_HALT_ACTIVATED`¶

Purpose: - trading halt due to risk threshold

Payload fields: - reason - rule - activated_at

`SYMBOL_BLOCKED`¶

Purpose: - a symbol was blocked manually or automatically

Payload fields: - symbol - block_scope - reason - expires_at

9. Order and Execution Events¶

`ORDER_COMMAND_CREATED`¶

Purpose: - OMS created an order intent to be routed

Payload fields: - client_order_id - symbol - side - order_type - quantity - strategy_id

`ORDER_SUBMITTED`¶

Purpose: - broker adapter submitted the order

Payload fields: - client_order_id - broker_order_id - symbol - submitted_at

`ORDER_ACKNOWLEDGED`¶

Purpose: - broker acknowledged the order

Payload fields: - client_order_id - broker_order_id - status - acknowledged_at

`ORDER_REJECTED`¶

Purpose: - broker rejected the order

Payload fields: - client_order_id - broker_order_id - symbol - reason - rejected_at

`ORDER_CANCELLED`¶

Purpose: - order cancel completed

Payload fields: - client_order_id - broker_order_id - cancelled_at

`EXECUTION_FILLED`¶

Purpose: - full fill or partial fill event

Payload fields: - execution_id - client_order_id - broker_order_id - symbol - side - filled_quantity - fill_price - fill_timestamp - commission - fees

`POSITION_UPDATED`¶

Purpose: - normalized position state changed after execution

Payload fields: - symbol - quantity - average_entry_price - market_price - unrealized_pnl - status

10. Health and Operational Events¶

`COMPONENT_HEALTH_CHANGED`¶

Purpose: - component changed health state

Payload fields: - component_name - previous_status - new_status - latency_ms - detail

`BROKER_CONNECTIVITY_CHANGED`¶

Purpose: - broker connection state changed

Payload fields: - broker_name - broker_role - previous_status - new_status - detail

Broker roles: - MARKET_DATA - EXECUTION

`EMERGENCY_HALT_TRIGGERED`¶

Purpose: - operator or risk system triggered emergency halt

Payload fields: - reason - triggered_by - liquidation_requested

`RECONCILIATION_COMPLETED`¶

Purpose: - startup, reconnect, or end-of-day reconciliation completed

Payload fields: - reconciliation_type - status - differences_found - summary

11. Analytics Events¶

`TRADE_CLOSED`¶

Purpose: - full trade lifecycle completed

Payload fields: - trade_id - symbol - strategy_id - entry_time - exit_time - gross_pnl - net_pnl

`TRADE_FEATURES_CAPTURED`¶

Purpose: - entry/exit/in-trade features stored for trade analytics

Payload fields: - trade_id - capture_stage - feature_count

`TRADE_EXPLANATION_CREATED`¶

Purpose: - explanation generated for entry, exit, or post-trade summary

Payload fields: - trade_id - explanation_type - explanation_version

`RECOMMENDATION_GENERATED`¶

Purpose: - recommendation derived from historical trade patterns

Payload fields: - recommendation_id - scope_type - scope_value - confidence_score - sample_size

12. Producer / Consumer Matrix¶

Event Type	Producer	Consumer
`MARKET_TICK`	Market Data Service	Radar, analytics, caches
`TOP_GAINER_SCAN_RESULT`	Momentum Radar	Scanner, UI cache, analytics
`WATCHLIST_CANDIDATE_CREATED`	Scanner / UI	Watchlist manager, allocator
`STRATEGY_ASSIGNED`	Strategy Allocator	UI, analytics
`ENTRY_SIGNAL_GENERATED`	Strategy Engine	Risk Manager, OMS, analytics
`RISK_VIOLATION`	Risk Manager	UI, OMS, alerting
`ORDER_COMMAND_CREATED`	OMS	Broker Adapter, analytics
`ORDER_ACKNOWLEDGED`	Broker Adapter	OMS, UI, analytics
`EXECUTION_FILLED`	Broker Adapter / Execution Handler	Positions, pnl, analytics
`TRADE_CLOSED`	Execution / Analytics Pipeline	Trade journal, recommendations
`COMPONENT_HEALTH_CHANGED`	Services	UI, alerting

13. Idempotency Guidance¶

Consumers should process key events idempotently.

Recommended idempotency anchors: - event_id for generic event replay protection - client_order_id for order submission flows - execution_id for fill processing - trade_id for trade analytics finalization - (symbol, minute_ts) for radar snapshot writes

14. Versioning Guidance¶

If an event contract changes: - increment version - preserve older consumer support where practical - document field additions and removals - avoid repurposing an existing field with new meaning

Recommended version pattern: - 1.0 - 1.1 - 2.0

15. Validation Rules¶

Each consumer should validate: - known type - supported version - required envelope fields present - payload required fields present - timestamp parseable - identifiers non-empty

If validation fails: - reject safely - log structured error - route to dead-letter or error handling path if implemented

16. Recommended Next Companion Document¶

The next useful precision document after this one is an OpenAPI / JSON Schema package or a Redis Streams Consumer Group Reference, depending on whether implementation friction is currently higher on the REST side or the event-processing side.

QuantMatrix Event Contract Reference¶

1. Event Design Principles¶

2. Standard Event Envelope¶

Required Envelope Fields¶

Optional Envelope Fields¶

3. Event Categories¶

4. Redis Stream Reference¶

stream:market_ticks¶

stream:top_gainer_scans¶

stream:watchlist_events¶

stream:strategy_events¶

stream:risk_events¶

stream:order_events¶

stream:execution_events¶

stream:health_events¶

stream:analytics_events¶

5. Market Data Events¶

MARKET_TICK¶

MARKET_BAR_1M¶

6. Radar and Scanner Events¶

TOP_GAINER_SCAN_RESULT¶

MOMENTUM_SNAPSHOT_WRITTEN¶

WATCHLIST_CANDIDATE_CREATED¶

WATCHLIST_STATUS_CHANGED¶

7. Strategy Events¶

STRATEGY_ASSIGNED¶

ENTRY_SIGNAL_GENERATED¶

EXIT_SIGNAL_GENERATED¶

STRATEGY_HEALTH_CHANGED¶