Glassnode CLI (`gn`)

Command-line interface for the Glassnode API

Installation

Install script (one command)

Linux / macOS

curl -sSL https://raw.githubusercontent.com/glassnode/glassnode-cli/main/install.sh | bash

Installs the latest release to /usr/local/bin (uses sudo if needed). To install elsewhere:

INSTALL_DIR=~/bin curl -sSL https://raw.githubusercontent.com/glassnode/glassnode-cli/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/glassnode/glassnode-cli/main/install.ps1 | iex

Installs to %LOCALAPPDATA%\glassnode\bin and adds it to your user PATH if needed.

Manual download

Download the archive for your OS and architecture from Releases, extract it, then move the binary into your PATH and make it executable (chmod +x gn on Unix).

From source

go install github.com/glassnode/glassnode-cli@latest

The binary from go install is named glassnode-cli. To get the same gn command as the release, build with: go build -o gn . and put gn in your PATH.

Quick Start

# Sign in with your Glassnode account
gn login

# List available assets
gn asset list

# Fetch Bitcoin's closing price for the last 30 days
gn metric get market/price_usd_close --asset BTC --since 30d

Or authenticate with an API key instead:

export GLASSNODE_API_KEY=your-key

Authentication

OAuth

Sign in with your Glassnode account:

gn login

And to sign out:

gn logout

API key

The CLI resolves the API key in the following priority order:

--api-key flag (highest priority)
GLASSNODE_API_KEY environment variable
~/.gn/config.yaml configuration file

However the OAuth access token has precedence and will be used if it is available.

To persist the API key in the config file:

gn config set api-key=your-key

Commands

`gn asset list`

List all available assets.

gn asset list
gn asset list --filter "asset.semantic_tags.exists(tag,tag=='stablecoin')"
gn asset list --filter "asset.id=='BTC'"

Use --prune to return only specific fields as an array of objects (e.g. for scripting or piping to jq):

# Only asset IDs (array of objects with one field)
gn asset list --prune id -o json

# ID and symbol
gn asset list -p id,symbol -o json

Flag	Short	Description
`--filter`		CEL filter expression
`--prune`	`-p`	Comma-separated fields to keep (e.g. `id`, `symbol`, `name`); output is array of objects with only those fields

`gn asset describe <id>`

Show details about an asset.

gn asset describe BTC

`gn asset tags`

List all asset semantic tags, optionally over a CEL-filtered subset of assets.

gn asset tags
gn asset tags --filter "asset.categories.exists(c,c=='spot')"

Flag	Short	Description
`--filter`		CEL filter expression

`gn asset categories`

List all asset categories, optionally over a CEL-filtered subset of assets.

gn asset categories
gn asset categories --filter "asset.semantic_tags.exists(tag,tag=='erc20')"

Flag	Short	Description
`--filter`		CEL filter expression

`gn asset blockchains`

List all blockchains on which at least one asset is supported, optionally over a CEL-filtered subset of assets.

gn asset blockchains
gn asset blockchains --filter "asset.id=='USDT'"

Flag	Short	Description
`--filter`		CEL filter expression

`gn metric tags`

List all tags used across metric metadata.

gn metric tags

`gn metric list`

List all available metrics, optionally filtered by metadata query parameters.

gn metric list
gn metric list --asset BTC
gn metric list -a BTC -e binance -i 24h
gn metric list --assets BTC --assets ETH
gn metric list --from-exchange binance --to-exchange coinbase

Flag	Short	Description
`--asset`	`-a`	Filter by asset (single)
`--assets`		Filter by multiple assets (repeat for each, e.g. `--assets BTC --assets ETH`)
`--currency`	`-c`	Filter by currency (e.g. `native`, `usd`)
`--exchange`	`-e`	Filter by exchange (e.g. `binance`, `coinbase`)
`--interval`	`-i`	Filter by time interval (e.g. `1h`, `24h`)
`--from-exchange`		Source exchange for inter-exchange metrics
`--to-exchange`		Destination exchange for inter-exchange metrics
`--miner`		Miner identifier for mining-related metrics
`--maturity`		Maturity period for derivatives metrics
`--network`		Network/blockchain for cross-chain metrics
`--period`		Time period for aggregation
`--quote-symbol`		Quote currency symbol for trading pairs

`gn metric describe <path>`

Show metadata for a metric: supported assets, intervals, exchanges, currencies, and parameters.

gn metric describe market/price_usd_close
gn metric describe market/price_usd_close --asset BTC

`gn metric get <path>`

Fetch metric data from the API.

gn metric get market/price_usd_close --asset BTC --interval 24h
gn metric get market/price_usd_close --asset BTC --since 2024-01-01 --until 2024-02-01
gn metric get indicators/sopr --asset BTC --interval 24h --since 30d
gn metric get distribution/balance_exchanges --asset BTC --exchange binance --currency usd
# Bulk: append /bulk to the path; use -a '*' for all assets or multiple -a for specific ones.
# --since is required; longer ranges than the API allows per request need --split
gn metric get market/marketcap_usd/bulk -a '*' --since 30d
gn metric get market/marketcap_usd/bulk -a BTC -a ETH --since 2024-01-01 --split

Flag	Short	Description
`--asset`	`-a`	Asset symbol (repeatable for bulk metrics; use `*` for all assets)
`--since`	`-s`	Start time (ISO date or relative: `30d`, `1h`)
`--until`	`-u`	End time (ISO date or relative)
`--interval`	`-i`	Resolution (`1h`, `24h`, `1w`, `1month`)
`--currency`	`-c`	Currency for the metric (`usd`, `native`)
`--exchange`	`-e`	Exchange filter (repeatable for bulk)
`--network`	`-n`	Network filter
`--split`		Bulk only: fetch a range longer than the API allows per request in several requests

For bulk metrics, append /bulk to the path (e.g. market/marketcap_usd/bulk). To pass multiple assets, repeat the -a (or --asset) flag for each: -a BTC -a ETH -a SOL. Use -a '*' to request all assets.

Point-in-time metrics (*_pit) include computed_at, the time the value was computed, as a field in JSON and as a trailing column in CSV and table output.

The API requires --since for bulk metrics and accepts at most 10 days per request at 10m/1h, 31 days at 24h and 93 days at 1w/1month, counted from the start of the interval containing --since (weeks start on Monday, months on the 1st, UTC). A longer range is rejected before any request is sent unless you pass --split: the CLI then fetches it window by window, prints how many requests that takes on stderr, and merges the points. Every request is billed per asset, so narrow -a for long ranges. The merged result is assembled in memory before it is printed.

`gn user credits`

Show the current API usage for your account.

gn user credits

Example output:

{
  "creditsLeft": integer,
  "creditsLimit": integer,
  "creditsPeriod": "daily" | "monthly",
  "creditsUsed": integer
}

All four fields describe the same window. creditsLimit is the allowance granted per creditsPeriod, both read from your account's API addon, and creditsUsed and creditsLeft are the usage and remainder within that window. The period depends on your plan: the advanced product is metered daily, in requests, every other product monthly, in credits.

If the API reports a period the CLI does not know, or add-ons of different periods, creditsPeriod carries what the API sent (or mixed) and creditsUsed and creditsLeft are omitted rather than measured against a counter of another period.

`gn config set key=value`

Set a configuration value.

gn config set api-key=your-key
gn config set output=csv

`gn config get <key|all>`

Read a configuration value, or all values. Sensitive values (api-key, oauth-access-token, oauth-refresh-token) are masked as *****-<last4> so they're safe to show in screen shares, recordings, or shell scrollback.

gn config get api-key       # e.g. "*****-cdef"
gn config get all

OAuth session fields (oauth-access-token, oauth-refresh-token, oauth-expires-at) are read-only: they are written only by gn login / token refresh and cannot be changed via gn config set.

Global Flags

Flag	Short	Description
`--api-key`		Glassnode API key
`--output`	`-o`	Output format: `json` (default), `csv`, `table`
`--dry-run`		Print the endpoint and parameters of the request without sending it. The API key is sent in the `X-Api-Key` header and is not part of the URL. The URL is built from the flags, not by the SDK: metric requests are sent with `f=json` appended, and parameter validation (empty values, `--since` after `--until`) happens only when the request is sent
`--timestamp-format`		Timestamp format in output

Output Formats

json (default) — structured JSON, suitable for piping to jq
csv — comma-separated values for spreadsheets and data pipelines
table — human-readable ASCII table

# Pipe JSON to jq
gn metric get market/price_usd_close -a BTC --since 7d | jq '.[].v'

# Export to CSV
gn metric get market/price_usd_close -a BTC --since 30d -o csv > prices.csv

# Quick look in the terminal
gn metric get market/price_usd_close -a BTC --since 7d -o table

Examples

Discover metrics for an asset

gn metric list --asset BTC
gn metric describe market/price_usd_close --asset BTC

Preview a request without executing

gn metric get market/price_usd_close --asset BTC --since 30d --dry-run

Bulk fetch across multiple assets

Append /bulk to the metric path. Specify multiple assets by repeating -a for each, or use -a '*' for all:

# Multiple specific assets (repeat -a for each); a range over the API's
# per-request limit is fetched in several requests with --split
gn metric get market/marketcap_usd/bulk -a BTC -a ETH -a SOL -s 2024-01-01 -u 2024-04-01 --split

# All assets (wildcard)
gn metric get market/marketcap_usd/bulk -a '*' --interval 24h --since 30d

Filter assets by tag

gn asset list --filter "asset.semantic_tags.exists(tag,tag=='stablecoin')"

Development

Build from source

git clone https://github.com/glassnode/glassnode-cli.git
cd glassnode-cli
go build -o gn .

Run tests

go test ./...

See CONTRIBUTING.md for linting, the changelog and releases.

License

Apache-2.0

Name		Name	Last commit message	Last commit date
.github		.github
cmd		cmd
internal		internal
skills/glassnode-cli		skills/glassnode-cli
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.goreleaser.yml		.goreleaser.yml
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
go.mod		go.mod
go.sum		go.sum
install.ps1		install.ps1
install.sh		install.sh
main.go		main.go

Latest commit

History

Folders and files

Repository files navigation

Glassnode CLI (gn)

Installation

Install script (one command)

Manual download

From source

Quick Start

Authentication

OAuth

API key

Commands

gn asset list

gn asset describe <id>

gn asset tags

gn asset categories

gn asset blockchains

gn metric tags

gn metric list

gn metric describe <path>

gn metric get <path>

gn user credits

gn config set key=value

gn config get <key|all>

Global Flags

Output Formats

Examples

Discover metrics for an asset

Preview a request without executing

Bulk fetch across multiple assets

Filter assets by tag

Development

Build from source

Run tests

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages