> ## Documentation Index
> Fetch the complete documentation index at: https://docs.numofx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Order lifecycle

> How an order moves through markets-service, execution-service, execution-contracts, and risk-core

## System overview

Numo's futures orderbook is split across four layers:

<CardGroup cols={2}>
  <Card title="markets-service" icon="book-open">
    Public REST API for market discovery, orderbook reads, trades, order entry, and cancellation.
  </Card>

  <Card title="execution-service" icon="bolt">
    Backend executor that validates crossed-order payloads and submits `verifyAndMatch(...)`.
  </Card>

  <Card title="execution-contracts" icon="file-contract">
    Onchain matching and action-verification contracts used by the trusted backend executor.
  </Card>

  <Card title="risk-core" icon="shield-halved">
    Margin engine, subaccounts, cash asset accounting, manager hooks, settlement, and liquidation.
  </Card>
</CardGroup>

## End-to-end flow

<Steps>
  <Step title="1. Market discovery">
    Clients call `GET /v1/markets` on `markets-service` to discover enabled instruments and retrieve the canonical `asset_address` and `sub_id`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="4. Matching">
    The matcher loop in `markets-service` scans for crossed orders, computes fill amounts, and builds an executor payload for the market.
  </Step>

  <Step title="5. Onchain execution">
    `execution-service` validates the payload, ABI-encodes `TradeModule.OrderData`, simulates `Matching.verifyAndMatch(...)`, and broadcasts the transaction through `execution-contracts`.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Deliverable cNGN future

The physically delivered FX future exposed by the backend is:

* `market`: `USDCcNGN-APR30-2026`
* `contract_type`: `deliverable_fx_future`
* `settlement_type`: `physical_delivery`
* `display_name`: `USDC/cNGN APR-30-2026 Future`

The settlement note in the matcher registry is:

> Physically delivered on Base. Long pays cNGN and receives fixed USDC notional; short pays fixed USDC notional and receives cNGN.

## 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