Order Management

Create, list, read, cancel, and replace exchange orders.

Order routes automate trading activity for your Stabyl account. Order writes require X-Api-Key and Idempotency-Key. Matching is asynchronous, so use order reads as the canonical source for status, filled quantity, remaining quantity, and rejection state.

Before You Place an Order

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

1. Fetch GET /partner/exchange/markets and confirm the pair is enabled.
2. Validate side, order_type, quantity, and price against the market rules.
3. Confirm available balance with GET /partner/wallets/balances/overview.
4. Generate and store an Idempotency-Key for this exact order intent.
5. Decide how your service will poll or reconcile the order after submission.

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 A Market Order

Market orders prioritize execution against available liquidity. Because the final price depends on available depth, read the current ticker or order book first and keep your own risk controls conservative.

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"
  }'

Create 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",
    "pair_id": "USD/NGN",
    "side": "buy",
    "order_type": "limit",
    "status": "pending",
    "quantity": "100.00",
    "price": "1520.00"
  }
}

Store the returned order_id. Use it for all later reads, cancels, replacements, and reconciliation.

List Orders By Status

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

Use list filters for dashboards and background reconciliation. For a single order, prefer the detail endpoint.

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"

Cancel 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.

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 creates a new order intent for the remaining quantity according to the API response. Always read the returned order and do not assume the original order is still active.

Status Handling

Status	Your action
pending	Continue polling or schedule a reconciliation read
accepted	Treat as live unless a later read says otherwise
partially_filled	Show executed and remaining amounts separately
filled	Stop polling and reconcile fills
cancelled	Stop polling and reconcile any partial fills
rejected	Stop polling and surface the public error message

Retry Rules

Situation	What to do
Request timed out before a response	Retry with the same Idempotency-Key
Response was 429	Back off, then retry with the same Idempotency-Key
Response was 409	Read the existing order or correct the conflicting request
Order status is terminal	Do not retry the same action as a new order

Common failures include invalid pair, insufficient available balance, stale order status, or idempotency conflicts.