SDK Reference

Official SDKs for Titan Direct — TypeScript (high-level client) and Rust (types + codec).

Titan provides official SDKs for TypeScript and Rust. Both connect to Titan Direct over WebSocket using MessagePack encoding with optional compression.

---

TypeScript SDK

A high-level client with built-in connection management, compression negotiation, and full type safety.

• Package: @titanexchange/sdk-ts

• Source: github.com/Titan-Pathfinder/titan-sdk-ts

• Node.js: >=18.19

Installation

npm install @titanexchange/sdk-ts

Connecting

import { V1Client } from '@titanexchange/sdk-ts';

// The SDK automatically negotiates compression (zstd, brotli, gzip, or none)
const url = `wss://${process.env.TITAN_ENDPOINT}/ws?auth=${process.env.TITAN_API_KEY}`;
const client = await V1Client.connect(url);

Connection state:

• client.closed — boolean, true if the connection is closed.

• client.listen_closed() — Returns a Promise that resolves with the close event.

• client.close() — Gracefully closes the connection.

API methods

• client.getInfo() → ServerInfo — Protocol version and server settings.

• client.newSwapQuoteStream(params) → { response, stream, streamId } — Opens a streaming quote.

• client.stopStream(streamId) → StopStreamResponse — Stops a stream by ID.

• client.getVenues(params?) → VenueInfo — Lists available on-chain venues.

• client.listProviders(params?) → ProviderInfo[] — Lists active quote providers.

• client.getSwapPrice(params) → SwapPrice — One-shot price check without streaming.

Streaming quotes

import bs58 from 'bs58';

const { stream, streamId } = await client.newSwapQuoteStream({
  swap: {
    inputMint: bs58.decode('So11111111111111111111111111111111111111112'),
    outputMint: bs58.decode('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v'),
    amount: 1_000_000_000n, // 1 SOL — must be BigInt
    slippageBps: 50,
  },
  transaction: {
    userPublicKey: bs58.decode('YOUR_WALLET_PUBLIC_KEY'),
  },
});

// Async iterator — yields SwapQuotes on each update
for await (const quotes of stream) {
  // Use metadata.ExpectedWinner for the best slippage-adjusted route
  const winner = quotes.metadata?.ExpectedWinner;
  const best = winner && quotes.quotes[winner];

  if (best?.instructions?.length) {
    console.log(`Best: ${winner} — ${best.outAmount} out`);
  }
}

Stopping a stream

// Method 1: via client
await client.stopStream(streamId);

// Method 2: via stream — calls stopStream() internally
await stream.cancel('done');

Types

import { types } from '@titanexchange/sdk-ts';

types.v1.SwapQuoteRequest;
types.v1.SwapParams;
types.v1.TransactionParams;
types.v1.TransactionFormat;

Selecting a transaction format

transactionFormat selects the Solana transaction wire format Titan uses when sizing candidate routes. It is separate from titanSwapVersion, which selects the Titan swap instruction version.

import { types } from '@titanexchange/sdk-ts';

const { stream } = await client.newSwapQuoteStream({
  swap: {
    inputMint,
    outputMint,
    amount: 1_000_000n,
  },
  transaction: {
    userPublicKey,
    titanSwapVersion: types.v1.SwapVersion.V3,
    transactionFormat: types.v1.TransactionFormat.V1,
  },
});

TransactionFormat.V0 (0) is the default. TransactionFormat.V1 (1) enables Transaction V1 route sizing, uses a 4096-byte maximum, does not support ALTs, and requires Titan Swap V3. You may omit titanSwapVersion and let the server resolve V1 requests to V3; explicitly combining Transaction V1 with Swap V2 is rejected.

Transaction V1 requires the Agave 4.2 feature set to be active on the cluster where you submit. Titan does not verify activation; continue using V0 until activation is confirmed.

Error handling

All error classes are exported from the SDK:

• ConnectionClosed — WebSocket connection closed. Properties: code, reason, wasClean.

• ConnectionError — WebSocket error event. Property: cause.

• ErrorResponse — Server rejected a request. Property: response (with code, message, requestId).

• StreamError — Stream ended with an error. Properties: streamId, errorCode, errorMessage.

• ProtocolError — Implementation bug — report to Titan. Properties: reason, data.

Reconnection

The SDK does not include built-in reconnect logic. Handle reconnection manually:

client.listen_closed().then(async (event) => {
  if (!event.wasClean) {
    // Reconnect and re-establish streams
    const newClient = await V1Client.connect(url);
    // Re-open your streams on newClient
  }
});

See Error Handling & Reconnect for backoff strategies.

Browser usage

import { V1Client } from '@titanexchange/sdk-ts/browser';

Do not expose your API key in client-side code. Use a middleware proxy that accepts user connections, validates authentication, and forwards to Titan with the API key server-side. See examples/middleware.ts in the SDK repository.

Key details

• BigInt amounts — Pass amount as BigInt (e.g. 1_000_000_000n). Numbers >= 2^32 may be encoded as float64, which the server rejects.

• quotes is a map — SwapQuotes.quotes is Record<string, SwapRoute>, keyed by provider ID. Not every provider appears in every update.

• num_quotes uses snake_case — In QuoteUpdateParams, the field is num_quotes (not numQuotes).

Logging BigInt values:

JSON.stringify(data, (key, value) => {
  if (typeof value === 'bigint') return value.toString() + 'n';
  if (value instanceof Uint8Array) return `<Uint8Array: ${value.length} bytes>`;
  return value;
}, 2);

---

Rust SDK

Low-level type definitions and MessagePack codec — you manage the WebSocket connection yourself.

• Crates: crates.io/search?q=titan-api-types

• titan-api-types — Type definitions for all WebSocket request and response messages.

• titan-api-codec — MessagePack encoding/decoding with compression support (zstd, brotli, gzip).

Installation

[dependencies]
titan-api-types = "5"
titan-api-codec = "1.2"

There is no high-level client in the Rust SDK. You manage the WebSocket connection using tokio-tungstenite (or any async WebSocket library) and use the codec for serialization.

Connecting

use titan_api_codec::codec::{ws::v1::ClientCodec, Codec};
use titan_api_types::ws::v1;
use tokio_tungstenite::{
    connect_async,
    tungstenite::{
        client::IntoClientRequest,
        http::header::{AUTHORIZATION, SEC_WEBSOCKET_PROTOCOL},
        http::HeaderValue,
    },
};

let mut request = url.into_client_request()?;

// Set protocol negotiation header
let protocols = HeaderValue::from_str(
    &v1::WEBSOCKET_SUBPROTOCOLS.join(", ")
)?;
request.headers_mut().insert(SEC_WEBSOCKET_PROTOCOL, protocols);

// Set auth header
let bearer = HeaderValue::from_str(&format!("Bearer {}", token))?;
request.headers_mut().insert(AUTHORIZATION, bearer);

// Connect and create codec from negotiated protocol
let (stream, response) = connect_async(request).await?;
let protocol_str = response
    .headers()
    .get(SEC_WEBSOCKET_PROTOCOL)
    .and_then(|v| v.to_str().ok())
    .unwrap();
let codec = ClientCodec::from_str(protocol_str)?;

let (sink, stream) = stream.split();

Sending requests

use titan_api_types::ws::v1::*;
use titan_api_codec::codec::Codec;

let encoder = codec.encoder();
let decoder = codec.decoder();

// GetInfo request
let request = ClientRequest {
    id: 0,
    data: RequestData::GetInfo(GetInfoRequest::default()),
};

// Encode to MessagePack and send as binary frame
let bytes = encoder.encode(&request)?;
sink.send(Message::Binary(bytes)).await?;

Streaming quotes

let request = ClientRequest {
    id: 1,
    data: RequestData::NewSwapQuoteStream(SwapQuoteRequest {
        swap: SwapParams {
            input_mint: sol_mint,
            output_mint: usdc_mint,
            amount: 1_000_000_000u64,
            slippage_bps: Some(50),
            ..Default::default()
        },
        transaction: TransactionParams {
            user_public_key: wallet,
            ..Default::default()
        },
        update: None,
    }),
};

Processing responses

while let Some(msg) = stream.next().await {
    let msg = msg?;
    if let Message::Binary(data) = msg {
        let server_msg: ServerMessage = decoder.decode(data.into())?;
        match server_msg {
            ServerMessage::Response(resp) => {
                // Handle RPC response
            }
            ServerMessage::StreamData(data) => {
                if let StreamDataPayload::SwapQuotes(quotes) = data.payload {
                    for (provider, route) in &quotes.quotes {
                        println!("{}: {} out", provider, route.out_amount);
                    }
                }
            }
            ServerMessage::Error(err) => {
                eprintln!("Error {}: {}", err.code, err.message);
            }
            ServerMessage::StreamEnd(end) => {
                println!("Stream {} ended", end.id);
            }
        }
    }
}

Field naming

The Rust SDK uses standard snake_case field names. Serde handles the conversion to camelCase on the wire:

• input_mint → inputMint

• output_mint → outputMint

• slippage_bps → slippageBps

• user_public_key → userPublicKey

• only_direct_routes → onlyDirectRoutes

Reconnection

No built-in reconnect logic. Handle connection drops and re-establish streams manually, same as the TypeScript SDK.

Dependencies

• tokio-tungstenite — Async WebSocket client.

• rmp-serde — MessagePack serialization.

• zstd — Zstandard compression.

• brotli — Brotli compression.

• flate2 — Gzip compression.

• five8 / five8_const — Base58 pubkey encoding.

---

Related pages

• Quickstart — End-to-end integration example

• Stream & Execute a Swap — Full guide with transaction building

• Wire Protocol — Encoding rules and message envelopes

• Error Codes — Error codes and SDK error classes