ClOrdID#

Most exchanges support a custom ClOrdID when creating or referencing an order. This is typically a free-form text field with limitations on length and what characters are allowed. For example, maximum length of 20 and characters compatible with base 64 encoding.

The ClOrdID field is used by Roq to encode enough information relevant for the gateway to route updates back to the origin.

Identifiers#

The following information identifies the origin of an order request:

  • user_id (8 bits) is the identifier for the client application sending the request to the gateway.

  • order_id (48 bits) is a session specific sequential number used by the client application to maintain order state.

  • version (24 bits) is the request version which has relevance to the FIX protocol where it is allowed to chain requests.

  • strategy_id (24 bits) is a pass-through field allowing a client application to manage many strategies or route orders on behalf of clients.

Ranges#

user_id

Maximum 254 distinctly named client applications.

Note

user_id 0 and 255 are reserved.

order_id

The gateway will seed the per-user max_order_id using current time and a reference date (2023-08-06) at startup (accuracy is 10 microseconds). Any downloaded orders with a higher order_id will override the seed. Clients must choose only strictly increasing order_id’s for new orders.

Important

It is important that the gateway seeds with current time. This is done to achieve uniqueness across gateway restarts.

Note

There is an implicit assumption that orders are created with an average frequency of less than 10 microseconds between restarts. Even so, we pack more information such as user_id and strategy_id also to further increase entropy.

Important

The default seed will consume ~8e9 order_id per day allowing ~10 years of operation before wrap-around.

A solution to wrap-around must be found before the year 2033. If not, all working orders must be canceled prior to wrap-around.

version

It is possible to rewrite an order ~16e6 times.

strategy_id

It is possible to manage ~16e6 distinct strategies or route ~16e6 distinct client identifiers.

Encoding (binary)#

The binary length is 15 bytes.

Offset

Length

Type

Content

0

1

byte

Checksum (*)

1

1

byte

Type (*)

2

1

byte

user_id

3

6

48 bit unsigned integer

order_id

9

3

24 bit unsigned integer

version

12

3

24 bit unsigned integer

strategy_id

Note

Integers are encoded little endian.

Note

Checksum is XOR of 0x47 (initial value) and each byte from offset 1 to 14.

Note

Type is a bitmask

  • bit 0 (0x01) allows for a shorter binary version (placeholder)

  • bit 1 (0x02) (internal)

  • bit 2 (0x04) (not used)

  • bit 3 (0x08) (not used)

  • bit 4-7 (0xF0) gateway instance (4 bit unsigned integer, experimental)

Encoding (binary-to-text)#

  • Base64 (length 20) is typically used.

    Note

    Exchange requirments my dictate the use of the web-safe character set (+ instead of / and - instead of _).

  • Base32 (length 24) is used when only alphanumeric characters are allowed.

The protocol is specific to the gateway and published as roq::GatewaySettings.