birdeye

package module
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 5 Imported by: 0

README

Birdeye Go SDK

Birdeye Golang SDK

CI Tests Go Version License CodeQL Codecov GitHub Release GoDoc

An idiomatic, context-first Go client for the Birdeye public API. It currently focuses on the price and OHLCV workflows that most trading dashboards, portfolio tools, and market monitors need first.

The SDK handles authentication, JSON envelopes, request metadata, typed API errors, and conservative retries. It also includes a raw request API, so a new Birdeye endpoint never has to block your work.

Maintained by Igor Sazonov · sovletig@gmail.com. This is an independent community project, not an official Birdeye SDK.

Contents

Requirements and installation

This module requires Go 1.22+.

go get github.com/tigusigalpa/birdeye-go

Create an API key in Birdeye, then store it outside the repository. On macOS/Linux:

export BIRDEYE_API_KEY="your-key"

On PowerShell:

$env:BIRDEYE_API_KEY = "your-key"

Use .env.example as a reminder of the variable name. Do not commit a populated .env file.

Configure the client

NewClient is inexpensive and does not perform network I/O. The API key is sent as X-API-KEY for every request. Most Birdeye DeFi endpoints also use x-chain; set a default once and override it only where needed.

client := birdeye.NewClient(
    os.Getenv("BIRDEYE_API_KEY"),
    birdeye.WithChain(birdeye.ChainSolana),
    birdeye.WithTimeout(10*time.Second),
    birdeye.WithRetries(2),
)

Available options:

Option Purpose
WithChain(chain) Default x-chain, such as birdeye.ChainSolana or birdeye.ChainEthereum.
WithTimeout(duration) Timeout for the default HTTP client.
WithHTTPClient(client) Bring your own *http.Client, for proxies, tracing, or custom transports.
WithBaseURL(url) Point at a local mock server or another compatible Birdeye host.
WithRetries(attempts) Set the maximum number of attempts while keeping the default backoff policy.
WithRetryPolicy(policy) Fully control retry timing and the OnRetry hook.
WithLogger(logger) Receive structured request lifecycle logs. Never log secrets in your logger.

Every request options struct has a Chain field. It wins over the client's default:

quote, err := client.Price.GetPrice(ctx, token, price.Options{
    Chain: birdeye.ChainEthereum,
})

The SDK does not validate plan access or supported chains locally. Birdeye's response is authoritative, which means your application receives a normal typed error when an endpoint is not available on its subscription.

Quick start

Fetch the current USD price of wrapped SOL:

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    birdeye "github.com/tigusigalpa/birdeye-go"
    "github.com/tigusigalpa/birdeye-go/price"
)

func main() {
    client := birdeye.NewClient(
        os.Getenv("BIRDEYE_API_KEY"),
        birdeye.WithChain(birdeye.ChainSolana),
    )

    quote, err := client.Price.GetPrice(
        context.Background(),
        "So11111111111111111111111111111111111111112",
        price.Options{},
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("$%.4f (24h: %.2f%%)\n", quote.Value, quote.PriceChange24h)
}

Common recipes

The snippets in this section are intended to live in a helper that returns an error; replace return err with the error-handling approach used by your application when placing them directly in main.

Ask for liquidity with a price

Optional booleans and numeric filters use pointers so that false and 0 can be sent deliberately.

includeLiquidity := true
minimumLiquidity := 25_000.0

quote, err := client.Price.GetPrice(ctx, token, price.Options{
    IncludeLiquidity: &includeLiquidity,
    CheckLiquidity:   &minimumLiquidity,
})
if err != nil { return err }

fmt.Println("price:", quote.Value, "liquidity:", quote.Liquidity)
Load a watchlist in one request

Use the GET variant for a short list. A returned nil map value means that Birdeye has no price data for that address; it is not an SDK error.

prices, err := client.Price.GetMultiPrice(ctx, []string{
    "So11111111111111111111111111111111111111112", // SOL
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC
}, price.Options{})
if err != nil { return err }

for address, quote := range prices {
    if quote == nil {
        fmt.Printf("%s: no price data\n", address)
        continue
    }
    fmt.Printf("%s: $%.6f\n", address, quote.Value)
}

For longer lists, call GetMultiPricePOST; it puts the same comma-separated addresses in a JSON request body and is never automatically retried.

Draw a 24-hour candle chart

V3 OHLCV supports fine intervals, count mode, padding, and outlier control. Use Unix seconds for TimeFrom and TimeTo.

now := time.Now()
page, err := client.Price.GetOHLCVv3(ctx, price.TokenOHLCVOptions{
    Address:  token,
    Type:     price.Interval1H,
    TimeFrom: now.Add(-24 * time.Hour).Unix(),
    TimeTo:   now.Unix(),
    Currency: price.CurrencyUSD,
})
if err != nil { return err }

for _, candle := range page.Items {
    fmt.Printf("%s close=$%.4f volume=%.2f\n",
        time.Unix(candle.UnixTime, 0).UTC().Format(time.RFC3339),
        candle.C,
        candle.V,
    )
}

For one pool rather than a token-wide aggregation, use GetOHLCVv3Pair with price.PairOHLCVOptions. For an aggregated base/quote market, use GetOHLCVBaseQuote.

Get an exact historical checkpoint
point, err := client.Price.GetHistoricalPriceByUnixTime(ctx, token, price.HistoricalPriceOptions{
    UnixTime: time.Date(2025, time.January, 1, 0, 0, 0, 0, time.UTC).Unix(),
})
if err != nil { return err }

fmt.Printf("historical value: $%.6f\n", point.Value)

To request a time series instead, use GetHistoricalPriceSeries. Birdeye does not publish a stable response-field schema for that endpoint, so it returns price.RawObject: a map of field name to json.RawMessage. This preserves all data without making invented type guarantees.

series, err := client.Price.GetHistoricalPriceSeries(ctx, price.HistoricalSeriesOptions{
    Address: token, AddressType: "token", Type: price.Interval1H,
    TimeFrom: from.Unix(), TimeTo: to.Unix(),
})
if err != nil { return err }

var items []map[string]any
if err := json.Unmarshal(series["items"], &items); err != nil { return err }
Add rolling volume to a token card
snapshot, err := client.Price.GetPriceVolume(ctx, token, price.VolumeOptions{
    Type: "24h",
})
if err != nil { return err }

// The field schema is deliberately preserved rather than guessed.
for field, raw := range snapshot {
    fmt.Printf("%s: %s\n", field, raw)
}

GetMultiPriceVolume is the batch POST equivalent. Like all POST requests in this SDK, it is sent once to avoid repeating an unsafe operation.

Supported API surface

Area Methods Response
Spot prices GetPrice, GetMultiPrice, GetMultiPricePOST Typed Data
Historical prices GetHistoricalPriceByUnixTime, GetHistoricalPriceSeries Typed point / RawObject series
Candles GetOHLCVv3, GetOHLCVv3Pair, GetOHLCVBaseQuote Typed V3 candles / RawObject
Rolling activity GetPriceVolume, GetMultiPriceVolume RawObject

See docs/endpoints.md for every route, HTTP method, SDK method, and official Birdeye documentation link.

The upstream-deprecated /defi/ohlcv and /defi/ohlcv/pair routes are intentionally unsupported. Wallets, transactions, holders, token lists, Perps, blockchain data, x402, and WebSockets are not yet mapped as typed services, but can be called through the raw API below.

Errors and retries

Use errors.Is for the action your application should take. Use errors.As when you need diagnostic details for logging or support.

_, err := client.Price.GetPrice(ctx, token, price.Options{})
switch {
case err == nil:
    // success
case errors.Is(err, transport.ErrUnauthorized):
    return fmt.Errorf("check BIRDEYE_API_KEY: %w", err)
case errors.Is(err, transport.ErrForbidden):
    return fmt.Errorf("endpoint is unavailable for this Birdeye plan: %w", err)
case errors.Is(err, transport.ErrRateLimited):
    return fmt.Errorf("slow down and retry later: %w", err)
default:
    var apiErr *transport.BirdeyeError
    if errors.As(err, &apiErr) {
        log.Printf("Birdeye request %s failed: status=%d code=%s message=%q",
            apiErr.RequestID, apiErr.HTTPStatus, apiErr.Code, apiErr.Message)
    }
    return err
}

The default retry policy makes up to three attempts for GET requests after HTTP 429 or a transient transport failure. Backoff is bounded, jittered, and respects Retry-After. The SDK never retries POST, PUT, PATCH, or DELETE requests on its own. Disable retries with birdeye.NoRetry():

client := birdeye.NewClient(apiKey, birdeye.WithRetryPolicy(birdeye.NoRetry()))

Use an endpoint before it is typed

Client.Do is the low-level escape hatch. It still adds the API key and chain header, serializes query parameters, decodes Birdeye's data envelope, and returns the same typed errors.

var data map[string]any
_, err := client.Do(
    ctx,
    http.MethodGet,
    "/defi/token_overview",
    map[string]string{"address": token},
    "", // use the client default chain
    nil,
    &data,
)

Some endpoint families require an extra header. DoWithHeaders supports this without allowing the configured API key to be replaced:

_, err := client.DoWithHeaders(
    ctx,
    http.MethodGet,
    "/perps/v1/token/list",
    nil,
    "",
    http.Header{"x-perp": {"true"}},
    nil,
    &data,
)

Examples, testing, and security

All examples are executable and read BIRDEYE_API_KEY from the environment:

go run ./examples/get_price
go run ./examples/get_ohlcv
go run ./examples/multi_price
go run ./examples/error_handling
go run ./examples/token_search
go run ./examples/wallet_pnl # also requires BIRDEYE_WALLET

Tests use local httptest servers and hand-written responses—no test spends Birdeye Compute Units:

go test ./...
go test -race ./... # requires CGO
go vet ./...
gofmt -l .

Every push to main and every pull request runs the same formatting check, go vet, race-enabled test suite, coverage collection, and package/example build in GitHub Actions.

Codecov measures the SDK packages (., ./price, and ./transport) and enforces an 80% minimum for both project and patch coverage. Executable examples are built in CI but excluded from coverage because they intentionally do not contain unit tests or make live API calls.

Never commit a real BIRDEYE_API_KEY. Keep production keys in your deployment platform's secret store, rotate them if exposed, and avoid printing full upstream response bodies in application logs.

License

MIT. See LICENSE.

Documentation

Overview

Package birdeye is an idiomatic Go client for the Birdeye crypto market data API (https://public-api.birdeye.so), written from scratch against Birdeye's official documentation — not generated code.

Docs: https://docs.birdeye.so/reference/birdeye-api-getting-started

Index

Constants

View Source 
const (
	ChainSolana    = "solana"
	ChainEthereum  = "ethereum"
	ChainArbitrum  = "arbitrum"
	ChainAvalanche = "avalanche"
	ChainBSC       = "bsc"
	ChainOptimism  = "optimism"
	ChainPolygon   = "polygon"
	ChainBase      = "base"
	ChainZkSync    = "zksync"
	ChainMonad     = "monad"
	ChainHyperEVM  = "hyperevm"
	ChainAptos     = "aptos"
	ChainFogo      = "fogo"
	ChainMantle    = "mantle"
	ChainMegaETH   = "megaeth"
	ChainRobinhood = "robinhood"
	ChainSui       = "sui"
)

Chain values accepted by the x-chain header. This list is not exhaustive and not enforced client-side — different endpoint families support different chain subsets (confirmed via documentation research across only a handful of endpoints), so passing an unlisted chain string is never blocked locally; let Birdeye's API be the source of truth and return an error for an unsupported chain.

Docs: https://docs.birdeye.so/reference/birdeye-api-authentication

View Source 
const DefaultBaseURL = "https://public-api.birdeye.so"

DefaultBaseURL is Birdeye's production REST host.

Variables

View Source 
var (
	// NewDefaultRetryPolicy creates the SDK's conservative default retry policy.
	NewDefaultRetryPolicy = transport.NewDefaultRetryPolicy
	// NoRetry creates a retry policy that makes one attempt only.
	NoRetry = transport.NoRetry
)

Functions

This section is empty.

Types

type Client 

type Client struct {

	// Price groups every implemented price/OHLCV endpoint.
	//
	// Docs: https://docs.birdeye.so/reference/price-ohlcv
	Price *price.Client
	// contains filtered or unexported fields
}

Client is the SDK entry point. Construct with NewClient.

func NewClient 

func NewClient(apiKey string, opts ...Option) *Client

NewClient builds a fully wired Client. apiKey is required — Birdeye rejects every endpoint without an X-API-KEY header. Performs no network I/O.

Docs: https://docs.birdeye.so/reference/birdeye-api-authentication

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method, path string, query map[string]string, chain string, body interface{}, result interface{}) (*transport.ResponseMeta, error)

Do is the raw request escape hatch: call any Birdeye endpoint — including ones this SDK hasn't mapped to a typed method yet — without waiting for an SDK update. method/path/query/body follow the same conventions as every typed service method; chain overrides the client's default x-chain header for this call only ("" to use the default). result is decoded from the response envelope's "data" field (nil to discard it).

func (*Client) DoWithHeaders 

func (c *Client) DoWithHeaders(ctx context.Context, method, path string, query map[string]string, chain string, headers http.Header, body interface{}, result interface{}) (*transport.ResponseMeta, error)

DoWithHeaders is the raw escape hatch for endpoints that require an endpoint-specific header, such as x-perp. X-API-KEY is always taken from the client configuration and cannot be overridden here.

type ClientConfig 

type ClientConfig struct {
	APIKey string

	BaseURL      string
	DefaultChain string

	HTTPClient *http.Client
	Timeout    time.Duration

	Clock  Clock
	Logger Logger

	RetryPolicy *RetryPolicy
}

ClientConfig holds every configurable knob of a Client. Zero value is unusable — an APIKey is always required; NewClient fills in defaults for every other unset field.

type Clock 

type Clock = transport.Clock

Clock supplies the current time to client components that need it.

type Logger 

type Logger = transport.Logger

Logger receives structured client lifecycle messages.

type Option 

type Option func(*ClientConfig)

Option configures a ClientConfig at construction time.

func WithBaseURL 

func WithBaseURL(url string) Option

WithBaseURL overrides the REST host. Defaults to DefaultBaseURL.

func WithChain 

func WithChain(chain string) Option

WithChain sets the default x-chain header sent on every request that doesn't override it per-call via a method's Options.Chain field. Leaving this unset is valid — Birdeye defaults to "solana" server-side when the header is omitted entirely.

func WithClock 

func WithClock(clock Clock) Option

WithClock injects a clock used by retry timing. It is mainly useful for deterministic tests.

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient uses hc to make API requests. Its timeout and transport are preserved, so WithTimeout has no effect when this option is used.

func WithLogger 

func WithLogger(logger Logger) Option

WithLogger sets the structured logger used by the client. The default logger discards all messages.

func WithRetries 

func WithRetries(maxAttempts int) Option

WithRetries changes only the maximum number of attempts while retaining the default backoff bounds. Values below one disable retries. GET requests alone are eligible; unsafe methods are never retried automatically.

func WithRetryPolicy 

func WithRetryPolicy(policy *RetryPolicy) Option

WithRetryPolicy overrides the default conservative retry policy (GET requests only; see transport.RetryPolicy). Pass NoRetry() to disable automatic retries entirely.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the timeout of the SDK-created HTTP client. Use WithHTTPClient to configure a custom client directly.

type RetryPolicy 

type RetryPolicy = transport.RetryPolicy

RetryPolicy configures automatic retry behaviour for eligible requests.

Source Files

View all Source files

Directories

Path Synopsis
examples
error_handling command
Example: handle a Birdeye API error gracefully using the typed error hierarchy (sentinel errors + *transport.BirdeyeError for detail).
 Example: handle a Birdeye API error gracefully using the typed error hierarchy (sentinel errors + *transport.BirdeyeError for detail).
get_ohlcv command
Example: fetch v3 OHLCV candles for a token.
 Example: fetch v3 OHLCV candles for a token.
get_price command
Example: fetch a single token's real-time price.
 Example: fetch a single token's real-time price.
multi_price command
Example: fetch prices for multiple tokens in one call.
 Example: fetch prices for multiple tokens in one call.
token_search command
token_search calls the current search endpoint through the raw API.
 token_search calls the current search endpoint through the raw API.
wallet_pnl command
wallet_pnl demonstrates the raw request escape hatch for an endpoint that has not yet received a typed service.
 wallet_pnl demonstrates the raw request escape hatch for an endpoint that has not yet received a typed service.
Package price implements Birdeye's price and OHLCV endpoints: single and multi-token real-time price, v3 OHLCV candles (token and pair), and historical price lookup by Unix timestamp.
 Package price implements Birdeye's price and OHLCV endpoints: single and multi-token real-time price, v3 OHLCV candles (token and pair), and historical price lookup by Unix timestamp.
Package transport implements the shared HTTP request executor, response metadata capture, and error hierarchy used by every Birdeye service.
 Package transport implements the shared HTTP request executor, response metadata capture, and error hierarchy used by every Birdeye service.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.