> ## 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

> 使用 Rust 构建生产级智能体与索引器：面向 RPC、WebSocket、Yellowstone gRPC 与 Jetstream 的类型安全客户端，内置重试、故障转移与重连。

当你已过原型阶段，要交付生产守护进程、索引器、交易机器人或长期运行的智能体 worker 时，请使用 Rust SDK。无需自行管理原始 HTTP 请求、gRPC 通道与 WebSocket 连接，SDK 在简洁 API 背后处理连接生命周期、认证、重试、故障转移与重连。

<Tip>
  在 Claude Code 或 Cursor 中进行交互式智能体工作流时，优先使用 [MCP 服务器](/cn/agents/mcp)。Shell 脚本与 CI 优先使用 [CLI](/cn/agents/cli)。SDK 适用于智能体**编写**的代码：独立运行的生产服务。
</Tip>

## 安装

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

按需组合特性，例如索引器需两种界面时使用 `--features "ws grpc"`。

## 包含内容

| 服务                    | 作用                                                   |
| --------------------- | ---------------------------------------------------- |
| **RPC**               | 面向常见 Solana 方法的 JSON-RPC 客户端及类型化辅助方法，另含原始出口          |
| **WebSocket**         | 账户、日志、槽位、签名订阅，重连后自动重新订阅                              |
| **gRPC（Yellowstone）** | Yellowstone Geyser 流式传输：交易、账户、槽位与区块。支持 YAML 或编程式过滤器  |
| **JetStream**         | OrbitFlare 解码碎片以 gRPC 流投递。与 Yellowstone 客户端模式相同，协议不同 |

## 环境变量

若未显式传入端点，SDK 从环境读取。这是智能体生成代码的推荐模式：智能体无需硬编码 URL 或密钥，同一二进制可在不同区域与网络运行。

| 变量                         | 使用者           | 用途                  |
| -------------------------- | ------------- | ------------------- |
| `ORBITFLARE_LICENSE_KEY`   | RPC、WebSocket | 附加到端点 URL 的 API 密钥  |
| `ORBITFLARE_RPC_URL`       | RPC           | 未调用 `.url()` 时的默认端点 |
| `ORBITFLARE_WS_URL`        | WebSocket     | 未调用 `.url()` 时的默认端点 |
| `ORBITFLARE_GRPC_URL`      | gRPC          | 未调用 `.url()` 时的默认端点 |
| `ORBITFLARE_JETSTREAM_URL` | JetStream     | 未调用 `.url()` 时的默认端点 |

## 简短示例

从环境读取端点并查询余额的最小 RPC 智能体，重试/故障转移自动处理：

```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(())
}
```

显式多区域故障转移：

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

第一个 URL 为主端点；其余按失败顺序依次尝试。

## 使用 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` 从 YAML 读取过滤器；编程式过滤器请改用 `client.subscribe(SubscribeRequest { .. })`。Jetstream 客户端模式相同。将 `GeyserClientBuilder` 换为 `JetstreamClientBuilder` 即可。

## 为何使用 SDK 而非原始 HTTP

对智能体编写的生产代码，SDK 处理容易出错的横切关注点：

* **指数退避重试**，可按客户端配置
* **多区域故障转移**：主端点失败后按顺序尝试备用
* **认证注入**：许可证密钥加入每个请求，不存储在端点字符串中
* **WebSocket 重连**：断开后订阅自动恢复
* **gRPC 通道管理**：keepalive、重连、退避
* **类型化响应**：常用方法反序列化为 Rust 结构体，其余仍可用原始出口

当你让智能体编写 OrbitFlare 集成时，指向 SDK，生成的代码将更短小、地道且具备韧性。

## 源码

* SDK 仓库：[github.com/orbitflare/orbitflare-sdk-rs](https://github.com/orbitflare/orbitflare-sdk-rs)
* 完整参考：[SDK 概述](/cn/sdk/overview)、[RPC](/cn/sdk/rust-rpc)、[WebSocket](/cn/sdk/rust-websocket)、[gRPC](/cn/sdk/rust-grpc)、[Jetstream](/cn/sdk/rust-jetstream)