DEV Community: Igor

Stop Fighting Generated Code: Introducing a Hand-Crafted Go SDK for KuCoin

Igor — Sun, 09 Aug 2026 12:58:39 +0000

Integrating an exchange API is rarely difficult because an endpoint is missing. It is difficult because the integration becomes part of a system that must behave predictably when the network is slow, when rate limits are reached, when API documentation is ambiguous, and when a number must retain every decimal place. In that environment, convenience wrappers can be expensive: a client that merely exposes every endpoint is not necessarily a client that feels safe to build upon.

That is the motivation behind kucoin-go, an unofficial Go client for KuCoin’s UTA (Unified Trading Account) and Classic API families. The project is built from scratch against KuCoin’s current documentation rather than as a wrapper over the official Universal SDK. Its goal is deliberately narrower: offer a consistent, idiomatic Go experience and expand endpoint coverage method by method, with tests and documentation keeping pace. 1

“We'd rather ship a small, correct surface than a large, half-tested one.” — kucoin-go project README 1

This is not a claim that generated SDKs have no place. If your application needs comprehensive KuCoin coverage immediately, the official client remains the sensible choice. kucoin-go is for Go developers who prefer an explicit, thoughtfully designed API surface—and who value being able to see precisely what is implemented today.

Why a smaller SDK can be a better foundation

An exchange client occupies an awkward but important boundary. On one side are remote API shapes, rate limits, account models, and authentication rules. On the other are your Go services, jobs, alerting pipeline, or trading logic. A useful SDK should make that boundary visible rather than hiding it behind generic types and optimistic defaults.

kucoin-go applies a few clear rules at that boundary. Network calls take a context.Context as their first argument, letting an application define cancellation and timeout behavior using standard Go mechanisms. The client can also receive an injected *http.Client, clock, and logger, which makes it easier to apply a house network policy in production and to write controlled tests. 1

The project keeps KuCoin’s two account models explicit. UTA and Classic expose different permissions, hosts, and response shapes, so the SDK does not flatten them into one misleading abstraction. The current UTA surface is accessed through client.UTA; the Classic service root is planned for later coverage. This distinction is especially helpful when an application needs to reason about which account model a request actually belongs to. 1

Design choice	What it means in practice	Why it matters
Context-first calls	Every network method begins with `context.Context`.	Request deadlines and cancellation stay under application control.
Explicit service roots	UTA and Classic are modeled as separate domains.	Account-specific permissions and payload differences are not blurred.
Injected dependencies	HTTP client, clock, logger, and retry policy are configurable.	Production behavior and testing can be tailored without forking the SDK.
Typed transport errors	Errors work with `errors.Is` and `errors.As`.	Code can branch on meaningful conditions instead of matching strings.

Treat money as data, not as a float

One of the most intentional choices in kucoin-go is deceptively simple: price, quantity, PnL, and fee fields are represented as strings at the transport boundary. 1

That may look less convenient than decoding directly into float64, but it is the correct friction for financial values. Binary floating-point numbers cannot represent many decimal fractions exactly. If a service receives an exchange value, performs arithmetic, and serializes it again, silent rounding can turn an apparently harmless conversion into a difficult reconciliation problem.

The library therefore preserves the value exactly as it arrives from the API and asks the application to choose an arithmetic type intentionally—for example, math/big.Rat or a decimal package. It is a small API design decision with a useful message: precision should be an explicit responsibility, never an accidental by-product of JSON unmarshalling.

Transport behavior designed for production realities

A clean Go method signature is only half of an SDK. What happens when the server rejects a call, sends a business-level error, or asks the caller to slow down matters just as much.

kucoin-go uses a shared transport executor that decodes response envelopes and exposes useful metadata, including the HTTP status, KuCoin business code and message, request ID, rate-limit headers, and server timing headers. The SDK’s error hierarchy is designed to be inspected with Go’s native error helpers rather than parsed as text. 1

_, err := client.UTA.Market.GetTickers(ctx, market.TradeTypeSpot, "BTC-USDT" )
if errors.Is(err, transport.ErrRateLimited) {
    // Apply the application's backoff strategy.
}

var apiErr *transport.KucoinError
if errors.As(err, &apiErr) {
    fmt.Println(apiErr.HTTPStatus, apiErr.Code, apiErr.Message)
}

Its retry policy is conservative by design. It applies exponential backoff with jitter only to GET requests and bounds the total retry window. Write operations are not automatically retried. That distinction is important: reissuing a data lookup after a transient failure may be safe; reissuing a request that places, cancels, or amends an order can create a duplicate-action problem. The project makes the safer default explicit and leaves idempotency decisions with the application. 1

Authentication follows the same philosophy. The library includes an independently implemented HMAC-SHA256 signer for KuCoin authentication headers and validates it with known-answer fixture vectors. The README also recommends obtaining credentials from environment variables or a secret store, using the minimum permission required, and restricting keys by IP where the exchange supports it. 1

Documentation that is checked, not merely written

Many SDK repositories start with a good endpoint table and gradually lose the race between code changes and documentation. kucoin-go tries to remove that failure mode.

Its endpoint reference is generated from an internal manifest, internal/endpoints.yaml. Contributors update the manifest, regenerate docs/ENDPOINTS.md, and CI rejects a change if the generated file differs from the committed version. In addition, each exported method must link to the exact KuCoin documentation page that it implements. 2

The practical result is a highly useful question to ask before starting an integration: does the method exist here today? Rather than inferring coverage from a roadmap or package name, a developer can consult a concise list of supported methods, their account mode, HTTP method, permission requirement, test location, and a direct upstream documentation link. 2

Current scope: the honest version

This is an early, pre-1.0 Phase 1 checkpoint. Today, kucoin-go implements and tests UTA Market functionality only. It does not yet implement UTA account, order, position, leverage, or transfer operations; Classic Spot, Margin, and Futures coverage; or any WebSocket client. 1

The current coverage map contains ten UTA Market methods. Most are public read operations, while order-book retrieval is a notable exception: development smoke testing showed that GetOrderBook requires authentication and the General permission, despite appearing public alongside similar market-data endpoints. The SDK documents that requirement rather than letting users discover it at runtime. 2

Available now	Notes
`GetInstruments`, `GetTickers`, `GetKlines`, `GetTrades`	UTA market discovery and trading-data retrieval.
`GetCurrencies`, `GetCurrency`, `GetServiceStatus`, `GetAnnouncements`, `GetTradeStatistics`	UTA market and platform information.
`GetOrderBook`	Supported, but requires credentials with the `General` permission. 2
WebSockets, order placement, transfers, Classic APIs	Not implemented yet. 1

That candor is a feature, not a disclaimer hidden at the bottom of the page. A library that makes its limits obvious allows developers to select it appropriately: it is ready to support UTA market-data integration and not ready to run a production order-execution workflow.

Quick start: fetch a ticker without API credentials

Public market-data calls offer the fastest way to evaluate the SDK. The repository requires Go 1.22 or later and installs with the standard command below. 1

go get github.com/tigusigalpa/kucoin-go

The following example retrieves the latest price for the BTC-USDT spot symbol. Because this call is public, the client can be created without credentials. 1

package main

import (
    "context"
    "fmt"
    "log"

    kucoin "github.com/tigusigalpa/kucoin-go"
    "github.com/tigusigalpa/kucoin-go/uta/market"
)

func main() {
    client := kucoin.NewClient()

    tickers, err := client.UTA.Market.GetTickers(
        context.Background(),
        market.TradeTypeSpot,
        "BTC-USDT",
    )
    if err != nil {
        log.Fatal(err)
    }

    fmt.Println(tickers.List[0].LastPrice)
}

The example captures the intended ergonomics: the account model and domain are visible in the call path, request lifetime is represented by a context, and LastPrice remains an exact string until the application decides how to process it.

An invitation to shape the roadmap

The roadmap is organized around a reliable core first, then broader trading domains, then specialty capabilities such as funding, subaccounts, and additional KuCoin products. Contributions are welcome, particularly for a single missing REST endpoint accompanied by fixtures, tests, a documentation link, and an updated generated coverage entry. 1

If your project needs full API coverage now, start with the official SDK. If you need a compact Go client for UTA market data and want a codebase that favors clear constraints, typed boundaries, testability, and documentation fidelity, try kucoin-go.

Explore the repository, inspect the coverage map before integrating, and open an issue if the next endpoint on the roadmap is the one your project needs: github.com/tigusigalpa/kucoin-go.

kucoin-go is an unofficial community-maintained client. It is provided as-is and is not financial advice. Review the project’s security notice and test new integrations with least-privilege credentials before using them with funded accounts. 1

References

Introducing bitget-php: a production-grade PHP and Laravel SDK for Bitget UTA v3

Igor — Sun, 09 Aug 2026 09:21:11 +0000

PHP is a strong fit for dashboards, back-office systems, trading utilities, and event-driven services. Yet exchange integrations can still become the most fragile part of the stack. Developers must sign authenticated requests correctly, retain decimal precision, surface actionable API errors, and keep real-time connections healthy when a network or remote service interrupts them.

bitget-php is an open-source SDK that aims to make that boundary more dependable. It is a production-oriented PHP 8.2+ client for the Bitget Unified Trading Account (UTA) v3 API, with optional Laravel 10–13 integration. The project’s initial release focuses deliberately on a practical core: market data, account operations, trading operations, and a reconnecting WebSocket client. 1

The library is built for demo-first trading safety. Its own documentation recommends validating new code against Bitget demo credentials before connecting an application to a live account. 1

This article introduces the library from a developer’s perspective: what it covers today, how its design avoids several common integration pitfalls, and how it can become a stable starting point for a PHP-based Bitget integration.

The exchange-integration problem is more than HTTP

Calling an exchange endpoint may look like a simple POST or GET, but a production integration has a much wider responsibility. A client must consistently apply request signing, make error states intelligible to the application, avoid leaking API credentials through logs, and preserve the exact meaning of a decimal value. It also needs an operational model for real-time transport: what happens after a disconnect, and how does an application recover its subscriptions?

bitget-php addresses these concerns at the SDK layer. It uses Guzzle for HTTP transport and allows a GuzzleHttp\Client to be injected, which is helpful when testing, routing requests through a proxy, or applying project-specific transport configuration. It supports PSR-3 logging while using a no-op logger by default, and its documentation states that credentials are never logged. 1

Design concern	How `bitget-php` addresses it
Decimal values	Prices, quantities, PnL, and fee values are represented as strings rather than floats. 1
API failures	A typed exception hierarchy exposes specific application-level failure paths and the raw Bitget error code. 1
HTTP testing and customization	The Guzzle client is injectable instead of being fixed internally. 1
Observability	The SDK accepts a PSR-3 logger and defaults to `NullLogger`; credentials are not written to logs. 1
Real-time reliability	The WebSocket client maintains heartbeat handling, reconnection, and prior subscription recovery. 1
Framework flexibility	Laravel support is supplied without making Laravel a requirement for non-Laravel projects. 1

The approach to decimals deserves special attention. Binary floating-point values cannot precisely represent many decimal fractions, so silently converting exchange quantities or prices into PHP floats can change a value in ways that matter to accounting and order logic. By keeping API-facing numeric values as strings, the SDK leaves exact arithmetic under the developer’s control, including the option to use BCMath or another appropriate decimal strategy.

A modern PHP foundation without framework lock-in

The package requires PHP 8.2 or newer and uses strict typing throughout its codebase. It also uses readonly constructor properties, a small but important design choice that makes an object’s initialized dependencies harder to mutate accidentally. 1

Although the project offers first-class Laravel 10–13 conveniences—an auto-discovered service provider, publishable configuration, and a Bitget facade—the core SDK does not have a hard illuminate/* dependency outside of Laravel applications. 1 That distinction matters. A Laravel team can adopt the package with familiar configuration conventions, while a CLI worker, Symfony project, or framework-free PHP application can use the same client directly.

Installation is a single Composer command:

composer require tigusigalpa/bitget-php

For a Laravel application, credentials can live in configuration backed by environment variables. For a standalone service, they can be loaded through the project’s own secure configuration mechanism. In either case, API credentials should not be committed to source control or embedded into a front-end application.

Phase 1 REST coverage: the useful essentials

The project is transparent about its scope. Rather than implying that every endpoint in the Bitget UTA v3 surface is wrapped, it documents precisely which operations are included in Phase 1 and which are not. 2 That is a meaningful advantage for planning: teams can decide early whether the current surface matches their workflow rather than discovering a missing endpoint late in implementation.

Area	Supported SDK methods in Phase 1	Typical role
Public market data	`Market::getInstruments()`, `Market::getTickers()`, `Market::getOrderBook()`	Discover instruments, display prices, and obtain order-book data. 2
Private account operations	`Account::getAssets()`, `Account::getSettings()`, `Account::setLeverage()`	Read available assets and settings, then adjust leverage where supported. 2
Private trade operations	`Trade::placeOrder()`, `Trade::modifyOrder()`, `Trade::cancelOrder()`, `Trade::getOpenOrders()`, `Trade::getOrderHistory()`, `Trade::getPositions()`	Manage an order lifecycle and reconcile positions. 2

This is enough to support a well-defined first version of several products: a market-monitoring page, a controlled order-entry service, a bot that watches positions, or an internal trading-operations console. The SDK’s endpoint map also links every listed method to its corresponding Bitget API documentation, helping engineers trace an integration requirement from application code back to the exchange specification. 2

Equally important, the repository documents the current boundaries. In Phase 1, it does not include areas such as transfers, Trading Bot, Copy Trading, RFQ, Fiat, Finance/earn, batch orders, plan/trigger orders, or the other UTA v3 REST endpoints. 2 A reliable promotion should say this plainly: the library is a focused foundation, not an unsupported promise of complete coverage.

Safer order code starts in the demo environment

The project provides a direct demo-trading mode. When demoTrading: true—or the BITGET_DEMO=true setting—is used with Demo API credentials, REST requests include Bitget’s required paptrading: 1 header. The SDK also exposes demo public and private WebSocket URLs. 1

The following example follows the repository’s safety pattern. An order is both configured for demo trading and guarded by an explicit environment-variable opt-in. The intentionally distant limit price helps prevent an accidental fill during a test.

use Tigusigalpa\Bitget\Client;

$client = new Client(
    apiKey: config('bitget.api_key'),
    secretKey: config('bitget.secret_key'),
    passphrase: config('bitget.passphrase'),
    demoTrading: true,
);

// Do not send an order unless the explicit gate is enabled.
if (getenv('BITGET_ENABLE_TRADING') === '1') {
    $client->trade()->placeOrder([
        'category' => 'SPOT',
        'symbol' => 'BTCUSDT',
        'side' => 'buy',
        'orderType' => 'limit',
        'price' => '10000',
        'qty' => '0.001',
    ]);
}

That pattern does not replace testing, permissions management, risk limits, or review. It does, however, make the safer path easier to follow. A team can wire up application behavior in a simulated environment, exercise success and failure paths, and remove the deliberate gate only after it has made a conscious production decision.

Typed errors make recovery logic explicit

Exchange error handling should not collapse every failure into one generic exception. An invalid API key, a rate-limit response, insufficient funds, and an order lookup failure lead to very different recovery actions.

bitget-php exposes typed exceptions including AuthenticationException, RateLimitException, InvalidParameterException, InsufficientFundsException, and OrderNotFoundException. Each inherits from the SDK’s exception model and retains Bitget’s raw error code; a general BitgetException also gives access to the raw response. 1

use Tigusigalpa\Bitget\Exceptions\AuthenticationException;
use Tigusigalpa\Bitget\Exceptions\InsufficientFundsException;
use Tigusigalpa\Bitget\Exceptions\RateLimitException;
use Tigusigalpa\Bitget\Exceptions\BitgetException;

try {
    $client->trade()->placeOrder([/* order payload */]);
} catch (AuthenticationException $e) {
    // Rotate or correct credentials; do not retry blindly.
} catch (InsufficientFundsException $e) {
    // Notify the workflow that the required balance or margin is unavailable.
} catch (RateLimitException $e) {
    // Back off before retrying according to your application policy.
} catch (BitgetException $e) {
    // Record $e->bitgetCode and $e->rawResponse for diagnostics.
}

The value here is architectural. Application code can decide which failures are retriable, which should create an alert, and which should immediately stop a workflow. That leads to clearer observability and safer automation than a single catch-all branch.

Real-time data with reconnection built in

A WebSocket is often the right channel for reacting to market updates or private fill notifications, but it needs operational safeguards. The SDK’s WebsocketClient uses a pluggable ConnectionInterface. It ships with a synchronous textalk/websocket adapter, while projects using ReactPHP, Amp, or Laravel Octane can implement their own adapter for a non-blocking event loop. 1

Here is the documented shape of a public ticker subscription:

use Tigusigalpa\Bitget\WebsocketClient;

$ws = new WebsocketClient(WebsocketClient::DEFAULT_PUBLIC_URL);
$ws->connect();

$ws->subscribe([
    'instType' => 'SPOT',
    'topic' => 'ticker',
    'symbol' => 'BTCUSDT',
]);

$ws->listen(function (array $push) {
    echo json_encode($push), PHP_EOL;
});

listen() is a blocking call in the default synchronous transport. It responds to Bitget’s text-frame ping/pong heartbeat and, after an unexpected disconnection, reconnects with exponential backoff from one second to a 60-second cap before resubscribing every channel that was active. 1 This turns a raw socket connection into a more usable building block for long-running workers.

For private streams, credentials can be passed to the client constructor and connect() performs authentication. The repository includes a fast-fill example for UTA order-fill events. The subscription and listener are otherwise channel-agnostic, meaning a developer can subscribe to other Bitget channels by supplying the appropriate payload and decoding the returned array. The documentation is careful to distinguish that flexibility from endpoint-level support: beyond fast-fill, additional channel payloads are not separately wrapped or decoded by Phase 1. 1

A focused starting point for PHP teams

bitget-php is compelling because it concentrates on the reliability details that are easy to overlook: strings for API decimal fields, strict PHP conventions, injectable transport, typed exceptions, carefully handled logs, and a WebSocket client that tries to restore its prior state after a disconnect. It also does not conceal its roadmap. The public endpoint map makes current coverage visible and invites contributions to extend it. 1

If you are building a PHP or Laravel service around Bitget UTA v3, the library is worth evaluating in a demo environment first. Install it, inspect the endpoint map against your requirements, and use the documented examples to validate your authentication, error handling, and real-time design before any production rollout.

Visit the project on GitHub: tigusigalpa/bitget-php. Feedback, bug reports, and endpoint-coverage contributions are welcome through the repository. 1

This article is for software-development information only. It does not constitute investment, trading, or financial advice.

References

Introducing bitget-go: An Idiomatic Go SDK for Bitget UTA v3

Igor — Sun, 09 Aug 2026 06:33:12 +0000

Building a trading service in Go should mean spending time on execution logic, risk controls, and observability—not reimplementing request signatures, decoding generic JSON maps, or rebuilding WebSocket recovery loops for every project.

That is the problem bitget-go aims to solve. It is an open-source, idiomatic Go SDK for the Bitget Unified Trading Account (UTA) API v3, providing typed REST access to essential market, account, and trading operations alongside a reconnecting WebSocket client.1

The short version: bitget-go gives Go developers typed API models, context-aware network calls, exact string representations for financial values, and automatic WebSocket reconnection—while keeping the runtime dependency footprint intentionally small.1

This post looks at why those design decisions matter and how you can make your first request or stream market data in just a few lines of Go.

The friction behind a “simple” exchange integration

A raw exchange API integration tends to accumulate infrastructure code quickly. Authentication must match the exchange’s HMAC signing rules; query parameters and request bodies must be encoded exactly; remote errors need useful application-level handling; and persistent streaming connections need recovery after the inevitable network interruption. None of those concerns is the business logic of a trading system, but all of them can affect its reliability.

There is also a deceptively important data-modeling concern: numeric precision. Exchange payloads contain prices, quantities, PnL, and fees. Converting decimal values directly into binary float64 can introduce representation artifacts. For a trading application, it is often safer to preserve the exact wire value and perform arithmetic with math/big.Rat or a decimal package selected by the application.

bitget-go treats those operational details as first-class SDK responsibilities. It returns monetary and quantity fields as strings, exposes typed models rather than interface{}, and takes context.Context as the first argument of every network call.1

Common integration concern	How `bitget-go` addresses it
Request authentication	Signs REST requests and sets the required headers internally.1
Precision-sensitive values	Keeps prices, quantities, PnL, and fees as strings instead of coercing them to `float64`.1
Cancellations and deadlines	Accepts `context.Context` on every network call.1
Response parsing	Uses typed models and a generic `models.BitgetResponse[T]` envelope.1
Connection interruptions	Reconnects WebSockets with exponential backoff and restores subscriptions.1
Testability	Allows a custom `*http.Client` to be injected through functional options.1

The result is not a wrapper that hides Go’s standard idioms. Instead, it makes them central to the API.

A deliberately Go-native client

The SDK’s public surface is designed around conventions Go developers already expect. A REST client is constructed once, services are grouped by responsibility, and methods return typed values plus an error. If a caller cancels a context or its deadline expires, the cancellation flows through the request instead of being concealed behind a custom concurrency abstraction.1

The package also favors a lightweight dependency profile. According to its README, gorilla/websocket is the only required runtime dependency; stretchr/testify is used for tests.1 This is a sensible default for services where transparent dependency trees, quick builds, and straightforward vendoring matter.

Installation requires Go 1.21 or later and follows the usual Go module workflow:1

go get github.com/tigusigalpa/bitget-go

Your first REST request

The following example asks for the spot BTC/USDT ticker. Notice what is absent from the application: no manually constructed signature, no hand-written JSON response struct, and no float64 conversion for the reported last price.

package main

import (
    "context"
    "fmt"
    "log"
    "os"

    bitget "github.com/tigusigalpa/bitget-go"
    "github.com/tigusigalpa/bitget-go/models"
 )

func main() {
    client := bitget.NewRestClient(
        os.Getenv("BITGET_API_KEY"),
        os.Getenv("BITGET_SECRET_KEY"),
        os.Getenv("BITGET_PASSPHRASE"),
    )

    tickers, err := client.Market.GetTickers(
        context.Background(),
        models.CategorySpot,
        "BTCUSDT",
    )
    if err != nil {
        log.Fatal(err)
    }

    if len(tickers) > 0 {
        fmt.Printf("BTC/USDT last price: %s\n", tickers[0].LastPrice)
    }
}

The client signs the request, applies the relevant headers, parses the exchange response, and delivers typed ticker data to the caller.1 For a production service, replace context.Background() with a context that has an intentional deadline, so an obsolete request does not outlive the trading decision that initiated it.

REST coverage for the first phase

The project is candid about its current scope: Phase 1 focuses on core REST services plus WebSockets rather than claiming total endpoint coverage. That makes the package particularly useful for projects that need a strong foundation for market observation, account state, and order lifecycle management today.1

Area	Available methods in Phase 1	Typical application use
Market	`GetInstruments`, `GetTickers`, `GetOrderBook`	Discover instruments, display prices, evaluate liquidity.1
Account	`GetAssets`, `GetSettings`, `SetLeverage`	Read balances and configuration; update leverage where appropriate.1
Trade	`PlaceOrder`, `ModifyOrder`, `CancelOrder`, `GetOpenOrders`, `GetOrderHistory`, `GetPositions`	Implement an order workflow and monitor its outcome.1

The repository’s endpoint documentation is the authoritative place to check precise paths, request parameters, and the status of individual models before you depend on an endpoint in production.2

WebSockets that recover instead of merely connect

REST is ideal for commands and snapshots; it is not the preferred path for a real-time ticker or execution feed. A reliable streaming client needs to plan for unexpected disconnections. bitget-go provides both public and private WebSocket clients and exposes incoming pushes through Go channels.1

Here is a minimal public ticker subscription:

ws := bitget.NewPublicWSClient()

if err := ws.Connect(ctx); err != nil {
    log.Fatal(err)
}
defer ws.Close()

pushes, err := ws.Subscribe(ctx, models.WSArg{
    InstType: "SPOT",
    Topic:    "ticker",
    Symbol:   "BTCUSDT",
})
if err != nil {
    log.Fatal(err)
}

for push := range pushes {
    fmt.Println(string(push.Data))
}

For authenticated streams, create the client with NewPrivateWSClient(apiKey, secretKey, passphrase); authentication occurs during Connect.1 On an unexpected disconnect, the implementation retries with an exponential backoff beginning at one second and capped at 60 seconds, then resubscribes to channels opened earlier.1 The Phase 1 private channel is fast-fill; the same subscription and raw-data shape can be used for other available channels as the project expands.1

That recovery behavior is especially valuable in long-running worker processes. It reduces the amount of state-reconciliation code each consumer has to write, while still letting the application decide how it should process, persist, or validate the messages it receives.

Errors that work with the standard library

A good Go SDK should not force a bespoke error framework on its users. bitget-go returns regular Go errors: callers can use errors.Is with the package’s sentinel errors and errors.As to access a typed *BitgetError containing an API error code and message.1

_, err := client.Account.GetAssets(ctx)
if err != nil {
    if errors.Is(err, bitget.ErrUnauthorized) {
        log.Println("authentication failed — check credentials")
        return
    }

    var apiErr *bitget.BitgetError
    if errors.As(err, &apiErr) {
        log.Printf("Bitget error %s: %s", apiErr.Code, apiErr.Message)
        return
    }

    log.Printf("request failed: %v", err)
}

This small distinction improves operational handling. Authentication failures can be surfaced to configuration management, exchange business errors can be logged with their code, and network or timeout errors can follow a retry policy appropriate to the application.

Start with demo trading, not real funds

Trading code deserves a careful rollout. The SDK supports Bitget demo trading through bitget.WithDemoTrading(), which sends the paptrading: 1 header with REST requests.1 The included REST example additionally gates a trading action behind both BITGET_DEMO=1 and BITGET_ENABLE_TRADING=1, helping prevent accidental execution while exploring the codebase.1

client := bitget.NewRestClient(
    os.Getenv("BITGET_API_KEY"),
    os.Getenv("BITGET_SECRET_KEY"),
    os.Getenv("BITGET_PASSPHRASE"),
    bitget.WithDemoTrading(),
)

Important: Use demo API credentials when demo mode is enabled. The project documentation warns that combining demo mode with production credentials will fail.1

The client is also configurable without turning its constructor into a long, brittle parameter list. Functional options support a custom HTTP client, REST base URL, timeout, logger, locale, and demo mode.1 Injecting an *http.Client is particularly useful for tracing, proxies, custom TLS transport, and httptest-based unit tests.

client := bitget.NewRestClient(
    os.Getenv("BITGET_API_KEY" ),
    os.Getenv("BITGET_SECRET_KEY"),
    os.Getenv("BITGET_PASSPHRASE"),
    bitget.WithHTTPClient(&http.Client{
        Timeout:   30 * time.Second,
        Transport: myProxyTransport,
    } ),
    bitget.WithDemoTrading(),
)

The repository provides offline unit tests with go test ./... and optional demo-environment integration tests with go test -tags=integration ./... once demo credentials are configured.1

A practical foundation for Go trading systems

bitget-go does not attempt to prescribe a strategy, a database, or a trading architecture. Its value is more focused: it handles the exchange-integration mechanics so your application can keep ownership of the decisions that truly belong to it—risk limits, position sizing, persistence, monitoring, and execution policy.

The project is released under the MIT License and welcomes contributions, bug reports, and endpoint additions.1 If your stack also includes PHP or Laravel services, the author maintains a corresponding bitget-php SDK.1

If you are building Bitget UTA v3 integrations in Go, clone the repository, start with the runnable REST and WebSocket examples, and validate your workflow against demo credentials before any production rollout.

Repository: github.com/tigusigalpa/bitget-go

This SDK is not affiliated with Bitget. Trading involves risk; test carefully, protect API credentials, and never commit secrets to source control.

References

Building Robust Crypto Data Pipelines in PHP: Introducing the Token Terminal SDK

Igor — Sun, 09 Aug 2026 06:05:28 +0000

The cryptocurrency and decentralized finance ecosystems generate an overwhelming amount of data every single day. For developers building financial dashboards, algorithmic trading tools, or market research platforms, accessing clean, standardized, and reliable data is absolutely critical. Token Terminal has established itself as a premier provider of fundamental financial data for the crypto space, offering institutional-grade metrics across various blockchains and decentralized applications 1. However, integrating complex third-party APIs into enterprise PHP applications often requires writing significant amounts of boilerplate code to handle edge cases, rate limits, and unexpected response structures.

To solve this problem and streamline the developer experience, the PHP community now has access to a dedicated solution: the tokenterminal-php SDK. This new open-source package provides a robust, fully-typed, and developer-friendly PHP 8.1+ client for the Token Terminal API v2 2. Designed with modern PHP standards and framework integration in mind, it abstracts away the complexities of the underlying HTTP transport, allowing developers to focus entirely on building their applications rather than wrestling with API mechanics.

The Challenge of Integrating Financial APIs

When working with comprehensive financial data APIs like Token Terminal, developers frequently encounter several architectural challenges. First, there is the issue of rate limiting. Token Terminal enforces a strict limit of 1,000 requests per minute 3. When building data pipelines that ingest historical metrics across hundreds of assets, hitting this limit is practically guaranteed. A naive implementation will simply crash or drop data, requiring manual intervention.

Second, the cryptocurrency space moves rapidly. Projects frequently rebrand, merge, or migrate to new smart contracts. The Token Terminal API handles this gracefully by issuing HTTP 308 Permanent Redirects when a requested project ID has been renamed 3. However, standard HTTP clients often require explicit configuration to follow these redirects correctly while preserving the original request context and authentication headers.

Finally, there is the challenge of partial success. When requesting data for multiple metrics simultaneously, some metric IDs might be valid while others are deprecated or misspelled. A rigid API client might throw an exception and discard the entire response, forcing the developer to parse raw JSON to salvage the valid data. Building a robust client that gracefully handles these scenarios requires careful architectural planning and extensive testing.

Introducing the Token Terminal PHP SDK

The tokenterminal-php SDK was created specifically to address these integration challenges while providing a fluent, modern PHP interface. It acts as a comprehensive bridge between your PHP application and the Token Terminal infrastructure, ensuring that your data pipelines remain resilient and maintainable 2.

Comprehensive Endpoint Coverage

One of the primary strengths of the SDK is its complete coverage of the Token Terminal API v2. It supports all 24 documented endpoints out of the box. Whether you need to fetch a list of supported market sectors, retrieve deep financial statements for a specific decentralized protocol, or access specialized datasets like the crypto screener and insider transactions, the SDK provides a dedicated, strongly-typed method for the job.

API Domain	Available Data	Example SDK Method
Assets	Individual token metrics and historical data	`$client->assets()->historicalMetrics($id, $req)`
Projects	Protocol financial statements and aggregations	`$client->projects()->financialStatement($id, $req)`
Market Sectors	Categorized industry segments	`$client->marketSectors()->all()`
Metrics	Specific data points across the ecosystem	`$client->metrics()->data($id, $req)`
Datasets	Pre-compiled research and screening data	`$client->datasets()->cryptoScreener($req)`

Built for Resilience and Reliability

Reliability is paramount when dealing with financial data. The SDK implements sophisticated retry logic to ensure that transient network issues or rate limits do not disrupt your application flow. When the client encounters an HTTP 429 Too Many Requests response, or a 5xx server error, it automatically initiates a retry sequence using exponential backoff and jitter 2. Furthermore, it natively respects the Retry-After header provided by the Token Terminal API, ensuring that your application waits exactly as long as required before attempting the request again.

This resilience extends to how the SDK handles the aforementioned 308 redirects. If a project undergoes a rebranding and its identifier changes, the SDK transparently follows the redirect, retrieves the data using the new identifier, and returns the result to your application without requiring any code changes on your end.

Graceful Handling of Partial Success

Perhaps one of the most developer-friendly features of the tokenterminal-php package is its approach to partial success responses. When querying multiple metrics, Token Terminal may return valid data alongside an array of errors for the invalid parameters. Instead of throwing a generic exception and discarding the payload, the SDK encapsulates the response in an immutable TokenTerminalResult object.

This object allows developers to easily access both the successful data payload and the specific error details. You can iterate through the valid data to populate your database while simultaneously logging the errors for the invalid metric IDs, ensuring zero data loss during complex batch operations.

Getting Started with the SDK

Integrating the SDK into your project is straightforward. Because it relies on the PSR-18 standard for HTTP clients, it is highly decoupled and framework-agnostic. While Guzzle is provided as the default transport, you can easily substitute it with any PSR-18 compatible client of your choosing.

Installation is handled via Composer:

composer require tigusigalpa/tokenterminal-php

Once installed, initializing the client requires nothing more than your API key. You can instantiate it directly from your environment variables or build a custom configuration object.

use Tigusigalpa\TokenTerminal\TokenTerminalClient;

// Initialize the client using your API key
$client = TokenTerminalClient::make('your-api-key');

// Fetch all supported projects and iterate through the results
$result = $client->projects()->all();

foreach ($result->data() as $project) {
    echo $project['name'] . ' (ID: ' . $project['project_id'] . ")\n";
}

The configuration architecture is entirely immutable. If you need to adjust timeout settings or modify the retry behavior for a specific task, you can use the fluent with*() methods to generate a new configuration instance without altering the global state of your application.

Exception Handling

The SDK provides a granular exception hierarchy, allowing developers to catch and handle specific HTTP errors cleanly. Instead of parsing status codes manually, you can catch UnauthorizedException for invalid keys, RateLimitException for quota issues, or a general ApiException as a fallback.

use Tigusigalpa\TokenTerminal\Exceptions\RateLimitException;
use Tigusigalpa\TokenTerminal\Exceptions\NotFoundException;

try {
    $result = $client->projects()->get('uniswap');
} catch (RateLimitException $e) {
    // The SDK handles retries automatically, but if max attempts are exceeded:
    echo "Rate limit exceeded. Try again after: " . $e->getRetryAfter();
} catch (NotFoundException $e) {
    echo "Project not found in the Token Terminal registry.";
}

First-Class Laravel Integration

While the SDK is perfectly suited for vanilla PHP applications, it truly shines when integrated into the Laravel ecosystem. The package includes auto-discovery, meaning the service provider and facade are registered automatically upon installation.

Laravel developers can publish the configuration file to their config directory and manage their API credentials directly through the standard .env file. Once configured, accessing the Token Terminal API becomes as simple as calling the facade from anywhere in your application:

use Tigusigalpa\TokenTerminal\Laravel\Facades\TokenTerminal;

// Fetch the revenue breakdown for Uniswap
$metrics = TokenTerminal::projects()->metricAggregations('uniswap');

This zero-configuration approach significantly reduces the time to market for Laravel-based financial applications and analytics dashboards.

Conclusion

Building reliable data pipelines in the cryptocurrency space requires tools that can handle the unique challenges of the ecosystem. The tokenterminal-php SDK provides PHP developers with a powerful, resilient, and elegant solution for integrating Token Terminal's comprehensive financial data into their applications. By abstracting away rate limits, redirects, and complex error handling, it allows you to focus on extracting insights and delivering value to your users.

If you are building data-driven applications in PHP, we highly encourage you to explore the package. You can view the source code, read the extensive documentation, and contribute to the project on GitHub.

Explore the repository: tigusigalpa/tokenterminal-php on GitHub

References

Build Resilient Web3 Data Pipelines in Go with tokenterminal-go

Igor — Wed, 05 Aug 2026 12:32:12 +0000

When a Go application needs on-chain and protocol-level data, the HTTP request itself is usually the easy part. The difficult work starts afterward: defining request models, decoding inconsistent payloads, respecting rate limits, recovering from transient failures, and deciding what to do when one part of a multi-metric query succeeds while another part does not. Those concerns can quietly turn a small integration into a maintenance burden.

tokenterminal-go is an open-source, production-oriented Go SDK for Token Terminal API v2 that aims to remove that plumbing. The project supports all 24 documented API routes across Assets, Projects, Market Sectors, Metrics, and Datasets; it requires Go 1.21 or newer and uses only the Go standard library. 1 It is a focused choice for engineers building internal analytics services, data jobs, dashboards, research tooling, or any application that needs Token Terminal data without hand-rolling an HTTP client.

The practical promise: keep the integration idiomatic and type-aware, while the client handles the failure modes that normally appear only after an application reaches real traffic.

Why an SDK matters here

Token Terminal’s API gives programmatic access to its data, but it requires an API key and an API-enabled plan. 2 That makes the client layer part of the application’s operational surface: it needs to handle credentials, request timeouts, rate limits, pagination or filtering parameters where relevant, and failures that should not crash a larger data pipeline.

The library addresses these needs with a small, deliberate design. Its client methods take a context.Context, its response envelopes use generic Result[T] types, and its errors can be inspected with standard Go mechanisms such as errors.Is and errors.As. 1 In other words, callers can keep control of cancellation and business policy instead of receiving opaque, string-only errors.

Capability	What it means in practice	Why it is useful
Zero external dependencies	The package uses the standard library rather than adding third-party runtime packages. 1	A smaller dependency surface makes the SDK easier to audit, vendor, and upgrade.
Type-safe API models	Typed request structures and generic `Result[T]` envelopes are used across the client. 1	Editors provide better completion, and more mistakes are caught before a request is sent.
Context-aware calls	Every client method accepts `context.Context`. 1	A service can enforce deadlines or stop in-flight work when a request is cancelled.
Retry with backoff	GET requests can be retried for rate limiting, server errors, and transient network failures. 1	Temporary failures are less likely to become application-visible outages.
Partial-success preservation	Valid `data` and API-supplied `errors` are both retained in the result. 1	A single invalid metric does not have to discard all usable data from the same response.
Concurrency-safe client	One `Client` may be shared safely across goroutines. 1	Parallel collection jobs do not need to create a separate client for each worker.

A fast path from API key to useful data

Installing the package follows the normal Go workflow:

go get github.com/tigusigalpa/tokenterminal-go

The client can be created with an API key, environment-driven configuration, or functional options. The repository documents options for the base URL, a custom HTTP client, timeout, retry count and delay, User-Agent, and opt-in POST retries. 1 The following example is adapted from the project’s historical-metrics example. It requests Uniswap fees and revenue on Ethereum for a specified time range, then prints any partial issues rather than throwing away the successful data. 3

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "time"

    tt "github.com/tigusigalpa/tokenterminal-go"
)

func main() {
    apiKey := os.Getenv("TOKEN_TERMINAL_API_KEY")
    if apiKey == "" {
        log.Fatal("TOKEN_TERMINAL_API_KEY is not set")
    }

    client, err := tt.NewClient(
        apiKey,
        tt.WithTimeout(15*time.Second),
        tt.WithRetry(3, time.Second),
    )
    if err != nil {
        log.Fatalf("create client: %v", err)
    }

    start, _ := tt.NewDate("2025-01-01")
    end, _ := tt.NewDate("2025-01-31")

    result, err := client.Projects.HistoricalMetrics(
        context.Background(),
        "uniswap",
        &tt.HistoricalMetricsParams{
            MetricIDs:      []string{"fees", "revenue"},
            ChainIDs:       []string{"ethereum"},
            Start:          &start,
            End:            &end,
            OrderDirection: tt.OrderAscending,
        },
    )
    if err != nil {
        log.Fatalf("load historical metrics: %v", err)
    }

    fmt.Printf("received %d data points\n", len(result.Data))
    for _, issue := range result.Errors {
        fmt.Printf("partial issue: %s %s=%s\n", issue.Code, issue.Field, issue.Value)
    }
}

This is the essential advantage of the SDK: the application code describes the question—which project, which chain, which metrics, which dates—rather than manually assembling URLs and decoding generic maps. The parameter structure makes filters explicit, while the Result object gives callers access to both the returned data and granular API feedback. 1

Coverage without a maze of wrappers

tokenterminal-go does not stop at a single “get metrics” helper. The repository’s endpoint coverage map groups the 24 routes into five service areas. 1 That makes the SDK suitable for broader workflows that need reference data, detailed time series, aggregates, and curated datasets in the same Go codebase.

Service area	Representative SDK methods	Typical use case
Assets	`client.Assets.List`, `Get`, `HistoricalMetrics`, `MetricsBreakdown`	Discover assets and examine an asset’s historical or aggregated metrics. 1
Projects	`client.Projects.List`, `Get`, `HistoricalMetrics`, `FinancialStatement`	Build protocol research pages, compare projects, or load financial statement data. 1
Market Sectors	`client.MarketSectors.List`, `Get`	Organize projects and assets by market sector. 1
Metrics	`client.Metrics.List`, `Data`, `Aggregations`, `Breakdown`	Query available metrics and retrieve detailed or summarized observations. 1
Datasets	`client.Datasets.CryptoScreener`, `CohortAnalysis`, `TrendingContracts`, and others	Start with curated screens and specialized analytical datasets. 1

This breadth matters because application needs evolve. A first version of a dashboard may list projects and draw one time series. A later version may need a screener, an aggregation view, or a financial-statement endpoint. With the same client abstraction across these areas, the transition does not require introducing a second API integration pattern.

Reliability is a feature, not an afterthought

A resilient client should have predictable behavior under pressure. By default, tokenterminal-go retries GET requests after HTTP 429 responses, 5xx responses, and transient network errors. It uses capped exponential backoff with jitter and honors a server-provided Retry-After header. POST retries are intentionally disabled unless the application explicitly enables them with WithRetryPOST(). Context cancellation stops retry waits immediately. 1

That policy is a strong default for data retrieval: reads are commonly safe to retry, while automatic retries of requests that may change server state deserve an explicit decision. It is also aligned with Token Terminal’s documentation, which calls out HTTP 429 as the rate-limit status that clients should handle. 4

The error model is equally practical. Instead of forcing consumers to compare error strings, the SDK exports sentinel values such as ErrUnauthorized, ErrNotFound, and ErrRateLimited, plus an *APIError that exposes structured details including status code, message, and retry information. 1 A caller can therefore implement a clear policy without coupling its business logic to the client’s internal wording.

if _, err := client.Projects.List(ctx); err != nil {
    switch {
    case errors.Is(err, tt.ErrUnauthorized):
        // Refresh configuration or surface a credential error.
        log.Println("check the Token Terminal API key")

    case errors.Is(err, tt.ErrRateLimited):
        var apiErr *tt.APIError
        if errors.As(err, &apiErr) {
            log.Printf("rate limited; retry after %s", apiErr.RetryAfter)
        }

    case errors.Is(err, tt.ErrNotFound):
        log.Println("project, asset, or metric was not found")

    default:
        log.Printf("Token Terminal request failed: %v", err)
    }
}

The SDK also follows HTTP 308 redirects, which the project documents as a way to handle project or asset renames transparently. 1 That is the kind of edge case developers rarely enjoy discovering after a production identifier changes.

Preserve partial results instead of losing a whole response

One of the more thoughtful details in tokenterminal-go is its treatment of partial success. Some Token Terminal responses can contain valid data alongside an errors array. The SDK keeps both. 1 This matters when a query asks for several metrics, chains, or entities: one unsupported input should not automatically erase the observations that were returned successfully.

A production workflow can turn this into a useful policy. Persist result.Data, emit structured logs or metrics for result.Errors, and alert only when the missing values break a required business rule. This approach is more robust than treating every non-empty error array as a total failure, and it gives downstream consumers a transparent view of data completeness.

Pair the SDK with Token Terminal’s API guidance

The SDK gives Go applications a sound transport and type layer; efficient data architecture is still the caller’s responsibility. Token Terminal recommends maintaining an up-to-date cache or index for /projects and /metrics, refreshing it daily or weekly according to the application’s needs. 4

“Maintain an up-to-date cache of projects and metrics.” — Token Terminal API best practices 4

That guidance fits naturally with tokenterminal-go. Fetch the project and metric catalogs on a schedule that matches your product, store them in your preferred cache or database, and use those local records to validate user-selected identifiers before issuing more focused API calls. The SDK intentionally does not impose an invisible persistent cache; the repository documents an optional integration point so an application can choose its own caching strategy. 1

For aggregate questions, Token Terminal also advises using the Breakdown API instead of first downloading a time series and aggregating it client-side. According to the official guidance, that can reduce transferred data and improve response time. 4 In the SDK, the relevant methods are exposed as client.Metrics.Breakdown and client.Assets.MetricsBreakdown, so the optimization is available without abandoning the same typed client model. 1

Built for normal Go engineering practices

The project includes dedicated examples for basics, historical project metrics, metric breakdowns, datasets, error handling, and concurrent calls. 1 It also documents conventional validation commands, including go test ./... -v, go test -race ./..., gofmt -l ., and go vet ./.... Its tests use httptest.Server rather than calling the live Token Terminal API. 1 That is a welcome design choice for teams that want deterministic tests and no hidden network dependency in their CI pipelines.

The package is published under the MIT license, so it is straightforward to evaluate and incorporate into an appropriate open-source or commercial Go project. 1

Give your Go code the API client it deserves

Reliable Web3 analytics infrastructure is not just about obtaining the right endpoint. It is about handling latency, retries, cancellation, redirects, structured errors, partial results, and concurrent workload patterns without distracting from the product you are actually building.

tokenterminal-go packages those operational details into a concise, zero-dependency SDK for Token Terminal API v2. If your Go service needs project metrics, asset data, sector information, or specialized datasets, it is worth exploring the repository, running the examples, and adapting the client to your own pipeline.

Start here: github.com/tigusigalpa/tokenterminal-go. If the SDK saves your team implementation time, consider starring the project, opening an issue with feedback, or contributing an improvement.

References

Stop Hand-Rolling HTTP Clients for Glassnode: Meet glassnode-go

Igor — Fri, 31 Jul 2026 11:50:23 +0000

Building with on-chain data is exciting right up until the integration work begins. A dashboard, research tool, alerting service, or backtesting pipeline may start with one metric, but it rarely stops there. Soon you are assembling request URLs by hand, decoding JSON into map[string]interface{}, checking every response for rate-limit headers, and adding retry logic that you hope will not become the next production incident.

That glue code is necessary, but it is not where a product becomes valuable. glassnode-go is designed to move that plumbing out of the way. It is an unofficial, community-built Go SDK for the Glassnode Basic API, aimed at developers who want a more idiomatic and production-oriented integration layer. It is not affiliated with or endorsed by Glassnode; it is a focused tool for teams that would rather build with on-chain data than continually maintain HTTP wrappers around it. 1

“A dependency-light, production-oriented Go module for the Glassnode Basic API, built with the kind of care you'd want from a library you depend on every day.” — the glassnode-go project README 1

The problem is not fetching a number—it's operating the integration

A raw API integration can fetch a price just fine. The difficult part begins when the application has to do it reliably: propagate cancellations through context.Context, protect the API key, distinguish bad input from an exhausted quota, tune timeouts, and retrieve multiple metrics concurrently without turning the client layer into a fragile tangle of helpers.

glassnode-go approaches that problem with a deliberately Go-native design. The module targets Go 1.21+ and declares no third-party module dependencies, keeping the integration limited to the standard library rather than adding transitive packages to the project. 1 Its client uses functional options for configuration, supports custom HTTP transports, and is documented as safe for concurrent use across goroutines. 1

What a data service needs	What `glassnode-go` provides	Why it matters
Familiar, discoverable access to standard metrics	25 typed category services such as `Market`, `Addresses`, `Indicators`, `Mining`, and `Transactions`	Code is easier to navigate, review, and autocomplete. 1
A way to reach newly introduced or unusual endpoints	A generic `MetricsService` for raw JSON, scalar time series, and object time series	You do not have to wait for a typed wrapper to start experimenting. 1
Clarity before making requests	Runtime metadata methods for assets, metric paths, and supported parameters	Fewer invalid requests and less guesswork around endpoint capabilities. 1
Resilience under load	Automatic handling of HTTP 429 responses and configurable retry behavior	Rate-limit logic stays centralized instead of leaking into every call site. 1
Safer operations	Header-based API-key authentication by default and redaction in URLs and error messages	Secrets are less likely to appear in logs and diagnostics. 1

Start with a useful result, not a pile of boilerplate

Installation is a familiar Go command:

go get github.com/tigusigalpa/glassnode-go

The quick-start experience is intentionally small. Put your Glassnode API key in GLASSNODE_API_KEY, create the client from the environment, and request the metric through a typed service. The following example retrieves BTC price data at daily resolution. 1

package main

import (
    "context"
    "fmt"
    "log"

    glassnode "github.com/tigusigalpa/glassnode-go"
)

func main() {
    client, err := glassnode.NewClientFromEnv()
    if err != nil {
        log.Fatal(err)
    }

    ctx := context.Background()
    price, err := client.Market.Price(ctx, &glassnode.MetricQuery{
        Asset:      "BTC",
        Resolution: glassnode.Resolution24h,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, point := range price {
        fmt.Printf("BTC price at %d: $%.2f\n", point.T, point.V)
    }
}

The important detail is not merely that the example is short. It encodes a useful boundary: application code talks in terms of market data and queries, while the SDK takes responsibility for building the request, applying authentication, decoding the response, and returning a typed time series. That separation makes a dashboard handler, scheduled research job, or backtest easier to test and evolve.

Typed when you can; generic when you need to

The primary API surface is made of category services that mirror Glassnode's documented endpoint families. For example, a dashboard can request OHLC data from client.Market.PriceOHLC, activity data from client.Addresses.ActiveCount, and an indicator such as SOPR from client.Indicators.SOPR. The repository maintains an endpoint-coverage document that maps API paths to the corresponding SDK methods. 1

But strongly typed wrappers should never become a release-cycle bottleneck. APIs evolve, new metrics appear, and some response shapes are inherently specialized. For those moments, glassnode-go supplies the generic MetricsService. It can return raw JSON through Get, scalar time-series data through GetTimePoints, or object time-series data through GetObjectPoints. 1

// Use a valid metric path even when you do not need a dedicated convenience method.
data, err := client.Metrics.GetTimePoints(ctx, "/indicators/sopr", &glassnode.MetricQuery{
    Asset:      "BTC",
    Resolution: glassnode.Resolution24h,
})
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Received %d SOPR observations\n", len(data))

That combination is especially useful in real products. Your stable, frequently used calls can remain concise and self-documenting; exploratory work, internal analytics, and recently introduced paths can still proceed without compromising the client architecture.

Discover capabilities before you spend requests

Metric paths alone do not tell the whole story. A query may support different resolutions, assets, bulk access, currencies, or time formats depending on the underlying endpoint. Guessing at those parameters often results in failed calls that are hard to diagnose in a busy service.

glassnode-go exposes a metadata layer for exactly this reason. The MetadataService can list supported assets, discover metric paths, and inspect a metric's available parameters at runtime. The SDK documentation recommends this metadata-first workflow before making data calls. 1

metric, err := client.Metadata.Metric(ctx, "/market/price_usd")
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Metric: %s\n", metric.Description)
fmt.Printf("Supported resolutions: %v\n", metric.Resolutions)

For a product team, this is more than a convenience. It lets a configuration screen, query builder, or data pipeline validate its choices against the API instead of embedding assumptions that eventually become stale.

Rate limits deserve first-class engineering

A high-quality SDK should make the correct behavior the default behavior. In glassnode-go, HTTP 429 responses trigger automatic retries for idempotent GET requests. The client uses the x-rate-limit-reset header when the server supplies it and falls back to exponential backoff when it does not. It avoids retrying 400, 401, and 404 responses because those represent problems a retry is unlikely to fix. Retry behavior can be configured with WithRetry. 1

This decision is quietly powerful. Every endpoint call retains the same clean shape, while the behavior that protects the service is standardized in one place. When the retry budget is exhausted, the caller still gets actionable context through the exported APIError type and the ErrRateLimited sentinel. 1

_, err := client.Indicators.SOPR(ctx, &glassnode.MetricQuery{Asset: "BTC"})
if err != nil && errors.Is(err, glassnode.ErrRateLimited) {
    var apiErr *glassnode.APIError
    if errors.As(err, &apiErr) {
        log.Printf("Rate limit exhausted; reset in %ds", apiErr.RateLimitReset)
    }
}

The same philosophy applies to the rest of the error model. The package exposes sentinel errors for conditions such as bad requests, unauthorized access, missing metric paths, rate limits, and internal server errors. That gives callers the familiar errors.Is and errors.As workflow rather than forcing production code to branch on error-message strings. 1

Security should not be an afterthought

An API key is an operational secret, not a configuration string that belongs in source code or a query URL. The library defaults to the X-Api-Key header mode and supports query-string authentication only as an explicit opt-in for exceptional environments. It also documents API-key redaction in URLs, response metadata, and error messages. 1

The recommended developer experience is therefore straightforward: keep the key in GLASSNODE_API_KEY, construct the client with NewClientFromEnv(), and let the client carry the secret in headers. It is a small convention with a meaningful payoff in log hygiene and incident response.

Built for dashboards today—and historical research tomorrow

The SDK is not limited to a single-metric dashboard. Its BulkQuery support can request data for explicitly specified multiple assets in one call, reducing round trips where the underlying metric supports bulk access. The project documentation also notes that the cost model remains per asset, so bulk requests optimize throughput rather than magically reducing credit consumption. 1

For researchers, the Point-in-Time API is another standout capability. PIT response models preserve a computed_at timestamp alongside the observation timestamp. This matters when historical metric values may later be revised: a backtest can distinguish what the current dataset says from what was known at a particular historical moment. The SDK offers typed PIT response models and generic point-in-time methods for that workflow. 1

Use case	A practical `glassnode-go` path
Market dashboard	Typed `Market`, `Indicators`, and `Addresses` services for the metrics displayed most often. 1
Multi-asset research job	`Metrics.GetBulk` with explicit asset lists, plus metadata checks before the request. 1
API explorer or no-code query builder	`Metadata.Assets`, `Metadata.Metrics`, and `Metadata.Metric` to populate valid options dynamically. 1
Strategy backtesting	Point-in-Time response models that retain `computed_at` for historically aware analysis. 1
Custom or newly added endpoint	`Metrics.Get`, `GetTimePoints`, or `GetObjectPoints` with a valid metric path. 1

The developer experience is the feature

glassnode-go does not try to hide Glassnode behind a proprietary abstraction. Instead, it gives Go developers a reliable, conventional way to work with the Basic API: typed services for everyday endpoints, generic access when flexibility is needed, metadata for discovery, and production-minded defaults for context propagation, concurrency, security, and retries. The project's initial v1.0.0 release documents these capabilities along with typed response models, configurable transport options, and a mocked-transport test suite. 2

If your next Go project needs on-chain metrics, take the SDK for a spin, browse the examples, and consider contributing an issue, documentation improvement, or pull request. The repository is MIT licensed and welcomes contributions. 1

Repository: github.com/tigusigalpa/glassnode-go

Note: This post discusses developer tooling for accessing data. It is not investment, trading, or financial advice.

References

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

Igor — Thu, 30 Jul 2026 16:41:15 +0000

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

Stop Fighting the CryptoPanic API: Meet cryptopanic-php, the Modern PHP SDK

Igor — Wed, 29 Jul 2026 14:42:43 +0000

Integrating a news aggregator API into your application often sounds straightforward. You just need to pull a few endpoints, parse some JSON, and display the results. However, when working with financial data platforms like CryptoPanic, the reality quickly becomes complicated. You find yourself writing boilerplate code for authentication, handling evolving response schemas, implementing retry logic for rate limits, and managing pagination state. Every project seems to demand the same tedious plumbing.

The CryptoPanic API is an incredibly powerful resource for developers building crypto trackers, trading bots, and portfolio dashboards. Yet, consuming it cleanly in PHP has historically required developers to reinvent the wheel. This is where cryptopanic-php steps in. It is a modern, framework-neutral PHP SDK designed to make fetching crypto news, managing portfolios, and consuming RSS feeds an elegant experience.

In this article, we will explore why you should stop fighting raw cURL requests and start using cryptopanic-php to build robust crypto applications.

Why Another SDK?

When integrating external services, the goal is to spend time building business logic, not wrestling with HTTP clients. cryptopanic-php was built with modern PHP practices in mind, targeting PHP 8.1 and above. It provides a typed, predictable, and safe interface to the CryptoPanic API repo.

Typed Response Models

Instead of dealing with anonymous arrays returned by json_decode(), the SDK maps known response shapes into strictly typed objects. When you request a page of posts, you receive a PostsPage object containing an array of Post instances. Each Post exposes properties like title, source, votes, and publication dates parsed into DateTimeImmutable objects. This allows your IDE to provide accurate autocompletion and static analysis tools like PHPStan to catch errors before they reach production repo.

Safe and Immutable Design

Security and predictability are paramount when handling API tokens. The SDK ensures that your authentication token is never included in exception messages or data dumps. Furthermore, when the API returns pagination URLs, the SDK automatically redacts the token from them repo.

The core components, such as CryptoPanicConfig and PostsQuery, are designed as immutable value objects. When you need to request the next page or modify a filter, you use the with() method to create a new instance without mutating the original state. This functional approach eliminates side effects and makes your code easier to reason about repo.

Robust Error Handling and Retries

Network requests fail, and APIs enforce rate limits. cryptopanic-php abstracts these challenges with a rich exception hierarchy. Instead of catching generic HTTP errors, you can handle specific scenarios:

Situation	Dedicated exception	Practical response
Invalid or missing token	`UnauthorizedException`	Refresh or replace the credential without exposing it in application logs.
Plan-restricted endpoint	`ForbiddenException`	Adjust the workflow or verify account access before retrying.
Request quota exceeded	`RateLimitException`	Respect the available `retryAfter` guidance and slow down.

These explicit failure modes make it easier to implement intentional recovery paths rather than treating every unsuccessful request as the same generic error repo.

Moreover, the SDK includes configurable retry logic with exponential backoff. You can instruct the client to automatically retry transient failures like HTTP 429 (Too Many Requests) or 502 (Bad Gateway) without writing a custom retry loop repo.

Getting Started

Installing the package is as simple as running a Composer command. The SDK requires PHP 8.1+, ext-json, and ext-curl repo.

composer require tigusigalpa/cryptopanic-php

Framework-Neutral Usage

If you are building a plain PHP worker or a Symfony service, you can initialize the client using environment variables. Keep your token secure in your environment:

export CRYPTOPANIC_AUTH_TOKEN="your-super-secret-token"

Then, instantiate the client and fetch a page of posts filtered by specific currencies:

<?php

declare(strict_types=1);

use Tigusigalpa\CryptoPanic\CryptoPanicClient;
use Tigusigalpa\CryptoPanic\PostsQuery;
use Tigusigalpa\CryptoPanic\Enums\Filter;

$client = CryptoPanicClient::fromEnv();

$query = new PostsQuery(
    currencies: ['BTC', 'ETH'],
    filter: Filter::Rising,
    page: 1,
);

$page = $client->posts($query);

foreach ($page->results as $post) {
    printf("[%s] %s\n", $post->kind ?? 'unknown', $post->title ?? 'Untitled');

    if ($post->publishedAt !== null) {
        echo 'Published: ' . $post->publishedAt->format(DATE_ATOM) . PHP_EOL;
    }
}

The PostsQuery object validates your parameters locally, ensuring you do not send malformed requests. It also uses backed enums for known filters and kinds, while remaining flexible enough to accept custom strings for forward compatibility repo.

First-Class Laravel Integration

While the SDK is framework-neutral, it shines particularly bright in Laravel applications. The package includes an auto-discovered service provider that registers the client as a singleton, merges configuration, and provides a convenient Facade repo.

After installation, you can publish the configuration file:

php artisan vendor:publish --tag=cryptopanic-config

Add your credentials to your .env file:

CRYPTOPANIC_AUTH_TOKEN=your-token
CRYPTOPANIC_API_PLAN=growth
CRYPTOPANIC_TIMEOUT=15
CRYPTOPANIC_RETRY_ATTEMPTS=3
CRYPTOPANIC_RETRY_DELAY=1

You can now inject the CryptoPanicClient directly into your controllers or use the Facade for rapid development:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Tigusigalpa\CryptoPanic\Enums\Filter;
use Tigusigalpa\CryptoPanic\Laravel\Facades\CryptoPanic;
use Tigusigalpa\CryptoPanic\PostsQuery;

class CryptoNewsController extends Controller
{
    public function index(): JsonResponse
    {
        $page = CryptoPanic::posts(new PostsQuery(
            currencies: ['SOL', 'ADA'],
            filter: Filter::Important,
        ));

        return response()->json($page->results);
    }
}

The service provider defers network connections until you actually make a request, ensuring it does not impact your application's boot time repo.

Advanced Capabilities

The SDK is not limited to just fetching JSON posts. It provides comprehensive coverage of the CryptoPanic API surface.

Handling Unstable Schemas

Some API endpoints, like the Portfolio endpoint, do not have a strictly defined public schema. Instead of guessing domain fields and risking breakages when the API evolves, the SDK returns a PortfolioResponse where the raw property contains the decoded JSON. This treats the unstable endpoint as an integration boundary, allowing you to map the data into your own DTOs repo.

$portfolio = $client->portfolio();
// Inspect the raw array and map it to your application's needs
$data = $portfolio->raw;

Raw RSS Access

If your application relies on XML feeds, the SDK provides dedicated methods for the RSS endpoints. Methods like postsRss() and newsRss() return an RSSResponse containing the raw XML body, allowing you to stream it directly or parse it with your preferred XML library repo.

$feed = $client->newsRss();
header('Content-Type: application/rss+xml');
echo $feed->body;

Flexible Transports

By default, the SDK uses a lightweight cURL transport to minimize dependencies. However, if your application already standardizes on PSR-18 HTTP clients (like Guzzle), you can inject your preferred client and request factory repo.

use GuzzleHttp\Client;
use GuzzleHttp\Psr7\HttpFactory;
use Tigusigalpa\CryptoPanic\CryptoPanicClient;
use Tigusigalpa\CryptoPanic\CryptoPanicConfig;

$client = new CryptoPanicClient(
    config: CryptoPanicConfig::fromEnv(),
    psrClient: new Client(),
    requestFactory: new HttpFactory(),
);

This flexibility ensures that cryptopanic-php plays nicely with your existing logging, middleware, and mocking strategies.

Navigating API Plans

It is important to note that the CryptoPanic API operates on a tiered plan system. Its public documentation labels the free Developer API plan as discontinued, so you should verify the current commercial details in your CryptoPanic account rather than assume free access is available api. Feature availability is determined by CryptoPanic, not by the SDK.

API capability	Current plan note in the public API reference
`portfolio()`	Listed for Growth and Enterprise plans.
`size`, `with_content`, and `search`	Listed as Enterprise-gated parameters.
RSS responses	Documented as returning 20 items regardless of API plan.

These constraints come from the API provider and may change; the package surfaces the response cleanly while preserving CryptoPanic as the authority for account entitlements repo.

The SDK validates obvious syntax locally but defers to CryptoPanic for account entitlements. If you attempt to use a feature outside your plan, the SDK will gracefully throw a ForbiddenException, allowing your application to handle the restriction cleanly repo.

Conclusion

Building applications around financial news requires reliability and precision. cryptopanic-php delivers both by abstracting the complexities of the CryptoPanic API behind a modern, strictly typed, and developer-friendly interface. Whether you are orchestrating background workers in plain PHP or building a rapid prototype in Laravel, this SDK provides the tools you need to succeed.

Stop writing boilerplate API wrappers and start focusing on your application's unique value. Check out the cryptopanic-php repository on GitHub, explore the source code, and give it a star if it saves you time on your next crypto project.

References

repo
api

Stop Plumbing Crypto News APIs by Hand: Introducing cryptopanic-go

Igor — Wed, 29 Jul 2026 09:16:08 +0000

Building a crypto-facing product in Go can begin with a deceptively small task: fetch a news feed, filter it for a few assets, and surface the result in a dashboard, worker, or command-line tool. The integration becomes much less small once the production concerns arrive. You need a versioned API path, authenticated requests, query encoding, typed decoding, deadlines, pagination, useful failures, and a safe policy for transient outages.

The upstream CryptoPanic API exposes a posts endpoint with filters for currencies, regions, content kind, and pagination, and it requires an authentication token for requests.2 That is an entirely reasonable HTTP API. The question for a Go team is whether each application should rebuild the same integration layer around it.

cryptopanic-go is a focused answer to that question: a production-oriented Go SDK for the CryptoPanic API. Rather than wrapping the API in a framework or inventing business abstractions, it supplies a small, typed, context-aware client that is appropriate for services, background workers, and CLI tools.1

“The SDK deliberately stays close to the public CryptoPanic API. It does not invent a portfolio schema, hide server-side plan rules, or force a framework on your application.” — cryptopanic-go README 1

This article shows what that design buys you, how to get started, and where the SDK fits in a production Go codebase. It discusses integration engineering, not trading strategy or financial advice.

The problem is not making one HTTP request

A raw net/http request is often the correct first prototype. But the moment a crypto-news feature becomes part of a real product, the surrounding code tends to spread across handlers, workers, and scripts. Each call site may have to reconstruct the API URL, serialize filters, decode a response, decide what to retry, and avoid logging secrets. Those are all solvable problems—but they are poor places to spend the same engineering effort repeatedly.

The API itself returns next, previous, and results in a posts response.2 A generic client leaves your application responsible for interpreting those values, including making sure an authentication token in an upstream URL never makes it into a log line. Likewise, upstream permissions and plan-gated parameters remain important even when your request code is concise. A useful SDK should reduce boilerplate without concealing those operational realities.

Integration concern	What repetitive hand-written code must handle	What `cryptopanic-go` provides
Request construction	API plan paths, query encoding, and optional filters	`PostsQuery`, typed constants, and configurable client options.1
Request lifetime	Cancellation and an operation-specific deadline	A `context.Context` on every network-facing method.1
Sensitive data	Avoiding token leakage through URLs and errors	Token redaction in pagination URLs and SDK errors.1
Transient failure	Backoff, retry selection, and `Retry-After` handling	An opt-in retry policy with capped exponential backoff and jitter.1
Response shape	JSON structs, optional fields, and raw endpoint formats	Typed post models, deliberate raw portfolio JSON, and raw RSS XML.1

The result is not “magic.” It is simply a clearer boundary: application code decides which data matters, while the client consistently handles the mechanics of asking for it.

Why `cryptopanic-go` is a good fit for Go services

The library is intentionally compact. It requires Go 1.22 or newer and uses only the Go standard library at runtime, so adopting it does not introduce a broad transitive dependency tree.1 A configured Client can also be shared safely between goroutines, which matches the normal shape of Go servers and workers.1

More importantly, it uses types to make the common path explicit. Instead of decoding unstructured maps, you receive models such as Post and PostsPage. Optional or plan-gated values are represented carefully, so your code has a natural reason to check whether data is actually present before relying on it.1 That is a better failure mode than assuming a field will always exist and discovering otherwise at runtime.

The library also chooses not to over-model the upstream API where the source contract is not stable enough. For example, Portfolio returns a PortfolioResponse containing json.RawMessage; the README explains that this avoids guessing at a complete portfolio schema that the public API does not define as stable.1 The RSS methods similarly return raw XML rather than pretending it is the same thing as a JSON news page.1 Those choices preserve flexibility for the application instead of locking it into a potentially inaccurate SDK abstraction.

Install it and make the first request

Install the package with Go's standard tooling:

go get github.com/tigusigalpa/cryptopanic-go

The repository documents CRYPTOPANIC_AUTH_TOKEN as the environment variable used by NewFromEnv; keeping the token outside source control is the recommended starting point.1

export CRYPTOPANIC_AUTH_TOKEN="your-token"

Here is a compact, production-shaped example. It creates one reusable client, configures a client timeout and retry policy, then applies a shorter deadline to this individual operation.

package main

import (
    "context"
    "fmt"
    "log"
    "time"

    cryptopanic "github.com/tigusigalpa/cryptopanic-go"
 )

func main() {
    client, err := cryptopanic.NewFromEnv(
        cryptopanic.WithPlan(cryptopanic.PlanGrowth),
        cryptopanic.WithTimeout(10*time.Second),
        cryptopanic.WithRetryPolicy(cryptopanic.RetryPolicy{
            MaxAttempts: 3,
        }),
    )
    if err != nil {
        log.Fatal(err)
    }

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()

    page, err := client.Posts(ctx, cryptopanic.PostsQuery{
        Currencies: []string{"BTC", "ETH"},
        Filter:     cryptopanic.FilterRising,
        Page:       cryptopanic.IntPtr(1),
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, post := range page.Results {
        fmt.Printf("[%s] %s\n", post.Kind, post.Title)
    }
}

This example follows the package's documented configuration model: choose the API plan explicitly, set the underlying client timeout deliberately, and give the request its own context deadline.1 The explicit plan matters because access and available parameters are ultimately determined by the upstream CryptoPanic account and plan rather than by the SDK itself.1

Filter without manually assembling query strings

The core Posts method accepts a PostsQuery. Empty fields are omitted from the request, while the client validates rules that are safe to check locally; the upstream service remains the authority on evolving account permissions and capabilities.1

That distinction is useful in real applications. You can write an intent-oriented query in Go and still keep the underlying API semantics visible in your code:

size := 20
pageNumber := 1

page, err := client.Posts(ctx, cryptopanic.PostsQuery{
    Currencies: []string{"BTC", "ETH", "SOL"},
    Regions:    "en",
    Kind:       cryptopanic.KindNews,
    Filter:     cryptopanic.FilterHot,
    Size:       &size,
    Page:       &pageNumber,
})
if err != nil {
    log.Fatal(err)
}

for _, post := range page.Results {
    fmt.Println(post.Title)
    if post.Source != nil {
        fmt.Println("source:", post.Source.Title)
    }
}

The SDK exposes typed constants for commonly documented values such as filters, kinds, panic periods, panic sorting, and plans.1 The underlying API documents filters including currencies, regions, filter, kind, and page for its posts endpoint.2 That combination gives you good editor support without making the client falsely claim control over server-side entitlement rules.

Pagination that does not spread secret URLs through your code

Pagination is exactly the type of small detail that gets copied badly. CryptoPanic returns next and previous URLs in its response envelope.2 cryptopanic-go preserves the useful paging information while redacting the authentication token and extracting page numbers where possible. Its PostsPage exposes helpers such as HasNext, HasPrevious, NextPage, and PreviousPage.1

That makes a page-by-page retrieval loop direct and easy to review:

page, err := client.Posts(ctx, cryptopanic.PostsQuery{
    Page: cryptopanic.IntPtr(1),
})
if err != nil {
    log.Fatal(err)
}

for page.HasNext && page.NextPage != nil {
    next, err := client.Posts(ctx, cryptopanic.PostsQuery{
        Page: page.NextPage,
    })
    if err != nil {
        log.Fatal(err)
    }

    for _, post := range next.Results {
        fmt.Println(post.Title)
    }

    page = next
}

The important design choice is that your application keeps sending a normal PostsQuery; it is not asked to treat an upstream pagination URL as an executable instruction. That is both easier to test and safer to log.

Treat errors as part of the interface

In production, a useful client does more than return a non-nil error. It tells your application whether the error is a configuration problem, an access problem, a rate-limit event, or a server-side failure.

cryptopanic-go provides sentinel errors that work with errors.Is, including ErrMissingAuthToken, ErrInvalidQuery, ErrUnauthorized, ErrForbidden, ErrRateLimited, and ErrServerError. It also exposes an APIError that can be inspected with errors.As for details such as the status code, request ID, and retry count.1

page, err := client.Posts(ctx, query)
if err != nil {
    switch {
    case errors.Is(err, cryptopanic.ErrUnauthorized):
        log.Println("Authentication failed; check the configured token.")
    case errors.Is(err, cryptopanic.ErrRateLimited):
        log.Println("The rate limit was reached and retries were exhausted.")
    case errors.Is(err, cryptopanic.ErrServerError):
        log.Println("The upstream service returned a server error.")
    }

    var apiErr *cryptopanic.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("status=%d request_id=%s retried=%d\n",
            apiErr.StatusCode,
            apiErr.RequestID,
            apiErr.Retried,
        )
    }
}

This style lets a worker send an operational signal for an invalid token, apply its own queuing policy after a rate limit, or preserve a request ID for troubleshooting. The SDK documents that its error details use a redacted, truncated raw body, which is a thoughtful safeguard when diagnostics are routed to centralized logging.1

Retry deliberately, not by default

Automatic retries are useful only when they are intentional. The library leaves retries disabled by default and makes them an explicit RetryPolicy choice.1 When enabled, its documented retry scope covers HTTP 429, 500, 502, and 503, plus selected transient network failures; permanent failures such as bad requests, unauthorized access, invalid URLs, and certificate failures are not retried.1

The policy uses exponential backoff with jitter, caps the delay, and respects an upstream Retry-After header within that cap.1 That is a sensible foundation for idempotent GET operations such as reading news. It does not remove the need for application-level discipline: use a context deadline, apply caching where your traffic pattern calls for it, and make sure a retry policy aligns with the workload you operate.

More than one endpoint, without pretending they are the same

The package currently provides a small surface area that maps to meaningful API operations.1

API task	Go method	Returned form	Why it matters
Fetch filtered posts	`client.Posts(ctx, query)`	`*PostsPage`	Typed news data and paging helpers support normal application flows.1
Read a portfolio response	`client.Portfolio(ctx)`	`*PortfolioResponse` with raw JSON	Your application can decode an evolving schema on its own terms.1
Read filtered posts as RSS	`client.PostsRSS(ctx, query)`	`*RSSResponse` with raw XML	RSS stays XML instead of being forced into JSON models.1
Read the news RSS feed	`client.NewsRSS(ctx)`	`*RSSResponse` with raw XML	A simple option for feed-oriented integrations.1

This is a strong example of an SDK being useful without becoming large. It handles the repeated transport work, preserves the distinctions between the remote formats, and lets your application own its own product model.

Production-minded, testable, and easy to adopt

The project supports custom *http.Client values for proxies, transports, TLS configuration, and testing. Its WithBaseURL option is designed for mock servers, while WithSleeper supports deterministic retry tests.1 The repository's own tests use httptest.Server and fixtures rather than live API calls, a practical pattern worth retaining in your own test suite.1

For applications that need CryptoPanic data but do not want a broad framework or a pile of copied HTTP boilerplate, cryptopanic-go makes a compelling trade-off. You get a small Go-native interface, explicit configuration, typed data where the API schema is stable, raw data where it is not, and operational safeguards around timeouts, retries, and credentials.

If that matches your use case, start with the repository, run the examples, and adapt the query and error-handling patterns to your service. You can find the source, documentation, and contribution guidance on GitHub.1

Try it: go get github.com/tigusigalpa/cryptopanic-go and build the integration code your product actually needs—not another layer of hand-rolled request plumbing.

References

Building Reliable Crypto Alerting Systems in Go: A Deep Dive into the whale-alert-go SDK

Igor — Sat, 25 Jul 2026 07:39:30 +0000

Tracking large cryptocurrency transactions—commonly known as "whales"—has become a crucial tool for traders, analysts, and blockchain researchers. The Whale Alert Enterprise API is one of the leading data providers in this space, offering both historical data and real-time alerts. However, integrating third-party APIs into Go applications often requires writing a significant amount of boilerplate code. Developers must manually implement robust HTTP clients, manage the lifecycle of WebSocket connections, carefully handle pagination, and resolve floating-point precision issues when dealing with financial data.

To address these challenges, the whale-alert-go SDK was created 1. This unofficial Go library is designed specifically for interacting with the Whale Alert Enterprise API. It abstracts away the routine networking tasks, allowing engineers to focus entirely on the business logic of their applications.

Core Philosophy: Idiomatic Go

When designing whale-alert-go, the primary focus was on adhering to the standards and best practices of the Go programming language. Every method that performs a network request accepts a context.Context 1. This ensures proper timeout management and the ability to cancel long-running operations, which is critical for high-load microservices. Furthermore, the client is designed to be entirely concurrency-safe, meaning it can be shared across multiple goroutines without the need for additional mutexes 1.

One of the most common pitfalls when working with cryptocurrency APIs is using the float64 type to represent monetary amounts. Due to the nature of floating-point arithmetic, this inevitably leads to a loss of precision when dealing with very small values (such as satoshi fees) or extremely large numbers. In whale-alert-go, this problem is solved radically: all monetary values and fees are preserved as strings 1. Developers can pass these strings directly into specialized decimal arithmetic packages, such as shopspring/decimal, completely eliminating the risk of data distortion.

REST API: Clean and Resilient

Working with REST APIs often involves network failures, rate limits, and temporary server errors. The SDK provides a powerful retry mechanism that can be configured during client initialization using functional options.

// Create a client with retries enabled: up to 3 attempts, starting at
// 500ms and capped at 10s. Retries only apply to idempotent GET requests.
client := whalealert.NewClient(apiKey,
    whalealert.WithRetry(3, 500*time.Millisecond, 10*time.Second),
)

The retry policy is implemented with safety as the top priority. Only idempotent GET requests are retried, eliminating the risk of duplicating transactions or unintentionally altering state 1. The client automatically responds to HTTP status 429 (Too Many Requests) and 5xx series errors. It uses an exponential backoff strategy with added jitter (random deviation) to prevent the "thundering herd" effect, and it also respects the Retry-After header if provided by the server 1.

WebSocket Alerts: Built to Survive

For real-time data delivery, Whale Alert provides a WebSocket API. Maintaining long-lived connections is a complex task because networks are inherently unstable and servers may forcefully drop sessions. The websocket package included in the SDK offers an elegant solution with automatic reconnection capabilities 1.

client := websocket.NewClient(websocket.Config{
    URL: wsURL,
    Reconnect: websocket.ReconnectConfig{
        MaxAttempts:  5,
        InitialDelay: 1 * time.Second,
        MaxDelay:     30 * time.Second,
    },
})

client.OnMessage(func(msg websocket.Message) {
    if msg.EventType == websocket.EventTypeAlert && msg.Alert != nil {
        fmt.Printf("[ALERT] %s: %s\n", msg.Alert.Blockchain, msg.Alert.Text)
    }
})

A developer simply needs to define the reconnection parameters and register handlers for messages and errors. The client independently manages the read loop, decodes incoming events into strongly typed structs, and handles ping/pong control messages to keep the connection alive 1.

Safe Pagination and Error Handling

Endpoints that return lists, such as transaction histories, require pagination. whale-alert-go offers two approaches. The first is a lazy TransactionIterator that hides the logic of fetching subsequent pages under the hood 1. The second approach allows developers to manually manage navigation using the Next URL links.

A notable security feature of the SDK is its validation of URLs for subsequent pages. The library verifies that the Next URL shares the same origin as the client's base URL, preventing potential redirection attacks to malicious servers 1.

Error handling is also executed in the best traditions of Go 1.13+. The API returns a typed APIError containing the HTTP status and the message from the server. In addition, sentinel errors such as ErrUnauthorized or ErrRateLimited are provided, which can be easily checked using errors.Is and errors.As 1.

Conclusion

Integrating with financial and cryptocurrency APIs demands a high degree of reliability. The whale-alert-go library provides developers with a ready-to-use, carefully designed toolkit that resolves issues related to network instability, data precision loss, and connection management. Thanks to strongly typed models and an idiomatic approach, writing code becomes faster and safer.

You can install the library using the standard Go command:

go get github.com/tigusigalpa/whale-alert-go

Please note that this is an unofficial SDK, and you will need a valid Whale Alert Enterprise API key to access authenticated endpoints. Check out the source code, examples, and full documentation in the project's GitHub repository.

References

Track Blockchain Whale Activity in PHP with whale-alert-php

Igor — Thu, 23 Jul 2026 06:10:20 +0000

Large on-chain transfers are valuable events for monitoring, analytics, and alerting workflows. A product may need to retrieve a historical transaction, inspect the synchronization status of a blockchain, or notify a team the moment a high-value transfer appears. In PHP, those needs can quickly turn into repetitive work: composing requests, parsing responses, treating money safely, retrying temporary failures, and maintaining a live WebSocket connection.

That is the problem whale-alert-php is designed to solve. It is an unofficial, MIT-licensed PHP client for the Whale Alert Enterprise API, with coverage for documented REST endpoints and real-time WebSocket alerts. Rather than exposing a loose collection of arrays and request helpers, the library presents a typed, immutable, and framework-friendly interface for PHP applications. 1

Important: whale-alert-php is an independent, unofficial SDK. It is not affiliated with, endorsed by, or sponsored by Whale Alert. A valid API key is required for authenticated API operations. 1

Why a dedicated PHP SDK matters

Integrating an external blockchain-data API is not difficult in the narrowest sense: an HTTP request can return JSON in a few lines. The engineering work begins after that request. Production code must decide how to represent token quantities, distinguish a missing API key from a rate-limit response, follow a paginated result safely, and recover from a short-lived network or provider failure.

whale-alert-php packages those concerns into a focused client. Monetary values and fees are deliberately returned as strings rather than PHP floats, protecting applications from silent precision loss. API responses are mapped to immutable DTOs, while failures are exposed through typed exceptions. The client can use any PSR-18 compatible HTTP implementation, and Laravel applications can opt into a service provider, configuration publishing, a facade, and dependency injection. 1

Capability	What the SDK provides	Practical benefit
REST API access	Methods for supported blockchains, blockchain status, transactions, blocks, and address transactions. 1	Build historical views and data-enrichment workflows without hand-writing endpoint wrappers.
Real-time WebSocket events	Alert and social-event streaming, subscriptions, decoded messages, ping/pong keep-alives, and optional reconnection. 1	React to relevant on-chain activity as it arrives.
Typed, immutable DTOs	Structured response objects instead of ad hoc response arrays. 1	Improve autocomplete, readability, and confidence when integrating the API.
Precision-aware amounts	Fees and monetary fields remain strings. 1	Avoid float-rounding surprises in financial or analytical code.
Resilience controls	Configurable exponential-backoff retries for idempotent GET requests on HTTP 429 and 5xx responses. 1	Make short-lived API or network failures less disruptive.
Laravel integration	Optional service provider, facade, configuration publishing, and singleton client binding. 1	Add the SDK naturally to Laravel projects without sacrificing dependency injection.

Install it with Composer

The fastest path is a standard Composer install:

composer require tigusigalpa/whale-alert-php

The package uses Guzzle by default, but its PSR-18 design lets an application substitute another compatible HTTP client when needed. That is useful for teams with an existing HTTP stack or a deliberate preference for a different client implementation. 1

Start with the REST API

The following example creates a client, lists the blockchains supported by the public status endpoint, fetches Ethereum synchronization status, and retrieves a page of transactions. The code follows the library's documented API surface. 1

use Tigusigalpa\WhaleAlert\Config;
use Tigusigalpa\WhaleAlert\WhaleAlertClient;

$config = new Config(
    apiKey: getenv('WHALE_ALERT_API_KEY'),
    maxRetries: 3,
);

$client = new WhaleAlertClient($config);

// Public endpoint: an API key is not required here.
$chains = $client->getSupportedBlockchains();

foreach ($chains as $chain) {
    echo $chain->getName() . ': ' . implode(', ', $chain->getSymbols()) . "\n";
}

// Authenticated endpoint: supply a valid API key.
$status = $client->getBlockchainStatus('ethereum');

echo "Ethereum: {$status->getStartHeight()}-{$status->getEndHeight()}\n";

$page = $client->listTransactions('ethereum', [
    'start_height' => $status->getStartHeight(),
    'limit' => 100,
]);

foreach ($page->getTransactions() as $tx) {
    echo "Transaction {$tx->getHash()}\n";
    echo "Fee: {$tx->getFee()} {$tx->getFeeSymbol()}\n";
}

The key detail is not merely that the calls are concise. The return values are DTOs, so readers of the code can see that a transaction hash and fee are part of an explicit API contract. Since fee values are strings, the application can display them as received or use a decimal-math library for precise calculations rather than implicitly converting them to floats. 1

Make pagination a safe default

Pagination is often treated as a trivial concern until it becomes a security or reliability issue. List calls return a TransactionPage that contains the current transactions and an optional next URL. When the next page exists, the client can follow it with listTransactionsNext(). The SDK validates next URLs against the configured base origin, which avoids accidentally following an arbitrary URL returned in a response. Equivalent helpers are available for address-transaction pagination. 1

if ($page->getNext() !== null) {
    $nextPage = $client->listTransactionsNext($page->getNext());

    foreach ($nextPage->getTransactions() as $tx) {
        echo $tx->getHash() . "\n";
    }
}

For applications that process large transaction sets, this small design choice keeps the calling code readable while retaining an important validation boundary.

Stream real-time alerts with WebSockets

Polling has its place, but a real-time alerting product should not have to wait for the next scheduled request. whale-alert-php includes a WebSocket client that lets an application connect, subscribe to alerts, register handlers, and enter a read loop. Automatic reconnection is opt-in: configure maxReconnects with a value greater than zero when that behavior is appropriate for the application. 1

Here is a compact example that listens for Ethereum alerts with a minimum USD value of 500,000:

use Tigusigalpa\WhaleAlert\WebSocket\AlertSubscription;
use Tigusigalpa\WhaleAlert\WebSocket\Client;
use Tigusigalpa\WhaleAlert\WebSocket\EventType;

$apiKey = getenv('WHALE_ALERT_API_KEY');
$wsUrl = sprintf(
    'wss://leviathan.whale-alert.io/ws?api_key=%s',
    $apiKey,
);

$client = new Client($wsUrl, maxReconnects: 5);

$client->onMessage(function ($message) {
    if ($message->type === EventType::Alert && $message->alert !== null) {
        echo "Blockchain: {$message->alert['blockchain']}\n";
        echo "Alert: {$message->alert['text']}\n";
    }
});

$client->onError(function (\Throwable $exception) {
    fwrite(STDERR, "Connection issue: {$exception->getMessage()}\n");
});

$client->connect();

$client->subscribeAlerts(new AlertSubscription(
    id: 'eth-whale-watch',
    blockchains: ['ethereum'],
    minValueUsd: 500000,
));

$client->listen();

This is a useful foundation for an internal operations feed, a Discord or Telegram notification bridge, a data-ingestion worker, or a real-time dashboard. The SDK takes responsibility for the WebSocket protocol mechanics—connection, subscription management, message decoding, keep-alives, and optional reconnection—so the application can focus on what should happen after an alert is received. 1

Handle failures intentionally

A reliable integration should make it easy to tell a configuration mistake from a temporary upstream problem. The SDK maps API failures to named exception types, including UnauthorizedException for an invalid or missing credential, RateLimitException for HTTP 429 responses, NotFoundException, validation errors, and server-side errors. 1

use Tigusigalpa\WhaleAlert\Exceptions\ApiException;
use Tigusigalpa\WhaleAlert\Exceptions\RateLimitException;
use Tigusigalpa\WhaleAlert\Exceptions\UnauthorizedException;

try {
    $status = $client->getBlockchainStatus('ethereum');
} catch (UnauthorizedException $exception) {
    // Check WHALE_ALERT_API_KEY.
} catch (RateLimitException $exception) {
    // Use the provider's suggested retry timing when present.
    $retryAfter = $exception->getRetryAfter();
} catch (ApiException $exception) {
    // Log or handle other API-specific failures.
}

The retry strategy is intentionally conservative. It is disabled by default, applies only to idempotent GET requests, retries rate-limit and 5xx responses, uses exponential backoff with jitter, and can honor a Retry-After header. The library also redacts api_key values from error excerpts and does not log the key itself. 1

Configuration option	Default	Role
`apiKey`	Empty string	Sets the credential used for authenticated endpoints. 1
`timeout`	`30` seconds	Defines the HTTP timeout. 1
`maxRetries`	`0`	Enables retry attempts for eligible GET requests when set above zero. 1
`retryDelayMs`	`500` ms	Sets the initial delay used by exponential backoff. 1
`retryMaxDelayMs`	`10000` ms	Caps the retry delay. 1

A natural fit for Laravel

For Laravel projects, the optional WhaleAlertServiceProvider can publish a config/whale-alert.php file and register WhaleAlertClient as a singleton. Developers can then either use the WhaleAlert facade or request WhaleAlertClient through dependency injection. That offers a clean path from a simple prototype to maintainable application code. 1

use Tigusigalpa\WhaleAlert\WhaleAlertClient;

public function index(WhaleAlertClient $client)
{
    $chains = $client->getSupportedBlockchains();

    return view('chains.index', compact('chains'));
}

The project also contains runnable REST and WebSocket examples plus PHPUnit tests covering the REST client, WebSocket client, DTOs, and error handling. Those resources make it easier to evaluate the package before embedding it in a broader workflow. 1

Build the blockchain feature, not the plumbing

whale-alert-php is for PHP teams that want to work with Whale Alert Enterprise API data without rebuilding the client layer from scratch. Its value is in the details that application code should not need to rediscover: PSR-18 flexibility, immutable typed responses, string-safe monetary fields, explicit error types, controlled retries, guarded pagination, and real-time WebSocket support. 1

If you are building a PHP or Laravel tool that monitors, enriches, visualizes, or routes blockchain-transfer events, install the SDK, review the examples, and tailor the subscriptions and request flow to your use case. Visit the GitHub repository for the complete README, source code, and release information. 1

References

Supercharge Your Algorithmic Trading with CoinQuant PHP: The Ultimate SDK for Laravel and PHP 8.1+

Igor — Tue, 21 Jul 2026 18:35:38 +0000

Are you tired of wrestling with raw cURL requests, parsing Server-Sent Events (SSE) by hand, and building complex polling loops just to interact with trading APIs? If you are a PHP developer or a Laravel enthusiast looking to dive into algorithmic trading, your life is about to get a whole lot easier. Meet coinquant-php, the official PHP and Laravel SDK for the CoinQuant Public API.

CoinQuant is revolutionizing the way we approach algorithmic trading. It takes a trading idea described in plain English and turns it into a backtestable strategy using advanced AI. However, integrating such powerful tools into your own applications can often be a daunting task. That is where coinquant-php steps in. This robust SDK wraps the public API, providing a seamless, developer-friendly experience that lets you focus on what really matters: building profitable trading strategies.

In this comprehensive guide, we will explore why coinquant-php is a game-changer for PHP developers, delve into its standout features, and show you how to get started in minutes.

Why Choose CoinQuant PHP?

The landscape of algorithmic trading is often dominated by Python, but PHP remains a powerhouse for web development, especially with frameworks like Laravel. coinquant-php bridges the gap, allowing PHP developers to leverage the cutting-edge AI capabilities of CoinQuant without leaving their preferred ecosystem.

1. Built for Modern PHP

The library is designed for the modern era of PHP. It requires PHP 8.1+ and embraces strict typing, ensuring your code is robust and free from legacy baggage. Whether you are building a standalone script or a complex enterprise application, the SDK provides a solid foundation.

2. First-Class Laravel Integration

If you are using Laravel 10, 11, 12, or 13, you are in for a treat. The package auto-registers its ServiceProvider and Facade, meaning there is absolutely zero manual wiring required. You can simply install the package and start using the CoinQuant facade anywhere in your controllers, jobs, or commands. It also binds the client as a singleton for elegant dependency injection.

3. Comprehensive API Coverage

The SDK doesn't just cover the basics; it provides access to all 37 public endpoints of the CoinQuant API. This includes health checks, chat interactions, strategy generation, versioning, backtesting, reports, templates, credit management, and even community features like leaderboards. Everything you need is right at your fingertips.

4. Effortless Streaming via Generators

One of the most powerful features of CoinQuant is its AI engine, which responds over Server-Sent Events (SSE). Handling SSE in PHP can be tricky, but the SDK abstracts this away completely. It reads the stream and classifies events into categories like chat, strategy, report, error, or unknown. You can even iterate over the generator directly to stream tokens to a browser in real-time, creating a highly responsive user experience.

5. Simplified Backtesting

Backtesting is the core of algorithmic trading, and coinquant-php makes it incredibly simple. The createBacktestAndWait() method is a one-call solution that submits the run, polls until completion, and returns the final results along with CSV exports for deep analysis.

6. Actionable Exceptions

Debugging API integrations can be frustrating, but not with this SDK. Any non-2xx response throws a CoinQuantException that carries the HTTP status, a unique request_id, a machine-readable code, and a descriptive message. This makes error handling and troubleshooting a breeze.

Getting Started: From Zero to Backtest

Let's walk through how easy it is to get started with coinquant-php.

Installation

First, pull the package in via Composer. Guzzle, the underlying HTTP client, is installed automatically.

composer require tigusigalpa/coinquant-php

Configuration

CoinQuant uses a JWT bearer token for authentication. You can generate one from the Settings menu in the CoinQuant web app. Keep this token secure in an environment variable (COINQUANT_TOKEN).

For standalone PHP:

use CoinQuant\CoinQuantClient;

$client = new CoinQuantClient(getenv('COINQUANT_TOKEN'));
$credits = $client->getCredits();

echo "Available credits: {$credits['available_credits_total']}";

For Laravel, simply add the token to your .env file:

COINQUANT_TOKEN=your_token_here

And you are ready to use the facade:

use CoinQuant\Laravel\Facades\CoinQuant;

$credits = CoinQuant::getCredits();

The Workflow: Idea to Metrics

The true power of the SDK shines when you use it to turn an idea into a fully backtested strategy. Here is a complete workflow in just a few lines of code:

// 1. Describe the idea and let the AI draft a strategy.
$res = $client->prompt('Long BTCUSDT when price crosses above the 200 EMA on 1h, exit on cross below.');

// 2. Materialize it if it came back schema-only.
$versionId = $res->strategyVersionId
    ?? $client->finalizeChat($res->chatId, 'EMA 200 Crossover', '')['latest_version']['id'];

// 3. Backtest and wait for the verdict.
$outcome = $client->createBacktestAndWait($versionId, 900, 5);

// 4. Analyze the results
print_r($outcome['results']['metrics']);

In this example, we simply ask the AI to create a strategy based on the 200 EMA crossover. The SDK handles the streaming response, materializes the strategy blueprint into a backtestable version, runs the backtest, and polls for the results. It is algorithmic trading made remarkably accessible.

Advanced Usage: Streaming and Customization

For developers who need more control, coinquant-php delivers.

Real-Time Streaming

If you are building a user interface and want to show the AI's thought process in real-time, you can iterate the generator directly:

use CoinQuant\Streaming\StreamEvent;

foreach ($client->streamPrompt('Explain the RSI indicator.') as $event) {
    if ($event->type === StreamEvent::TYPE_CHAT) {
        echo $event->text; // Flush to the client in real time
    }
}

Custom HTTP Clients

Under the hood, the SDK uses Guzzle. If you need to configure retries, route traffic through a proxy, or add custom headers for tracing, you can pass your own configured Guzzle client:

use GuzzleHttp\Client as GuzzleClient;

$http = new GuzzleClient([
    'timeout' => 60,
    'headers' => ['Authorization' => 'Bearer ' . getenv('COINQUANT_TOKEN' )],
]);

$client = new CoinQuantClient(getenv('COINQUANT_TOKEN'), $http );

Conclusion

The coinquant-php SDK is a masterclass in developer experience. By abstracting away the complexities of the CoinQuant API, SSE parsing, and asynchronous polling, it empowers PHP developers to build sophisticated trading applications with unprecedented speed and ease.

Whether you are a solo developer exploring algorithmic trading or a team building a comprehensive financial platform on Laravel, this SDK provides the tools you need to succeed. The strict typing, elegant Laravel integration, and comprehensive endpoint coverage make it a joy to use.

Ready to turn your trading ideas into reality? Head over to the GitHub repository, give it a star, and start building today!

Happy Coding and Happy Trading!

Repository Author: Igor Sazonov (@tigusigalpa)License: MIT