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: 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

// 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:

{
  "records": [
    {
      "orderId": 4180284841,
      "clientOrderId": "grid-btc-sell-003",
      "market": "BTC_USDT",
      "side": "sell",
      "type": "limit",
      "timestamp": 1595792396.165973,
      "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:

Cancellation by clientOrderId takes priority over orderId
Use either orderId or clientOrderId, but not both in the same request

// 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 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:

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: Broker Implementation

Broker Implementation Guide

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

brk: Broker identifier prefix
clientId: Internal client identifier
orderType: Order type (market/limit)
purpose: Trading purpose/strategy
timestamp: Ensures 24-hour uniqueness

Individual Clients

brk-ind123-market-spot-1678234567

Corporate Clients

brk-corp789-limit-hedge-1678234567

Managed Portfolios

brk-port555-market-dca-1678234567

Trading Purpose Examples

Spot Trading

brk-ind123-market-spot-1678234567

DCA Strategy

brk-port555-market-dca-1678234567

Grid Trading

brk-ind123-limit-grid-1678234567

Portfolio Rebalancing

brk-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: "brk-ind123-limit-spot-1678234567"
};

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

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

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

This structured approach allows brokers to:

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

Order Management for Brokers

Client Order Management

Cancelling Client Orders

Brokers can efficiently cancel orders for any of their clients using the structured clientOrderId:

// Function to cancel a client's order
async function cancelClientOrder(clientId, orderPurpose, orderId) {
  const cancelRequest = {
    market: "BTC_USDT",
    clientOrderId: `brk-${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

Brokers can retrieve and analyze historical order data for reporting, analysis, and compliance:

// Function to get client order history with optional filtering
async function getClientOrderHistory(clientId, orderPurpose, startTime, endTime) {
  // Base query parameters
  const queryParams = {
    market: "BTC_USDT",
    limit: 100,
    offset: 0
  };

  // Add clientOrderId filter if specific client and purpose
  if (clientId && orderPurpose) {
    // Using partial match prefix to get all orders matching the pattern
    queryParams.clientOrderId = `brk-${clientId}-*-${orderPurpose}-*`;
  }

  // Add time range if specified
  if (startTime) queryParams.start_time = startTime;
  if (endTime) queryParams.end_time = endTime;

  try {
    const response = await api.get('/api/v4/trade-account/order/history', { params: queryParams });
    return response.data.records;
  } catch (error) {
    console.error("Failed to fetch client order history:", error);
    throw error;
  }
}

// Example: Get all spot trades for a specific client
const clientSpotOrders = await getClientOrderHistory('ind123', 'spot',
  Date.now() - 30 * 24 * 60 * 60 * 1000, // 30 days ago
  Date.now() // now
);

// Example: Get all DCA orders across clients
const allDcaOrders = await getClientOrderHistory(null, 'dca');

Broker Analytics and Reporting

With structured clientOrderId patterns, brokers can implement powerful analytics and reporting by parsing the IDs:

// Parse clientOrderId to extract metadata
function parseClientOrderId(clientOrderId) {
  // Format: brk-{clientId}-{orderType}-{purpose}-{timestamp}
  const parts = clientOrderId.split('-');
  if (parts.length !== 5 || parts[0] !== 'brk') {
    throw new Error('Invalid broker clientOrderId format');
  }

  return {
    clientId: parts[1],
    orderType: parts[2],
    purpose: parts[3],
    timestamp: parseInt(parts[4])
  };
}

// Example usage for reporting
function generateClientReport(orderHistory) {
  const clientStats = {};

  orderHistory.forEach(order => {
    try {
      const { clientId, purpose } = parseClientOrderId(order.clientOrderId);

      if (!clientStats[clientId]) {
        clientStats[clientId] = {
          totalOrders: 0,
          volume: 0,
          byPurpose: {}
        };
      }

      // Update client stats
      clientStats[clientId].totalOrders++;
      clientStats[clientId].volume += parseFloat(order.dealMoney);

      // Update purpose-specific stats
      if (!clientStats[clientId].byPurpose[purpose]) {
        clientStats[clientId].byPurpose[purpose] = {
          count: 0,
          volume: 0
        };
      }

      clientStats[clientId].byPurpose[purpose].count++;
      clientStats[clientId].byPurpose[purpose].volume += parseFloat(order.dealMoney);

    } catch (error) {
      console.warn("Skipping order with invalid clientOrderId:", order.clientOrderId);
    }
  });

  return clientStats;
}

Platform Features

Guides

AI Hub

Resources

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: Broker Implementation

Broker Implementation Guide

Individual Clients

Corporate Clients

Managed Portfolios

Trading Purpose Examples

Spot Trading

DCA Strategy

Grid Trading

Portfolio Rebalancing

API Usage Example

Order Management for Brokers

Cancelling Client Orders

Retrieving Historical Client Orders

Broker 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: Broker Implementation

Broker Implementation Guide

Individual Clients

Corporate Clients

Managed Portfolios

​Trading Purpose Examples

Spot Trading

DCA Strategy

Grid Trading

Portfolio Rebalancing

​API Usage Example

​Order Management for Brokers

​Cancelling Client Orders

​Retrieving Historical Client Orders

​Broker Analytics and Reporting

Overview

Specifications

Best Practices

Common Use Cases

Order Management

Error Handling

Common Error Cases

Example error handling:

Example: Broker Implementation

Trading Purpose Examples

API Usage Example

Order Management for Brokers

Cancelling Client Orders

Retrieving Historical Client Orders

Broker Analytics and Reporting