TESTNET
Connect

Schemas and codecs

Every frame on the SBE WebSocket is one message of the trading schema: an 8-byte header, a fixed block, then any repeating groups and variable-length fields. Generate your codec from the schema of the environment you connect to, and let it handle offsets and null values.

The schema

The schema ID is 7. Each environment publishes its own XML and accepts exactly one version of it. Schema version links the published files and a download script that checks the XML against the manifest.

Version rules:

  • Send the XML's version in every message header. Any other version is answered with a CommandReject with code BAD_REQUEST and is not processed.
  • The server encodes its messages with the same version, so decode with the same codec.
  • A new version can change any message. Regenerate your codec whenever the environment's manifest names a new schema file, before that version goes live on your environment.
  • A field's sinceVersion records when it was added. It does not let you send an older layout.

Generate codecs

Real Logic's Simple Binary Encoding tool generates codecs from the XML. Download the sbe-all jar of a recent release from Maven Central (uk.co.real-logic:sbe-all) and run it with Java 17 or later. Pin the release you use so that regenerated code stays stable.

java --add-opens java.base/jdk.internal.misc=ALL-UNNAMED 
  -Dsbe.output.dir=generated/java 
  -jar sbe-all-<release>.jar tradews.xml

Java is the default target. The codecs land in the tradews package and use the Agrona library for their buffers.

Message layout

+----------------------+--------------------+----------------------+--------------------------+
| messageHeader 8 B    | fixed block        | repeating groups     | variable-length fields   |
| blockLength          | blockLength bytes  | 4 B size header +    | 4 B length + bytes,      |
| templateId           |                    | entries, in schema   | in schema order          |
| schemaId = 7         |                    | order                |                          |
| version              |                    |                      |                          |
+----------------------+--------------------+----------------------+--------------------------+

The rules every message follows:

  • Byte order: every integer is little-endian.
  • Header: four uint16 values, blockLength, templateId, schemaId, and version. The templateId selects the message; see the template index.
  • Fixed block: fields sit at fixed offsets with no padding. blockLength must equal the block length of that message in your environment's schema. A different value is rejected.
  • Groups: a 4-byte header of uint16 entry block length and uint16 entry count, then the entries. Each entry is its own fixed block followed by its own variable-length fields.
  • Variable-length fields: a uint32 length, then that many bytes. An empty value is a length of 0. Note the 4-byte length: many SBE examples use a 2-byte length.
  • Order: write and read the parts in schema order. Generated codecs enforce this.
  • Trailing bytes: a frame must end exactly at its last field. Extra bytes are rejected.

When you decode server messages, read blockLength from the header and skip to the end of the fixed block by that value, as generated codecs do.

Field encodings

Null values

Optional fields carry a null value when they are not set. The schema uses two conventions:

  • Optional int64 · null -9223372036854775808 (INT64_MIN)
    For example baseQtyScaled, priceTicks, expireAtTsNs.
  • Optional int32 · null -2147483648 (INT32_MIN)
    For example marketMaxSlippageBps.
  • Optional uint64 · null 18446744073709551615 (UINT64_MAX)
    For example rateLimitRemaining.
  • IDs and enums of a ZeroNull type · null 0
    For example orderId, symbolId in a cancel, side, stpMode, RejectCode.

Optional IDs and enums use 0 as their null value. For example, a cancel by client order ID sets orderId to 0, and a symbolId of 0 lets the service resolve the Pair from the order.

A required enum whose type is zero-null, such as side, rejects 0. A required enum with a uint8 encoding, such as orderType, has no value 0 either.

Prices, quantities, and timestamps

Field pattern Encoding
*PriceTicks, priceTicks Price in quote units scaled by 109, for every Pair
marketMaxSlippageTicks Price delta in the same 10-9 quote-unit ticks
*QtyScaled, baseQtyScaled Base quantity scaled by the Pair's base_quantity_scale
maxQuoteDebitScaled Quote amount scaled by the Pair's quote_quantity_scale
*Bps Basis points: 1 is 0.01%
*TsNs Nanoseconds since the Unix epoch, UTC
*Ns durations Nanoseconds

Read each Pair's symbol_id, base_quantity_scale, quote_quantity_scale, tick size, and step size from GET /v1/spot/config (ConnectRPC GetSpotConfig). Price ticks never use the quote Asset's quantity scale. See Scaled integers for conversion rules and common mistakes.

Identifiers

orderId fields carry the public order ID as an unsigned 64-bit integer, the same value ConnectRPC carries as fixed64. REST shows the same ID as a base58 string. See ConnectRPC identifiers and Public IDs. symbolId is the Pair's numeric symbol_id.

clientOrderId and newClientOrderId are ASCII: 1 to 36 letters, digits, ., _, :, /, or -. See Client order IDs. The detail text of a CommandReject is UTF-8.

Enums and bitsets

Enums are one or two bytes; their values are listed in the Message reference. The two bitsets are uint32: in EventChannels, bit 0 is executions, bit 1 orders, and bit 2 marketResync; in OrderFlags, bit 0 is postOnly. Every other bit must be 0.

Boolean fields such as dryRun and cancelledOrdersTruncated are uint8 values 0 or 1.

Worked examples

The examples are real encodings, checked against codecs generated from the schema. vv vv stands for your environment's schema version as a little-endian uint16. Offsets count from the start of the frame.

A Ping with seq 1, correlationId 100, and payload hello is 33 bytes:

  0  10 00                      blockLength = 16
  2  01 00                      templateId = 1 (Ping)
  4  07 00                      schemaId = 7
  6  vv vv                      version
  8  01 00 00 00 00 00 00 00    seq = 1
 16  64 00 00 00 00 00 00 00    correlationId = 100
 24  05 00 00 00                payload length = 5
 28  68 65 6c 6c 6f             payload = "hello"

The server answers with a Pong of the same shape, template ID 22, echoing seq, correlationId, and payload.

Test your codec

  • Encode a Ping and compare it byte for byte with the example above.
  • Send the Ping on Testnet and check that Pong echoes all three values.
  • Send a command with a deliberately wrong version and check that you decode the CommandReject, including its detail text.
  • Decode every server template, even ones you do not act on, so that an unexpected message never stalls your reader.
Previous

Connection and authentication
Next

Order entry