Overview
The
clientOrderId is an optional identifier that allows you to track and manage your orders with your own custom identifiers. It provides an additional layer of order management and tracking capabilities alongside the exchange-provided orderId.Specifications
Type & Requirements
- Type: String
- Mandatory: No
- Uniqueness: Must be unique per account
Allowed Characters
- Latin letters
- Numbers
- Dashes (-)
- Dots (.)
- Underscores (_)
Length and Format Guidelines
- Recommended length: 32 characters
- Case-sensitive: “Order1” and “order1” are different IDs
- Leading/trailing spaces are not allowed
- Cannot be an empty string if provided
Best Practices
- Naming Convention
- Timestamp
- Strategy
- Examples
Structured Naming Convention
Common Use Cases
- Limit Order
- Market Order
- Stop-Limit
- OTO Orders
Basic Limit Order
Order Management
Tracking Orders
You can track orders using 2. Query Order HistoryUse the Query Order History endpoint (3. Cancelling Orders Using ClientOrderIdUse the Cancel Order endpoint (
clientOrderId through the following endpoints:1. Query Active OrdersUse the Query Active Orders endpoint (/api/v4/orders) to get all unexecuted orders:Example response includes order details such as ID, status, and execution information:
/api/v4/trade-account/order/history) to get executed orders:Example response showing execution details and final order status:
/api/v4/order/cancel) to cancel an order by its clientOrderId:Important notes about order cancellation:
- Cancellation by
clientOrderIdtakes priority overorderId - You can use either
orderIdorclientOrderId, but not both in the same request
Error Handling
Common Error Cases
Duplicate ID
The
clientOrderId must be unique per account.Invalid Format
Ensure the ID only contains allowed characters.
Length Limit
The recommended length is 32 characters, with a maximum permissible length of 64 characters.
Order Not Found
Handle cases where an order with the specified
clientOrderId doesn’t exist.Example error handling:
Example: Broker Implementation
Broker Implementation Guide
ClientOrderId StructureFormat:
brk-{clientId}-{orderType}-{purpose}-{timestamp} Example: brk-ind123-limit-spot-1678234567Components:brk: Broker identifier prefixclientId: Your internal client identifierorderType: Order type (market/limit)purpose: Trading purpose/strategytimestamp: Ensures 24-hour uniqueness
Individual Clients
brk-ind123-market-spot-1678234567Corporate Clients
brk-corp789-limit-hedge-1678234567Managed Portfolios
brk-port555-market-dca-1678234567Trading Purpose Examples
Spot Trading
brk-ind123-market-spot-1678234567DCA Strategy
brk-port555-market-dca-1678234567Grid Trading
brk-ind123-limit-grid-1678234567Portfolio Rebalancing
brk-port555-limit-rebal-1678234567API Usage Example
- Track orders for multiple clients
- Identify order types and purposes
- Maintain unique identifiers
- Query and manage orders efficiently