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 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 a UUID Idempotency-Key and a unique client_order_id, and store both with the local order intent.
  2. Submit the order with POST /partner/exchange/orders and store the returned order_id.
  3. If the create response is uncertain, retry with the same Idempotency-Key. A retry answers with a new order_id; the duplicate command is discarded, so reconcile by client_order_id rather than trusting the retry’s ID. See Idempotency.
  4. Apply exchange webhooks or private WebSocket updates to the local order.
  5. Periodically reconcile order detail, its 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 with trades:view for reads, trades:create for order creation, and trades:execute for cancel and replace. Always send Idempotency-Key on order writes.