Exchange Overview

Market data, order lifecycle, and status reconciliation for account trading automation.

The exchange routes let approved Stabyl accounts automate trading activity that would otherwise be performed in the product interface. Build against them like a trading API: discover markets first, validate amounts and precision locally, submit order intents with idempotency, then reconcile from order and fill reads until the order reaches a terminal state.

Core Objects

Object	Description
Market	A tradable pair such as USD/NGN, with supported order rules and precision
Ticker	Current best bid/ask and 24h market statistics for a pair
Order book	Aggregated price levels available for a pair at a point in time
Trade	A recent public market execution
Fill	An execution linked to your account’s order history
Order	Your instruction to buy or sell a base asset against a quote asset

Use IDs and symbols exactly as returned by the API. Do not infer pair names, decimal precision, minimum sizes, or route availability from hardcoded configuration.

Today, the supported exchange pair is USD/NGN. As new pairs are added, they will appear in GET /partner/exchange/markets; build against discovery rather than assuming this list is permanent.

Market Data

Market data routes are read-only and should be used before order submission and during reconciliation:

Need	Endpoint family
Discover tradable products	GET /partner/exchange/markets
Show a current quote	GET /partner/exchange/ticker/24h
Inspect depth before placing a limit order	GET /partner/exchange/orderbook/{pair_id}/snapshot
Draw charts or backfill candles	GET /partner/exchange/candles
Reconcile recent executions	GET /partner/exchange/trades and GET /partner/exchange/fills

Market data changes frequently. Treat responses as snapshots, cache only for short intervals, and refresh before sending price-sensitive orders.

Orders

An order request is an instruction, not a guarantee that the order has fully executed. The create route validates the request, records the intent, and returns an order that may still be pending. Matching and final settlement are asynchronous.

Order type	Use when	Required price
limit	You want execution at a specific price or better	Yes
market	You prefer immediate execution against available liquidity	No

Side	Meaning
buy	Spend quote currency to acquire base currency
sell	Sell base currency for quote currency

For example, on USD/NGN, USD is the base currency and NGN is the quote currency.

Order Lifecycle

Orders can move through the following statuses:

Status	Meaning
pending	Request accepted for processing
accepted	Order is live or eligible for matching
partially_filled	Some quantity has executed
filled	Full quantity has executed
cancelled	Remaining quantity was cancelled
rejected	Order was not accepted

Only filled, cancelled, rejected should be treated as terminal. A partially_filled order still has remaining quantity unless the order later moves to a terminal state.

Reconciliation Pattern

1. Generate an Idempotency-Key and store it with the local order intent.
2. Submit the order with POST /partner/exchange/orders.
3. If the create response is uncertain, retry with the same Idempotency-Key.
4. Read GET /partner/exchange/orders/{order_id} until the status is terminal.
5. Use fills and wallet transactions to reconcile execution and balance movement.

Never assume a network timeout means an order did not exist. Query the order state before creating a replacement.

Authenticated exchange endpoints require X-Api-Key. Order write routes also require Idempotency-Key.