Skip to content

v1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@tigusigalpa tigusigalpa released this 30 Jul 14:20
v1.0.0
eda3161

Release v1.0.0 — First Stable Release

Tag: v1.0.0
Date: January 15, 2025
License: MIT
Requires: PHP 8.1+, ext-curl, ext-json

The first stable release of glassnode-php — an unofficial, framework-agnostic PHP SDK for the Glassnode Basic API, with a first-class Laravel bridge.

This release ships the complete documented metric surface: 25 typed category resources, a generic metric API for any present or future path, runtime metadata discovery, automatic 429 retry handling, a rich exception hierarchy, and immutable configuration. It works in plain PHP out of the box and auto-discovers in Laravel 10 through 13.

Highlights

Three Layers of API

  1. Transport & config — GlassnodeClient with a zero-dependency cURL transport (default) or any PSR-18 compatible client (Guzzle, Symfony HTTP Client, etc.). GlassnodeConfig is immutable, with fromArray() and fromEnv() factories.
  2. Metadata & generic — MetadataResource for runtime discovery of assets, metrics, and parameters; GlassnodeClient::get() for any metric path, present or future.
  3. Ergonomic category resources — 25 typed resource classes mapping 1:1 to Glassnode's endpoint categories.

25 Category Resources

Addresses, Bridges, Blockchain, Breakdowns, DeFi, Derivatives, Distribution, Entities, ETH 2.0, Fees, Global, Indicators, Institutions, Lightning, Macro, Market, Mempool, Mining, Options, Point-In-Time, Protocols, Signals, Supply, Transactions, Treasuries — plus MetadataResource and UserResource.

Authentication

  • Header mode (X-Api-Key) by default — the key never appears in URLs or logs
  • Query-string mode (api_key) opt-in via GlassnodeConfig::AUTH_MODE_QUERY for environments where headers aren't supported

Retry & Rate-Limit Awareness

  • Automatic retry on HTTP 429, GET requests only
  • Honors the x-rate-limit-reset header when present; falls back to exponential backoff otherwise
  • Never retries 400, 401, or 404 — client errors that won't resolve by retrying
  • Configurable via retryAttempts (default: 3) and retryDelay (default: 1.0s)

Exception Hierarchy

A typed, catchable hierarchy so you can branch on errors without string matching:

GlassnodeException (base)
├── BadRequestException        (HTTP 400)
├── UnauthorizedException      (HTTP 401)
├── NotFoundException          (HTTP 404)
├── RateLimitException         (HTTP 429, after retries)
├── ConfigurationException     (invalid config)
└── TransportException         (network/HTTP errors)

Each exception carries the HTTP status code, response body, and (for RateLimitException) the rateLimitReset value.

Laravel Bridge

  • Auto-discovered service provider and Glassnode facade — no manual registration
  • Publishable config file (php artisan vendor:publish --tag=glassnode-config)
  • Dependency-injectable GlassnodeClient for controllers and services
  • No network requests at boot time — won't slow down app startup

PSR-18 Support

Bring your own HTTP client. Plug in Guzzle, Symfony HTTP Client, or any PSR-18 implementation alongside PSR-17 request/stream factories — useful for projects that already standardize on a particular client or need custom middleware (logging, circuit breakers, proxies).

Installation

composer require tigusigalpa/glassnode-php

No hard dependencies beyond ext-curl and ext-json (both enabled by default in virtually every PHP installation). PSR-18/17 interfaces are required only if you opt out of the built-in cURL transport.

Quick Start

Plain PHP

use Tigusigalpa\Glassnode\GlassnodeClient;
use Tigusigalpa\Glassnode\GlassnodeConfig;

$client = new GlassnodeClient(new GlassnodeConfig(
    apiKey: 'YOUR_API_KEY',
    timeout: 15.0,
    retryAttempts: 3,
));

$price = $client->market->price(['a' => 'BTC', 'i' => '24h']);
foreach ($price as $point) {
    printf("BTC price at %d: $%.2f\n", $point['t'], $point['v']);
}

Laravel

use Tigusigalpa\Glassnode\Laravel\Facades\Glassnode;

$price = Glassnode::market()->price(['a' => 'BTC', 'i' => '24h']);
$sopr = Glassnode::indicators()->sopr(['a' => 'BTC']);
$assets = Glassnode::metadata()->assets();

Or via dependency injection:

use Tigusigalpa\Glassnode\GlassnodeClient;

class DashboardController extends Controller
{
    public function index(GlassnodeClient $client)
    {
        $price = $client->market->price(['a' => 'BTC']);
        $activeAddresses = $client->addresses->activeCount(['a' => 'BTC']);

        return view('dashboard', [
            'price' => $price,
            'activeAddresses' => $activeAddresses,
        ]);
    }
}

What's Included

  • GlassnodeConfig — immutable configuration with fromArray() and fromEnv() factories
  • GlassnodeClient — cURL transport (default) and PSR-18 client support
  • Header (X-Api-Key) and query-string (api_key) authentication modes
  • MetadataResource — assets(), metrics(), metric() endpoints
  • UserResource — apiUsage() endpoint
  • 25 category resources with typed convenience methods
  • Exception hierarchy: GlassnodeException, ApiException, BadRequestException, UnauthorizedException, NotFoundException, RateLimitException, ConfigurationException, TransportException
  • Automatic retry on HTTP 429 with x-rate-limit-reset header support and exponential backoff
  • Laravel service provider, facade, and publishable configuration file
  • Comprehensive test suite — 41 tests (37 unit + 4 feature) covering authentication, retries, errors, URL encoding, resource routing, and Laravel integration
  • docs/endpoint-coverage.md documenting all covered endpoints

Compatibility

  • PHP 8.1+ (uses named arguments, readonly properties, enums)
  • Laravel 10, 11, 12, 13 (auto-discovery, facade, config publishing)
  • ext-curl and ext-json required (both enabled by default in standard PHP)
  • PSR-18 client optional (for custom HTTP transports like Guzzle or Symfony HTTP Client)

Documentation

Examples

  • Basic usage — price, indicators, assets, API usage
  • Laravel — facade and dependency injection in a controller
  • Error handling — exception types and recovery strategies

Acknowledgements

This is an unofficial, community-built SDK. It is not affiliated with or endorsed by Glassnode. The official API documentation at docs.glassnode.com is the source of truth for endpoint behavior.

Links

Full Changelog: CHANGELOG.md

Assets 2
Loading