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

> Public orderbook and order-entry endpoints exposed by markets-service

# Markets service

`markets-service` is the public-facing REST surface for Numo's futures orderbook.

## Public endpoints

The service exposes these core routes:

* `GET /healthz`
* `GET /v1/markets`
* `GET /v1/book`
* `GET /v1/trades`
* `POST /v1/orders`
* `POST /v1/orders/cancel`

## Market discovery

Use `GET /v1/markets` before you submit anything. The response contains the canonical metadata you need for order entry:

* `market`
* `asset_address`
* `sub_id`
* `contract_type`
* `settlement_type`
* `display_name`
* `tick_size`
* `order_entry_spec` when a market has a specialized UI contract

## Reading the book

`GET /v1/book` accepts either:

* `symbol=USDCcNGN-APR30-2026`, or
* `asset_address=0x...&sub_id=1777507200`

The response returns:

* `market_presentation`
* `bids`
* `asks`

The matcher currently returns the top 25 levels on each side.

## Reading trade history

`GET /v1/trades` supports:

* `symbol`
* `asset_address`
* `sub_id`
* `limit`
* `before_trade_id`

The response includes:

* `market_presentation`
* `stats_24h`
* `trades`
* `next_before_trade_id`

## Submitting an order

`POST /v1/orders` persists a signed order after validating the embedded action payload.

Required fields include:

* `order_id`
* `owner_address`
* `signer_address`
* `subaccount_id`
* `recipient_id`
* `nonce`
* `side`
* `asset_address`
* `sub_id`
* `desired_amount`
* `limit_price`
* `worst_fee`
* `expiry`
* `action_json`
* `signature`

The service rejects the order if the order metadata and `action_json` disagree on owner, signer, subaccount, or nonce.

## Cancelling an order

Use `POST /v1/orders/cancel` with:

* `owner_address`
* `nonce`

Cancellation is owner-and-nonce based, not order-id based.