PHPackages                             tigusigalpa/coinmarketcap - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. tigusigalpa/coinmarketcap

ActiveLibrary[API Development](/categories/api)

tigusigalpa/coinmarketcap
=========================

CoinMarketCap API Client for Laravel

v1.0.2(5mo ago)126MITPHPPHP ^8.1

Since Jan 29Pushed 3mo ago1 watchersCompare

[ Source](https://github.com/tigusigalpa/coinmarketcap-php)[ Packagist](https://packagist.org/packages/tigusigalpa/coinmarketcap)[ RSS](/packages/tigusigalpa-coinmarketcap/feed)WikiDiscussions main Synced today

READMEChangelog (2)Dependencies (8)Versions (3)Used By (0)

CoinMarketCap API Client for Laravel & PHP
==============================================

[](#coinmarketcap-api-client-for-laravel--php)

[![CoinMarketCap PHP SDK](https://camo.githubusercontent.com/c49f4792c9428bfc57fc698910ec0e50fa8097bfa59e52d3946ecbd345210b4c/68747470733a2f2f692e706f7374696d672e63632f4d5a516353726d662f636f696e6d61726b65746361702d7068702d62616e6e65722e6a7067)](https://camo.githubusercontent.com/c49f4792c9428bfc57fc698910ec0e50fa8097bfa59e52d3946ecbd345210b4c/68747470733a2f2f692e706f7374696d672e63632f4d5a516353726d662f636f696e6d61726b65746361702d7068702d62616e6e65722e6a7067)

[![Latest Version on Packagist](https://camo.githubusercontent.com/7936c62263cbb61c7ff5913c7e10e79c01408318210555916ee6f70e95d26378/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74696775736967616c70612f636f696e6d61726b65746361702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/coinmarketcap)[![License](https://camo.githubusercontent.com/487d2e8fd3c710ae6b85807a98f0b23c3ea21d3e2bfed163271ac2544be44718/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f74696775736967616c70612f636f696e6d61726b65746361702e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/tigusigalpa/coinmarketcap)

PHP client for the [CoinMarketCap API v1](https://coinmarketcap.com/api/documentation/v1/). Works standalone or with Laravel (service provider, facade, DI). Covers cryptocurrency listings, quotes, OHLCV, exchanges, global metrics, and price conversion.

Built on PHP 8.1+ with strict types, PSR-18 HTTP client, PHPStan level 8, and PHPUnit tests.

Features
--------

[](#features)

### Core

[](#core)

- PHP 8.1+ with strict types, readonly properties, enums
- PSR-18 HTTP client abstraction
- Fluent `ClientBuilder` for configuration
- Laravel service provider, facade, dependency injection
- Type-safe DTO models for all responses
- Custom exceptions for rate limits, auth errors, invalid requests
- PHPUnit test suite, PHPStan level 8, PSR-12 code style

### API coverage

[](#api-coverage)

- Real-time prices and market cap rankings
- Historical quotes and OHLCV data
- Price conversion (crypto ↔ fiat)
- Trending coins, gainers, losers
- Cryptocurrency metadata (logos, links, descriptions)
- Exchange listings, trading pairs, market pairs
- Global market metrics (total market cap, BTC dominance)

### Developer experience

[](#developer-experience)

- Composer install, works out of the box with Laravel
- Sandbox mode for testing without production credits
- Rate limit detection and handling
- Configurable via `.env` and config files

Requirements
------------

[](#requirements)

- PHP 8.1 or higher
- Laravel 10.x or 11.x
- CoinMarketCap API key ([Get one here](https://coinmarketcap.com/api/))

Installation
------------

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require tigusigalpa/coinmarketcap
```

Laravel auto-discovery registers the service provider automatically.

### 2. Get your API key

[](#2-get-your-api-key)

1. Visit [CoinMarketCap API Portal](https://coinmarketcap.com/api/)
2. Sign up for an account (Basic plan: 10,000 calls/month, free)
3. Copy your API key from the dashboard

### 3. Publish config (Laravel)

[](#3-publish-config-laravel)

```
php artisan vendor:publish --tag=coinmarketcap-config
```

### 4. Configure `.env`

[](#4-configure-env)

```
# CoinMarketCap API Configuration
COINMARKETCAP_API_KEY=your-api-key-here
COINMARKETCAP_BASE_URL=https://pro-api.coinmarketcap.com
COINMARKETCAP_TIMEOUT=30
COINMARKETCAP_USE_SANDBOX=false
```

### 5. Clear config cache

[](#5-clear-config-cache)

```
php artisan config:clear
```

### Standalone PHP (without Laravel)

[](#standalone-php-without-laravel)

```
use Tigusigalpa\CoinMarketCap\ClientBuilder;

$client = (new ClientBuilder())
    ->setApiKey('your-coinmarketcap-api-key')
    ->build();
```

### Verify installation

[](#verify-installation)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

// Get Bitcoin price
$bitcoin = CoinMarketCap::cryptocurrency()->quotesLatest([
    'symbol' => 'BTC',
    'convert' => 'USD'
]);

echo "Bitcoin Price: $" . $bitcoin['data']['BTC']['quote']['USD']['price'];
```

Quick Start
-----------

[](#quick-start)

### Using Facade (Recommended for Laravel)

[](#using-facade-recommended-for-laravel)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

// Get top 10 cryptocurrencies
$listings = CoinMarketCap::cryptocurrency()->listingsLatest([
    'start' => 1,
    'limit' => 10,
    'convert' => 'USD'
]);

// Get Bitcoin and Ethereum quotes
$quotes = CoinMarketCap::cryptocurrency()->quotesLatest([
    'symbol' => 'BTC,ETH',
    'convert' => 'USD'
]);
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use Tigusigalpa\CoinMarketCap\Client;

class CryptoController extends Controller
{
    public function __construct(private Client $client)
    {
    }

    public function index()
    {
        $listings = $this->client->cryptocurrency()->listingsLatest([
            'limit' => 10
        ]);

        return view('crypto.index', compact('listings'));
    }
}
```

### Standalone Usage (Outside Laravel)

[](#standalone-usage-outside-laravel)

```
use Tigusigalpa\CoinMarketCap\ClientBuilder;

$client = (new ClientBuilder())
    ->setApiKey('your-api-key')
    ->setBaseUrl('https://pro-api.coinmarketcap.com')
    ->setTimeout(30)
    ->build();

$quote = $client->cryptocurrency()->quotesLatest([
    'symbol' => 'BTC,ETH',
    'convert' => 'USD'
]);
```

Available API Methods
---------------------

[](#available-api-methods)

### Cryptocurrency API

[](#cryptocurrency-api)

MethodEndpointDescription`listingsLatest()``/v1/cryptocurrency/listings/latest`Get list of cryptocurrencies by market cap`listingsHistorical()``/v1/cryptocurrency/listings/historical`Historical listings`quotesLatest()``/v2/cryptocurrency/quotes/latest`Current quotes for specific cryptocurrencies`quotesHistorical()``/v2/cryptocurrency/quotes/historical`Historical quotes`info()``/v2/cryptocurrency/info`Metadata (logos, links, description)`map()``/v1/cryptocurrency/map`CoinMarketCap ID mapping`ohlcvLatest()``/v2/cryptocurrency/ohlcv/latest`Latest OHLCV data`ohlcvHistorical()``/v2/cryptocurrency/ohlcv/historical`Historical OHLCV data`categories()``/v1/cryptocurrency/categories`Cryptocurrency categories`trendingLatest()``/v1/cryptocurrency/trending/latest`Trending cryptocurrencies`trendingGainersLosers()``/v1/cryptocurrency/trending/gainers-losers`Top gainers and losers### Exchange API

[](#exchange-api)

MethodEndpointDescription`listingsLatest()``/v1/exchange/listings/latest`List of exchanges by trading volume`quotesLatest()``/v1/exchange/quotes/latest`Current exchange data`quotesHistorical()``/v1/exchange/quotes/historical`Historical data`info()``/v1/exchange/info`Exchange metadata`map()``/v1/exchange/map`Exchange ID mapping`marketPairsLatest()``/v1/exchange/market-pairs/latest`Exchange trading pairs### Global Metrics API

[](#global-metrics-api)

MethodEndpointDescription`quotesLatest()``/v1/global-metrics/quotes/latest`Current global metrics`quotesHistorical()``/v1/global-metrics/quotes/historical`Historical global metrics### Tools API

[](#tools-api)

MethodEndpointDescription`priceConversion()``/v2/tools/price-conversion`Convert prices between currenciesUsage examples
--------------

[](#usage-examples)

### Portfolio tracker

[](#portfolio-tracker)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

class CryptoPortfolioController extends Controller
{
    public function showPortfolio()
    {
        // User's cryptocurrency holdings
        $portfolio = [
            'BTC' => 0.5,      // 0.5 Bitcoin
            'ETH' => 10,       // 10 Ethereum
            'BNB' => 50,       // 50 Binance Coin
            'ADA' => 1000,     // 1000 Cardano
        ];

        // Get current prices for all holdings
        $quotes = CoinMarketCap::cryptocurrency()->quotesLatest([
            'symbol' => implode(',', array_keys($portfolio)),
            'convert' => 'USD'
        ]);

        $totalValue = 0;
        $holdings = [];

        foreach ($portfolio as $symbol => $amount) {
            $price = $quotes['data'][$symbol]['quote']['USD']['price'];
            $value = $amount * $price;
            $totalValue += $value;

            $holdings[] = [
                'name' => $quotes['data'][$symbol]['name'],
                'symbol' => $symbol,
                'amount' => $amount,
                'price' => $price,
                'value' => $value,
                'change_24h' => $quotes['data'][$symbol]['quote']['USD']['percent_change_24h']
            ];
        }

        return view('portfolio', compact('holdings', 'totalValue'));
    }
}
```

### Price alert system

[](#price-alert-system)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;
use Illuminate\Support\Facades\Notification;

class CryptoPriceAlertService
{
    public function checkPriceAlerts()
    {
        // Get user-defined price alerts from database
        $alerts = PriceAlert::where('active', true)->get();

        // Group alerts by cryptocurrency symbol
        $symbols = $alerts->pluck('symbol')->unique()->implode(',');

        // Fetch current prices
        $quotes = CoinMarketCap::cryptocurrency()->quotesLatest([
            'symbol' => $symbols,
            'convert' => 'USD'
        ]);

        foreach ($alerts as $alert) {
            $currentPrice = $quotes['data'][$alert->symbol]['quote']['USD']['price'];

            // Check if price crossed threshold
            if ($alert->type === 'above' && $currentPrice >= $alert->target_price) {
                $this->sendAlert($alert, $currentPrice);
            } elseif ($alert->type === 'below' && $currentPrice target_price) {
                $this->sendAlert($alert, $currentPrice);
            }
        }
    }

    private function sendAlert($alert, $currentPrice)
    {
        Notification::send($alert->user, new CryptoPriceAlert([
            'symbol' => $alert->symbol,
            'current_price' => $currentPrice,
            'target_price' => $alert->target_price,
        ]));

        $alert->update(['active' => false]);
    }
}
```

### Top cryptocurrencies by market cap

[](#top-cryptocurrencies-by-market-cap)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

class CryptoMarketController extends Controller
{
    public function topCryptocurrencies()
    {
        $top100 = CoinMarketCap::cryptocurrency()->listingsLatest([
            'start' => 1,
            'limit' => 100,
            'convert' => 'USD',
            'sort' => 'market_cap',
            'sort_dir' => 'desc'
        ]);

        $cryptocurrencies = collect($top100['data'])->map(function ($crypto) {
            return [
                'rank' => $crypto['cmc_rank'],
                'name' => $crypto['name'],
                'symbol' => $crypto['symbol'],
                'price' => $crypto['quote']['USD']['price'],
                'market_cap' => $crypto['quote']['USD']['market_cap'],
                'volume_24h' => $crypto['quote']['USD']['volume_24h'],
                'change_1h' => $crypto['quote']['USD']['percent_change_1h'],
                'change_24h' => $crypto['quote']['USD']['percent_change_24h'],
                'change_7d' => $crypto['quote']['USD']['percent_change_7d'],
            ];
        });

        return view('crypto.market', compact('cryptocurrencies'));
    }
}
```

### Price converter

[](#price-converter)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

class CryptoConverterController extends Controller
{
    public function convert(Request $request)
    {
        $conversion = CoinMarketCap::tools()->priceConversion([
            'amount' => $request->amount,
            'symbol' => $request->from_currency,
            'convert' => $request->to_currency
        ]);

        $result = [
            'from' => [
                'amount' => $request->amount,
                'currency' => $request->from_currency,
            ],
            'to' => [
                'amount' => $conversion['data']['quote'][$request->to_currency]['price'],
                'currency' => $request->to_currency,
            ],
            'rate' => $conversion['data']['quote'][$request->to_currency]['price'] / $request->amount,
            'timestamp' => $conversion['data']['last_updated']
        ];

        return response()->json($result);
    }
}
```

### Trending cryptocurrencies

[](#trending-cryptocurrencies)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

class TrendingCryptoController extends Controller
{
    public function trending()
    {
        // Get trending cryptocurrencies
        $trending = CoinMarketCap::cryptocurrency()->trendingLatest([
            'limit' => 10,
            'convert' => 'USD'
        ]);

        // Get top gainers and losers
        $gainersLosers = CoinMarketCap::cryptocurrency()->trendingGainersLosers([
            'limit' => 10,
            'convert' => 'USD',
            'time_period' => '24h'
        ]);

        return view('crypto.trending', [
            'trending' => $trending['data'],
            'gainers' => $gainersLosers['data']['gainers'],
            'losers' => $gainersLosers['data']['losers']
        ]);
    }
}
```

### Cryptocurrency metadata

[](#cryptocurrency-metadata)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

$info = CoinMarketCap::cryptocurrency()->info([
    'symbol' => 'BTC,ETH,BNB',
]);

foreach ($info['data'] as $symbol => $crypto) {
    echo "Name: {$crypto['name']}\n";
    echo "Symbol: {$crypto['symbol']}\n";
    echo "Description: {$crypto['description']}\n";
    echo "Website: {$crypto['urls']['website'][0]}\n";
    echo "Logo: {$crypto['logo']}\n";
    echo "Twitter: {$crypto['urls']['twitter'][0]}\n";
}
```

### Global market metrics

[](#global-market-metrics)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

$metrics = CoinMarketCap::globalMetrics()->quotesLatest([
    'convert' => 'USD'
]);

$data = $metrics['data'];

$marketStats = [
    'total_market_cap' => $data['quote']['USD']['total_market_cap'],
    'total_volume_24h' => $data['quote']['USD']['total_volume_24h'],
    'btc_dominance' => $data['btc_dominance'],
    'eth_dominance' => $data['eth_dominance'],
    'active_cryptocurrencies' => $data['active_cryptocurrencies'],
    'active_exchanges' => $data['active_exchanges'],
    'active_market_pairs' => $data['active_market_pairs'],
];

return view('crypto.global-stats', compact('marketStats'));
```

### Exchange comparison

[](#exchange-comparison)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

class ExchangeComparisonController extends Controller
{
    public function compareExchanges()
    {
        $exchanges = CoinMarketCap::exchange()->listingsLatest([
            'limit' => 50,
            'sort' => 'volume_24h',
            'convert' => 'USD'
        ]);

        $exchangeData = collect($exchanges['data'])->map(function ($exchange) {
            return [
                'name' => $exchange['name'],
                'volume_24h' => $exchange['quote']['USD']['volume_24h'],
                'num_market_pairs' => $exchange['num_market_pairs'],
                'traffic_score' => $exchange['traffic_score'] ?? 0,
            ];
        });

        return view('crypto.exchanges', compact('exchangeData'));
    }
}
```

### Historical price data

[](#historical-price-data)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

class HistoricalDataController extends Controller
{
    public function getHistoricalPrices($symbol)
    {
        $historical = CoinMarketCap::cryptocurrency()->quotesHistorical([
            'symbol' => $symbol,
            'convert' => 'USD',
            'time_start' => now()->subDays(30)->timestamp,
            'time_end' => now()->timestamp,
            'interval' => 'daily'
        ]);

        $priceData = collect($historical['data']['quotes'])->map(function ($quote) {
            return [
                'date' => $quote['timestamp'],
                'price' => $quote['quote']['USD']['price'],
                'volume' => $quote['quote']['USD']['volume_24h'],
                'market_cap' => $quote['quote']['USD']['market_cap'],
            ];
        });

        return response()->json($priceData);
    }
}
```

### Caching

[](#caching)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;
use Illuminate\Support\Facades\Cache;

class CachedCryptoService
{
    public function getTopCryptocurrencies($limit = 100)
    {
        $cacheKey = "crypto_top_{$limit}";

        return Cache::remember($cacheKey, now()->addMinutes(5), function () use ($limit) {
            return CoinMarketCap::cryptocurrency()->listingsLatest([
                'limit' => $limit,
                'convert' => 'USD'
            ]);
        });
    }

    public function getBitcoinPrice()
    {
        return Cache::remember('btc_price', now()->addMinutes(1), function () {
            $quote = CoinMarketCap::cryptocurrency()->quotesLatest([
                'symbol' => 'BTC',
                'convert' => 'USD'
            ]);

            return $quote['data']['BTC']['quote']['USD']['price'];
        });
    }
}

## Error handling

### Exception types

| Exception | HTTP Code | Description | Common Causes |
|-----------|-----------|-------------|---------------|
| `AuthenticationException` | 401 | Invalid or missing API key | Wrong API key, expired key |
| `RateLimitException` | 429 | API rate limit exceeded | Too many requests, plan limit reached |
| `InvalidRequestException` | 400 | Invalid request parameters | Wrong parameter format, missing required fields |
| `NotFoundException` | 404 | Resource not found | Invalid cryptocurrency ID or symbol |
| `ApiException` | Various | General API error | Network issues, server errors |

### Basic Error Handling

```php
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;
use Tigusigalpa\CoinMarketCap\Exception\RateLimitException;
use Tigusigalpa\CoinMarketCap\Exception\AuthenticationException;
use Tigusigalpa\CoinMarketCap\Exception\InvalidRequestException;
use Tigusigalpa\CoinMarketCap\Exception\NotFoundException;
use Tigusigalpa\CoinMarketCap\Exception\ApiException;
use Illuminate\Support\Facades\Log;

try {
    $listings = CoinMarketCap::cryptocurrency()->listingsLatest([
        'limit' => 100,
        'convert' => 'USD'
    ]);

    // Process cryptocurrency data

} catch (AuthenticationException $e) {
    // Invalid API key - check your .env configuration
    Log::error('CoinMarketCap Authentication Error', [
        'message' => $e->getMessage(),
        'status_code' => $e->statusCode,
    ]);

    return response()->json([
        'error' => 'API authentication failed. Please check your API key.'
    ], 401);

} catch (RateLimitException $e) {
    // Rate limit exceeded - implement retry logic
    $retryAfter = $e->getRetryAfter();

    Log::warning('CoinMarketCap Rate Limit Exceeded', [
        'message' => $e->getMessage(),
        'retry_after' => $retryAfter,
    ]);

    return response()->json([
        'error' => 'Rate limit exceeded. Please try again later.',
        'retry_after' => $retryAfter
    ], 429);

} catch (InvalidRequestException $e) {
    // Invalid parameters - check your request
    Log::error('CoinMarketCap Invalid Request', [
        'message' => $e->getMessage(),
        'response' => $e->getResponse(),
    ]);

    return response()->json([
        'error' => 'Invalid request parameters.',
        'details' => $e->getMessage()
    ], 400);

} catch (NotFoundException $e) {
    // Resource not found - invalid cryptocurrency ID/symbol
    Log::warning('CoinMarketCap Resource Not Found', [
        'message' => $e->getMessage(),
    ]);

    return response()->json([
        'error' => 'Cryptocurrency not found.'
    ], 404);

} catch (ApiException $e) {
    // General API error
    Log::error('CoinMarketCap API Error', [
        'message' => $e->getMessage(),
        'status_code' => $e->statusCode,
        'response' => $e->getResponse(),
    ]);

    return response()->json([
        'error' => 'An error occurred while fetching cryptocurrency data.'
    ], 500);
}
```

### Retry logic

[](#retry-logic)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;
use Tigusigalpa\CoinMarketCap\Exception\RateLimitException;

class ResilientCryptoService
{
    public function getCryptoPricesWithRetry($symbols, $maxRetries = 3)
    {
        $attempt = 0;

        while ($attempt < $maxRetries) {
            try {
                return CoinMarketCap::cryptocurrency()->quotesLatest([
                    'symbol' => $symbols,
                    'convert' => 'USD'
                ]);

            } catch (RateLimitException $e) {
                $attempt++;

                if ($attempt >= $maxRetries) {
                    throw $e;
                }

                $retryAfter = $e->getRetryAfter() ?? 60;
                Log::info("Rate limit hit. Retrying after {$retryAfter} seconds...");
                sleep($retryAfter);
            }
        }
    }
}
```

### Fallback with cache

[](#fallback-with-cache)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;
use Tigusigalpa\CoinMarketCap\Exception\ApiException;
use Illuminate\Support\Facades\Cache;

class CryptoServiceWithFallback
{
    public function getBitcoinPrice()
    {
        try {
            $quote = CoinMarketCap::cryptocurrency()->quotesLatest([
                'symbol' => 'BTC',
                'convert' => 'USD'
            ]);

            $price = $quote['data']['BTC']['quote']['USD']['price'];

            // Cache successful response
            Cache::put('btc_price_fallback', $price, now()->addHours(1));

            return $price;

        } catch (ApiException $e) {
            Log::error('Failed to fetch Bitcoin price', ['error' => $e->getMessage()]);

            // Return cached data as fallback
            return Cache::get('btc_price_fallback', 0);
        }
    }
}
```

### Monitoring API usage

[](#monitoring-api-usage)

```
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

class ApiUsageMonitor
{
    public function trackApiUsage()
    {
        try {
            $response = CoinMarketCap::cryptocurrency()->listingsLatest(['limit' => 1]);

            $creditCount = $response['status']['credit_count'];
            $timestamp = $response['status']['timestamp'];

            // Log API usage
            Log::info('CoinMarketCap API Usage', [
                'credits_used' => $creditCount,
                'timestamp' => $timestamp,
            ]);

            // Store in database for monitoring
            ApiUsage::create([
                'credits_used' => $creditCount,
                'endpoint' => 'cryptocurrency/listings/latest',
                'called_at' => $timestamp,
            ]);

        } catch (\Exception $e) {
            Log::error('Failed to track API usage', ['error' => $e->getMessage()]);
        }
    }
}
```

### Common Issues and Solutions

[](#common-issues-and-solutions)

**Issue: "Authentication failed" error**

- **Solution**: Verify your API key in `.env` file is correct
- Check that `COINMARKETCAP_API_KEY` is set properly
- Ensure no extra spaces or quotes around the API key
- Run `php artisan config:clear` after changing `.env`

**Issue: Rate limit exceeded**

- **Solution**: Implement caching to reduce API calls
- Upgrade your CoinMarketCap API plan for higher limits
- Use the sandbox environment for testing
- Implement exponential backoff retry logic

**Issue: Invalid cryptocurrency symbol**

- **Solution**: Use the `map()` endpoint to get valid symbols
- Check CoinMarketCap documentation for correct symbol format
- Use cryptocurrency ID instead of symbol for more reliability

**Issue: Timeout errors**

- **Solution**: Increase timeout in configuration
- Check your network connection
- Use asynchronous requests for multiple API calls

Sandbox mode
------------

[](#sandbox-mode)

### Via `.env`

[](#via-env)

```
COINMARKETCAP_USE_SANDBOX=true
COINMARKETCAP_API_KEY=your-sandbox-api-key
```

### Enable Sandbox Programmatically

[](#enable-sandbox-programmatically)

```
use Tigusigalpa\CoinMarketCap\ClientBuilder;

$client = (new ClientBuilder())
    ->setApiKey('your-sandbox-api-key')
    ->useSandbox()
    ->build();

// Now all API calls will use the sandbox environment
$quotes = $client->cryptocurrency()->quotesLatest([
    'symbol' => 'BTC',
    'convert' => 'USD'
]);
```

Sandbox uses the same response format as production, so you can test without spending credits.

Performance tips
----------------

[](#performance-tips)

### Caching

[](#caching-1)

```
use Illuminate\Support\Facades\Cache;
use Tigusigalpa\CoinMarketCap\Facades\CoinMarketCap;

// Cache for 5 minutes
$cryptoData = Cache::remember('crypto_top_100', 300, function () {
    return CoinMarketCap::cryptocurrency()->listingsLatest([
        'limit' => 100,
        'convert' => 'USD'
    ]);
});
```

### Batch requests

[](#batch-requests)

```
// Good: Single API call for multiple cryptocurrencies
$quotes = CoinMarketCap::cryptocurrency()->quotesLatest([
    'symbol' => 'BTC,ETH,BNB,ADA,XRP,SOL,DOT,DOGE',
    'convert' => 'USD'
]);

// Bad: Multiple API calls
// Don't do this - wastes API credits
foreach (['BTC', 'ETH', 'BNB'] as $symbol) {
    $quote = CoinMarketCap::cryptocurrency()->quotesLatest([
        'symbol' => $symbol
    ]);
}
```

### Background jobs

[](#background-jobs)

```
use Illuminate\Bus\Queueable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Contracts\Queue\ShouldQueue;

class UpdateCryptoPricesJob implements ShouldQueue
{
    use Queueable, InteractsWithQueue;

    public function handle()
    {
        $prices = CoinMarketCap::cryptocurrency()->listingsLatest([
            'limit' => 100
        ]);

        // Update database
        foreach ($prices['data'] as $crypto) {
            CryptoCurrency::updateOrCreate(
                ['symbol' => $crypto['symbol']],
                ['price' => $crypto['quote']['USD']['price']]
            );
        }
    }
}

// Dispatch job
UpdateCryptoPricesJob::dispatch();
```

### Store historical data locally

[](#store-historical-data-locally)

```
// Fetch once and store
$historical = CoinMarketCap::cryptocurrency()->quotesHistorical([
    'symbol' => 'BTC',
    'time_start' => now()->subDays(30)->timestamp,
    'interval' => 'daily'
]);

foreach ($historical['data']['quotes'] as $quote) {
    HistoricalPrice::create([
        'symbol' => 'BTC',
        'price' => $quote['quote']['USD']['price'],
        'date' => $quote['timestamp']
    ]);
}

// Query from database for charts
$chartData = HistoricalPrice::where('symbol', 'BTC')
    ->whereBetween('date', [now()->subDays(30), now()])
    ->get();
```

### Request only needed fields

[](#request-only-needed-fields)

```
// Only fetch required fields
$listings = CoinMarketCap::cryptocurrency()->listingsLatest([
    'limit' => 10,
    'convert' => 'USD',
    'aux' => 'num_market_pairs,cmc_rank' // Only specific auxiliary fields
]);
```

FAQ
---

[](#faq)

### General Questions

[](#general-questions)

**Q: Is this package free to use?**A: The package is open-source (MIT). You need a CoinMarketCap API key — the Basic plan is free (10,000 calls/month).

**Q: What's the difference between this package and calling the API directly?**A: Type-safe models, automatic error handling, Laravel integration, retry logic, and a clean interface. Saves boilerplate.

**Q: Can I use this package outside of Laravel?**A: Yes. Use the standalone `ClientBuilder` in any PHP 8.1+ project.

**Q: Does this support all CoinMarketCap API endpoints?**A: All major cryptocurrency, exchange, global metrics, and tools endpoints are covered.

### API &amp; Authentication

[](#api--authentication)

**Q: How do I get a CoinMarketCap API key?**A: Visit [coinmarketcap.com/api](https://coinmarketcap.com/api/), sign up for a free account, and get your API key from the dashboard.

**Q: What are the API rate limits?**A: The free Basic plan includes 10,000 calls/month. Paid plans offer higher limits. The package automatically handles rate limit errors.

**Q: Can I use multiple API keys?**A: Yes, you can create multiple client instances with different API keys using the ClientBuilder.

**Q: Is my API key secure?**A: Yes, store your API key in the `.env` file (never commit it to version control). The package sends it securely via HTTPS headers.

### Cryptocurrency Data

[](#cryptocurrency-data)

**Q: How often is cryptocurrency data updated?**A: CoinMarketCap updates prices every 60 seconds for most cryptocurrencies. Implement caching to avoid unnecessary API calls.

**Q: Can I get historical cryptocurrency prices?**A: Yes, use the `quotesHistorical()` or `ohlcvHistorical()` methods to fetch historical price data.

**Q: How many cryptocurrencies are supported?**A: CoinMarketCap tracks 10,000+ cryptocurrencies including Bitcoin, Ethereum, and all major altcoins.

**Q: Can I convert between different fiat currencies?**A: Yes, use the `convert` parameter with currencies like USD, EUR, GBP, JPY, etc.

### Technical Questions

[](#technical-questions)

**Q: What PHP version is required?**A: PHP 8.1 or higher is required to use modern PHP features like readonly properties and union types.

**Q: Does this work with Laravel 11?**A: Yes, the package supports both Laravel 10.x and 11.x.

**Q: Can I customize the HTTP client?**A: Yes, the package uses PSR-18 standard, allowing you to inject any compatible HTTP client.

**Q: How do I handle API errors?**A: The package provides specific exceptions for different error types. See the Error Handling section above.

### Performance &amp; Optimization

[](#performance--optimization)

**Q: How can I reduce API calls?**A: Implement caching, use batch requests, and store frequently accessed data in your database.

**Q: What's the best caching strategy?**A: Cache cryptocurrency listings for 5 minutes, individual prices for 1 minute, and metadata for 1 hour.

**Q: Can I use this in a high-traffic application?**A: Yes, with proper caching and a suitable CoinMarketCap API plan. Consider upgrading to Professional plan for high-volume applications.

Integration examples
--------------------

[](#integration-examples)

### WordPress Plugin Integration

[](#wordpress-plugin-integration)

```
// WordPress plugin example
add_shortcode('crypto_price', function($atts) {
    $symbol = $atts['symbol'] ?? 'BTC';

    $client = (new ClientBuilder())
        ->setApiKey(get_option('coinmarketcap_api_key'))
        ->build();

    $quote = $client->cryptocurrency()->quotesLatest([
        'symbol' => $symbol,
        'convert' => 'USD'
    ]);

    $price = $quote['data'][$symbol]['quote']['USD']['price'];

    return sprintf('$%s', number_format($price, 2));
});

// Usage: [crypto_price symbol="BTC"]
```

### API Endpoint for Mobile Apps

[](#api-endpoint-for-mobile-apps)

```
// routes/api.php
Route::get('/crypto/prices', function () {
    $prices = Cache::remember('mobile_crypto_prices', 60, function () {
        return CoinMarketCap::cryptocurrency()->listingsLatest([
            'limit' => 50,
            'convert' => 'USD'
        ]);
    });

    return response()->json($prices);
});
```

### Webhook Integration

[](#webhook-integration)

```
// Send crypto price updates via webhook
class CryptoPriceWebhook
{
    public function sendPriceUpdate($symbol)
    {
        $quote = CoinMarketCap::cryptocurrency()->quotesLatest([
            'symbol' => $symbol,
            'convert' => 'USD'
        ]);

        $data = [
            'symbol' => $symbol,
            'price' => $quote['data'][$symbol]['quote']['USD']['price'],
            'change_24h' => $quote['data'][$symbol]['quote']['USD']['percent_change_24h'],
            'timestamp' => now()->toIso8601String()
        ];

        Http::post('https://your-webhook-url.com/crypto-update', $data);
    }
}
```

Testing
-------

[](#testing)

### Run tests

[](#run-tests)

```
composer test
```

### Coverage report

[](#coverage-report)

```
composer test-coverage
```

### Static analysis (PHPStan level 8)

[](#static-analysis-phpstan-level-8)

```
composer phpstan
```

### Code style (PSR-12)

[](#code-style-psr-12)

```
composer cs-fix
```

### Writing tests

[](#writing-tests)

```
namespace Tigusigalpa\CoinMarketCap\Tests\Unit;

use PHPUnit\Framework\TestCase;
use Tigusigalpa\CoinMarketCap\ClientBuilder;

class YourFeatureTest extends TestCase
{
    public function test_your_feature_works()
    {
        $client = (new ClientBuilder())
            ->setApiKey('test-key')
            ->build();

        // Your test assertions
        $this->assertInstanceOf(Client::class, $client);
    }
}
```

Contributing
------------

[](#contributing)

1. **Fork the Repository**

    ```
    git clone https://github.com/tigusigalpa/coinmarketcap.git
    cd coinmarketcap
    ```
2. **Install Dependencies**

    ```
    composer install
    ```
3. **Create a Feature Branch**

    ```
    git checkout -b feature/add-new-endpoint
    ```
4. **Make Your Changes**

    - Write clean, well-documented code
    - Follow PSR-12 coding standards
    - Add type hints to all methods
    - Use strict types declaration
5. **Write Tests**

    ```
    # Add tests in tests/Unit or tests/Feature
    composer test
    ```
6. **Run Quality Checks**

    ```
    composer phpstan      # Static analysis
    composer cs-fix       # Code style
    composer test         # All tests
    ```
7. **Commit Your Changes**

    ```
    git commit -m "Add support for new CoinMarketCap endpoint"
    ```
8. **Push and Create Pull Request**

    ```
    git push origin feature/add-new-endpoint
    ```

### Guidelines

[](#guidelines)

- Follow PSR-12, use PHP 8.1+ features, PHPDoc blocks on public methods
- PHPStan level 8 must pass
- Write unit tests for new features
- Update README and CHANGELOG as needed

Security
--------

[](#security)

Do **not** create public GitHub issues for security vulnerabilities. Email: ****

License
-------

[](#license)

MIT License — see [LICENSE](LICENSE).

Author
------

[](#author)

**Igor Sazonov**

- GitHub: [@tigusigalpa](https://github.com/tigusigalpa)
- Email:

Links
-----

[](#links)

- [CoinMarketCap API Documentation](https://coinmarketcap.com/api/documentation/v1/)
- [CoinMarketCap API Portal](https://coinmarketcap.com/api/)
- [GitHub Repository](https://github.com/tigusigalpa/coinmarketcap)
- [Packagist](https://packagist.org/packages/tigusigalpa/coinmarketcap)
- [Changelog](CHANGELOG.md)

###  Health Score

37

—

LowBetter than 81% of packages

Maintenance76

Regular maintenance activity

Popularity11

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

156d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/2721390?v=4)[Igor Sazonov](/maintainers/tigusigalpa)[@tigusigalpa](https://github.com/tigusigalpa)

---

Top Contributors

[![tigusigalpa](https://avatars.githubusercontent.com/u/2721390?v=4)](https://github.com/tigusigalpa "tigusigalpa (5 commits)")

---

Tags

apibinancebingxbitcoinbybitchainlinkcoinmarketcapcoinmarketcap-apicoinmarketcap-clientcryptocryptocurrencylaravelnearnear-protocolphpapilaravelbitcoincryptocurrencyethereumcoinmarketcap

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/tigusigalpa-coinmarketcap/health.svg)

```
[![Health](https://phpackages.com/badges/tigusigalpa-coinmarketcap/health.svg)](https://phpackages.com/packages/tigusigalpa-coinmarketcap)
```

###  Alternatives

[mollie/mollie-api-php

Mollie API client library for PHP. Mollie is a European Payment Service provider and offers international payment methods such as Mastercard, VISA, American Express and PayPal, and local payment methods such as iDEAL, Bancontact, SOFORT Banking, SEPA direct debit, Belfius Direct Net, KBC Payment Button and various gift cards such as Podiumcadeaukaart and fashioncheque.

60216.0M85](/packages/mollie-mollie-api-php)[tempest/framework

The PHP framework that gets out of your way.

2.2k34.4k15](/packages/tempest-framework)[getbrevo/brevo-php

Official Brevo provided RESTFul API V3 php library

1003.9M50](/packages/getbrevo-brevo-php)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35789.4k2](/packages/telnyx-telnyx-php)[flow-php/flow

PHP ETL - Extract Transform Load - Data processing framework

85036.3k](/packages/flow-php-flow)[bushlanov-dev/max-bot-api-client-php

Max Bot API Client library

486.3k](/packages/bushlanov-dev-max-bot-api-client-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)