REST API

Gateways serve this API on port 8000. Every order route currently requires an x-player-id header carrying the player's UUID.

Sizes and prices are decimal strings with at most 8 decimal places.

Method	Path	Description
`POST`	`/api/v1/orders`	Place a limit or market order
`GET`	`/api/v1/orders`	List the player's orders
`GET`	`/api/v1/orders/{id}`	Get a specific order by ID
`DELETE`	`/api/v1/orders/{id}`	Cancel a specific order
`DELETE`	`/api/v1/orders`	Cancel all open orders for the player
`POST`	`/api/v1/admin/markets/reload`	Reload `markets.yaml` into this gateway

Place an order

POST /api/v1/orders

Field	Required	Meaning
`client_order_id`	Yes	Fresh UUIDv7 generated immediately before submitting. Persist it with the reservation
`symbol`	Yes	The market identifier (e.g. `DEMO`, `IRON`)
`side`	Yes	`buy` or `sell`
`type`	Yes	`limit` or `market`
`size`	Yes	Quantity, within the market's configured limits
`price`	Limit orders	Price per unit, aligned to market tick size. Market orders omit this

Example Request

{
  "client_order_id": "019a5430-11aa-7bc1-8c55-7e1f6f4f3c21",
  "symbol": "IRON",
  "side": "buy",
  "type": "limit",
  "size": "100",
  "price": "9.50"
}

A 201 Created returns the accepted order:

{
  "id": "019a5430-11aa-7bc1-8c55-7e1f6f4f3c21",
  "symbol": "IRON",
  "side": "buy",
  "type": "limit",
  "created_at": "2026-11-06T14:02:11.482Z",
  "size": "100",
  "filled_size": "0",
  "executed_value": "0",
  "status": "open",
  "settled": false,
  "price": "9.50"
}

List orders

GET /api/v1/orders

Query parameters:

symbol (optional): Filter orders by market symbol.
status (optional): open, filled, canceled, or rejected.
limit (optional): Defaults to 100 (maximum 1000).

History is recorded asynchronously by the trade reporter; very recent orders may take a few milliseconds to appear in query history.

Cancel an order

DELETE /api/v1/orders/{id}

200 OK with "status": "canceled": The engine confirmed immediate cancellation.
202 Accepted with "status": "pending": Cancel is in flight. Await reconciliation via the fill webhook.

Cancel all orders

DELETE /api/v1/orders

Query parameters:

symbol (optional): Restrict mass-cancellation to a single market symbol.

Field	Meaning
`canceled`	Array of order IDs that were successfully canceled
`not_open`	Orders that reached terminal state before the cancel arrived
`unresolved`	Orders with in-flight outcomes. Retry or await webhook
`more`	Boolean indicating additional open orders exceed batch limits

Reconciliation and retries

MMX suppresses duplicate client order IDs within the admission window (ORDER_ID_WINDOW_SECS, default 60s). A 409 duplicate_order indicates an ID was claimed; it does not prove execution or non-execution.

On 503 outcome_unknown or gateway connection drop, keep the asset reservation held and poll GET /api/v1/orders/{client_order_id}.
If an order returns status: "unknown" and settled: false, continue polling.
When the gateway returns status: "never_landed", the reservation can safely be released.
Do not release asset reservations purely on network timeouts.