Stop Wrestling with cURL: Meet glassnode-php, an Unofficial Glassnode SDK for PHP

Integrating on-chain metrics into a PHP product should not require every developer to become an HTTP error-handling specialist first. Yet that is often the reality: hand-written cURL calls, manually assembled query strings, JSON decoding scattered through services, and generic exceptions that make production incidents harder to diagnose. The problem becomes even more consequential when requests consume data credits and operate within provider-managed limits. Glassnode’s own documentation makes clear that API access, available data, and request consumption depend on the customer’s plan. 2

glassnode-php is built to remove that friction. It is an unofficial, production-oriented SDK for PHP 8.1+ that targets the Glassnode Basic API. The package is framework-agnostic, while also offering a first-class bridge for Laravel applications. It is not affiliated with or endorsed by Glassnode; instead, it is an independent developer tool designed to make integrations cleaner, safer, and much easier to maintain. 1

The short version: glassnode-php lets PHP developers spend less time wiring up HTTP and more time building dashboards, alerts, research tools, and data-driven product features.

Why an SDK Matters Here

A raw HTTP integration can be perfectly acceptable for a one-off script. It becomes much less attractive when an application needs many metrics, multiple assets, a predictable error model, secure key handling, and the ability to evolve as the upstream API evolves. That is the gap glassnode-php addresses.

Rather than exposing a single oversized client with an ever-growing list of methods, the SDK uses three complementary layers. At the foundation is GlassnodeClient, which pairs configuration with a built-in cURL transport or a PSR-18-compatible HTTP client. Above that, the package provides 25 typed category resources covering the documented endpoint categories. Finally, metadata discovery and a generic get() method give developers an escape hatch for valid metric paths that do not yet have a dedicated convenience wrapper. 1

Integration concern	What glassnode-php provides	Practical result
Repetitive API plumbing	Typed category resources and convenience methods	Less manual URL and parameter handling
Evolving metric catalog	Metadata discovery and generic metric access	New valid paths can be used without waiting for a wrapper
Rate limiting	Automatic handling of HTTP 429 responses	More resilient background jobs and dashboards
Credential exposure	X-Api-Key header authentication by default	Fewer secrets embedded in URLs and logs
Laravel integration	Auto-discovery, configuration publishing, Facade, and DI support	A familiar experience in Laravel projects

The table above reflects package capabilities documented in the project README. 1

A Developer-Friendly API Surface

The fastest way to appreciate the library is to look at its API shape. After installation, fetching Bitcoin price data does not require a request factory, an endpoint string, and a bespoke JSON decoder in your business logic. Instead, the code reads like the business question you are trying to answer.

composer require tigusigalpa/glassnode-php

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

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

$client = new GlassnodeClient($config);

// Fetch BTC price data with 24-hour resolution.
$prices = $client->market->price([
    'a' => 'BTC',
    'i' => '24h',
]);

foreach ($prices as $point) {
    printf("BTC price at %d: $%.2f\n", $point['t'], $point['v']);
}

This is a small example, but the design scales well. The same client exposes resources for areas such as addresses, market data, indicators, mining, supply, transactions, derivatives, and more. The typed layer is useful when you already know the metric family you need, while the generic API makes the client more durable in the face of an evolving upstream platform. 1

// A generic call for any valid metric path.
$data = $client->get(
    '/v1/metrics/addresses/sending_count',
    ['a' => 'BTC']
);

// Discover what an individual metric supports before requesting it.
$metric = $client->metadata->metric('/market/price_usd');

The metadata-first workflow deserves special attention. Glassnode documents metadata as a source of information about metric parameters, time ranges, descriptions, and assets. Using it at runtime gives a product team a more robust alternative to hardcoding assumptions about every endpoint. 2 In practice, it can help a dashboard expose only supported assets, allow users to select meaningful resolutions, or validate a metric choice before a more expensive data call is made.

Built for the Unhappy Path, Too

The happiest-path request is rarely what causes trouble in a production integration. Rate limits, bad credentials, invalid parameters, missing metrics, and temporary transport failures are the issues that tend to surface at the worst possible moment. glassnode-php makes those cases first-class citizens.

The package automatically retries HTTP 429 Too Many Requests responses for GET requests. When the server supplies an x-rate-limit-reset header, the SDK uses it; otherwise, it falls back to exponential backoff. It deliberately does not retry client errors such as 400, 401, or 404, where retrying is unlikely to change the outcome. 1 That distinction saves developers from implementing the same defensive logic in every command, queue job, or controller.

The exception model is equally practical. Instead of catching a generic failure and inspecting an opaque response, an application can handle UnauthorizedException, RateLimitException, BadRequestException, and NotFoundException separately. This makes it much easier to turn an API event into the correct product behaviour: surface a configuration problem, reschedule a job, prompt for a valid asset, or report that a requested metric does not exist. 1

use Tigusigalpa\Glassnode\Exceptions\RateLimitException;
use Tigusigalpa\Glassnode\Exceptions\UnauthorizedException;
use Tigusigalpa\Glassnode\Exceptions\GlassnodeException;

try {
    $sopr = $client->indicators->sopr(['a' => 'BTC']);
} catch (UnauthorizedException $e) {
    // Alert the operator to fix the API-key configuration.
} catch (RateLimitException $e) {
    // Requeue or delay the job using the available reset context.
} catch (GlassnodeException $e) {
    // Handle transport or other SDK-level failures.
}

Security has also been treated as a default, not an optional enhancement. The SDK sends credentials through the X-Api-Key header by default, although a query-parameter mode is available where it is required. Glassnode’s API documentation supports both forms of authentication. 1 Keeping a key out of URLs is a sensible default for applications that may record URLs in logs, monitoring systems, proxies, or analytics tooling.

A Natural Fit for Laravel

Laravel developers do not need to sacrifice framework conventions to use a specialized API client. glassnode-php supports service-provider and Facade auto-discovery, configuration publishing, and dependency injection. That means a Laravel project can keep secrets in .env, organize request logic inside services, and inject GlassnodeClient where it is needed. 1

use Tigusigalpa\Glassnode\Laravel\Facades\Glassnode;

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

$sopr = Glassnode::indicators()->sopr(['a' => 'BTC']);
$assets = Glassnode::metadata()->assets();

For larger applications, dependency injection provides an especially testable option.

use Illuminate\View\View;
use Tigusigalpa\Glassnode\GlassnodeClient;

class DashboardController extends Controller
{
    public function index(GlassnodeClient $client): View
    {
        return view('dashboard', [
            'price' => $client->market->price(['a' => 'BTC']),
            'activeAddresses' => $client->addresses->activeCount(['a' => 'BTC']),
        ]);
    }
}

This approach keeps the controller focused on application orchestration rather than request construction. The same client can be reused in a scheduled command, a queue worker, or a reporting service without duplicating API configuration or error-handling code.

More Than a Convenience Wrapper

The value of glassnode-php is not merely that it shortens syntax. Its transport flexibility, immutable configuration, metadata discovery, bulk-query support, rate-limit awareness, and detailed exceptions form a foundation for integrations that need to survive real operational conditions. The package also supports point-in-time metrics, preserving the computed_at timestamp for workflows that need to distinguish between a value as known at a specific time and later-updated data. 1

Bulk requests are another useful capability when a product needs to retrieve a metric for several explicitly selected assets. They can reduce HTTP round trips, but developers should still model request volume and data usage according to Glassnode’s service rules and plan entitlements. 1 The SDK is designed to make calls correct and manageable; access scope, data availability, and credits remain governed by Glassnode.

Start Building with Less Plumbing

If you are building a crypto analytics dashboard, an internal reporting system, a market-monitoring service, or any PHP application that needs on-chain metrics, glassnode-php offers a clear path away from fragile ad hoc requests. Install it with Composer, configure your Glassnode API key through environment variables, begin with the metadata endpoints, and let the SDK deal with the repetitive integration work.

Explore the repository, review the examples, and contribute improvements at github.com/tigusigalpa/glassnode-php. The project is released under the MIT License. 1

Note: This SDK is an engineering integration tool, not a source of investment advice. Any analysis based on retrieved data should be evaluated within the context of your own methodology and applicable requirements.

References