Skip to main content
The exchange routes let approved Stabyl accounts automate trading activity that would otherwise be performed in the product interface. Discover markets first, validate amounts and precision locally, submit order intents with idempotency, consume exchange events, and reconcile periodically from order and fill reads.

​
Core Objects

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: 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. 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: Only filled, cancelled, rejected, and expired 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. Apply exchange webhooks or private WebSocket updates to the local order.
  5. Periodically reconcile order detail, fills, and wallet transactions from REST.
  6. Run reconciliation after event-consumer downtime or a connection reset.
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.