Skip to main content

Documentation Index

Fetch the complete documentation index at: https://stabyl.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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

StatusYour action
pendingContinue polling or schedule a reconciliation read
acceptedTreat as live unless a later read says otherwise
partially_filledShow executed and remaining amounts separately
filledStop polling and reconcile fills
cancelledStop polling and reconcile any partial fills
rejectedStop polling and surface the public error message

​
Retry Rules

SituationWhat to do
Request timed out before a responseRetry with the same Idempotency-Key
Response was 429Back off, then retry with the same Idempotency-Key
Response was 409Read the existing order or correct the conflicting request
Order status is terminalDo not retry the same action as a new order
Common failures include invalid pair, insufficient available balance, stale order status, or idempotency conflicts.