websocket

package
v3.2.0 Latest Latest
Warning

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

 Go to latest Published: Jul 4, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// BaseURL is CoinGecko's websocket endpoint.
	BaseURL = "wss://stream.coingecko.com/v1"
)

Variables

View Source 
var (
	// ErrMissingAPIKey is returned when the websocket client is missing a Pro API key.
	ErrMissingAPIKey = errors.New("coingecko websocket api key is required")
	// ErrInvalidAuthMode is returned when the websocket client is configured with an unsupported auth mode.
	ErrInvalidAuthMode = errors.New("invalid websocket auth mode")
)
View Source 
var (
	// ErrMissingTargets is returned when a channel action is sent without any target ids.
	ErrMissingTargets = errors.New("at least one subscription target is required")
	// ErrInvalidOHLCVInterval is returned when the requested OHLCV interval is unsupported by CoinGecko.
	ErrInvalidOHLCVInterval = errors.New("invalid ohlcv interval")
	// ErrInvalidOHLCVToken is returned when the requested OHLCV token side is unsupported by CoinGecko.
	ErrInvalidOHLCVToken = errors.New("invalid ohlcv token side")
)

Functions

func FormatSubscriptionTarget 

func FormatSubscriptionTarget(networkID, address string) string

FormatSubscriptionTarget returns the network-scoped identifier CoinGecko expects for on-chain subscriptions.

Types

type AuthMode 

type AuthMode string

AuthMode controls how the CoinGecko Pro API key is sent during the websocket handshake. 

const (
	// AuthModeQuery appends the Pro API key as the x_cg_pro_api_key query parameter.
	AuthModeQuery AuthMode = "query"
	// AuthModeHeader sends the Pro API key in the x-cg-pro-api-key header.
	AuthModeHeader AuthMode = "header"
)

type CGSimplePriceUpdate 

type CGSimplePriceUpdate struct {
	ChannelType              string
	CoinID                   string
	VSCurrency               string
	MarketCapUSD             *Number
	Price                    *Number
	Price24hChangePercentage *Number
	LastUpdatedAt            *Number
	Volume24h                *Number
}

CGSimplePriceUpdate represents a CGSimplePrice update payload.

func (*CGSimplePriceUpdate) UnmarshalJSON 

func (u *CGSimplePriceUpdate) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Channel 

type Channel string

Channel identifies a CoinGecko websocket channel. 

const (
	// ChannelCGSimplePrice streams CoinGecko simple price updates.
	ChannelCGSimplePrice Channel = "CGSimplePrice"
	// ChannelOnchainSimpleTokenPrice streams GeckoTerminal token price updates.
	ChannelOnchainSimpleTokenPrice Channel = "OnchainSimpleTokenPrice"
	// ChannelOnchainTrade streams GeckoTerminal trade updates.
	ChannelOnchainTrade Channel = "OnchainTrade"
	// ChannelOnchainOHLCV streams GeckoTerminal OHLCV updates.
	ChannelOnchainOHLCV Channel = "OnchainOHLCV"
)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client manages websocket connection setup for CoinGecko's streaming API.

func NewClient 

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

NewClient creates a websocket client for CoinGecko's streaming API.

func (*Client) Connect 

func (c *Client) Connect(ctx context.Context) (*Conn, error)

Connect establishes a websocket connection to CoinGecko's streaming API.

type Conn 

type Conn struct {
	// contains filtered or unexported fields
}

Conn wraps an active CoinGecko websocket connection.

func (*Conn) Close 

func (c *Conn) Close() error

Close closes the websocket connection with a normal closure status.

func (*Conn) CloseWithStatus 

func (c *Conn) CloseWithStatus(code coderws.StatusCode, reason string) error

CloseWithStatus closes the websocket connection with a caller-provided status and reason.

func (*Conn) Raw 

func (c *Conn) Raw() *coderws.Conn

Raw returns the underlying websocket connection.

func (*Conn) Read 

func (c *Conn) Read(ctx context.Context) (Message, error)

Read reads and decodes the next websocket JSON message into one of the typed message variants.

func (*Conn) ReadRaw 

func (c *Conn) ReadRaw(ctx context.Context) ([]byte, error)

ReadRaw reads the next websocket message as raw JSON bytes.

func (*Conn) SetCGSimplePrice 

func (c *Conn) SetCGSimplePrice(ctx context.Context, coinIDs []string, vsCurrencies ...string) error

SetCGSimplePrice configures the CGSimplePrice channel for the provided coin ids and quote currencies.

func (*Conn) SetOnchainOHLCV 

func (c *Conn) SetOnchainOHLCV(ctx context.Context, targets []string, interval OHLCVInterval, token OHLCVToken) error

SetOnchainOHLCV configures the OnchainOHLCV channel for the provided pool targets.

func (*Conn) SetOnchainSimpleTokenPrice 

func (c *Conn) SetOnchainSimpleTokenPrice(ctx context.Context, targets []string) error

SetOnchainSimpleTokenPrice configures the OnchainSimpleTokenPrice channel for the provided token targets.

func (*Conn) SetOnchainTrade 

func (c *Conn) SetOnchainTrade(ctx context.Context, targets []string) error

SetOnchainTrade configures the OnchainTrade channel for the provided pool targets.

func (*Conn) Subscribe 

func (c *Conn) Subscribe(ctx context.Context, channel Channel) error

Subscribe subscribes the connection to a websocket channel.

func (*Conn) UnsetCGSimplePrice 

func (c *Conn) UnsetCGSimplePrice(ctx context.Context, coinIDs []string, vsCurrencies ...string) error

UnsetCGSimplePrice removes specific CGSimplePrice subscriptions for the provided coin ids and quote currencies.

func (*Conn) UnsetOnchainOHLCV 

func (c *Conn) UnsetOnchainOHLCV(ctx context.Context, targets []string, interval OHLCVInterval, token OHLCVToken) error

UnsetOnchainOHLCV removes specific OnchainOHLCV subscriptions for the provided pool targets.

func (*Conn) UnsetOnchainSimpleTokenPrice 

func (c *Conn) UnsetOnchainSimpleTokenPrice(ctx context.Context, targets []string) error

UnsetOnchainSimpleTokenPrice removes specific OnchainSimpleTokenPrice subscriptions for the provided token targets.

func (*Conn) UnsetOnchainTrade 

func (c *Conn) UnsetOnchainTrade(ctx context.Context, targets []string) error

UnsetOnchainTrade removes specific OnchainTrade subscriptions for the provided pool targets.

func (*Conn) Unsubscribe 

func (c *Conn) Unsubscribe(ctx context.Context, channel Channel) error

Unsubscribe unsubscribes the connection from a websocket channel.

type EventMessage 

type EventMessage struct {
	Type       string `json:"type"`
	Identifier string `json:"identifier,omitempty"`
}

EventMessage represents websocket lifecycle events such as welcome or confirm_subscription.

type Message 

type Message interface {
	// contains filtered or unexported methods
}

Message is a typed websocket payload returned by Read or ParseMessage.

func ParseMessage 

func ParseMessage(data []byte) (Message, error)

ParseMessage decodes a raw websocket payload into a typed message.

type Number 

type Number float64

Number decodes CoinGecko websocket numbers that may be emitted as JSON numbers or quoted strings.

func (Number) Float64 

func (n Number) Float64() float64

Float64 returns the underlying float64 value.

func (*Number) UnmarshalJSON 

func (n *Number) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type OHLCVInterval 

type OHLCVInterval string

OHLCVInterval identifies a supported OHLCV candle interval. 

const (
	OHLCVInterval1s  OHLCVInterval = "1s"
	OHLCVInterval1m  OHLCVInterval = "1m"
	OHLCVInterval5m  OHLCVInterval = "5m"
	OHLCVInterval15m OHLCVInterval = "15m"
	OHLCVInterval1h  OHLCVInterval = "1h"
	OHLCVInterval2h  OHLCVInterval = "2h"
	OHLCVInterval4h  OHLCVInterval = "4h"
	OHLCVInterval8h  OHLCVInterval = "8h"
	OHLCVInterval12h OHLCVInterval = "12h"
	OHLCVInterval1d  OHLCVInterval = "1d"
)

type OHLCVToken 

type OHLCVToken string

OHLCVToken identifies whether OHLCV updates are streamed for the base or quote token of a pool. 

const (
	OHLCVTokenBase  OHLCVToken = "base"
	OHLCVTokenQuote OHLCVToken = "quote"
)

type OnchainOHLCVUpdate 

type OnchainOHLCVUpdate struct {
	ChannelType string
	NetworkID   string
	PoolAddress string
	Token       OHLCVToken
	Interval    OHLCVInterval
	Open        *Number
	High        *Number
	Low         *Number
	Close       *Number
	Volume      *Number
	Timestamp   *Number
}

OnchainOHLCVUpdate represents an OnchainOHLCV update payload.

func (*OnchainOHLCVUpdate) UnmarshalJSON 

func (u *OnchainOHLCVUpdate) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type OnchainSimpleTokenPriceUpdate 

type OnchainSimpleTokenPriceUpdate struct {
	ChannelType              string
	NetworkID                string
	TokenAddress             string
	PriceUSD                 *Number
	Price24hChangePercentage *Number
	MarketCapUSD             *Number
	Volume24h                *Number
	LastUpdatedAt            *Number
}

OnchainSimpleTokenPriceUpdate represents an OnchainSimpleTokenPrice update payload.

func (*OnchainSimpleTokenPriceUpdate) UnmarshalJSON 

func (u *OnchainSimpleTokenPriceUpdate) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type OnchainTradeUpdate 

type OnchainTradeUpdate struct {
	ChannelType           string
	NetworkID             string
	PoolAddress           string
	TransactionHash       string
	TradeType             string
	TokenAmount           *Number
	QuoteTokenAmount      *Number
	VolumeUSD             *Number
	PriceInNativeCurrency *Number
	PriceUSD              *Number
	LastUpdatedAt         *Number
}

OnchainTradeUpdate represents an OnchainTrade update payload.

func (*OnchainTradeUpdate) UnmarshalJSON 

func (u *OnchainTradeUpdate) UnmarshalJSON(data []byte) error

UnmarshalJSON implements json.Unmarshaler.

type Option 

type Option func(*Client)

Option configures a websocket client.

func WithAuthMode 

func WithAuthMode(mode AuthMode) Option

WithAuthMode configures whether authentication is sent as a query parameter or request header.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient configures the HTTP client used during the websocket handshake.

func WithHeader 

func WithHeader(header http.Header) Option

WithHeader merges additional headers into the websocket handshake request.

func WithURL 

func WithURL(rawURL string) Option

WithURL configures a custom websocket endpoint.

type StatusMessage 

type StatusMessage struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

StatusMessage represents a command acknowledgement or server-side error payload.

type UnknownMessage 

type UnknownMessage struct {
	Raw json.RawMessage
}

UnknownMessage captures payloads the client does not recognize yet.

Source Files

View all Source files

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.