RPC 客户端

安装

go get github.com/orbitflare/orbitflare-sdk-go

import "github.com/orbitflare/orbitflare-sdk-go/rpc"

构建客户端

下面是设置了所有选项的客户端：

import (
    "time"

    "github.com/orbitflare/orbitflare-sdk-go/orbitflare"
    "github.com/orbitflare/orbitflare-sdk-go/rpc"
)

client, err := rpc.NewBuilder().
    URL("http://ny.rpc.orbitflare.com").
    FallbackURL("http://fra.rpc.orbitflare.com").
    FallbackURL("http://ams.rpc.orbitflare.com").
    APIKey("ORBIT-XXXXXX-NNNNNN-NNNNNN").
    Commitment("confirmed").
    Retry(orbitflare.RetryPolicy{
        InitialDelay: 100 * time.Millisecond,
        MaxDelay:     30 * time.Second,
        Multiplier:   2.0,
        MaxAttempts:  5,
    }).
    Timeout(30 * time.Second).
    Build()

大多数选项都有合理的默认值。最小化设置：

client, err := rpc.NewBuilder().
    URL("http://ny.rpc.orbitflare.com").
    Build()

每个方法都接收一个 context.Context，因此可传入带截止时间的 context 来限定单次调用：

ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()

构建器方法

.URL(url) - 发送请求的主端点。若未设置，SDK 会读取 ORBITFLARE_RPC_URL 环境变量。

.URL("http://ny.rpc.orbitflare.com")

.URLs(urls...) - 一次性设置主端点及全部回退端点。第一个为主端点，其余为回退端点。

.URLs("http://ny.rpc.orbitflare.com", "http://fra.rpc.orbitflare.com", "http://ams.rpc.orbitflare.com")

.FallbackURL(url) - 添加单个回退端点。可多次调用以添加多个。当主端点失败时，SDK 会按顺序尝试回退端点。

.FallbackURL("http://fra.rpc.orbitflare.com").
FallbackURL("http://ams.rpc.orbitflare.com")

.FallbackURLs(urls...) - 与 FallbackURL 相同，但可一次传入多个。

.FallbackURLs("http://fra.rpc.orbitflare.com", "http://ams.rpc.orbitflare.com")

.APIKey(key) - 你的 OrbitFlare 许可证密钥。若未设置，SDK 会读取环境变量 ORBITFLARE_LICENSE_KEY。密钥在请求时注入 URL，绝不存储于端点，也绝不出现在日志或错误信息中。

.APIKey("ORBIT-XXXXXX-NNNNNN-NNNNNN")

.Commitment(level) - 所有类型化辅助方法使用的默认承诺级别。可选："processed"、"confirmed"、"finalized"。默认 "confirmed"。

.Commitment("finalized")

.Retry(policy) - 控制 SDK 如何重试失败的请求。InitialDelay 是首次重试前的等待时间。Multiplier 在每次尝试时缩放延迟。MaxDelay 为退避上限。MaxAttempts 限制总重试次数（0 表示无限）。默认：100ms 初始、30s 上限、2 倍系数、无限次。

.Retry(orbitflare.RetryPolicy{
    InitialDelay: 200 * time.Millisecond,
    MaxDelay:     15 * time.Second,
    Multiplier:   2.0,
    MaxAttempts:  5,
})

.Timeout(duration) - 每次请求的 HTTP 超时。默认 30 秒。

.Timeout(10 * time.Second)

.Logger(slog.New(slog.NewTextHandler(os.Stderr, nil)))

可用 RPC 方法

类型化辅助方法返回 Go 值；其余方法返回可自行反序列化为你自己类型的 json.RawMessage。

`GetSlot(ctx)`

返回当前槽位号。

slot, err := client.GetSlot(ctx) // uint64

`GetBalance(ctx, address)`

返回账户余额（以 lamports 计）。

lamports, err := client.GetBalance(ctx, "So11111111111111111111111111111111111111112") // uint64
sol := float64(lamports) / 1_000_000_000

`GetAccountInfo(ctx, address)`

返回完整账户数据（json.RawMessage），账户不存在时为 nil。数据为 base64 编码。

raw, err := client.GetAccountInfo(ctx, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")
if raw != nil {
    var info struct {
        Owner    string `json:"owner"`
        Lamports uint64 `json:"lamports"`
    }
    json.Unmarshal(raw, &info)
}

`GetMultipleAccounts(ctx, addresses)`

一次调用获取多个账户。自动按每批 100 个分块（Solana 的单请求上限），因此可传入任意数量的地址。

accounts, err := client.GetMultipleAccounts(ctx, []string{"addr1", "addr2", "addr3"}) // []json.RawMessage

`GetLatestBlockhash(ctx)`

返回最新的 blockhash 及其有效的最后区块高度。

blockhash, lastValid, err := client.GetLatestBlockhash(ctx) // (string, uint64)

`GetTransaction(ctx, signature)`

按签名获取已确认交易。返回带元数据的完整交易（json.RawMessage）。

raw, err := client.GetTransaction(ctx, "5K8F2j...")

`GetSignaturesForAddress(ctx, address, limit)`

返回某地址最近的交易签名，最新的在前。

sigs, err := client.GetSignaturesForAddress(ctx, "So111...", 10) // []json.RawMessage

`GetProgramAccounts(ctx, programID)`

返回某程序拥有的全部账户。数据量可能很大。

accounts, err := client.GetProgramAccounts(ctx, "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA")

`GetRecentPrioritizationFees(ctx, addresses)`

返回一组账户的近期优先费。可用于估算计算单元定价。

fees, err := client.GetRecentPrioritizationFees(ctx, []string{"6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P"})

`SendTransaction(ctx, txBase64)`

向网络发送已签名交易。接收 base64 编码的序列化交易。返回交易签名。

signature, err := client.SendTransaction(ctx, txBase64) // string

`SimulateTransaction(ctx, txBase64)`

在不提交的情况下模拟交易。返回日志、消耗的计算单元以及任何错误（json.RawMessage）。

raw, err := client.SimulateTransaction(ctx, txBase64)

`GetTokenAccountsByOwner(ctx, owner, mint, programID)`

返回钱包的代币账户。传入特定 mint 或代币程序 ID。若两者均为空字符串，则默认使用 SPL Token 程序。

tokens, err := client.GetTokenAccountsByOwner(ctx, "wallet_address", "", "")

`GetTransactionsForAddress(ctx, address, options)`

OrbitFlare 专属方法，将 getSignaturesForAddress 与 getTransaction 合并为一次调用。返回带 Data 切片及可选 PaginationToken（用于翻页）的 GetTransactionsResult。支持四种详情级别（signatures、none、accounts、full）、双向排序、时间/槽位过滤、状态过滤以及代币账户包含。options 可为 nil 以使用默认值。

details, order, status := "full", "asc", "succeeded"
var limit uint32 = 100
gte, lte := int64(1704067200), int64(1706745600)

result, err := client.GetTransactionsForAddress(ctx, "address", &rpc.GetTransactionsOptions{
    TransactionDetails: &details,
    Limit:              &limit,
    SortOrder:          &order,
    Filters: &rpc.GetTransactionsFilters{
        Status:    &status,
        BlockTime: &rpc.RangeFilter[int64]{Gte: &gte, Lte: &lte},
    },
})

for _, tx := range result.Data {
    _ = tx // json.RawMessage
}
if result.PaginationToken != nil {
    // 在下次调用时设置 PaginationToken 以获取下一页
}

`Request(ctx, method, params)`

按名称调用任意 RPC 方法。SDK 构建 JSON-RPC 信封、处理重试与故障转移，并返回 result 字段（json.RawMessage）。

epoch, err := client.Request(ctx, "getEpochInfo", []any{})
inflation, err := client.Request(ctx, "getInflationRate", []any{})

`RequestRaw(ctx, body)`

发送原始 JSON-RPC 主体字符串。与其他方法一样具备重试与故障转移。

result, err := client.RequestRaw(ctx, `{"jsonrpc":"2.0","id":1,"method":"getHealth","params":[]}`)

完整示例

一个检查网络状态、获取钱包 SOL 余额并查询近期交易的程序。

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "time"

    "github.com/orbitflare/orbitflare-sdk-go/rpc"
)

func main() {
    client, err := rpc.NewBuilder().
        URL("http://ny.rpc.orbitflare.com").
        FallbackURL("http://fra.rpc.orbitflare.com").
        Commitment("confirmed").
        Build()
    if err != nil {
        log.Fatal(err)
    }

    ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
    defer cancel()

    wallet := "CKs1E69a2e9TmH4mKKLrXFF8kD3ZnwKjoEuXa6sz9WqX"

    slot, _ := client.GetSlot(ctx)
    blockhash, _, _ := client.GetLatestBlockhash(ctx)
    fmt.Printf("network slot: %d\nblockhash: %s\n", slot, blockhash)

    balance, _ := client.GetBalance(ctx, wallet)
    fmt.Printf("\n%s\n  SOL: %.4f\n", wallet, float64(balance)/1_000_000_000)

    sigs, _ := client.GetSignaturesForAddress(ctx, wallet, 5)
    fmt.Println("\nrecent transactions:")
    for _, raw := range sigs {
        var sig struct {
            Signature string `json:"signature"`
            Slot      uint64 `json:"slot"`
            Err       any    `json:"err"`
        }
        json.Unmarshal(raw, &sig)
        status := "ok"
        if sig.Err != nil {
            status = "failed"
        }
        fmt.Printf("  %d %s %s\n", sig.Slot, status, sig.Signature[:20])
    }
}

开始使用

产品

解决方案

数据获取

RPC

数据流

交易 API

安装

构建客户端

构建器方法

可用 RPC 方法

`GetSlot(ctx)`

`GetBalance(ctx, address)`

`GetAccountInfo(ctx, address)`

`GetMultipleAccounts(ctx, addresses)`

`GetLatestBlockhash(ctx)`

`GetTransaction(ctx, signature)`

`GetSignaturesForAddress(ctx, address, limit)`

`GetProgramAccounts(ctx, programID)`

`GetRecentPrioritizationFees(ctx, addresses)`

`SendTransaction(ctx, txBase64)`

`SimulateTransaction(ctx, txBase64)`

`GetTokenAccountsByOwner(ctx, owner, mint, programID)`

`GetTransactionsForAddress(ctx, address, options)`

`Request(ctx, method, params)`

`RequestRaw(ctx, body)`

完整示例

​安装

​构建客户端

​构建器方法

​可用 RPC 方法

​GetSlot(ctx)

​GetBalance(ctx, address)

​GetAccountInfo(ctx, address)

​GetMultipleAccounts(ctx, addresses)

​GetLatestBlockhash(ctx)

​GetTransaction(ctx, signature)

​GetSignaturesForAddress(ctx, address, limit)

​GetProgramAccounts(ctx, programID)

​GetRecentPrioritizationFees(ctx, addresses)

​SendTransaction(ctx, txBase64)

​SimulateTransaction(ctx, txBase64)

​GetTokenAccountsByOwner(ctx, owner, mint, programID)

​GetTransactionsForAddress(ctx, address, options)

​Request(ctx, method, params)

​RequestRaw(ctx, body)

​完整示例

安装

构建客户端

构建器方法

可用 RPC 方法

`GetSlot(ctx)`

`GetBalance(ctx, address)`

`GetAccountInfo(ctx, address)`

`GetMultipleAccounts(ctx, addresses)`

`GetLatestBlockhash(ctx)`

`GetTransaction(ctx, signature)`

`GetSignaturesForAddress(ctx, address, limit)`

`GetProgramAccounts(ctx, programID)`

`GetRecentPrioritizationFees(ctx, addresses)`

`SendTransaction(ctx, txBase64)`

`SimulateTransaction(ctx, txBase64)`

`GetTokenAccountsByOwner(ctx, owner, mint, programID)`

`GetTransactionsForAddress(ctx, address, options)`

`Request(ctx, method, params)`

`RequestRaw(ctx, body)`

完整示例