Responses and DTOs

The Coinglass API v4 spans dozens of heterogeneous endpoints, each returning data in different shapes. To provide a consistent and predictable developer experience, coinglass-php automatically unwraps the API's standard {"code", "msg", "data"} response envelope and hydrates the data payload into typed PHP objects.

The Hydration Process

When you call a resource method such as $client->futures()->openInterestOhlcHistory(...), the SDK's AbstractResource base class inspects the decoded data payload and applies the following rules:

1. List of associative arrays — hydrated into a CoinGlassCollection containing one CoinGlassDto per item.
2. Single associative array — hydrated into a single CoinGlassDto.
3. Map of lists — hydrated into a PHP array where each value is a CoinGlassCollection.
4. Scalar list or primitive — returned as-is (e.g., supportedCoins() returns a plain string[]).

This means you can always expect a consistent, object-oriented interface regardless of which endpoint you are calling.

CoinGlassDto

Tigusigalpa\CoinGlass\Dto\CoinGlassDto is a generic, read-only wrapper around a single Coinglass API response record. Because the API returns dozens of different field names across its endpoints, the DTO exposes the raw decoded payload dynamically rather than through a fixed set of typed properties.

Accessing Fields

The DTO supports three equivalent ways to access any field present in the response:

$dto = $client->futures()->openInterestOhlcHistory('BTC', '1d', 1)->first();

// 1. Property access (recommended for readability)
$openInterest = $dto->openInterestUsd;

// 2. Array access
$openInterest = $dto['openInterestUsd'];

// 3. Method access with an optional default value
$openInterest = $dto->get('openInterestUsd', 0.0);

Checking for Keys

You can check whether a specific key exists in the payload using either has() or the native isset() function:

if ($dto->has('fundingRate')) {
    $rate = $dto->fundingRate;
}

// Equivalent using isset
if (isset($dto->fundingRate)) {
    $rate = $dto->fundingRate;
}

Accessing the Raw Payload

The original decoded JSON payload is always preserved and accessible. This is useful when you need to serialize the data or pass it to another system:

// Get the raw associative array
$array = $dto->toArray();

// Or via the public readonly property
$array = $dto->raw;

CoinGlassCollection

Tigusigalpa\CoinGlass\Collections\CoinGlassCollection is a typed, read-only collection of CoinGlassDto records. It implements IteratorAggregate, Countable, and ArrayAccess, so it behaves like a standard PHP iterable while providing additional utility methods.

Iteration and Counting

$collection = $client->futures()->openInterestOhlcHistory('BTC', '1d', 30);

// Iterate with foreach
foreach ($collection as $point) {
    echo "{$point->t}: \${$point->openInterestUsd}\n";
}

// Array access
$firstPoint = $collection[0];

// Count the number of records
$count = count($collection);

Utility Methods

The collection provides a set of methods for common operations.

Method	Return Type	Description
first()	?CoinGlassDto	Returns the first item, or null if empty.
last()	?CoinGlassDto	Returns the last item, or null if empty.
all()	CoinGlassDto[]	Returns all items as a plain PHP array.
isEmpty()	bool	Returns true if the collection has no items.
isNotEmpty()	bool	Returns true if the collection has at least one item.
count()	int	Returns the number of items.
filter(callable)	CoinGlassCollection	Returns a new collection containing only items for which the callback returns true.
map(callable)	array	Applies a callback to each item and returns a plain PHP array of the results.
toArray()	array[]	Converts the collection to a plain PHP array of associative arrays.

Filtering and Mapping

The filter() method returns a new CoinGlassCollection, preserving the typed interface, while map() returns a standard PHP array:

// Keep only records with open interest above $1 billion
$highOi = $collection->filter(function (CoinGlassDto $item) {
    return $item->get('openInterestUsd', 0) > 1_000_000_000;
});

// Extract just the timestamps as a plain array
$timestamps = $collection->map(function (CoinGlassDto $item) {
    return $item->t;
});

WebSocket Messages

When using the WebSocket API, the Message::collection() method returns a CoinGlassCollection hydrated from the message's data payload, using the exact same mechanism as the REST client. This means you can use the same code patterns for both REST and WebSocket responses.

$stream->listen(function (Message $message) {
    $collection = $message->collection();
    $first = $collection->first();

    if ($first !== null) {
        echo $first->symbol . ": " . $first->get('volume_usd') . "\n";
    }
});

---

Next: Error Handling