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

graph TB Client[Client App] -->|REST| OrderAPI[Order Service API] OrderAPI -->|gRPC PreTradeCheck| Risk[Risk Service] OrderAPI -->|gRPC LockFunds / SettleTrade| Wallet[Wallet Service] OrderAPI -->|gRPC Instrument lookup| Metadata[Metadata Service] OrderAPI -->|gRPC LTP for market orders| MarketData[Market Data Service] OrderAPI -->|order.command.v1| ME[Matching Engine] ME -->|engine.event.v1| OrderAPI OrderAPI -->|Stores| PG[(PostgreSQL)] OrderAPI -->|Idempotency · dedup · cache| Redis[(Redis)] Other[Other Services] -->|gRPC OrderQueryService :50060| OrderAPI

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 Headers

All authenticated endpoints require headers set by the upstream API gateway after JWT validation:

Header	Required	Purpose
x-user-id	yes	User UUID
x-account-id	yes	Trading account UUID
x-source	no	Request source: api (default), web, mobile, broker, 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, SettleTrade — margin lifecycle
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

1. Auth: Extract x-user-id, x-account-id, x-source from headers (set by API Gateway after JWT validation)
2. Idempotency Check: Check idempotencyKey in Redis (24h TTL) → if hit, return cached response
3. DTO Validation: NestJS ValidationPipe runs class-validator decorators on CreateOrderDto
4. Instrument Lookup: Fetch instrument from Metadata Service (gRPC, cached in Redis 5 min)
5. Business Validation: Check quantity tick/lot size, min notional, price precision, leverage limits
6. Market Price Lookup (market orders only): MarketDataService.GetMarkPrice for sizing
7. Risk Check: RiskService.PreTradeCheck via gRPC (leverage, margin, exposure)
8. Wallet Lock: WalletService.LockFunds via gRPC (reserve margin)
9. Persist: Insert orders row (status = new) + order_events row + outbox row in a single transaction
10. Publish: Outbox relay polls and publishes order.command.v1 to Kafka
11. Response: Return HTTP 202 with the order in new status

Execution Report Processing

When engine.event.v1 arrives:

1. Deduplicate by engine sequence number (Redis)
2. Parse event (ORDER_ACCEPTED, TRADE, ORDER_CANCELED, ORDER_REJECTED, BOOK_DELTA — last one ignored)
3. Load order from DB
4. Apply state transition via the state-machine service
5. For fills: call WalletService.SettleTrade() to apply realized P&L and fees
6. Insert order_events row (audit trail)
7. Update order status, filled_qty, avg_fill_price
8. 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

Related Documentation

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