WebSocket Order Commands

Submit order create, cancel, and replace commands over WebSocket.

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

Action	Access requirement
order_create	API key enabled for order creation
order_cancel	API key enabled for order execution
order_replace	API key enabled for order execution
user.orders updates	API key enabled for exchange reads
user.fills updates	API 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:

Code	Meaning	Action
UNAUTHORIZED	The connection is not authenticated	Reconnect with a valid API key
FORBIDDEN	The API key is not permitted for the action	Use a key enabled for that action
VALIDATION_FAILED	The command payload is invalid	Correct the command before retrying
CONFLICT	The idempotency key or order state conflicts	Read the order state before sending a new intent
RATE_LIMITED	Too many messages or commands	Back 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.