> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitflare.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rust SDK

> Build production agents and indexers in Rust with type-safe clients for RPC, WebSocket, Yellowstone gRPC, and Jetstream, with retry, failover, and reconnection built in.

When you're past the prototype stage and shipping a production daemon, indexer, trading bot, or long-running agent worker, reach for the Rust SDK. Instead of managing raw HTTP requests, gRPC channels, and WebSocket connections yourself, the SDK handles connection lifecycle, authentication, retries, failover, and reconnection behind a clean API.

<Tip>
  For interactive agent workflows in Claude Code or Cursor, prefer the [MCP server](/agents/mcp). For shell scripts and CI, prefer the [CLI](/agents/cli). The SDK is for code your agents *write*: production services that run independently.
</Tip>

## Install

```bash theme={null}
cargo add orbitflare-sdk                          # RPC only
cargo add orbitflare-sdk --features ws            # + WebSocket
cargo add orbitflare-sdk --features grpc          # + Yellowstone gRPC
cargo add orbitflare-sdk --features jetstream     # + Jetstream
```

Combine features as needed, e.g. `--features "ws grpc"` for an indexer that subscribes to both surfaces.

## What's included

| Service                | What it does                                                                                                    |
| ---------------------- | --------------------------------------------------------------------------------------------------------------- |
| **RPC**                | JSON-RPC client with typed helpers for common Solana methods, plus raw escape hatches                           |
| **WebSocket**          | Subscriptions for accounts, logs, slots, signatures with auto-resubscribe on reconnect                          |
| **gRPC (Yellowstone)** | Yellowstone Geyser streaming for transactions, accounts, slots, and blocks. YAML config or programmatic filters |
| **JetStream**          | OrbitFlare's decoded shreds delivered as gRPC streams. Same client pattern as Yellowstone, different proto      |

## Environment variables

The SDK reads endpoints from the environment if you don't pass them explicitly. This is the recommended pattern for agent-generated code: the agent never has to hard-code URLs or keys, and the same binary works across regions and networks.

| Variable                   | Used by        | Purpose                                    |
| -------------------------- | -------------- | ------------------------------------------ |
| `ORBITFLARE_LICENSE_KEY`   | RPC, WebSocket | API key appended to endpoint URLs          |
| `ORBITFLARE_RPC_URL`       | RPC            | Default endpoint if `.url()` is not called |
| `ORBITFLARE_WS_URL`        | WebSocket      | Default endpoint if `.url()` is not called |
| `ORBITFLARE_GRPC_URL`      | gRPC           | Default endpoint if `.url()` is not called |
| `ORBITFLARE_JETSTREAM_URL` | JetStream      | Default endpoint if `.url()` is not called |

## Quick example

A minimal RPC agent that reads its endpoint from the environment and queries balance with retry/failover handled automatically:

```rust theme={null}
use orbitflare_sdk::{RpcClientBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = RpcClientBuilder::new().build()?;     // reads ORBITFLARE_RPC_URL + LICENSE_KEY
    let lamports = client.get_balance("Gh9ZwEm...").await?;
    println!("{} SOL", lamports as f64 / 1e9);
    Ok(())
}
```

With explicit failover regions:

```rust theme={null}
let client = RpcClientBuilder::new()
    .urls(&[
        "http://ny.rpc.orbitflare.com",
        "http://fra.rpc.orbitflare.com",
        "http://ams.rpc.orbitflare.com",
    ])
    .build()?;
```

The first URL is primary; the rest are fallbacks tried in order on failure.

## Streaming with Yellowstone gRPC

```rust theme={null}
use orbitflare_sdk::{GeyserClientBuilder, Result};

#[tokio::main]
async fn main() -> Result<()> {
    let client = GeyserClientBuilder::new()
        .url("http://fra.rpc.orbitflare.com:10000")
        .build()
        .await?;

    let mut stream = client.subscribe_yaml("stream.yml")?;
    while let Some(update) = stream.next().await {
        // process update
    }
    Ok(())
}
```

`subscribe_yaml` reads filters from a YAML config; for programmatic filters use `client.subscribe(SubscribeRequest { .. })` instead. The Jetstream client mirrors this pattern. Swap `GeyserClientBuilder` for `JetstreamClientBuilder`.

## Why use the SDK over raw HTTP

For agent-written production code, the SDK handles the cross-cutting concerns that are easy to get wrong:

* **Retries with exponential backoff**, configurable per client
* **Multi-region failover**: primary fails, fallbacks tried in order
* **Auth injection**: license key added to every request, never stored in the endpoint
* **WebSocket reconnect**: subscriptions auto-resubscribe after disconnect
* **gRPC channel management**: keepalive, reconnect, backoff
* **Typed responses**: common methods deserialize into Rust structs, with raw escape hatches available for everything else

When you ask an agent to write an OrbitFlare integration, point it at the SDK and the resulting code stays small, idiomatic, and resilient.

## Source

* SDK repo: [github.com/orbitflare/orbitflare-sdk-rs](https://github.com/orbitflare/orbitflare-sdk-rs)
* Full reference: [SDK overview](/sdk/overview), [RPC](/sdk/rust-rpc), [WebSocket](/sdk/rust-websocket), [gRPC](/sdk/rust-grpc), [Jetstream](/sdk/rust-jetstream)