Core Concepts

The order entry protocol uses a small set of conventions for identifiers, timestamps, rate-limit reporting, and capability discovery. This page defines them once. Reference pages later assume them.

Order IDs

Three different identifiers are used for an order through its lifetime:

Exchange Order ID: a string assigned by the exchange when the order is accepted. Stable for the order's lifetime.
Own Order ID: an ID (UUID v4) assigned by the client once, when the order is placed. Example: 123e4567-e89b-12d3-a456-426614174000.
Client Order ID: an ID (UUID v4) assigned by the client for each new or modified order. A new client order ID is assigned on every modification. Example: 11111111-e89b-12d3-a456-426614174000.

Tip

Generate a fresh UUID for ownOrderId per order; never reuse one. Generate a new clientOrderId for every modification, so the modification chain is traceable.

Fill IDs

Fills carry two identifiers:

Exchange Trade ID: a string assigned by the exchange.
Own Fill ID: a UUID string assigned by the adapter once.

Timestamps

Two timestamps usually accompany a message:

Exchange Timestamp: reported by the exchange, when available.
Adapter Timestamp: taken by the trading adapter when the event or response was received.

All nanosecond timestamp fields follow the same convention:

exchangeTimestampNs: from the exchange (when available).
adapterTimestampNs: when the adapter received or processed the message.
createTimestampNs: when the client created the request.

Timestamps are Unix epoch nanoseconds (since 1970-01-01 00:00:00 UTC).

Rate-limit loads

A rate-limit load is a value between 0.0 (no usage) and 1.0 (limit fully consumed). Loads are published periodically per key and typically correspond to UID-based limits, not IP-based.

The fields name the operation:

p: place.
a: amend.
r: replace.
c: cancel.

Range: 0.0 to 1.0.

Owner information

Every order can carry owner information identifying which strategy instance and process placed it:

{
  "owner": {
    "instanceId": "123e4567-e89b-12d3-a456-426614174000",
    "instanceName": "MyStrategy",
    "processId": "strategy-server-1",
    "configId": "config-v1",
    "configVersion": "1.0.0"
  }
}

Field	Type	Description
instanceId	string	UUID of the strategy instance
instanceName	string	Name of the strategy instance
processId	string	Name of the client process (e.g., strategy server)
configId	string	(Optional) ID of the current configuration
configVersion	string	(Optional) Version of the current configuration

Context

An order can carry an arbitrary JSON context for application-specific purposes:

{
  "context": {
    "signal": "momentum",
    "confidence": 0.85,
    "notes": "Custom data"
  }
}

The context survives the order's lifetime. It is included in order updates and fill messages whenever the includeContext login option is enabled.

Capabilities

The login response carries a capabilities object listing which features the trading adapter and exchange support. Always check capabilities before using an optional feature.

Capability	Type	Description
postOnly	boolean	Supports the post-only order flag
amend	boolean	Supports order modification operations
replace	boolean	Supports replace as a non-atomic cancel-and-place
cancelAll	boolean	Supports canceling all open orders
closeOnly	boolean	Supports close-only order flag
reduceOnly	boolean	Supports reduce-only order flag
displayQuantity	boolean	Supports iceberg and hidden orders
autoBorrow	boolean	Supports automatic borrowing for margin
autoRepay	boolean	Supports automatic loan repayment
cashBalance	boolean	Provides current cash balance for each wallet entry
walletUnrealizedPnl	boolean	Provides unrealized PnL for each wallet entry
availableBorrow	boolean	Provides amount available to borrow for each wallet entry
positionUnrealizedPnl	boolean	Provides unrealized PnL for each position entry
averageEntryPrice	boolean	Provides weighted average entry price for positions
rateLimitLoad	boolean	Provides rate limit load information
retryTime	boolean	Populates `retryTimeNs` on `OrderError` for rate-limit errors
liquidationPrice	boolean	Provides estimated liquidation price for positions
sparePlaceRequests	boolean	Provides spare place request pool in internal rate limiter
orderTypes	array	List of supported order types (see Order Type)
timeInForces	array	List of supported time-in-force values (see Time-In-Force)
walletTypes	array	List of supported wallet types (see Wallet Type)
maintenanceMargin	array	Maintenance margin support per wallet type
marginTypes	array	Margin type per wallet type

Note

Always inspect the capabilities returned by the login response before using an optional feature. Exchanges differ in what they support.