Client Order ID

Overview

The clientOrderId is an optional identifier for tracking and managing orders with 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: enforced only among open (pending) orders on the same market — the identifier can be reused once the previous order fills or cancels

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

// Format: strategy-pair-type-timestamp
const clientOrderId = "scalp-btcusdt-limit-1678234567";

// Format: botId-strategy-sequence
const clientOrderId = "bot123-grid-0001";

// Format: userAccount-orderType-customSequence
const clientOrderId = "trade15-market-a7b8c9";

Timestamp Integration

const getClientOrderId = (prefix: string) => {
  const timestamp = Date.now();
  return `${prefix}-${timestamp}`;
};

// Usage
const orderId = getClientOrderId("btc-dca"); // "btc-dca-1678234567890"

Strategy Identification

const generateStrategyOrderId = (
  strategy: string,
  pair: string,
  action: string
) => {
  const sequence = Math.floor(Math.random() * 1000)
    .toString()
    .padStart(3, "0");
  return `${strategy}-${pair}-${action}-${sequence}`;
};

// Usage
const orderId = generateStrategyOrderId("grid", "btcusdt", "buy");

Common Use Cases

Limit Order
Market Order
Stop-Limit
OTO Orders

Basic Limit Order

// Simple limit order with clientOrderId
const limitOrderRequest = {
  market: "BTC_USDT",
  side: "buy",
  amount: "0.01",
  price: "40000",
  clientOrderId: "limit-btc-buy-001"
};

Market Order with Strategy Tag

// Market order for DCA strategy
const marketOrderRequest = {
  market: "BTC_USDT",
  side: "buy",
  amount: "50", // Buy BTC for 50 USDT
  clientOrderId: "dca-btc-market-002"
};

Stop-Limit Order with Position Tracking

// Stop-limit order with position tracking
const stopLimitOrderRequest = {
  market: "BTC_USDT",
  side: "sell",
  amount: "0.01",
  price: "39000",
  activation_price: "39500",
  clientOrderId: "pos1-sl-btc-001"
};

OTO (One-Triggers-Other) Orders

// Main order with stop loss and take profit
const otoOrderRequest = {
  market: "BTC_USDT",
  side: "buy",
  amount: "0.01",
  price: "40000",
  clientOrderId: "oto-btc-main-001",
  stopLoss: "38000",
  takeProfit: "42000"
};

Order Management

Tracking Orders

Track orders using clientOrderId through the following endpoints:1. Query Active OrdersUse the Query Active Orders endpoint (/api/v4/orders) to get all unexecuted orders:

// Request
const queryActiveOrders = {
  market: "BTC_USDT",
  clientOrderId: "dca-btc-market-002"
};

Example response includes order details such as ID, status, and execution information:

{
  "orderId": 4180284841,
  "clientOrderId": "dca-btc-market-002",
  "market": "BTC_USDT",
  "side": "buy",
  "type": "limit",
  "timestamp": 1595792396.165973,
  "dealMoney": "0",
  "dealStock": "0",
  "amount": "0.001",
  "price": "40000",
  "status": "NEW"
}

2. Query Order HistoryUse the Query Order History endpoint (/api/v4/trade-account/order/history) to get executed orders:

// Request
const queryOrderHistory = {
  market: "BTC_USDT",
  clientOrderId: "grid-btc-sell-003",
  limit: 50,
  offset: 0
};

Example response showing execution details and final order status. The response groups orders by market name:

{
  "BTC_USDT": [
    {
      "id": 4180284841,
      "clientOrderId": "grid-btc-sell-003",
      "side": "sell",
      "type": "limit",
      "ctime": 1595792396.165973,
      "ftime": 1595792396.999999,
      "dealMoney": "41.258268",
      "dealStock": "0.001",
      "amount": "0.001",
      "price": "41258.27",
      "status": "FILLED"
    }
  ]
}

3. Cancelling Orders Using ClientOrderIdUse the Cancel Order endpoint (/api/v4/order/cancel) to cancel an order by its clientOrderId:

// Request
const cancelOrderRequest = {
  market: "BTC_USDT",
  clientOrderId: "dca-btc-market-002"
};

Important notes about order cancellation:

Use either orderId or clientOrderId, but not both in the same request
A request specifying both identifiers, or neither, returns a validation error

// Example response
{
  "orderId": 4180284841,
  "clientOrderId": "dca-btc-market-002",
  "market": "BTC_USDT",
  "side": "buy",
  "type": "limit",
  "timestamp": 1595792396.165973,
  "dealMoney": "0",
  "dealStock": "0",
  "amount": "0.001",
  "left": "0.001",
  "price": "40000",
  "status": "CANCELED"
}

Error Handling

Common Error Cases

Duplicate ID

The clientOrderId only has to be unique among the account’s open (pending) orders on the same market. Once a previous order is filled or canceled, the same identifier can be reused on the same market. The same identifier can also be used in parallel on different markets.

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 does not exist.

Example error handling:

try {
  const order = await queryOrderByClientId("dca-btc-market-002");
  // Process order
} catch (error) {
  if (error.code === 36) {
    console.error("Invalid clientOrderId format");
  } else if (error.code === 2) {
    console.error("Order not found");
  } else {
    console.error("Unexpected error:", error);
  }
}

Example: Account-operator implementation

For the full Embedded Trading integration guide — program enrollment, sub-account setup, fee share model, and revenue monitoring — see Embedded Trading integration.

Account-operator implementation

ClientOrderId StructureFormat: acct-{clientId}-{orderType}-{purpose}-{timestamp} Example: acct-ind123-limit-spot-1678234567Components:

acct: Account-operator prefix
clientId: Internal client identifier
orderType: Order type (market/limit)
purpose: Trading purpose/strategy
timestamp: Keeps each identifier distinct across submissions

Individual Clients

acct-ind123-market-spot-1678234567

Corporate Clients

acct-corp789-limit-hedge-1678234567

Managed Portfolios

acct-port555-market-dca-1678234567

Trading Purpose Examples

Spot Trading

acct-ind123-market-spot-1678234567

DCA Strategy

acct-port555-market-dca-1678234567

Grid Trading

acct-ind123-limit-grid-1678234567

Portfolio Rebalancing

acct-port555-limit-rebal-1678234567

API Usage Example

// Create an order for a client
const createClientOrder = {
  market: "BTC_USDT",
  side: "buy",
  amount: "0.01",
  price: "40000",
  clientOrderId: "acct-ind123-limit-spot-1678234567"
};

// Query client's active orders
const queryClientOrders = {
  market: "BTC_USDT",
  clientOrderId: "acct-ind123-limit-spot-1678234567"
};

// Cancel client's order using clientOrderId
const cancelClientOrder = {
  market: "BTC_USDT",
  clientOrderId: "acct-ind123-limit-spot-1678234567"
};

// Get historical data for client orders
const getClientOrderHistory = {
  market: "BTC_USDT",
  clientOrderId: "acct-ind123-limit-spot-1678234567",
  limit: 50,
  offset: 0
};

This structured approach lets an account operator:

Track orders for multiple clients
Identify order types and purposes
Maintain unique identifiers
Query and manage orders efficiently

Order management for account operators

Client Order Management

Cancelling Client Orders

An account operator can efficiently cancel orders for any client using the structured clientOrderId:

// Function to cancel a client's order
async function cancelClientOrder(clientId, orderPurpose, orderId) {
  const cancelRequest = {
    market: "BTC_USDT",
    clientOrderId: `acct-${clientId}-limit-${orderPurpose}-${orderId}`
  };

  try {
    const response = await api.post('/api/v4/order/cancel', cancelRequest);
    return response.data;
  } catch (error) {
    console.error(`Failed to cancel order for client ${clientId}:`, error);
    throw error;
  }
}

// Example usage
await cancelClientOrder('ind123', 'spot', '1678234567');

Retrieving Historical Client Orders

The Query Order History endpoint (/api/v4/trade-account/order/history) supports exact clientOrderId lookup only: pass the full identifier to retrieve a single order. When clientOrderId is supplied, the endpoint switches to single-order lookup mode and ignores the startDate, endDate, and status filters. Pattern or prefix matching on clientOrderId is not supported.

// Exact lookup of one client order (single-order mode)
const lookupClientOrder = {
  market: "BTC_USDT",
  clientOrderId: "acct-ind123-limit-spot-1678234567"
};

For reporting across many client orders, retrieve history in list mode — filtered by market, startDate, and endDate (Unix seconds) — and parse the structured identifiers client-side, as shown below.

Analytics and reporting

With structured clientOrderId patterns, an account operator can reconstruct per-client reporting from order history without a separate order database — each ID segment maps to a report dimension:

ID segment	Encodes	Analytics use
`acct`	Account-operator prefix	Separates operator flow from other orders
`clientId`	Internal client identifier	Groups orders and volume per client
`orderType`	Order type (market/limit)	Order-type mix per client
`purpose`	Trading purpose/strategy (spot, dca, grid, rebal)	Order count and volume per strategy
`timestamp`	Submission time	Keeps IDs distinct; submission-time analysis

The critical path is the parser — split the ID and validate its shape. Aggregating parsed segments into per-client totals (order counts, dealMoney volume, per-purpose breakdowns) is standard reporting code on top of it:

// Parse clientOrderId back into its metadata segments
// Format: acct-{clientId}-{orderType}-{purpose}-{timestamp}
function parseClientOrderId(clientOrderId) {
  const parts = clientOrderId.split('-');
  if (parts.length !== 5 || parts[0] !== 'acct') {
    throw new Error('Invalid account-operator clientOrderId format');
  }
  return {
    clientId: parts[1],
    orderType: parts[2],
    purpose: parts[3],
    timestamp: parseInt(parts[4])
  };
}

Overview

Specifications

Type & Requirements

Allowed Characters

Length and Format Guidelines

Best Practices

Basic Examples

Advanced Examples

Common Use Cases

Order Management

Tracking Orders

Error Handling

Common Error Cases

Duplicate ID

Invalid Format

Length Limit

Order Not Found

Example error handling:

Example: Account-operator implementation

Account-operator implementation

Individual Clients

Corporate Clients

Managed Portfolios

Trading Purpose Examples

Spot Trading

DCA Strategy

Grid Trading

Portfolio Rebalancing

API Usage Example

Order management for account operators

Cancelling Client Orders

Retrieving Historical Client Orders

Analytics and reporting

​Overview

​Specifications

Type & Requirements

Allowed Characters

Length and Format Guidelines

​Best Practices

Basic Examples

Advanced Examples

​Common Use Cases

​Order Management

Tracking Orders

​Error Handling

​Common Error Cases

Duplicate ID

Invalid Format

Length Limit

Order Not Found

​Example error handling:

​Example: Account-operator implementation

Account-operator implementation

Individual Clients

Corporate Clients

Managed Portfolios

​Trading Purpose Examples

Spot Trading

DCA Strategy

Grid Trading

Portfolio Rebalancing

​API Usage Example

​Order management for account operators

​Cancelling Client Orders

​Retrieving Historical Client Orders

​Analytics and reporting

Overview

Specifications

Best Practices

Common Use Cases

Order Management

Error Handling

Common Error Cases

Example error handling:

Example: Account-operator implementation

Trading Purpose Examples

API Usage Example

Order management for account operators

Cancelling Client Orders

Retrieving Historical Client Orders

Analytics and reporting