coinglass-go
CategoryThird-party APIs
SubcategoryThird-party APIs
Stars20
Go client for Coinglass API v4 with zero dependencies, WebSocket streams, and typed endpoints for futures, spot, options, ETF, and indicators
About coinglass-go
This large README is shown as a plain-text preview. Read the full README at the source
# CoinGlass Golang SDK
[](https://github.com/tigusigalpa/coinglass-go/actions/workflows/ci.yml)
[](https://github.com/tigusigalpa/coinglass-go/actions/workflows/test.yml)
[](https://github.com/tigusigalpa/coinglass-go/actions/workflows/codeql.yml)
[](https://codecov.io/gh/tigusigalpa/coinglass-go)
[](https://pkg.go.dev/github.com/tigusigalpa/coinglass-go)
[](https://go.dev/)
[](LICENSE)
> A Go client for the Coinglass API v4, with no external dependencies.
`coinglass-go` is a small, typed Go client for
the [Coinglass API v4](https://docs.coinglass.com/reference/getting-started-with-your-api). I built it to scratch
my own itch while working on liquidation dashboards and funding-rate tooling, and it covers the Futures, Spot,
Options, ETF, and Indicator endpoints. It leans entirely on the standard library, so adding it to your project won't
drag in a tree of transitive dependencies.
## Documentation
- [Project Wiki](https://github.com/tigusigalpa/coinglass-go/wiki) — guides, endpoint notes, and usage details.
- [Go package reference](https://pkg.go.dev/github.com/tigusigalpa/coinglass-go) — API reference generated from source comments.
- [Coinglass API documentation](https://docs.coinglass.com/reference/getting-started-with-your-api) — API keys, plans, rate limits, and upstream endpoint specifications.
## Highlights
- Covers all five endpoint groups: Futures, Spot, Options, ETF, and Indicators.
- Includes a WebSocket client for real-time liquidation, trade, and futures ticker streams.
- No third-party dependencies — just the standard library, for both the REST and WebSocket clients.
- Configured with functional options, the way most Go clients do it.
- Every method takes a `context.Context`, and the client is safe to share across goroutines.
- Retries rate-limited (429) requests with exponential backoff, and honors `Retry-After` when the API sends it.
- Returns typed sentinel errors for `401`, `404`, and `429`, and a detailed `APIError` (with the API's own
`code`/`msg`) for anything else.
- Each service ships with its own `httptest`-based tests.
- Lossless typed contracts for audited current-v4 historical series: aggregate OI, OI-weighted funding, aggregate liquidations, and global account ratios.
## Requirements
| Requirement | Version |
|-------------------|---------------------------------------|
| Go | 1.21+ |
| Dependencies | none (standard library only) |
| Coinglass API key | [Get one here](https://coinglass.com) |
## Installation
```bash
go get github.com/tigusigalpa/coinglass-go
```
## Getting started
```go
package main
import (
"context"
"fmt"
"log"
"time"
coinglass "github.com/tigusigalpa/coinglass-go"
)
func main() {
ctx := context.Background()
client := coinglass.NewClient("YOUR_API_KEY",
coinglass.WithTimeout(15*time.Second),
coinglass.WithRetry(3, time.Second), // 3 attempts, 1s initial backoff
)
// BTC open interest history (last 30 days, daily)
oi, err := client.Futures.OpenInterestHistory(ctx, &coinglass.OIHistoryParams{
Symbol: "BTC",
Interval: "1d",
Limit: coinglass.IntPtr(30),
})
if err != nil {
log.Fatal(err)
}
for _, point := range oi {
fmt.Printf("OI: %.2f USD at %d\n", point.OpenInterestUsd, point.Timestamp)
}
}
```
Compile and run it:
```bash
go run main.go
```
## Configuring the client
`NewClient` takes functional options:
```go
client := coinglass.NewClient("YOUR_API_KEY",
coinglass.WithBaseURL("https://open-api-v4.coinglass.com"), // default, shown for clarity
coinglass.WithTimeout(15*time.Second),
coinglass.WithRetry(3, time.Second),
coinglass.WithHTTPClient(&http.Client{}), // custom transport, proxies, TLS, etc.
)
```
| Option | What it does | When to use it |
|-------------------------------------------------------|-----------------------------------------------|-----------------------------------------------------|
| `WithBaseURL(url string)` | Overrides the API base URL. | Mocking the API in tests or using a custom gateway. |
| `WithHTTPClient(client *http.Client)` | Supplies your own HTTP client. | Custom TLS, proxies, tracing, or middleware. |
| `WithTimeout(d time.Duration)` | Sets the per-request timeout. | Default is 30s; lower it for fast UI endpoints. |
| `WithRetry(maxAttempts int, baseDelay time.Duration)` | Retries on HTTP 429 with exponential backoff. | Strongly recommended for production workloads. |
You can also read the API key from the `COINGLASS_API_KEY` environment variable:
```go
client, err := coinglass.NewClientFromEnv(coinglass.WithTimeout(15 * time.Second))
if err != nil {
log.Fatal(err)
}
```
## Rate limits by plan
| Plan | Requests/min |
|--------------|--------------|
| Hobbyist | 30 |
| Startup | 80 |
| Standard | 300 |
| Professional | 1200 |
If you enable retries, the client backs off automatically and doubles the wait on each attempt (or uses the
`Retry-After` header when Coinglass sends one):
```go
client := coinglass.NewClient("YOUR_API_KEY",
coinglass.WithRetry(3, time.Second), // 1s, then 2s, then 4s
)
```
## Full API reference
### Futures — `client.Futures`
#### Audited history contracts
The following additive methods use the current-v4 routes and retain exact
provider decimal lexemes plus the raw data payload and response envelope in a
`HistoryResponse`. `time` is represented as `EpochMilliseconds`; it is never
read from the legacy `t` field. Unknown fields remain available through each
point's `Raw` field. `HistoryResponse` also records each in-memory raw receipt
with SDK capture time and identifies the CoinGlass documentation URL/section
used by the contract; this provenance is not a provider dataset version.
| Method | Endpoint | Notes |
|---|---|---|
| `AggregatedOpenInterestHistory(ctx, params)` | `GET /api/futures/open-interest/aggregated-history` | `unit` is optional (`usd` by default; `coin` is supported). |
| `OIWeightedFundingHistory(ctx, params)` | `GET /api/futures/funding-rate/oi-weight-history` | The request deliberately excludes `limit`, `start_time`, and `end_time` until CoinGlass clarifies its conflicting time-unit documentation. |
| `FundingRateExchangeListV4(ctx)` | `GET /api/futures/funding-rate/exchange-list` | Current nested exchange funding contract. Returns a defensive snapshot of ordered stablecoin- and token-margin lists, preserving native decimal lexemes and raw provider receipts. |
| `AggregatedLiquidationHistory(ctx, params)` | `GET /api/futures/liquidation/aggregated-history` | `exchange_list` is required and defines the aggregate composition. |
| `GlobalAccountRatioHistory(ctx, params)` | `GET /api/futures/global-long-short-account-ratio/history` | Results remain scoped to the requested exchange and trading pair. |
These methods are tested with offline documentation-schema fixtures only; they
do not make live, credentialed, or paid-provider calls.
The similarly named methods in the endpoint list below remain available for
backward compatibility, but are legacy contracts. Prefer the audited methods
above for new integrations.
### Funding by exchange
`FundingRateExchangeListV4` mirrors CoinGlass's current nested response. Use a
snapshot to work with a defensive copy; `FundingRate.Lexeme` is the provider's
original decimal text and avoids a `float64` conversion.
The method admits only an explicit successful current-v4 envelope (`code`,
`msg`, and an array `data`), and rejects legacy flat rows rather than returning
empty typed markets. If admission fails, the returned response still exposes
the exact body through `RawEnvelope()` and `Receipts()` for inspection; both
accessors return defensive copies.
```go
response, err := client.Futures.FundingRateExchangeListV4(ctx)
if err != nil {
log.Fatal(err)
}
for _, market := range response.Snapshot() {
for _, rate := range market.StablecoinMarginList {
fmt.Printf("%s %s: %s (next: %d)\n",
market.Symbol, rate.Exchange, rate.FundingRate.Lexeme, rate.NextFundingTime.Value)
}
}
```
| Method | Endpoint | Description |
|----------------------------------------------|------------------------------------------------------------|--------------------------|
| `SupportedCoins(ctx)` | `GET /futures/supported-coins` | Supported futures coins |
| `SupportedExchangePairs(ctx, params)` | `GET /api/futures/supported-exchange-pairs` | Supported exchange pairs |
| `CoinsMarkets(ctx, params)` | `GET /api/futures/coins-markets` | Futures coin markets |
| `PairsMarkets(ctx, params)` | `GET /api/futures/pairs-markets` | Futures pair markets |
| `PriceChangeList(ctx)` | `GET /futures/price-change-list` | Price change list |
| `OpenInterestHistory(ctx, params)` | `GET /api/futures/openInterest/ohlc-history` | OI OHLC history |
| `OpenInterestAggregatedHistory(ctx, params)` | `GET /api/futures/openInterest/ohlc-aggregated-history` | Aggregated OI OHLC |
| `OpenInterestExchangeList(ctx, params)` | `GET /api/futures/openInterest/exchange-list` | OI by exchange |
| `FundingRateHistory(ctx, params)` | `GET /api/futures/fundingRate/ohlc-history` | Funding rate OHLC |
| `FundingRateOiWeighted(ctx, params)` | `GET /api/futures/fundingRate/oi-weight-ohlc-history` | OI-weighted funding rate |
| `FundingRateExchangeList(ctx, params)` | `GET /api/futures/fundingRate/exchange-list` | Legacy flat funding data; prefer `FundingRateExchangeListV4`. |
| `FundingRateArbitrage(ctx, params)` | `GET /api/futures/fundingRate/arbitrage` | Funding arbitrage |
| `LongShortRatioHistory(ctx, params)` | `GET /api/futures/global-long-short-account-ratio/history` | Global L/S ratio |
| `TopLongShortRatioHistory(ctx, params)` | `GET /api/futures/top-long-short-account-ratio/history` | Top trader L/S ratio |
| `LiquidationHistory(ctx, params)` | `GET /api/futures/liquidation/history` | Pair liquidation history |
| `LiquidationAggregatedHistory(ctx, params)` | `GET /api/futures/liquidation/aggregated-history` | Coin liquidation history |
| `LiquidationCoinList(ctx, params)` | `GET /api/futures/liquidation/coin-list` | Liquidation coin list |
| `LiquidationHeatmap(ctx, model, params)` | `GET /api/futures/liquidation/heatmap/model{1,2,3}` | Liquidation heatmaps |
| `LiquidationMap(ctx, params)` | `GET /api/futures/liquidation/map` | Liquidation map |
| `OrderbookHistory(ctx, params)` | `GET /api/futures/orderbook/history` | Orderbook heatmap |
| `LargeOrders(ctx, params)` | `GET /api/futures/orderbook/large-limit-order` | Large orderbook orders |
| `TakerBuySellHistory(ctx, params)` | `GET /api/futures/taker-buy-sell-volume/history` | Taker buy/sell history |
| `WhaleAlert(ctx, params)` | `GET /api/hyperliquid/whale-alert` | Hyperliquid whale alert |
### Spot — `client.Spot`
| Method | Endpoint | Description |
|------------------------------------|-----------------------------------------------|------------------------|
| `SupportedCoins(ctx)` | `GET /api/spot/supported-coins` | Supported coins |
| `CoinsMarkets(ctx, params)` | `GET /api/spot/coins-markets` | Coins markets |
| `PairsMarkets(ctx, params)` | `GET /api/spot/pairs-markets` | Pairs markets |
| `PriceHistory(ctx, params)` | `GET /api/spot/price/history` | Price OHLC history |
| `OrderbookHistory(ctx, params)` | `GET /api/spot/orderbook/history` | Orderbook heatmap |
| `TakerBuySellHistory(ctx, params)` | `GET /api/spot/taker-buy-sell-volume/history` | Taker buy/sell history |
### Options — `client.Options`
| Method | Endpoint | Description |
|-----------------------------------|----------------------------------------|-------------------------|
| `MaxPain(ctx, params)` | `GET /api/option/max-pain` | Option max pain |
| `Info(ctx, params)` | `GET /api/option/info` | Options info |
| `ExchangeOIHistory(ctx, params)` | `GET /api/option/exchange-oi-history` | Exchange OI history |
| `ExchangeVolHistory(ctx, params)` | `GET /api/option/exchange-vol-history` | Exchange volume history |
### ETF — `client.ETF`
| Method | Endpoint | Description |
|----------------------------------------|-------------------------------------------|--------------------|
| `BitcoinList(ctx)` | `GET /api/etf/bitcoin/list` | Bitcoin ETF list |
| `BitcoinFlowHistory(ctx, params)` | `GET /api/etf/bitcoin/flow-history` | BTC ETF flows |
| `BitcoinNetAssetsHistory(ctx, params)` | `GET /api/etf/bitcoin/net-assets/history` | ETF net assets |
| `EthereumList(ctx)` | `GET /api/etf/ethereum/list` | Ethereum ETF list |
| `EthereumFlowHistory(ctx, params)` | `GET /api/etf/ethereum/flow-history` | ETH ETF flows |
| `GrayscaleHoldings(ctx)` | `GET /api/grayscale/holdings-list` | Grayscale holdings |
### Indicators — `client.Indicators`
| Method | Endpoint | Description |
|------------------------------------|-----------------------------------------------|-----------------------|
| `FearGreedHistory(ctx, params)` | `GET /api/index/fear-greed-history` | Fear & Greed index |
| `RSIList(ctx, params)` | `GET /api/futures/rsi/list` | RSI list |
| `BasisHistory(ctx, params)` | `GET /api/futures/basis/history` | Futures basis |
| `CoinbasePremium(ctx, params)` | `GET /api/coinbase-premium-index` | Coinbase premium |
| `BitcoinRainbowChart(ctx)` | `GET /api/index/bitcoin/rainbow-chart` | BTC rainbow chart |
| `StockToFlow(ctx)` | `GET /api/index/stock-flow` | Stock-to-Flow model |
| `StablecoinMarketCap(ctx, params)` | `GET /api/index/stableCoin-marketCap-history` | Stablecoin market cap |
## Error handling
Any non-2xx response, or a response whose Coinglass envelope `code` isn't zero, comes back as an
`*coinglass.APIError`:
```go
type APIError struct {
StatusCode int
Code string
Message string
RawBody []byte
}
```
For the common cases, match on the sentinel errors with `errors.Is`; when you need the details, pull out the
`*APIError` with `errors.As`:
```go
import "errors"
oi, err := client.Futures.OpenInterestHistory(ctx, params)
if err != nil {
switch {
case errors.Is(err, coinglass.ErrUnauthorized):
log.Fatal("Invalid API key")
case errors.Is(err, coinglass.ErrRateLimited):
log.Println("Rate limited — retries exhausted")
default:
var apiErr *coinglass.APIError
if errors.As(err, &apiErr) {
log.Printf("API error %d (%s): %s", apiErr.StatusCode, apiErr.Code, apiErr.Message)
}
}
}
```
## WebSocket API
Alongside the REST client, `coinglass-go` ships a small WebSocket client under the `websocket` subpackage for
Coinglass's [real-time streams](https://docs.coinglass.com/reference/ws-getting-started) — liquidation orders, spot
and futures trades, and futures ticker snapshots. It's built entirely on the standard library too: the WebSocket
handshake, framing, and masking are implemented directly on top of `net`/`crypto/tls`, so no third-party dependency
is pulled in.
```go
package main
import (
"context"
"log"
"os"
"os/signal"
"syscall"
coinglass "github.com/tigusigalpa/coinglass-go"
"github.com/tigusigalpa/coinglass-go/websocket"
)
func main() {
client := coinglass.NewClient(os.Getenv("COINGLASS_API_KEY"))
ws := client.WSClient()
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
stream, err := ws.Connect(ctx)
if err != nil {
log.Fatal(err)
}
defer stream.Close()
stream.Subscribe(
websocket.ChannelLiquidationOrders(),
websocket.ChannelFuturesTicker("Binance", "BTCUSDT"),
)
for {
select {
case <-ctx.Done():
return
case msg, ok := <-stream.Messages():
if !ok {
return
}
if msg.Channel == websocket.ChannelLiquidationOrders() {
orders, _ := websocket.DecodeLiquidationOrders(msg.Data)
for _, o := range orders {
log.Printf("%s %s liquidated %.2f USD", o.Exchange, o.Symbol, o.VolumeUSD)
}
}
case err := <-stream.Errors():
log.Println("stream error:", err)
}
}
}
```
A single connection carries every subscription; `Subscribe`/`Unsubscribe` accept any number of channel names, and
the client sends the `"ping"` heartbeat every 20 seconds that Coinglass expects to keep the socket open.
### Channel helpers
| Helper | Channel | Docs |
|------------------------------------------------------|---------------------------------------|------------------------------------------------------------------------------------|
| `websocket.ChannelLiquidationOrders()` | `liquidation_orders` | [Liquidation Order](https://docs.coinglass.com/reference/ws-liquidation-order) |
| `websocket.ChannelSpotTrades(exchange, symbol, minVolumeUSD)` | `spot_trades@{exchange}_{symbol}@{minVolumeUSD}` | [Spot Trade Order](https://docs.coinglass.com/reference/websocket_spot_trades) |Frequently Asked Questions
What is coinglass-go?
coinglass-go is a Third-party APIs library for the Go programming language. Go client for Coinglass API v4 with zero dependencies, WebSocket streams, and typed endpoints for futures, spot, options, ETF, and indicators
How do I install coinglass-go?
Install coinglass-go with the Go module system using `go get tigusigalpa/coinglass-go`. Check the repository for the current installation instructions.
What category does coinglass-go belong to?
coinglass-go is listed under Third-party APIs, specifically Third-party APIs.