Order Service

The Order Service is a NestJS (TypeScript) microservice responsible for the complete order lifecycle — from intake and validation through risk/wallet checks to publishing commands for the matching engine and processing execution reports.

Responsibilities

• Order Intake & Validation: Accept order requests via REST API, validate against instrument rules and schema constraints.
• Risk & Session Checks: Call Risk Service for pre-trade checks (leverage, margin, exposure limits).
• Wallet Integration: Call Wallet Service to lock margin before accepting orders, unlock on cancel/reject, settle on fill.
• Lifecycle Persistence: Persist every order state transition to PostgreSQL with a full event-sourced audit trail (order_events table).
• Command Publishing: Publish order.command.v1 to Kafka for the matching engine.
• Execution Processing: Consume engine.event.v1 from the matching engine and update order states.
• Idempotency: Deduplicate order submissions via idempotency_key (Redis + DB).

The Order Service is the gateway between the client and the matching engine. It ensures orders are valid, funded, and risk-checked before entering the order book.

Architecture

graph TB Client[Client App] -->|REST| OrderAPI[Order Service API] OrderAPI -->|gRPC| Risk[Risk Service] OrderAPI -->|gRPC| Wallet[Wallet Service] OrderAPI -->|gRPC| Metadata[Metadata Service] OrderAPI -->|Kafka| ME[Matching Engine] ME -->|Kafka| OrderAPI OrderAPI -->|Stores| PG[(PostgreSQL)] OrderAPI -->|Cache| Redis[(Redis)]

Data Models (PostgreSQL / Drizzle ORM)

accounts

Field	Type	Description
id	UUID (PK)	Account ID
user_id	UUID	Owner user
account_type	ENUM	individual, institutional, system_market_maker
status	ENUM	active, suspended, closed
created_at	TIMESTAMPTZ	Creation time

instruments

Field	Type	Description
id	UUID (PK)	Instrument ID
symbol	VARCHAR(32) UNIQUE	Trading symbol (e.g., BTCUSDT-PERP)
base_currency	VARCHAR(10)	Base asset
quote_currency	VARCHAR(10)	Quote asset
tick_size	NUMERIC(24)	Minimum price increment
lot_size	NUMERIC(24)	Minimum quantity increment
min_notional	NUMERIC(24)	Minimum order notional value
max_leverage	INT	Maximum allowed leverage
status	ENUM	active, halted, delisted

orders

Field	Type	Description
id	UUID (PK)	Order ID
client_order_id	TEXT	Client-provided tracking ID
account_id	UUID (FK)	References accounts
instrument_id	UUID (FK)	References instruments
side	ENUM(buy, sell)	Order side
type	ENUM(limit, market, stop_limit, stop_market)	Order type
time_in_force	ENUM(gtc, ioc, fok, gtd)	Time-in-force policy
price	NUMERIC(24)	Limit price (NULL for market)
stop_price	NUMERIC(24)	Stop trigger price
quantity	NUMERIC(24)	Original quantity
filled_qty	NUMERIC(24)	Cumulative filled quantity
remaining_qty	NUMERIC(24)	Remaining to fill
avg_fill_price	NUMERIC(24)	Volume-weighted average fill price
leverage	INT	Leverage multiplier (1-100)
post_only	BOOLEAN	Reject if would take liquidity
reduce_only	BOOLEAN	Only reduce existing position
status	ENUM	Order state machine value
idempotency_key	TEXT UNIQUE	Deduplication key
fee_currency	VARCHAR(10)	Currency for fees
expires_at	TIMESTAMPTZ	Expiry for GTD orders
created_at	TIMESTAMPTZ	Order creation time
updated_at	TIMESTAMPTZ	Last status change

order_events

Field	Type	Description
id	UUID (PK)	Event ID
order_id	UUID (FK)	References orders
event_type	TEXT	created, accepted, partially_filled, filled, canceled, rejected, replaced
prev_status	TEXT	Previous order status
new_status	TEXT	New order status
filled_qty	NUMERIC(24)	Fill quantity for this event
fill_price	NUMERIC(24)	Fill price for this event
trade_id	UUID	Trade ID (for fill events)
reason	TEXT	Reason for reject/cancel
metadata	JSONB	Additional event context
trace_id	TEXT	OpenTelemetry trace ID
created_at	TIMESTAMPTZ	Event timestamp

outbox

Transactional outbox table for reliable Kafka publishing:

Field	Type	Description
id	UUID (PK)	Outbox entry ID
topic	TEXT	Target Kafka topic
key	TEXT	Kafka message key
payload	JSONB	Serialized message
published	BOOLEAN	Whether successfully published
created_at	TIMESTAMPTZ	Entry creation time
published_at	TIMESTAMPTZ	When published

Redis Keys

Key Pattern	Purpose	TTL
order:idem:{key}	Idempotency deduplication	24 hours
order:rate:{account_id}	Per-account rate limiter	Sliding window
instrument:{id}	Cached instrument definitions	5 min

Order State Machine

new --> accepted --> partially_filled --> filled
 |         |               |
 v         v               v
rejected  cancel_pending  filled
           |
           v
         canceled

accepted --> replace_pending --> replaced

filled / canceled --> expired

State Transitions

From	To	Trigger
new	accepted	Matching engine acknowledges order
new	rejected	Validation failure, risk check failure, or insufficient funds
accepted	partially_filled	Partial fill from matching engine
accepted	filled	Complete fill from matching engine
accepted	cancel_pending	Cancel request submitted
partially_filled	filled	Remaining quantity filled
partially_filled	cancel_pending	Cancel remaining
cancel_pending	canceled	Cancel confirmed by engine
accepted	replace_pending	Replace request submitted
replace_pending	replaced	Replace confirmed by engine
filled / canceled	expired	GTD expiry reached

API Endpoints

Orders

Method	Endpoint	Description
POST	/v1/orders	Create new order
GET	/v1/orders	List orders (paginated, filterable)
GET	/v1/orders/:id	Get order by ID
PUT	/v1/orders/:id	Replace order (cancel + new)
DELETE	/v1/orders/:id	Cancel order

Trades

Method	Endpoint	Description
GET	/v1/trades	List all trades
GET	/v1/trades/:instrument	List trades for instrument

Request/Response Format

Create Order Request:

{
  "instrumentId": "uuid",
  "side": "buy",
  "type": "limit",
  "quantity": "1.5",
  "price": "50000.00",
  "timeInForce": "gtc",
  "leverage": 10,
  "postOnly": false,
  "reduceOnly": false,
  "clientOrderId": "my-order-1",
  "idempotencyKey": "unique-key-123"
}

Response Format (List):

{
  "data": [ /* orders */ ],
  "pagination": { "page": 1, "limit": 50, "total": 142 }
}

Messaging (Kafka Topics)

Published

Topic	Description
order.command.v1	Order commands (new, cancel, replace) sent to matching engine

Consumed

Topic	Description
engine.event.v1	Execution reports from matching engine (fills, accepts, rejects, cancels)

OrderCommand Schema (Avro)

{
  "type": "record",
  "name": "OrderCommand",
  "fields": [
    { "name": "command_type", "type": "string" },
    { "name": "order_id", "type": "string" },
    { "name": "account_id", "type": "string" },
    { "name": "instrument_id", "type": "string" },
    { "name": "symbol", "type": "string" },
    { "name": "side", "type": "string" },
    { "name": "order_type", "type": "string" },
    { "name": "quantity", "type": "string" },
    { "name": "price", "type": ["null", "string"] },
    { "name": "time_in_force", "type": "string" },
    { "name": "trace_id", "type": "string" }
  ]
}

Request Lifecycle

1. Auth: Extract x-user-id, x-account-id from headers (set by API Gateway after JWT validation)
2. Idempotency Check: Check idempotency_key in Redis → if hit, return cached response
3. Schema Validation: Validate request body with Zod schemas
4. Instrument Lookup: Fetch instrument from Metadata Service (gRPC, cached in Redis)
5. Business Validation: Check quantity tick/lot size, min notional, price precision, leverage limits
6. Risk Check: Call RiskService.PreTradeCheck() via gRPC (leverage, margin, exposure)
7. Wallet Lock: Call WalletService.LockFunds() via gRPC (reserve margin)
8. Persist: Insert orders row (status = new) + order_events row + outbox row in single transaction
9. Publish: Outbox relay publishes order.command.v1 to Kafka
10. Response: Return order with status new

Execution Report Processing

When engine.event.v1 arrives:

1. Parse event (fill, cancel, reject)
2. Load order from DB
3. Apply state transition
4. For fills: call WalletService.SettleTrade() to apply P&L and fees
5. Insert order_events row
6. Update order status, filled_qty, avg_fill_price
7. If fully filled: update status to filled

Validation Rules

• Quantity: Must be positive, divisible by lot_size, does not exceed instrument max
• Price: Must be positive (for limit), divisible by tick_size
• Notional: price * quantity >= min_notional
• Leverage: 1 <= leverage <= instrument.max_leverage
• Time-in-Force: Market orders must be ioc or fok; limit orders can be gtc, ioc, fok, gtd
• GTD Expiry: expires_at must be in the future (for GTD orders)
• Post-Only: Only valid for limit orders
• Reduce-Only: Validated against current position

Rate Limiting

• Per-Account: 50 requests/second per account (configurable)
• Per-IP: 100 requests/second per IP
• Implementation: Redis sliding window counter

Observability

Metrics (Prometheus)

• order_created_total{side,type} — Orders created by side and type
• order_filled_total{side} — Orders filled
• order_rejected_total{reason} — Rejections by reason
• order_canceled_total — Cancellations
• order_latency_ms{stage} — Latency per processing stage
• outbox_pending_gauge — Pending outbox messages

Tracing (OpenTelemetry)

Spans: order.create, order.validate, order.risk_check, order.wallet_lock, order.persist, order.publish, order.process_fill

Logging

Structured JSON: order_id, account_id, instrument_id, side, type, status, trace_id. Prices and quantities are logged for debugging.

Failure & Recovery

Scenario	Handling
Risk service unavailable	Reject order with RISK_CHECK_UNAVAILABLE
Wallet lock fails	Reject order with INSUFFICIENT_BALANCE
Kafka publish fails	Outbox pattern retries; order stays in new until published
Engine event processing fails	Consumer retries with backoff; idempotent by trade_id
DB transaction fails	Automatic rollback; client retries with same idempotency key

SLOs

Metric	Target
Order acceptance latency (p95)	< 100 ms
Outbox drain latency (p95)	< 500 ms
Fill processing latency (p95)	< 200 ms
Order creation success rate	>= 99.5%

Configuration

Variable	Description	Default
POSTGRES_URL	PostgreSQL connection string	Required
REDIS_URL	Redis connection string	Required
KAFKA_BROKERS	Kafka broker addresses	Required
RISK_SERVICE_GRPC_URL	Risk service gRPC endpoint	Required
WALLET_SERVICE_GRPC_URL	Wallet service gRPC endpoint	Required
METADATA_SERVICE_GRPC_URL	Metadata service gRPC endpoint	Required
RATE_LIMIT_PER_ACCOUNT	Max requests per second per account	50

Technology Stack

• Language: TypeScript
• Framework: NestJS
• ORM: Drizzle ORM
• Database: PostgreSQL
• Cache: Redis
• Messaging: Kafka with Avro serialization
• gRPC: @nestjs/microservices with gRPC transport
• Validation: Zod schemas
• Package Manager: Bun

Related Documentation

• Order API Reference
• Matching Engine
• Wallet Service
• Kafka Events