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 /v1/markets on markets-service to discover enabled instruments and retrieve the canonical asset_address and sub_id.
2

2. Orderbook reads

Clients poll GET /v1/book and GET /v1/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 /v1/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, funding, and liquidation behavior.

​
USDC/cNGN market

The USDC/cNGN market exposed by the backend is:
  • market: USDCcNGN-SPOT
  • contract_type: spot
  • settlement_type: spot
  • display_name: USDC/cNGN Spot
The settlement note in the matcher registry is:
Spot-style orderbook market on Base. Trades exchange WRAPPED_CNGN against internal USDC cash using the existing single quote-asset rail.

​
What each repo is responsible for

​
markets-service

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

​
execution-service

  • accepts POST /execute
  • 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 PerpAsset primitives used by managers during settlement