README

bitculator.com · API documentation · Get an API key Packagist — bitculator/sdk · GitHub

The official PHP SDK for the Bitculator Data API. No Composer dependencies (native cURL), typed, PHP 8.1+.

Keep your API key server-side. It is a Bearer token with the data-api ability and is not meant for client-side embedding.

Install

composer require bitculator/sdk

Quick start

use Bitculator\Bitculator;

$client = new Bitculator(getenv('BITCULATOR_API_KEY'));

// Single resource — the { "data": ... } envelope is unwrapped for you.
$bitcoin = $client->coins->get('bitcoin');
echo $bitcoin['price']; // "63520.780763913" — a decimal string, never rounded

// A paginated list.
$page = $client->coins->list(['per_page' => 50, 'sort' => '-marketcap']);
print_r($page->data);
echo $page->meta['total'];

Prices are decimal strings

Prices, rates, and supplies come back as strings (e.g. "63520.780763913") to preserve full precision. Use BCMath / a big-decimal library if you need to do math — do not cast them to float, which silently loses precision.

Pagination

Every paginated method returns a Page. Read one page, or iterate to walk them all:

// One page at a time.
$page = $client->exchanges->list(['per_page' => 100]);
while ($page !== null) {
    foreach ($page->data as $exchange) {
        echo $exchange['name'], "\n";
    }
    $page = $page->nextPage();
}

// Or auto-paginate across every page (iterating a Page walks all pages).
foreach ($client->coins->list(['sort' => '-marketcap']) as $coin) {
    echo $coin['symbol'], "\n";
}

Errors

Every failure extends BitculatorException; HTTP failures throw a status-specific subclass carrying the { error: { code, message, details } } envelope.

use Bitculator\Exceptions\ValidationException;
use Bitculator\Exceptions\RateLimitException;
use Bitculator\Exceptions\ApiException;

try {
    $client->coins->list(['per_page' => 9999]); // over the plan cap -> 422
} catch (ValidationException $e) {
    echo $e->errorCode, $e->details;
} catch (RateLimitException $e) {
    echo 'retry after ', $e->retryAfter;
} catch (ApiException $e) {
    echo $e->status, $e->getMessage();
}

Timeouts throw TimeoutException; network failures throw ConnectionException.

Quota

Every response carries X-Quota-* headers, surfaced on the client after each call:

$client->coins->list();
$quota = $client->quota(); // Quota { limit, remaining, reset, raw }

Configuration

new Bitculator(
    apiKey: '...',                    // required
    baseUrl: 'https://bitculator.com', // default
    timeout: 30.0,                    // seconds, default
    maxRetries: 2,                    // auto-retry 429 / 5xx / network; 0 to disable
);

Passing parameters

Query parameters are an associative array whose keys mirror the API's names exactly (per_page, min_price, from, ...):

$client->conversion->convert(['from' => 'btc', 'to' => 'usd', 'amount' => 1]);

Resources

coins · prices · markets · exchanges · wallets · globalMarket · sentiment · indicators · liquidations · conversion · calculators · editorial · alarms · webhooks · meta

Full endpoint reference: https://bitculator.com/en/documentation/api/v1.

License

MIT