Order Management

Order routes automate trading activity for your Stabyl account. Order writes require X-Api-Key and Idempotency-Key. 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 enabled.
Validate side, order_type, quantity, and price against the market rules.
Confirm available balance with GET /partner/wallets/balances/overview.
Generate and store an Idempotency-Key for this exact order intent.
Configure exchange webhooks or private WebSocket topics before 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`	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

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.

Get Started

Wallets

Exchange

Webhooks

WebSocket

Before You Place an Order

Create A Limit Order

Create A Market Order

Create Response

List Orders By Status

Get Order Detail

Cancel Order

Replace Order

Status Handling

Retry Rules

​Before You Place an Order

​Create A Limit Order

​Create A Market Order

​Create Response

​List Orders By Status

​Get Order Detail

​Cancel Order

​Replace Order

​Status Handling

​Retry Rules

Before You Place an Order

Create A Limit Order

Create A Market Order

Create Response

List Orders By Status

Get Order Detail

Cancel Order

Replace Order

Status Handling

Retry Rules