gRPC Client (Yellowstone)

Install

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

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

Building the client

Here’s a client with every option set:

import (
    "time"

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

client, err := geyser.NewBuilder().
    URL("http://ny.rpc.orbitflare.com:10000").
    FallbackURL("http://fra.rpc.orbitflare.com:10000").
    Retry(orbitflare.RetryPolicy{
        InitialDelay: 100 * time.Millisecond,
        MaxDelay:     30 * time.Second,
        Multiplier:   2.0,
        MaxAttempts:  0,
    }).
    Timeout(30 * time.Second).
    Keepalive(60 * time.Second).
    PingInterval(10 * time.Second).
    MaxMissedPongs(3).
    ChannelCapacity(4096).
    Build()

Minimal setup:

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

gRPC needs no API key. The URL falls back to the ORBITFLARE_GRPC_URL environment variable.

Builder methods

.URL(url) - The primary gRPC endpoint. Falls back to ORBITFLARE_GRPC_URL. Use http:// for plaintext HTTP/2 and https:// for TLS.

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

.URLs(urls...) - Primary + fallbacks in one call. First element is primary.

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

.FallbackURL(url) / .FallbackURLs(urls...) - Add fallback endpoints. On connection failure, the SDK rotates through them.

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

.Retry(policy) - Controls reconnection backoff. When a connection drops, the SDK waits InitialDelay, then multiplies it each attempt (capped at MaxDelay). Set MaxAttempts to 0 for infinite retries. Default: 100ms initial, 30s max, 2x multiplier, infinite.

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

.Timeout(duration) - Connection/dial timeout. Default: 30s.

.Timeout(15 * time.Second)

.Keepalive(duration) - TCP/HTTP2 keepalive interval, used to detect dead connections at the transport level. Default: 60s.

.Keepalive(30 * time.Second)

.PingInterval(duration) - How often the SDK sends proto-level Ping messages to the server. The server should respond with a Pong. Default: 10s.

.PingInterval(15 * time.Second)

.MaxMissedPongs(n) - How many consecutive pings can go unanswered before the SDK considers the connection dead and reconnects. Default: 3. With the defaults, a dead connection is detected within 30 seconds.

.MaxMissedPongs(5)

.ChannelCapacity(n) - The bounded channel between the background goroutine and your code. If your code is slow to consume events, the background goroutine blocks when this fills up instead of eating unlimited memory. Default: 4096.

.ChannelCapacity(8192)

.Logger(logger) - A *slog.Logger for connection lifecycle events. When unset, logging is controlled by ORBITFLARE_LOG.

Building a subscription

Filters are built programmatically with SubscribeRequestBuilder and the typed filter types. A transaction matches if it involves any AccountInclude address; AccountExclude removes matches; AccountRequired means every listed address must be present.

request := geyser.NewSubscribeRequestBuilder().
    Transactions("pumpfun", geyser.NewTransactionFilter().
        Vote(false).
        Failed(false).
        AccountInclude("6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P")).
    Accounts("usdc-holders", geyser.NewAccountFilter().
        Owner("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA").
        Datasize(165).
        Memcmp(geyser.MemcmpBase58(0, "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v")).
        Lamports(geyser.LamportsGt(0))).
    Slots("slots", geyser.NewSlotFilter().FilterByCommitment(true)).
    Commitment(geyser.Confirmed).
    Build()

Filter types

NewTransactionFilter() - Vote(bool), Failed(bool), Signature(string), AccountInclude(...), AccountExclude(...), AccountRequired(...).
NewAccountFilter() - Account(...), Owner(...), Datasize(uint64), TokenAccountState(bool), Memcmp(...), Lamports(...), NonemptyTxnSignature(bool).
NewSlotFilter() - FilterByCommitment(bool), InterslotUpdates(bool).
NewBlockFilter() - AccountInclude(...), IncludeTransactions(bool), IncludeAccounts(bool), IncludeEntries(bool).
NewDeshredTransactionFilter() - Vote(bool), AccountInclude(...), AccountExclude(...), AccountRequired(...).

Memcmp is built with geyser.MemcmpBytes(offset, []byte), geyser.MemcmpBase58(offset, string), or geyser.MemcmpBase64(offset, string). Lamports with geyser.LamportsEq/Ne/Lt/Gt(uint64). Commitment is one of geyser.Processed, geyser.Confirmed, geyser.Finalized. Subscribe also accepts a raw *geyser.SubscribeRequest (a re-export of the proto type) if you’d rather build it by hand.

Reading the stream

Subscribe returns a *geyser.Stream. Call Next(ctx) to get the next update:

stream := client.Subscribe(request)
defer stream.Close()

for {
    update, err := stream.Next(ctx)
    if errors.Is(err, io.EOF) {
        break // stream closed
    }
    if err != nil {
        break // fatal: all retries exhausted
    }

    switch {
    case update.GetTransaction() != nil:
        tx := update.GetTransaction()
        // tx.GetSlot(), tx.GetTransaction() (signature, accounts, instructions, meta)
    case update.GetAccount() != nil:
        acct := update.GetAccount()
        // acct.GetSlot(), acct.GetAccount() (pubkey, lamports, owner, data), acct.GetIsStartup()
    case update.GetSlot() != nil:
        slot := update.GetSlot()
        // slot.GetSlot(), slot.GetStatus()
    case update.GetBlockMeta() != nil:
        meta := update.GetBlockMeta()
        // meta.GetSlot(), meta.GetBlockhash(), meta.GetParentSlot()
    }
}

Next(ctx) blocks until an event arrives. It returns io.EOF once the stream has ended (including after Close); any other non-nil error is fatal for that stream. It also returns ctx.Err() if the context is cancelled. Pong messages are consumed internally and never appear in your stream.

Closing

stream.Close()

Stops the background goroutine immediately. client.Close() stops every stream the client started.

Multiple streams

One client can run many streams at once. Each gets its own background connection:

pumpfun := client.Subscribe(pumpfunReq)
raydium := client.Subscribe(raydiumReq)
slots := client.Subscribe(slotsReq)

They share endpoint health state - if one stream quarantines a failing endpoint, the others skip it on their next reconnect. But their connections and lifecycles are fully independent. You can spin up new streams at any time.

Full example

A stream that watches pump.fun transactions and prints a summary for each one.

package main

import (
    "context"
    "errors"
    "fmt"
    "io"
    "log"

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

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

    request := geyser.NewSubscribeRequestBuilder().
        Transactions("pumpfun", geyser.NewTransactionFilter().
            Vote(false).
            Failed(false).
            AccountInclude("6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P")).
        Slots("slots", geyser.NewSlotFilter().FilterByCommitment(true)).
        Commitment(geyser.Confirmed).
        Build()

    stream := client.Subscribe(request)
    defer stream.Close()

    ctx := context.Background()
    var count int
    fmt.Println("streaming...")

    for {
        update, err := stream.Next(ctx)
        if errors.Is(err, io.EOF) {
            return
        }
        if err != nil {
            log.Fatal(err)
        }

        switch {
        case update.GetTransaction() != nil:
            count++
            tx := update.GetTransaction()
            fmt.Printf("#%d slot=%d\n", count, tx.GetSlot())
        case update.GetSlot() != nil:
            s := update.GetSlot()
            fmt.Printf("slot %d (%s)\n", s.GetSlot(), s.GetStatus())
        }
    }
}

Get Started

Agents

Products

Solutions

Fetching Data

RPC

Data Streaming

Trading APIs

gRPC Client (Yellowstone)

Install

Building the client

Builder methods

Building a subscription

Filter types

Reading the stream

Closing

Multiple streams

Full example

​Install

​Building the client

​Builder methods

​Building a subscription

​Filter types

​Reading the stream

​Closing

​Multiple streams

​Full example

Install

Building the client

Builder methods

Building a subscription

Filter types

Reading the stream

Closing

Multiple streams

Full example