Working with Responses

Every successful API request in Nansen PHP returns a Data Transfer Object (DTO). This ensures that responses are structured and predictable, rather than loose arrays.

Response Types

There are generally two types of responses:

1. List Responses: These extend Tigusigalpa\Nansen\Dto\ListResponse and contain a collection of items and optional pagination metadata.

2. Single Record Responses: These represent a single entity or result.

Handling List Responses

When an endpoint returns a list of items (like netflows() or tokenScreener()), the response object will have an items property, which is an instance of RecordCollection.

The RecordCollection implements Countable, IteratorAggregate, and ArrayAccess, meaning you can treat it like an array in foreach loops or use count() on it.

$netflows = $client->smartMoney()->netflows()->limit(5)->get();

// Loop over the items
foreach ($netflows->items as $item) {
    // Access properties dynamically
    echo "Chain: " . $item->chain . "\n";
    echo "Netflow: " . $item->netflow . "\n";
}

// Get the total number of items returned
echo "Count: " . count($netflows->items) . "\n";

// Access the first item
$firstItem = $netflows->items->first();

The Record DTO

Individual items within a collection are instances of Tigusigalpa\Nansen\Dto\Record.

Properties on a Record are accessed dynamically using PHP's __get magic method. If a property does not exist, it will return null instead of throwing an error.

$item = $netflows->items->first();

// Access properties
$chain = $item->chain;
$usdValue = $item->netflow_usd;

// You can also use array access syntax
$chain = $item['chain'];

The get() Method

For nested data, the Record class provides a get() method that accepts dot notation.

// Assuming the raw data has a structure like: ['token' => ['symbol' => 'ETH']]
$symbol = $item->get('token.symbol', 'default_value');

Pagination Metadata

If the API response includes pagination information, it will be available via the meta property on the ListResponse.

$response = $client->smartMoney()->netflows()->get();

if ($response->meta) {
    echo "Total records: " . $response->meta->total . "\n";
    echo "Has more pages? " . ($response->meta->hasMore ? 'Yes' : 'No') . "\n";
}

The raw Property (Future-Proof Access)

Nansen PHP is designed to never lose data. Every DTO, whether it is the main response object or an individual Record, keeps the exact, untouched JSON payload returned by the API in the ->raw property.

This is crucial because if Nansen adds a new field to an endpoint tomorrow, you do not need to wait for a package update to use it.

$response = $client->smartMoney()->netflows()->limit(1)->get();

// Access a newly added field that the library doesn't know about yet
$brandNewField = $response->raw['data'][0]['brand_new_field'] ?? null;

// The raw property is also available on individual Records
$firstRecord = $response->items->first();
$newField = $firstRecord->raw['brand_new_field'] ?? null;