README

A PHP client for the Coinglass API v4, with first-class Laravel support.

coinglass-php is a framework-agnostic PHP SDK for the Coinglass API v4. I put it together while building a liquidation dashboard and got tired of hand-rolling Guzzle calls and juggling raw arrays, so it wraps the Futures, Spot, Options, ETF, On-Chain, and Indicator endpoints — plus the real-time WebSocket streams — in a typed, PSR-18-friendly client that drops straight into Laravel if you need it, or works standalone if you don't.

Features

• Covers all six endpoint groups: Futures, Spot, Options, ETF, On-Chain, and Indicators.
• Ships a real-time WebSocket client for liquidation orders, spot/futures trades, and futures ticker snapshots — no extra WebSocket library needed, it's built on plain PHP streams.
• Framework-agnostic: use it standalone in any PHP 8.1+ project, or drop it straight into Laravel.
• PSR-18 swappable HTTP client — Guzzle by default, bring your own if you'd rather.
• Retries rate-limited (429) requests with exponential backoff, honoring Retry-After when Coinglass sends one.
• Hydrates every payload into a CoinGlassDto or CoinGlassCollection, with the original raw payload always within reach.
• A small, purposeful exception hierarchy — UnauthorizedException, NotFoundException, RateLimitException, and a generic ApiException for everything else — instead of one catch-all.
• Laravel-ready out of the box: publishable config, a bound singleton client, dependency injection, and a CoinGlass facade.

Requirements

Installation

composer require tigusigalpa/coinglass-php

Local development path

Working against a local checkout? Point Composer at it with a path repository in your composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../packages/coinglass-php"
        }
    ]
}

Configuration

Standalone

use Tigusigalpa\CoinGlass\CoinGlassClient;
use Tigusigalpa\CoinGlass\CoinGlassConfig;

// Simple initialization
$client = CoinGlassClient::make('YOUR_API_KEY');

// Full configuration
$config = new CoinGlassConfig(
    apiKey: 'YOUR_API_KEY',
    baseUrl: 'https://open-api-v4.coinglass.com',
    timeout: 15.0,
    retryAttempts: 3,
    retryDelay: 1.0,
);
$client = new CoinGlassClient($config);

// From environment variables (COINGLASS_API_KEY, COINGLASS_BASE_URL, ...)
$client = new CoinGlassClient(CoinGlassConfig::fromEnv());

Laravel

Publish the config file (optional):

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

COINGLASS_API_KEY=your-api-key
COINGLASS_BASE_URL=https://open-api-v4.coinglass.com
COINGLASS_TIMEOUT=15
COINGLASS_RETRY_ATTEMPTS=3
COINGLASS_RETRY_DELAY=1

Via the facade:

use Tigusigalpa\CoinGlass\Laravel\Facades\CoinGlass;

$oi = CoinGlass::futures()->openInterestOhlcHistory('BTC', '1d', 30);

Via dependency injection:

use Tigusigalpa\CoinGlass\CoinGlassClient;

class MarketController
{
    public function __construct(private readonly CoinGlassClient $coinGlass) {}

    public function index()
    {
        return $this->coinGlass->etf()->bitcoinFlowHistory('1w', 24);
    }
}

Quick Start

use Tigusigalpa\CoinGlass\CoinGlassClient;

$client = CoinGlassClient::make('YOUR_API_KEY');

// Futures
$oi = $client->futures()->openInterestOhlcHistory('BTC', '1d', 30);
foreach ($oi as $point) {
    echo "{$point->t}: \${$point->openInterestUsd}\n";
}

$funding = $client->futures()->fundingRateExchangeList('BTC');
$liq = $client->futures()->liquidationHistory('BTC', 'BTCUSDT', '1h');

// Spot
$markets = $client->spot()->coinsMarkets();
$orderbook = $client->spot()->orderbookHistory('BTCUSDT', 'Binance', '1h');

// ETF
$flows = $client->etf()->bitcoinFlowHistory('1w', 24);

// Indicators
$fearGreed = $client->indicators()->fearGreedHistory(30);

Whatever you call, you get back a Tigusigalpa\CoinGlass\Dto\CoinGlassDto for a single record or a Tigusigalpa\CoinGlass\Collections\CoinGlassCollection for a list. Reach for a field however feels natural — property syntax ($dto->openInterestUsd), array syntax ($dto['openInterestUsd']), or $dto->get('openInterestUsd') — and if you ever need the untouched payload, it's right there via $dto->raw / $dto->toArray().

Full API Reference

Every method maps to a single Coinglass endpoint and returns the hydrated data payload. Optional parameters are marked with ? below.

Futures — $client->futures()

Spot — $client->spot()

Options — $client->options()

ETF — $client->etf()

On-Chain — $client->onChain()

Indicators — $client->indicators()

WebSocket API

The REST client covers historical data; for anything real-time — liquidation orders, spot and futures trades, futures ticker snapshots — there's a small WebSocket client too. It talks Coinglass's WebSocket API directly over PHP streams (stream_socket_client), implementing just enough of the protocol to get the job done, so you don't need to pull in a separate WebSocket library.

use Tigusigalpa\CoinGlass\CoinGlassClient;
use Tigusigalpa\CoinGlass\WebSocket\Channels;
use Tigusigalpa\CoinGlass\WebSocket\Message;

$client = CoinGlassClient::make('YOUR_API_KEY');
$stream = $client->websocket()->connect();

$stream->subscribe(
    Channels::liquidationOrders(),
    Channels::futuresTicker('Binance', 'BTCUSDT'),
);

$stream->listen(function (Message $message) {
    if ($message->channel === Channels::liquidationOrders()) {
        foreach ($message->collection() as $order) {
            echo "{$order->exchange} {$order->symbol} liquidated \${$order->volume_usd}\n";
        }
    }
});

A single connection carries every subscription; subscribe()/unsubscribe() accept any number of channel names, and the "ping" heartbeat Coinglass expects every 20 seconds is sent automatically. listen() blocks forever, which fits a long-running CLI worker or queued job; if you need finer control (e.g. to integrate with an existing event loop), call $stream->read($timeoutSeconds) yourself to pull one message at a time.

Channel helpers

Every message's data payload can be hydrated with $message->collection(), returning the same CoinGlassCollection of CoinGlassDto records used throughout the REST client — access fields with $order->volume_usd, $order['volume_usd'], or $order->get('volume_usd').

Laravel

use Tigusigalpa\CoinGlass\Laravel\Facades\CoinGlass;

$stream = CoinGlass::websocket()->connect();

Publish the config (php artisan vendor:publish --tag=coinglass-config) to override the WebSocket endpoint via COINGLASS_WS_BASE_URL, COINGLASS_WS_CONNECT_TIMEOUT, and COINGLASS_WS_PING_INTERVAL.

Errors

Connection, handshake, and read/write failures throw Tigusigalpa\CoinGlass\Exceptions\WebSocketException (a CoinGlassException), so it's caught by the same catch (CoinGlassException $e) you might already have.

Error handling

Nothing fails silently. The common cases each get their own exception, so you can catch exactly what you care about and let the rest bubble up:

use Tigusigalpa\CoinGlass\Exceptions\ApiException;
use Tigusigalpa\CoinGlass\Exceptions\NotFoundException;
use Tigusigalpa\CoinGlass\Exceptions\RateLimitException;
use Tigusigalpa\CoinGlass\Exceptions\UnauthorizedException;

try {
    $oi = $client->futures()->openInterestOhlcHistory('BTC', '1d', 30);
} catch (UnauthorizedException $e) {
    // Invalid or missing API key
} catch (RateLimitException $e) {
    // Retries exhausted; $e->retryAfter holds the Retry-After value, if any
} catch (NotFoundException $e) {
    // Endpoint/resource not found
} catch (ApiException $e) {
    // Any other non-2xx response or non-zero envelope code
    // $e->statusCode, $e->apiCode, $e->responseBody are all available
}

Retry behavior

Coinglass rate-limits aggressively on some plans, so on HTTP 429 the client reads the Retry-After header if present, or falls back to exponential backoff (retryDelay * 2^attempt), retrying up to retryAttempts times before giving up and throwing RateLimitException:

$config = new CoinGlassConfig(
    apiKey: 'YOUR_API_KEY',
    retryAttempts: 3,
    retryDelay: 1.0, // 1s, then 2s, then 4s
);

Testing

composer install
vendor/bin/phpunit

The suite leans on Guzzle's MockHandler for the HTTP-layer unit tests and Orchestra Testbench for the Laravel integration tests, so it runs without ever touching the real Coinglass API.

License

MIT © Igor Sazonov