Client Order Identifiers

Extending the Kraken APIs with cl_ord_id parameter, enabling clients to tag orders with their own text or UUID identifiers.

Overview of client identifiers

What is cl_ord_id?

The cl_ord_id terminology is borrowed from Financial Information eXchange (FIX) protocol, it is simply a parameter used as a "client order identifier" for tracking and managing transactions.

Why is cl_ord_id important?

It's essential for clients to communicate about specific orders without confusion and the cl_ord_id provides a unique identifier for each open order. The client assigns a cl_ord_id on order placement and Kraken uses this identifier to provide status updates back to the client.

Kraken verifies cl_ord_id uniqueness across open orders for each client. FIX protocol extends this uniqueness check to across open orders and FIX session.

The cl_ord_id is particularly important when it comes to managing flow. If a client wants to cancel or amend an order, they can provide the cl_ord_id of that order in the request.

cl_ord_id versus other identifiers

Kraken has a range of order identifiers with different characteristics, the client can choose the combination of identifiers to best fit their requirements.

Characteristic	cl_ord_id	Kraken Id	Userref
Format	string	string	number
Encoding	UUID, free text	Kraken proprietary	+/- integer
Example	d15708c1-dbb6-465d-b77d-47258319cc90	OCNNCT-MEB2I-2XGM7L	123948576
Enforced Uniqueness	Open orders (+ FIX session) per client	Open and closed orders for all clients	None
Assigned By	Client	Kraken	Client
Good For	Managing daily flow with client preferred id format	Record keeping (unique across all orders over time) and managing flow.	Tagging groups of orders with single reference.

Note, the cl_ord_id and userref are mutually exclusive, they both cannot be used on the same order.

Format and performance details

cl_ord_id support 3 different formats, depending on the length of the string.

• Long UUID: 6d1b345e-2821-40e2-ad83-4ecb18a06876 32 hex characters separated with 4 dashes.
• Short UUID: da8e4ad59b78481c93e589746b0cf91f 32 hex characters with no dashes.
• Free text: meme-20240509-00010 Free format ascii text up to 18 characters.

Under the covers, the strings are stored as a 128-bit integer for efficiency and performance. A 128-bit integer is much more space efficient than a 36-character string.

Operations and indexing on integers is more efficient than strings, this means checking uniqueness and queries for orders can be much faster.

Example: simple order management using a Universally Unique Identifier (UUID)

New Order: Client creates a new passive order with UUID as cl_ord_id

{
    "method": "add_order",
    "params": {
        "order_type": "limit",
        "side": "buy",
        "limit_price": 60299.9,
        "order_qty": 1.0,
        "symbol": "BTC/USD",
        "cl_ord_id": "0835958d-c526-4ad8-aea8-af54836de47e"
    }
}

Cancel Order: Client cancels the orders using cl_ord_id (a list of identifiers is supported)

{
    "method": "cancel_order",
    "params": {
        "cl_ord_id": [
            "0835958d-c526-4ad8-aea8-af54836de47e"
        ]
    }
}

FIX detailed guidelines

In the FIX protocol, the Tags ClOrdID and OrigClOrdID (Tags 11 and 41) will be mapped to the new ClOrdID format as described above. This change means that these order parameters will no longer be limited to INT32. Instead, FIX ClOrdID will now support UUIDs.

The adoption of UUIDs, specifically timestamp-first version 4 UUIDs, significantly improves the efficiency and uniqueness of order identifiers. Unlike traditional INT32 identifiers, UUIDs offer a virtually limitless address space, greatly reducing the risk of identifier collisions and enhancing the robustness of the trading system.

Key Details of Timestamp-First v4 UUIDs

• Structure: Timestamp-first v4 UUIDs start with a timestamp, ensuring that each generated UUID is unique and sequential based on the time of creation.
• Uniqueness: These UUIDs combine the uniqueness of version 4 UUIDs with the time-based ordering, making them ideal for high-frequency trading environments.
• Compatibility: They are fully compatible with existing systems that support UUIDs, ensuring a smooth transition and integration.

Implementation Guidelines

To improve the efficiency of the FIX API, client will require to send a ClOrdID of either:

• Ever-Increasing Positive Numbers: Clients can use ever-increasing positive numbers, such as nanosecond timestamps, to ensure the uniqueness and sequential nature of the identifiers.
  • Example: Using the current microsecond timestamp as the ClOrdID, such as 1623448294234000 (the field is max 18 characters)
• Timestamp-First v4 UUIDs: Alternatively, clients can adopt timestamp-first v4 UUIDs, which provide a robust and scalable solution for order identification.
  • Example: A timestamp-first v4 UUID might look like 1b4e28ba-2fa1-11d2-883f-0016d3cca427, where the initial part (1b4e28ba-2fa1) of the UUID represents the timestamp.

FIX Migration Process

The migration of existing clients to the new ClOrdID model will be communicated and coordinated through their Account Managers. This will include detailed instructions and support to ensure a seamless transition to the new system.

By embracing these changes, we aim to enhance the overall efficiency, security, and reliability of the FIX protocol, ultimately providing a better trading experience for all users. For further details or assistance, please reach out to your Account Manager.