Skip to content

README.md

Latest commit

 

History

History
151 lines (108 loc) · 5.34 KB

README.md

File metadata and controls

151 lines (108 loc) · 5.34 KB
Raw

Glassnode API Examples

This directory contains example scripts that demonstrate how to use the Glassnode API TypeScript client (Node.js and browsers).

Setup

Before running the examples:

  1. Install the root dependencies (the examples import the client straight from ../src, which needs zod from the root install): 
    pnpm install   # in the repository root
  2. Install the examples' own dependencies in this directory with npm ci, which installs exactly what package-lock.json pins, as CI does: 
    npm ci
    examples/.npmrc disables install scripts. To add or update a dependency, only accept versions published at least 7 days ago (the repo's supply-chain rule), then commit the updated lockfile: 
    npm install <package>@<range> --before="$(date -u -v-7d +%F)"   # macOS; GNU: date -u -d '7 days ago' +%F
  3. Copy .env.example to .env and fill in what the example needs — GLASSNODE_API_KEY (from Glassnode) for the API-key examples, or the X402_* variables for the x402 example: 
    cp .env.example .env

Available Examples

Metadata Validation (ex.metadata.validation.ts)

Demonstrates how to:

  • Fetch and validate asset metadata
  • Get a list of available metrics
  • Fetch metadata for specific metrics (exchange balance example)
  • Work with metric parameters

Run with:

npx ts-node ex.metadata.validation.ts

Metric Dumping (ex.metric.dump.ts)

Shows how to:

  • Fetch the list of all available metrics
  • Get metadata for the first 10 metrics
  • Call each one with the first allowed value of every parameter
  • Print the first data point of each result

Run with:

npx ts-node ex.metric.dump.ts

Bulk Market Cap Ranking (ex.bulk.market-cap.ts)

Uses callBulkMetric() to fetch /market/marketcap_usd for all assets at once (a: '*', 24h resolution, last day), then ranks the latest entry and prints the top 20 assets by market cap.

Run with:

npx ts-node ex.bulk.market-cap.ts

Metric Stats — Data-Lag Visualization (ex.metric-stats.ts)

Uses the getMetricStats() method (the /v1/metadata/metric/stats endpoint) to show a metric's current data lag as p50/p90/p95/p99 percentiles per resolution over the trailing 30 days, and renders a colored in-console visualization. It inspects four metric/asset pairs:

  • BTC and SOL active addresses (/addresses/active_count)
  • BTC and SOL OHLC price (/market/price_usd_ohlc)

Each resolution gets a two-tone bar — solid = typical lag (p50), dim tail = worst case (p99) — scaled per metric. Colors auto-disable when the output isn't a terminal (or set NO_COLOR=1). Metadata calls don't consume API quota.

Run with:

npx ts-node ex.metric-stats.ts

x402 Paid Calls — Active Addresses (ex.x402.active-addresses.ts)

Demonstrates the x402 paid API (no API key — you pay per call in USDC on Base):

  • Build a payment-capable fetch from a funded Base wallet (createX402Fetch)
  • Hit the metadata endpoint ($0.01) to confirm the asset + resolution are supported
  • Fetch active addresses for the asset (default BTC), last 1 month at 24h ($0.05)
  • Defaults to mainnet; point at a different x402 endpoint by setting X402_API_URL

Defaults to BTC at 24h (active_count rejects 1h). The metadata check skips the paid query if the asset isn't supported.

Set these in .env (see .env.example):

X402_PRIVATE_KEY=0xyour_funded_wallet_private_key   # required
X402_MAX_PAYMENT=0.06                     # optional, per-call USDC ceiling (default 0.06)
X402_API_URL=https://x402.glassnode.com   # optional, x402 endpoint (default: mainnet)

Optional overrides (see the script header): X402_METRIC (default /addresses/active_count), X402_ASSET (default BTC), X402_RESOLUTION (24h | 1w | 1month, default 24h), and X402_SKIP_METADATA=1 to make a single paid metric call without the metadata check.

Wallet safety: use a dedicated, funded-but-limited wallet — never a primary key. On mainnet it spends real USDC; on a testnet endpoint fund the wallet with Base Sepolia test USDC. X402_MAX_PAYMENT caps each call, not total spend.

Run with:

npx ts-node ex.x402.active-addresses.ts

Dependencies

examples/package.json declares:

  • dotenv - For loading environment variables from .env
  • ts-node (dev dependency) - For running TypeScript files directly
  • @x402/fetch, @x402/evm, viem - For the x402 paid-API example (payment signing on Base)

examples/tsconfig.json configures ts-node: it enables experimentalResolver, which maps the .js import specifiers in ../src to their .ts sources. Run the examples from this directory so ts-node picks it up; otherwise they fail with Cannot find module './glassnode-api.js'.

zod (used directly in ex.metadata.validation.ts) is not listed there — it's a dependency of the client itself and resolves from the root install.

Adding New Examples

To add a new example:

  1. Create a new TypeScript file in this directory
  2. Import the Glassnode API client: import { GlassnodeAPI } from '../src'
  3. Load .env with import 'dotenv/config' and set up the client with process.env.GLASSNODE_API_KEY
  4. Implement your example code
  5. Run with npx ts-node your-example-file.ts