glassnode-api - v0.29.3
    Preparing search index...

    Class GlassnodeAPI

    Glassnode API client

    Index
    constructor
    callBulkMetric callMetric getAssetMetadata getMetricList getMetricMetadata getMetricStats

    • Create a new Glassnode API client

      Parameters

      • config: {
            apiKey?: string;
            apiKeyLocation?: "header" | "query";
            apiUrl?: string;
            fetch?: GlassnodeFetch;
            hooks?: {
                onError?: (event: GlassnodeErrorEvent) => void;
                onRequest?: (event: GlassnodeHookEventBase) => void;
                onResponse?: (event: GlassnodeResponseEvent) => void;
                onRetry?: (event: GlassnodeRetryEvent) => void;
            };
            logger?: Logger;
            maxRetries?: number;
            maxRetryDelay?: number;
            retryDelay?: number;
            timeout?: number;
            x402?: boolean;
        }

        Configuration object

        • OptionalapiKey?: string

          API key for authentication. Required unless x402 is enabled.

        • OptionalapiKeyLocation?: "header" | "query"

          Where the API key is sent: 'query' (default) as the api_key query parameter, or 'header' as the X-Api-Key request header, which keeps the key out of URLs (and so out of access logs, proxies, tracing and transport errors). 'header' is for server-side use: the Glassnode API's CORS preflight does not allow X-Api-Key, so browsers block it.

          With 'header', redirects are not followed (the request is sent with redirect: 'manual'): fetch would otherwise resend X-Api-Key to whatever origin a 3xx names. A 3xx surfaces as a non-retried GlassnodeApiError with that status; point apiUrl at the final URL. 'query' keeps fetch's default redirect handling (the URL, key included, goes wherever the server's Location says, which only the server that already received the key controls).

        • OptionalapiUrl?: string

          Base URL for the Glassnode API. Default https://api.glassnode.com, or https://x402.glassnode.com when x402 is set. An explicit value always wins over the x402 preset.

        • Optionalfetch?: GlassnodeFetch

          Optional custom fetch function (e.g. an x402-wrapped fetch, or for testing). Called with a string URL as fetch(url) or fetch(url, init); see GlassnodeFetch.

        • Optionalhooks?: {
              onError?: (event: GlassnodeErrorEvent) => void;
              onRequest?: (event: GlassnodeHookEventBase) => void;
              onResponse?: (event: GlassnodeResponseEvent) => void;
              onRetry?: (event: GlassnodeRetryEvent) => void;
          }

          Optional structured observability hooks (onRequest, onResponse, onRetry, onError), called synchronously and never awaited; a failing hook never affects the call. See GlassnodeHooks.

        • Optionallogger?: Logger

          Optional logger for API call debugging; its own failures (throw/rejection) are ignored.

        • OptionalmaxRetries?: number

          Maximum number of retries for retryable failures: a 429/5xx response, or a transport failure (GlassnodeNetworkError, including a per-attempt timeout). Default 0 (no retries).

        • OptionalmaxRetryDelay?: number

          Upper bound (ms) for a single retry wait, after exponential growth.

        • OptionalretryDelay?: number

          Base delay in milliseconds between retries (doubles each attempt, then full jitter).

        • Optionaltimeout?: number

          Per-request timeout in milliseconds. When set, each attempt is aborted via AbortSignal.timeout() after this many ms (a fresh signal per retry). Unset = no timeout.

        • Optionalx402?: boolean

          Route requests through the x402 paid endpoint (https://x402.glassnode.com).

      Returns GlassnodeAPI

    • Call a bulk metric endpoint (returns data for all assets at once)

      Parameters

      • metricPath: string

        Path of the metric (e.g. /market/marketcap_usd)

      • params: MetricParams = {}

        Query parameters (see MetricParams)

      • Optionaloptions: CallOptions

        Per-call options: signal to cancel, timeout to override the config one (see CallOptions)

      Returns Promise<{ bulk: { a: string; network?: string; v: number }[]; t: number }[]>

      Promise resolving to validated bulk response

      GlassnodeInputError (as a rejected promise, before any request) if metricPath is malformed, params.f is anything but json, params contains api_key, a param value cannot be converted (see MetricParamValue), or options is invalid

      GlassnodeAbortError if options.signal aborts (or was already aborted)

    • Call a generic metric, validating the response against a Zod schema.

      Type Parameters

      • S extends ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>

      Parameters

      • metricPath: string

        Path of the metric (e.g. /market/price_usd_close)

      • params: MetricParams | undefined

        Query parameters for the metric (see MetricParams); pass undefined or {} for none

      • options: CallMetricOptions<S>

        Per-call options plus schema: the Zod schema the response body must match (see CallMetricOptions), e.g. TimeSeriesResponseSchema for { t, v } metrics or TimeSeriesObjectResponseSchema for { t, o } metrics

      Returns Promise<output<S>>

      Promise resolving to the validated response, typed as the schema's output

      const series = await api.callMetric('/market/price_usd_close', { a: 'BTC' }, {
        schema: TimeSeriesResponseSchema,
      }); // TimeSeriesResponse — { t: number; v: number | null }[]

      GlassnodeValidationError (with endpoint) if the response does not match schema

      GlassnodeInputError (as a rejected promise, before any request) if metricPath is malformed, params.f is anything but json, params contains api_key, a param value cannot be converted (see MetricParamValue), options is invalid, or options.schema is not a Zod schema

      GlassnodeAbortError if options.signal aborts (or was already aborted)

    • Call a generic metric. The response body is returned unvalidated and cast to T — pass { schema } in options (see the other overload) for a validated, typed result.

      Type Parameters

      • T

      Parameters

      • metricPath: string

        Path of the metric (e.g. /accumulation_balance)

      • Optionalparams: MetricParams

        Query parameters for the metric, e.g. { a: 'BTC', s: 1609459200, i: '24h' } or { a: 'BTC', s: new Date('2021-01-01') } (see MetricParams)

      • Optionaloptions: CallOptions

        Per-call options: signal to cancel, timeout to override the config one (see CallOptions)

      Returns Promise<T>

      Promise resolving to the response data (not validated)

      GlassnodeInputError (as a rejected promise, before any request) if metricPath is malformed, params.f is anything but json, params contains api_key, a param value cannot be converted (see MetricParamValue), or options is invalid

      GlassnodeAbortError if options.signal aborts (or was already aborted)

    • Get metadata for all assets

      Parameters

      • Optionaloptions: CallOptions

        Per-call options: signal to cancel, timeout to override the config one (see CallOptions)

      Returns Promise<
          {
              asset_type: string;
              blockchains: {
                  address: string;
                  blockchain: string;
                  decimals: number;
                  on_chain_support: boolean;
              }[];
              categories?: string[];
              default_network?: string;
              external_ids: {
                  ccdata?: string;
                  coingecko?: string;
                  coinmarketcap?: string;
                  [key: string]: string;
              };
              id: string;
              logo_url?: string;
              name: string;
              semantic_tags?: string[];
              symbol: string;
          }[],
      >

      Promise resolving to validated asset metadata

      GlassnodeInputError (as a rejected promise, before any request) if options is invalid

      GlassnodeAbortError if options.signal aborts (or was already aborted)

    • Get a list of all metrics

      Parameters

      • Optionaloptions: CallOptions

        Per-call options: signal to cancel, timeout to override the config one (see CallOptions)

      Returns Promise<string[]>

      Promise resolving to validated metric metadata

      GlassnodeInputError (as a rejected promise, before any request) if options is invalid

      GlassnodeAbortError if options.signal aborts (or was already aborted)

    • Get metadata for a specific metric

      Parameters

      • metricPath: string

        Path of the metric

      • params: MetricParams = {}

        Query parameters for the metric (see MetricParams); numbers, booleans and Dates are converted (a Date → unix seconds), undefined values are omitted

      • Optionaloptions: CallOptions

        Per-call options: signal to cancel, timeout to override the config one (see CallOptions)

      Returns Promise<
          {
              bulk_supported?: boolean;
              descriptors?: {
                  data_sharing_group?: string;
                  description?: Record<string, string>;
                  group?: string;
                  name?: string;
                  short_name?: string;
                  tags?: string[];
              };
              is_pit?: boolean;
              modified: Date
              | undefined;
              parameters: Record<string, string[]>;
              parameters_defaults?: Record<string, string[]>;
              path: string;
              queried: Record<string, any>;
              refs: {
                  docs?: string;
                  metric_variant?: { base?: string; bulk?: string; pit?: string };
                  studio?: string;
              };
              tier: number;
              timerange?: { max: number; min: number };
          },
      >

      Promise resolving to validated metric metadata

      GlassnodeInputError (as a rejected promise, before any request) if metricPath is malformed, params.f is anything but json, params contains path or api_key, a param value cannot be converted (see MetricParamValue), or options is invalid

      GlassnodeAbortError if options.signal aborts (or was already aborted)

    • Get data-lag statistics for a specific metric. Returns the current data lag as aggregated percentiles over the past 30 days.

      Parameters

      • metricPath: string

        Path of the metric (e.g. /institutions/us_spot_etf_balances_all)

      • params: MetricParams = {}

        Optional query parameters (e.g. a to scope stats to an asset; see MetricParams for value conversion)

      • Optionaloptions: CallOptions

        Per-call options: signal to cancel, timeout to override the config one (see CallOptions)

      Returns Promise<
          {
              lag: {
                  resolution: Record<
                      string,
                      { p50?: number; p90?: number; p95?: number; p99?: number },
                  >;
                  unit: string;
                  window: string;
              }[];
          },
      >

      Promise resolving to validated metric stats

      GlassnodeInputError (as a rejected promise, before any request) if metricPath is malformed, params.f is anything but json, params contains path or api_key, a param value cannot be converted (see MetricParamValue), or options is invalid

      GlassnodeAbortError if options.signal aborts (or was already aborted)

    Settings
    Member Visibility

    On This Page
    Constructors
    Methods