Order Management

Order routes automate trading activity for your Stabyl account. Order creation requires X-Api-Key with trades:create; cancel and replace require trades:execute. Send a UUID Idempotency-Key for direct order creation, cancellation, and replacement. Quote acceptance uses the quote ID instead. Matching is asynchronous. Consume exchange webhooks or private WebSocket topics for timely changes, and use order reads for recovery, operator lookups, and periodic reconciliation.

Before You Place an Order

Perform these checks in your own system before sending the request:

Fetch GET /partner/exchange/markets and confirm the pair is listed.
Validate side, order_type, quantity, and price against tick_size, min_base_lot, and min_notional.
Confirm available balance with GET /partner/wallets/balances/overview. Creation does not check balance; an unfunded order is accepted and later reported as rejected.
Generate and store a UUID Idempotency-Key and a unique client_order_id for this exact order intent.
Configure exchange webhooks or private WebSocket topics before submission.

Request Fields

Field	Required	Notes
`pair_id`	Yes	Canonical pair such as `USD/NGN`
`side`	Yes	`buy` or `sell`
`order_type`	Yes	`limit` or `market`
`quantity`	Yes	Base-asset amount as a decimal string, at least `min_base_lot`
`price`	Limit	Decimal string on the `tick_size` grid. Ignored for market orders
`time_in_force`	No	`GTC` (default for limit), `IOC`, `FOK`, or `POST_ONLY`. Market orders are always `IOC`
`client_order_id`	No	Up to 128 characters, unique within your account. Generated when omitted
`idempotency_key`	No	Same value as the `Idempotency-Key` header when both are present

Unknown fields are rejected. POST_ONLY cancels the order instead of taking liquidity when it would cross the book.

Create A Limit Order

Limit orders specify the maximum buy price or minimum sell price you are willing to accept.

curl https://api-staging.stabyl.com/v1/partner/exchange/orders \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50221" \
  -d '{
    "pair_id": "USD/NGN",
    "side": "buy",
    "order_type": "limit",
    "price": "1520.00",
    "quantity": "100.00"
  }'

Create And Accept A Quote

Create a quote with trades:view:

curl https://api-staging.stabyl.com/v1/partner/exchange/quotes \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -d '{
    "pair_id": "USD/NGN",
    "side": "sell",
    "quantity": "50.00",
    "business_bps": 25
  }'

The response includes quote_id, expires_at, estimated pricing and fees, and protected_limit_price: the highest buy price or lowest sell price allowed. Quotes expire after 30 seconds; use the returned expires_at for your countdown. business_bps is an optional display spread, added for buys and subtracted for sells. It does not change execution or Stabyl fees. Fees are estimates until the order is accepted for execution. Accept with trades:create, no body, and no Idempotency-Key:

curl "https://api-staging.stabyl.com/v1/partner/exchange/quotes/$QUOTE_ID/accept" \
  -X POST \
  -H "X-Api-Key: $STABYL_API_KEY"

The response contains quote_id, order_id, status: "pending", and accepted_at. Check the returned order for the final result. Liquidity is not reserved: fills may be partial or zero, and any unfilled remainder is cancelled. Retry an uncertain acceptance with the same quote ID, including after expiry if acceptance had already begun. An expired, unaccepted quote returns 409; request a fresh quote. Unknown or another account’s quotes return 404. Do not also submit a separate order for the same quote.

POST /partner/exchange/orders/estimate is deprecated. It remains supported with the same request and response; use /partner/exchange/quotes for new integrations.

Create A Market Order

To submit a market order directly, use /partner/exchange/orders. This does not accept a quote or use its protected price.

curl https://api-staging.stabyl.com/v1/partner/exchange/orders \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50222" \
  -d '{
    "pair_id": "USD/NGN",
    "side": "sell",
    "order_type": "market",
    "quantity": "50.00"
  }'

Direct Order Response

The response confirms that Stabyl accepted the order request for processing. It does not mean the order is already filled.

{
  "status": "success",
  "data": {
    "order_id": "0198b731-2830-7f5d-a10d-7a5fda480491",
    "status": "pending",
    "created_at": "2026-09-09T08:12:04+00:00"
  }
}

Store the returned order_id. Use it for all later reads, cancels, replacements, and reconciliation. The response does not echo the order fields; read the order or wait for exchange.accepted to see them.

List Orders By Status

curl "https://api-staging.stabyl.com/v1/partner/exchange/orders?status=accepted" \
  -H "X-Api-Key: $STABYL_API_KEY"

Filters are status (pending, accepted, partially_filled, filled, cancelled, rejected, expired), pair_id, limit (default 50, maximum 100), and offset. An unrecognised status value is ignored rather than rejected. The response contains orders and count for the page; there is no cursor or total. Use list filters for dashboards and background reconciliation. For a single order, prefer the detail endpoint, which also returns the order’s fills.

Get Order Detail

curl https://api-staging.stabyl.com/v1/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491 \
  -H "X-Api-Key: $STABYL_API_KEY"

Cancel Order

curl https://api-staging.stabyl.com/v1/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491/cancel \
  -X POST \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50223"

The response is { "order_id", "status": "cancelling", "cancelled_at" }. Cancel is accepted only while the order is pending, accepted, or partially_filled; any other status returns 400. It is best effort for open quantity: if part of the order has already executed, the filled portion remains final and only remaining quantity can be cancelled. Confirm the outcome from exchange.cancelled or an order read.

Replace Order

curl https://api-staging.stabyl.com/v1/partner/exchange/orders/0198b731-2830-7f5d-a10d-7a5fda480491/replace \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $STABYL_API_KEY" \
  -H "Idempotency-Key: 0198b730-7cc2-79e4-b04e-5b5c41a50221" \
  -d '{
    "price": "1518.00",
    "quantity": "100.00"
  }'

Replace applies to live limit orders in accepted or partially_filled status; a pending or market order returns 400. Send at least one of price or quantity. Omitting quantity keeps the remaining unfilled quantity, and an optional client_order_id names the replacement. The response is { "original_order_id", "new_order_id", "status": "replacing", "replaced_at" }. Store new_order_id: the original is cancelled and the replacement continues under the new ID. Always read the returned order and do not assume the original order is still active.

Status Handling

Status	Your action
`pending`	Wait for an event and include it in periodic reconciliation
`accepted`	Treat as live until a later event or reconciliation update
`partially_filled`	Apply each fill event and show executed and remaining amounts
`filled`	Treat as terminal and reconcile all fills
`cancelled`	Treat as terminal and reconcile any partial fills
`rejected`	Treat as terminal and surface the public reason
`expired`	Treat as terminal when returned by REST reconciliation

cancelling and replacing appear only in the cancel and replace responses while the change is being applied; the order itself then moves to cancelled or is superseded by the replacement.

Retry Rules

These rules apply to direct order requests. For quote acceptance, retry the same quote ID as described above.

Situation	What to do
Request timed out before a response	Retry with the same `Idempotency-Key`, then reconcile by `client_order_id`; the retry’s `order_id` is not the live order
Response was `429`	Back off, then retry with the same `Idempotency-Key`
Response was `403`	Trading is suspended on the pair, production KYB is not approved, or the key lacks the scope. Do not retry until resolved
Order status is terminal	Do not retry the same action as a new order

Order writes return 400 for an invalid pair, price, quantity, or status transition, 401, 403, 404 for an unknown or foreign order, 429, and 503. They never return 409. Insufficient balance is not a write-time failure; it surfaces later as a rejected order.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Before You Place an Order

Request Fields

Create A Limit Order

Create And Accept A Quote

Create A Market Order

Direct Order Response

List Orders By Status

Get Order Detail

Cancel Order

Replace Order

Status Handling

Retry Rules