Module encoder 

Deterministic two-way encoder for Binance Link broker ID prefixing.

The Binance broker ID is automatically prefixed to supported system-generated client order IDs placed through the Binance adapter. Prefixing is transparent to strategies and requires no user configuration. Inbound order events are decoded back to the original ClientOrderId before reaching the trading system.

Binance’s Link and Trade program requires the newClientOrderId parameter to start with x-{BROKER_ID} for order attribution. Binance enforces a 36-character limit on this field with the regex ^[\.A-Z\:/a-z0-9_-]{1,36}$.

Internal Nautilus ClientOrderId values (O-format: 23+ chars, UUID: 32-36 chars) exceed the 36-char limit when combined with the broker prefix. This module provides compact, deterministic, two-way encoding via pure functions.

Wire format

Legacy:    x-TD67BGP9-{signal}{base62_payload}
Short tag: x-TD67BGP9A{base62_payload}

The prefix x-{BROKER_ID}- is 11 chars (for an 8-char broker ID), leaving 25 chars for the encoded component. Spot and Futures use separate broker IDs defined in consts. The supplementary A format omits the separator after the broker ID and occupies 24 characters in total.

Signal chars

The first character after the prefix identifies the original format so the decoder can reconstruct the exact original ClientOrderId string.

Signal	Original format	Payload length	Total
T	O-format with hyphens	13 base62	25
t	O-format without hyphens	13 base62	25
U	UUID with hyphens	22 base62	34
u	UUID without hyphens	22 base62	34
R	Raw passthrough	variable	<= 36
A	O-format with a short tag	13 base62	24

O-format packing (72 bits -> 13 base62 chars)

The O-format ClientOrderId O-YYYYMMDD-HHMMSS-TTT-SSS-CCC is packed into a 72-bit integer:

bits [71:40] (32 bits): seconds since 2020-01-01 epoch
bits [39:30] (10 bits): trader tag (0-1023)
bits [29:20] (10 bits): strategy tag (0-1023)
bits [19:0]  (20 bits): count (0-1048575)

Short-tag O-format packing (77 bits -> 13 base62 chars)

The A format preserves hyphenated factory IDs such as O-20260922-160119-V2-000-8. One tag contains one or two ASCII alphanumeric characters; the other is a canonical numeric tag in [0, 1023], padded to at least three digits. The count is in [0, 4194303] without leading zeros. Timestamps cover [2020-01-01 00:00:00, 2156-02-07 06:28:15] UTC.

bits [76:45] (32 bits): seconds since 2020-01-01 epoch
bit  [44]    (1 bit):  short tag is the strategy tag
bits [43:32] (12 bits): one/two-character base62 tag, with length
bits [31:22] (10 bits): numeric tag
bits [21:0]  (22 bits): count

Exact reconstruction preserves tag spelling and rejects normalized dates. Existing numeric, UUID, and raw encodings take precedence and retain their wire representation. Historical unprefixed fallback outputs contain at least 25 characters, so the 24-character supplementary format cannot be mistaken for any historical encoder output. A custom ID resembling this format is short enough to use the existing R wrapper.

IDs outside the supported compact formats and raw prefix budget are sent unchanged with a warning; Binance’s length and character limits still apply.

UUID packing (128 bits -> 22 base62 chars)

The UUID is parsed from hex into a 128-bit integer and base62-encoded.

Decoding

The decoder recognizes the 24-character x-{BROKER_ID}A format first, then the legacy x-{BROKER_ID}- signal formats. Other strings pass through unchanged, including historical unprefixed IDs. This keeps a longer custom ID starting with x-{BROKER_ID}A distinct from the short-tag format.

Existing-order operations without a venue order ID query both supplementary and historical unprefixed identities. Different matching venue IDs are rejected as ambiguous before modification or cancellation.

Performance

Base62 encoding uses a stack buffer and ten-digit chunks to limit wide integer division. Prefix construction writes directly into the result string. The bench_encode_decode_timing test provides a local timing check. Existing-order compatibility resolution may add two HTTP lookups.

An isolated codec comparison compiled with opt-level=3 measures the following median nanoseconds per operation over 25 interleaved batches of 100,000 calls. Timings are machine-dependent and exclude HTTP requests.

Format	Encode before	Encode after	Decode before	Decode after
O-format with hyphens	102	44	201	124
O-format without hyphens	99	41	192	116
UUID with hyphens	243	60	72	47
UUID without hyphens	240	57	67	43
Raw prefixed ID	34	16	39	21
Short-tag O-format	N/A	174	N/A	117

Short-tag IDs previously used unprefixed passthrough (37 ns encode, 38 ns decode), which performs no compression and is not equivalent to short-tag encoding.

Functions

decode_broker_id

Decodes an encoded string back to the original ClientOrderId value.

encode_broker_id

Encodes a ClientOrderId into a Binance-compatible string with broker ID prefix.