Skip to main content

System overview

Numo’s orderbook is split across four layers:

markets-service

Public REST API for market discovery, orderbook reads, trades, order entry, and cancellation.

execution-service

Backend executor that validates crossed-order payloads and submits verifyAndMatch(...).

execution-contracts

Onchain matching and action-verification contracts used by the trusted backend executor.

risk-core

Margin engine, subaccounts, cash asset accounting, manager hooks, settlement, and liquidation.

End-to-end flow

1

1. Market discovery

Clients call GET /markets on markets-service to discover enabled instruments and retrieve the canonical asset_address and sub_id.
2

2. Orderbook reads

Clients poll GET /book and GET /trades on markets-service for top-of-book state, recent prints, and 24h stats.
3

3. Signed order submission

Clients submit signed order payloads to POST /orders. The service validates that order metadata matches the embedded action payload before persisting the order.
4

4. Matching

The matcher loop in markets-service scans for crossed orders, computes fill amounts, and builds an executor payload for the market.
5

5. Onchain execution

execution-service validates the payload, ABI-encodes TradeModule.OrderData, simulates Matching.verifyAndMatch(...), and broadcasts the transaction through execution-contracts.
6

6. Risk and settlement

risk-core validates account state through manager and asset hooks, updates margin state, and handles cash settlement, variation margin, and liquidation behavior.

What each repo is responsible for

markets-service

  • stores active orders and trade fills
  • exposes GET /markets, GET /book, GET /trades
  • accepts POST /orders and POST /orders/cancel
  • resolves market metadata from exact (asset_address, sub_id)

execution-service

  • runs on a private network and takes matched orders only from the matcher, so you never call it
  • holds the key that submits fills on chain
  • requires actions.length === signatures.length
  • requires actions[0].subaccount_id === order_data.taker_account
  • requires every action.module === module_address

execution-contracts

  • verifies signed actions
  • owns the trusted Matching execution path
  • executes matched transfers against the core account system

risk-core

  • stores balances in SubAccounts
  • lets managers validate final account state
  • lets assets track transfer semantics and settlement inputs
  • provides CashAsset and FutureAsset primitives the MarginEngine uses during settlement