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.

WebSocket order commands are useful when your service already keeps a live trading connection open. They follow the same business rules as REST order routes, but the response model is streaming oriented:
  1. Send a command message with a unique request_id.
  2. Receive command_ack or command_error.
  3. Track final order status through user.orders or REST order reads.
command_ack means the command was accepted for processing. It does not mean the order is filled, cancelled, or replaced. Use user.orders and GET /partner/exchange/orders/{order_id} for canonical status.

​
Required Access

ActionAccess requirement
order_createAPI key enabled for order creation
order_cancelAPI key enabled for order execution
order_replaceAPI key enabled for order execution
user.orders updatesAPI key enabled for exchange reads
user.fills updatesAPI key enabled for exchange reads

​
Command Envelope

Every command uses the same outer shape: 
{
  "type": "command",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "action": "order_create"
}
Use request_id as your local correlation ID. If idempotency_key is omitted, Stabyl uses request_id as the idempotency key. For clarity, production clients should send both values and store them before sending the command.

​
Create Order

Use the REST pair ID in command payloads. For the currently supported pair, send USD/NGN; topic keys such as USD_NGN are only used in subscription topic names. 
{
  "type": "command",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "action": "order_create",
  "pair_id": "USD/NGN",
  "side": "buy",
  "order_type": "limit",
  "quantity": "100.00",
  "price": "1650.00",
  "time_in_force": "GTC",
  "client_order_id": "cli-123",
  "idempotency_key": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b"
}
Acknowledgement: 
{
  "type": "command_ack",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "action": "order_create",
  "data": {
    "order_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "pending",
    "created_at": "2026-01-14T10:30:00Z"
  }
}

​
Cancel Order

{
  "type": "command",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91c",
  "action": "order_cancel",
  "pair_id": "USD/NGN",
  "order_id": "123e4567-e89b-12d3-a456-426614174000",
  "idempotency_key": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91c"
}
Acknowledgement: 
{
  "type": "command_ack",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91c",
  "action": "order_cancel",
  "data": {
    "order_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "cancelling",
    "cancelled_at": "2026-01-14T10:31:00Z"
  }
}

​
Replace Order

{
  "type": "command",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91d",
  "action": "order_replace",
  "pair_id": "USD/NGN",
  "order_id": "123e4567-e89b-12d3-a456-426614174000",
  "quantity": "150.00",
  "price": "1655.00",
  "client_order_id": "cli-456",
  "idempotency_key": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91d"
}
Acknowledgement: 
{
  "type": "command_ack",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91d",
  "action": "order_replace",
  "data": {
    "original_order_id": "123e4567-e89b-12d3-a456-426614174000",
    "new_order_id": "123e4567-e89b-12d3-a456-426614174111",
    "status": "replacing",
    "replaced_at": "2026-01-14T10:31:00Z"
  }
}

​
Command Errors

Command rejections use command_error. 
{
  "type": "command_error",
  "request_id": "019bd2d1-5a9c-7e23-9cf1-1f87a3f2e91b",
  "code": "VALIDATION_FAILED",
  "message": "limit orders require a price"
}
Common error classes:
CodeMeaningAction
UNAUTHORIZEDThe connection is not authenticatedReconnect with a valid API key
FORBIDDENThe API key is not permitted for the actionUse a key enabled for that action
VALIDATION_FAILEDThe command payload is invalidCorrect the command before retrying
CONFLICTThe idempotency key or order state conflictsRead the order state before sending a new intent
RATE_LIMITEDToo many messages or commandsBack off and retry later

​
Production Pattern

  1. Subscribe to user.orders before submitting commands.
  2. Store {request_id, idempotency_key, action, local_order_intent} before sending.
  3. Treat command_ack as asynchronous acceptance.
  4. Reconcile final status from user.orders.
  5. If the socket disconnects after a command, reconnect, resubscribe with resume, and read the order by REST before sending a replacement intent.