> ## 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.
# List order history
> The authenticated owner's orders in every status (active, matching, filled, cancelled, expired), newest first. The owner is taken from the signed X-Numo-Auth frame, never from a parameter. Filled orders, and any cancelled or expired order that traded, are retained indefinitely; cancelled and expired orders with no fills for 30 days.
Returns your orders in every status — `active`, `matching`, `filled`, `cancelled` and `expired` —
newest first.
Authentication is required, and the owner is taken from the signature, never from a parameter.
Resting orders are public on the book and fills settle on chain, but cancelled and expired orders
are not published anywhere else.
## Authentication
Build and sign this exact message with `personal_sign` (unix seconds, no trailing newline). The
domain is the same one the WebSocket uses.
```text theme={null}
wants you to view your Numo order history.
Address:
Nonce:
Issued At:
Expiration Time:
```
Send the frame — `address`, `signature`, `nonce`, `issued_at`, `expiry` — as JSON, base64url-encoded,
in the `X-Numo-Auth` header. One frame can be reused across requests until it expires; the service
accepts a validity window of up to 24 hours.
A frame signed for the WebSocket `orders` channel is not accepted here, and an order-history frame
does not authenticate a WebSocket: the two messages differ, so each recovers a different address
from the other's signature.
## What traded
Each order that has filled carries `filled_quote`: the USDC that actually changed hands, summed over
its fills at the prices they executed at. Use it to reconcile balances. Do not derive a size from the
order's own amount and limit price — a marketable order is signed with slippage room past the touch,
so that figure overstates what filled. `filled_quote` is absent for an order with no fills.
## Retention
Filled orders are kept indefinitely, and so is any cancelled or expired order that traded before it
ended, so its fills and `filled_quote` stay reportable. Cancelled and expired orders with no fills are
kept for 30 days, then pruned.
## Paging
Pages hold up to `limit` orders (default 50, maximum 100). When a page is full, the response includes
`next_before`; pass it back as `before` to fetch older orders. The last page has no `next_before`.
## OpenAPI
````yaml GET /v1/orders
openapi: 3.1.0
info:
title: Numo orderbook API
description: >-
REST endpoints exposed by Numo's markets-service and execution-service for
dollar stablecoins. Real-time book, trades, and order streams are served
over the WebSocket endpoint documented in the WebSocket streams reference.
version: 1.0.0
servers:
- url: https://api.numofx.com
description: markets-service
- url: https://executor.numofx.com
description: execution-service
security: []
tags:
- name: Markets service
- name: Execution service
paths:
/v1/orders:
get:
tags:
- Markets service
summary: List order history
description: >-
The authenticated owner's orders in every status (active, matching,
filled, cancelled, expired), newest first. The owner is taken from the
signed X-Numo-Auth frame, never from a parameter. Filled orders, and any
cancelled or expired order that traded, are retained indefinitely;
cancelled and expired orders with no fills for 30 days.
operationId: listOrderHistory
parameters:
- name: X-Numo-Auth
in: header
required: true
schema:
type: string
description: >-
Base64url-encoded JSON auth frame {address, signature, nonce,
issued_at, expiry}, signed with personal_sign over the order-history
message. See the endpoint page for the exact message.
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: before
in: query
required: false
schema:
type: string
description: >-
The next_before value from the previous page, to page to older
orders.
responses:
'200':
description: One page of the owner's orders, newest first
content:
application/json:
schema:
$ref: '#/components/schemas/OrderHistoryResponse'
'400':
description: Invalid limit or before cursor
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Missing, malformed, expired or mismatched auth frame
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
OrderHistoryResponse:
type: object
required:
- orders
properties:
orders:
type: array
items:
allOf:
- $ref: '#/components/schemas/Order'
- type: object
properties:
cancel_reason:
type: string
description: Why the order was cancelled; absent otherwise.
cancelled_at:
type: string
format: date-time
description: When the order was cancelled; absent otherwise.
filled_quote:
type: string
description: >-
What actually traded, in USDC to 6 decimal places: the sum
of fill price x size over the order's fills, taker or
maker. Absent when the order has no fills. Prefer it over
a size derived from the order's amount, which is valued at
the signed limit and overstates a marketable order.
next_before:
type: string
description: Pass as before to fetch older orders. Absent on the last page.
ErrorResponse:
type: object
properties:
error:
type: string
Order:
type: object
properties:
order_id:
type: string
owner_address:
type: string
signer_address:
type: string
subaccount_id:
type: string
recipient_id:
type: string
nonce:
type: string
side:
type: string
enum:
- buy
- sell
asset_address:
type: string
sub_id:
type: string
desired_amount:
type: string
filled_amount:
type: string
limit_price:
type: string
worst_fee:
type: string
expiry:
type: integer
action_json: {}
signature:
type: string
status:
type: string
created_at:
type: string
format: date-time
description: When the order was accepted onto the book.
market:
type: string
contract_type:
type: string
settlement_type:
type: string
base_asset_symbol:
type: string
quote_asset_symbol:
type: string
display_name:
type: string
display_label:
type: string
tick_size:
type: string
price_semantics:
type: string
display_semantics:
type: string
spot_contract:
$ref: '#/components/schemas/SpotContract'
SpotContract:
type: object
description: >-
Present only on spot markets. Restates the raw engine order in
trader-facing terms. Read ui_intent.price for a price in cNGN per USDC;
the sibling price and limit_price fields are raw engine values in USDC
per cNGN.
properties:
spec:
type: string
example: usdc_cngn_spot_v1
ui_intent:
$ref: '#/components/schemas/SpotUIIntent'
engine_order:
type: object
description: >-
The order as the matching engine sees it: cNGN traded against
internal USDC cash.
properties:
side:
type: string
enum:
- buy
- sell
description: Always the inverse of ui_intent.side.
price:
type: string
description: Engine price in USDC per cNGN.
example: '0.000728875182750367'
amount:
type: string
description: Engine amount as a whole cNGN quantity.
example: '1646'
balance_delta:
type: object
description: Balance change if the order fills completely.
properties:
usdc:
type: string
example: '-1.199729'
cngn:
type: string
example: '+1646'
SpotUIIntent:
type: object
description: Trader-facing view of a spot order, in the units a UI displays.
properties:
side:
type: string
enum:
- buy
- sell
description: >-
buy acquires USDC and sells cNGN inventory; sell delivers USDC and
buys cNGN inventory.
price:
type: string
description: Price in cNGN per USDC. The reciprocal of the engine price.
example: '1371.977018'
size:
type: string
description: Size as a USDC notional.
example: '1.199729'
````