Wire Protocol

MessagePack encoding conventions, data types, and serialization rules for Titan's API.

This page covers how data is encoded on the wire — the serialization format, encoding conventions, and shared types used across all Titan API messages.

Both Titan Direct and Titan Gateway use MessagePack binary encoding. JSON is not supported.

Data format

The basic data format for serialization of all messages is MessagePack.

• Objects/structs are encoded as maps — this allows additional fields to be added without breaking compatibility with previous versions.

• Field names are camelCase unless otherwise specified.

• Integers are encoded using the smallest MessagePack int type that fits the value.

• Use BigInt for u64 values (amounts, timestamps) — values above 2^53 lose precision as float64, which the server rejects.

Optional data

If a value is optional, its type is Option<T> in Rust and T? or T | null in TypeScript.

Optional fields in objects may be omitted entirely from the serialized map. Otherwise, a missing optional value should be encoded as nil (0xc0) — decoded as None in Rust and null in TypeScript.

Simple enumerations

Simple enumerations (those without associated data) are encoded as strings matching the variant name exactly:

Rust

enum SwapMode {
  ExactIn,
  ExactOut,
}
// Encoded as: "ExactIn" or "ExactOut"

TypeScript

enum SwapMode {
  ExactIn = "ExactIn",
  ExactOut = "ExactOut",
}

Complex enumerations

Complex enumerations (those with associated data) are encoded as single-value maps, mapping the variant name to the associated data.

• Single associated item → the value is that data.

• Multiple associated items → the value is an array.

Rust

struct Request2Data {
  id: u32,
  amount: u64,
}

enum Complex {
  Request1(String),
  Request2(Request2Data),
  Request3(u32, u32),
}

// Valid encodings (shown as JSON for readability):
// { "Request1": "hello" }
// { "Request2": {"id": 1, "amount": 34} }
// { "Request3": [3, 4] }

TypeScript

interface Request2Data {
  id: number;
  amount: number;
}

type Complex =
  | { Request1: string }
  | { Request2: Request2Data }
  | { Request3: [number, number] };

This pattern applies to both client requests (RequestData) and server messages (ServerMessage). To determine the message type, check which key is present in the top-level map.

Binary data

Binary data is encoded using MessagePack bin formats.

Rust

// Variable-sized byte array
Vec<u8>
// Fixed-size byte array (N bytes)
[u8; N]

TypeScript

// Binary data in TypeScript
Uint8Array
// or
ArrayBuffer

TypeScript has no way to specify byte array size — refer to the Rust types for size constraints.

---

Common types

Pubkey

Solana public keys are 32-byte binary data. Encoded using MessagePack bin 8 format — all pubkeys start with c4 20 followed by 32 bytes of key data.

Example — the WSOL public key So11111111111111111111111111111111111111112:

c4 20 069b8857feab8184fb687f634618c035dac439dc1aeb3b5598a0f00000000001

Rust

// Type alias for public keys
type Pubkey = [u8; 32];

TypeScript

// Type alias for public keys to differentiate from other binary data
type Pubkey = Uint8Array; // 32 bytes

AccountMeta

Compact account descriptor used in instructions. Uses single-letter field names to minimize message size.

Rust

struct AccountMeta {
  p: Pubkey, // public key
  s: bool,   // is_signer
  w: bool,   // is_writable
}

TypeScript

interface AccountMeta {
  p: Pubkey;  // public key
  s: boolean; // is_signer
  w: boolean; // is_writable
}

Instruction

A single on-chain instruction. Also uses single-letter field names for compactness.

Rust

struct Instruction {
  p: Pubkey,           // program_id
  a: Vec<AccountMeta>, // accounts
  d: Vec<u8>,          // data
}

TypeScript

interface Instruction {
  p: Pubkey;        // program_id
  a: AccountMeta[]; // accounts
  d: Uint8Array;    // data
}

AccountMeta and Instruction use single-letter field names (p, s, w, a, d) to reduce payload size. These are Titan's wire format, not abbreviations of the standard Solana SDK types.

---

Message envelope types

ClientRequest

Every client request wraps an RPC method call with a monotonically increasing id.

Rust

struct ClientRequest {
  /// Request ID, echoed in the server's response.
  id: u32,
  /// One of the RPC method variants.
  data: RequestData,
}

enum RequestData {
  GetInfo(GetInfoRequest),
  NewSwapQuoteStream(SwapQuoteRequest),
  StopStream(StopStreamRequest),
  GetVenues(GetVenuesRequest),
  ListProviders(ListProvidersRequest),
  GetSwapPrice(SwapPriceRequest),
}

TypeScript

interface ClientRequest {
  // Request ID, echoed in the server's response.
  id: number;
  // One of the RPC method variants.
  data: RequestData;
}

type RequestData =
  | { GetInfo: GetInfoRequest }
  | { NewSwapQuoteStream: SwapQuoteRequest }
  | { StopStream: StopStreamRequest }
  | { GetVenues: GetVenuesRequest }
  | { ListProviders: ListProvidersRequest }
  | { GetSwapPrice: SwapPriceRequest };

ServerMessage

The server sends one of four message types:

Rust

/// A message sent by the server to the client.
enum ServerMessage {
  /// Successful response to a request, may optionally start a stream.
  Response(ResponseSuccess),
  /// An error response to a request.
  Error(ResponseError),
  /// Data for a stream.
  StreamData(StreamData),
  /// Notification that a stream has ended.
  StreamEnd(StreamEnd),
}

/// A successful response.
struct ResponseSuccess {
  /// Identifier of the request that triggered this response.
  requestId: u32,
  /// The response data.
  data: ResponseData,
  /// If this request starts a new stream, contains stream info.
  stream: Option<StreamStart>,
}

/// An error response.
struct ResponseError {
  /// Identifier of the request that triggered this response.
  requestId: u32,
  /// A numeric error code.
  code: u32,
  /// A message describing the error.
  message: String,
}

/// Data packet for a stream.
struct StreamData {
  /// ID of the stream.
  id: u32,
  /// Sequence number of this data packet.
  seq: u32,
  /// Data payload.
  payload: StreamDataPayload,
}

/// Notification that a stream has closed.
struct StreamEnd {
  /// ID of the stream that has ended.
  id: u32,
  /// Error code, if the stream ended abnormally.
  errorCode: Option<u32>,
  /// Error message, if the stream ended abnormally.
  errorMessage: Option<String>,
}

/// Notification that a new stream has been started.
struct StreamStart {
  /// Stream ID — present in all StreamData and StreamEnd for this stream.
  id: u32,
  /// Type of data that will be sent in this stream.
  dataType: StreamDataType,
}

enum StreamDataType {
  SwapQuotes,
  // May be expanded in the future.
}

enum StreamDataPayload {
  SwapQuotes(SwapQuotes),
  // May be expanded in the future.
}

enum ResponseData {
  GetInfo(ServerInfo),
  NewSwapQuoteStream(QuoteSwapStreamResponse),
  StreamStopped(StopStreamResponse),
  GetVenues(VenueInfo),
  ListProviders(Vec<ProviderInfo>),
  GetSwapPrice(SwapPrice),
}

TypeScript

type ServerMessage =
  | { Response: ResponseSuccess }
  | { Error: ResponseError }
  | { StreamData: StreamData }
  | { StreamEnd: StreamEnd };

interface ResponseSuccess {
  // Identifier of the request that triggered this response.
  requestId: number;
  // The response data.
  data: ResponseData;
  // If the request started a new stream, contains stream info.
  stream?: StreamStart;
}

interface ResponseError {
  // Identifier of the request that triggered this response.
  requestId: number;
  // A numeric error code.
  code: number;
  // A message describing the error.
  message: string;
}

interface StreamData {
  // ID of the stream.
  id: number;
  // Sequence number of this data packet.
  seq: number;
  // Data payload.
  payload: StreamDataPayload;
}

interface StreamEnd {
  // ID of the stream that has ended.
  id: number;
  // Error code, if the stream ended abnormally.
  errorCode?: number;
  // Error message, if the stream ended abnormally.
  errorMessage?: string;
}

interface StreamStart {
  // Stream ID.
  id: number;
  // Type of data that will be sent in this stream.
  dataType: StreamDataType;
}

enum StreamDataType {
  SwapQuotes = "SwapQuotes",
}

type StreamDataPayload = { SwapQuotes: SwapQuotes };

type ResponseData =
  | { GetInfo: ServerInfo }
  | { NewSwapQuoteStream: QuoteSwapStreamResponse }
  | { StreamStopped: StopStreamResponse }
  | { GetVenues: VenueInfo }
  | { ListProviders: ProviderInfo[] }
  | { GetSwapPrice: SwapPrice };

---

Compression

Compression wraps the MessagePack payload. The order of operations:

Sending: serialize to MessagePack → compress → send as binary WebSocket frame

Receiving: receive binary frame → decompress → deserialize from MessagePack

The compression scheme is negotiated once at connection time. See Connection & Negotiation for protocol strings and setup.

Gateway differences

Titan Gateway uses the same MessagePack encoding but over HTTP REST:

• Requests — query parameters (pubkeys as Base58 strings, not binary)

• Responses — MessagePack body with Content-Type: application/vnd.msgpack

• Pubkeys in responses are still binary Uint8Array in the MessagePack body

---

Related pages

• Connection & Negotiation — WebSocket setup, authentication, and compression negotiation

• GetInfo — server settings and protocol version

• NewSwapQuoteStream — streaming swap quotes