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.
Market Order Pricing: Call Market Data Service for last-traded price when sizing market orders.
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 via a transactional outbox.
Execution Processing: Consume engine.event.v1 from the matching engine and update order states. Per-engine-sequence deduplication via Redis.
Idempotency: Deduplicate order submissions via idempotency_key (Redis 24h TTL + DB unique constraint).
gRPC Query Surface: Serve internal queries — GetOrdersByUser, ListOrderByUserIds, CancelAllOrdersForPool — on port 50060 for other services.

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

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

All POST / PUT / DELETE endpoints return HTTP 202 Accepted with { orderId, status, message } — order processing is asynchronous via the outbox + matching engine.

Method	Endpoint	Description
`POST`	`/v1/orders`	Create new order (202)
`GET`	`/v1/orders`	List orders (paginated / filterable / cursor-based)
`GET`	`/v1/orders/:id`	Get order by ID
`PUT`	`/v1/orders/:id`	Replace / amend order (202)
`DELETE`	`/v1/orders/:id`	Cancel order (202)

GET /v1/orders supports: page, limit, status, type, symbol, fromDate, toDate, search, cursor. Results are ordered by updatedAt DESC and the list response is 60s cached in Redis (counts 5 min).

Trades

Method	Endpoint	Description
`GET`	`/v1/trades`	List all trades for the authenticated user
`GET`	`/v1/trades/:symbol`	List trades for a specific symbol

Health & Admin

Method	Endpoint	Description
`GET`	`/health`	Health check (no auth)
—	`/admin/*`	Operational endpoints (instrument refresh, etc.)
—	`/docs`, `/docs-json`	Swagger UI + OpenAPI spec

Authentication

A global JwtAuthGuard (apps/order-service/src/auth/) verifies Authorization: Bearer <token> against auth-service’s JWKS on every route except @Public() ones (health, metrics, docs). Identity (userId, accountId) comes only from the verified principal:

user token: userId/accountId = the token’s sub/account_id. A forged x-user-id/ x-account-id that disagrees with the token → 403 IDENTITY_MISMATCH.
service token with scope orders:on_behalf (market-maker, game-service): may act for another user by sending x-user-id/x-account-id, which are honored only in this case.
/v1/admin/* and the gRPC OrderQueryService require role admin or service.

Header	Required	Purpose
`authorization`	yes	`Bearer <token>` — user or service JWT
`x-user-id` / `x-account-id`	only for service on-behalf calls	Target user/account; ignored (and mismatch-checked) for a plain user token
`x-source`	no	Request source: `api` (default), `web`, `mobile`, `broker`, `market_maker` (the latter only accepted from `svc:market-maker`)
`x-idempotency-key`	no	Deduplication key for write operations

Request/Response Format

Create Order Request (POST /v1/orders — CreateOrderDto, validated with class-validator):

{
  "symbol": "BTCUSDT-PERP",
  "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",
  "feeCurrency": "USDT"
}

All financial fields are decimal strings (never JSON numbers) per the platform’s precision rules.

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)

Internal gRPC Server (Port 50060)

Order Service also serves an inbound gRPC API used by other internal services. Service name: OrderQueryService.

RPC	Purpose	Called By
`GetOrdersByUser(user_id, account_id)`	All orders for one user / account	Risk, Settlement
`ListOrderByUserIds(user_ids[])`	Batch lookup across users	Risk, Reporting
`CancelAllOrdersForPool(pool_id, allocation_id, trace_id)`	Bulk-cancel for a market-maker pool	Market Maker Service

Outbound gRPC Clients

Service	gRPC Package	Purpose
Risk Service	`risk.v1`	`PreTradeCheck` — leverage / margin / exposure validation
Wallet Service	`wallet.v1`	`LockFunds`, `UnlockFunds` — margin lifecycle (trade settlement is async via position-service `settlement.v1`, not a gRPC call)
Metadata Service	`metadata.v1`	Instrument lookup — tick size, lot size, min notional, fee schedule
Market Data Service	`marketdata.v1`	Last-traded price for sizing market orders

TLS is enabled automatically for non-localhost connections.

OrderCommand Schema (Avro)

{
  "type": "record",
  "name": "OrderCommand",
  "fields": [
    { "name": "command_type", "type": "string" },
    { "name": "order_id", "type": "string" },
    { "name": "account_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

Auth: JwtAuthGuard verifies the Authorization: Bearer token via auth-service JWKS; userId/accountId come from the principal (or from x-user-id/x-account-id only for a service principal with orders:on_behalf), x-source read separately
Idempotency Check: Check idempotencyKey in Redis (24h TTL) → if hit, return cached response
DTO Validation: NestJS ValidationPipe runs class-validator decorators on CreateOrderDto
Instrument Lookup: Fetch instrument from Metadata Service (gRPC, cached in Redis 5 min)
Business Validation: Check quantity tick/lot size, min notional, price precision, leverage limits
Market Price Lookup (market orders only): MarketDataService.GetMarkPrice for sizing
Risk Check: RiskService.PreTradeCheck via gRPC (leverage, margin, exposure)
Wallet Lock: WalletService.LockFunds via gRPC (reserve margin)
Persist: Insert orders row (status = new) + order_events row + outbox row in a single transaction
Publish: Outbox relay polls and publishes order.command.v1 to Kafka
Response: Return HTTP 202 with the order in new status

Execution Report Processing

When engine.event.v1 arrives:

Deduplicate by engine sequence number (Redis)
Parse event (ORDER_ACCEPTED, TRADE, ORDER_CANCELED, ORDER_REJECTED, BOOK_DELTA — last one ignored)
Load order from DB
Apply state transition via the state-machine service
For fills: settlement is applied asynchronously — position-service computes realized P&L and fees and emits settlement.v1, which wallet-service consumes (no gRPC settle call from order-service)
Insert order_events row (audit trail)
Update order status, filled_qty, avg_fill_price
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_URL`	Wallet service gRPC endpoint	Required
`METADATA_SERVICE_URL`	Metadata service gRPC endpoint	Required
`MARKETDATA_SERVICE_GRPC_URL`	Market Data service gRPC endpoint	Required
`ORDER_GRPC_PORT`	Inbound gRPC server (OrderQueryService)	50060
`RATE_LIMIT_PER_ACCOUNT`	Max requests per second per account	50

Technology Stack

Language: TypeScript
Framework: NestJS (Fastify adapter)
ORM: Drizzle ORM
Database: PostgreSQL
Cache: Redis (idempotency, rate limiting, instrument cache, engine-seq dedup, list cache)
Messaging: Confluent Kafka with Avro serialization via Schema Registry
gRPC: @nestjs/microservices with gRPC transport
Validation: class-validator + class-transformer via NestJS ValidationPipe
OpenAPI: @nestjs/swagger (UI at /docs)
Decimal arithmetic: fraction.js
Package Manager: Bun