PHP Packagist PHP 8.1+

PHP SDK

Official PHP client built on Guzzle. PHP 8.1+, PSR-4 autoloading, typed exception hierarchy, and automatic batch chunking.

install composer

$ composer require tcgpricelookup/sdk

Key Features

PHP 8.1+

Leverages enums, fibers, readonly properties, and union types.

Guzzle HTTP

Built on the industry-standard Guzzle HTTP client.

PSR-4 Autoloading

Integrates seamlessly with any PSR-4 compliant project.

Typed Exceptions

AuthenticationException, PlanAccessException, RateLimitException.

Auto-chunk Batches

Pass any number of IDs — SDK splits into ≤20-ID chunks.

Rate Limit Access

$client->rateLimit['remaining'] after each request.

Quickstart

quickstart.php PHP

<?php

require_once 'vendor/autoload.php';

use TcgPriceLookup\Client;

// Initialize the client
$client = new Client(getenv('TCG_API_KEY'));

// Search for cards
$results = $client->cards->search(['q' => 'charizard', 'game' => 'pokemon', 'limit' => 5]);
foreach ($results->data as $card) {
    echo $card->name . "\n";
}

// Get a specific card
$card = $client->cards->get('019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2');
echo $card->prices->raw->near_mint->tcgplayer->market;

// Check rate limit
echo $client->rateLimit['remaining'] . ' / ' . $client->rateLimit['limit'];

API Surface

$client->cards->search([]) Search & batch

// Keyword search
$results = $client->cards->search(['q' => 'black lotus', 'game' => 'mtg']);

// Batch lookup by IDs — auto-chunks beyond 20
$results = $client->cards->search(['ids' => ['uuid1', 'uuid2']]);

$client->cards->get($id) Single card lookup

$card = $client->cards->get('019535a1-d5d0-7c12-a3e8-b7f4c6d8e9a2');
echo $card->prices->raw->near_mint->tcgplayer->market;

$client->cards->history($id, []) Trader+ required

$history = $client->cards->history($card->id, ['period' => '30d']);
foreach ($history->data as $point) {
    echo $point->date . ': ' . $point->near_mint->tcgplayer->market . "\n";
}

$client->sets->list() / $client->games->list() Browse sets and games

$sets  = $client->sets->list(['game' => 'pokemon', 'limit' => 10]);
$games = $client->games->list();

Error Handling

error-handling.php

use TcgPriceLookup\Exceptions\AuthenticationException;
use TcgPriceLookup\Exceptions\PlanAccessException;
use TcgPriceLookup\Exceptions\NotFoundException;
use TcgPriceLookup\Exceptions\RateLimitException;

try {
    $card = $client->cards->get('some-id');
} catch (AuthenticationException $e) {
    echo 'Invalid API key';
} catch (PlanAccessException $e) {
    echo 'Plan upgrade required: ' . $e->getRequiredPlan();
} catch (NotFoundException $e) {
    echo 'Card not found';
} catch (RateLimitException $e) {
    echo 'Rate limited. Retry after ' . $e->getRetryAfter() . 's';
}

Rate Limit Headers

rate-limits.php

$client->cards->search(['q' => 'pikachu']);

echo $client->rateLimit['limit'];      // 100000
echo $client->rateLimit['remaining'];  // 99987
echo $client->rateLimit['reset'];      // Unix timestamp

Links

Start building with PHP

Get your free API key and query card prices in minutes.

Get Free API Key Read the Docs