# The Card API — Complete Reference for LLMs

> This file is designed to be fetched and pasted into an LLM context window to give the model everything needed to work with The Card API. Fetch this URL to get the full reference: https://thecardapi.com/llms-full.txt

Last updated: 2025-05-19.

---

## What is The Card API?

The Card API is a REST API and MCP server providing programmatic access to trading card sold prices across all major platforms. It is the market data infrastructure layer for the trading card industry — targeting developers, data scientists, AI agents, and products that need real market transaction data rather than averaged estimates.

Key differentiators:
- Individual sale records (not averages or estimates)
- True Best Offer accepted prices on eBay (most sources show the asking price, not the negotiated price)
- 7 platforms unified in one schema: eBay, Goldin, Heritage, Fanatics-Vault, REA, Alt, Pristine
- 38+ card categories: baseball, basketball, football, hockey, soccer, Pokemon, non-sport, memorabilia
- 200,000+ new records ingested daily
- MCP server with 7 AI-native tools for use with Claude, Cursor, and other MCP clients

---

## Authentication

All API requests require an `x-market-api-key` header. Get a free key (no credit card required) at https://thecardapi.com.

```
# REST API
GET https://thecardapi.com/api/v1/market/sales
x-market-api-key: tca_your_key_here

# MCP Server
POST https://thecardapi.com/api/mcp
Authorization: Bearer tca_your_key_here
```

Free tier: 10,000 sales per day, 7-day lookback.

---

## Base URLs

- REST API: `https://thecardapi.com/api/v1/market`
- MCP Server: `https://thecardapi.com/api/mcp`

---

## REST Endpoints

### GET /sales

Search and filter sale records. This is the primary endpoint.

**Query parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| q | string | No | Full-text search across all card titles |
| platform | string | No | Filter to one platform: eBay, Goldin, Heritage, Fanatics-Vault, REA, Alt, Pristine |
| listing_type | string | No | Auction, FixedPrice, or BestOffer |
| date_from | string | No | Start date (YYYY-MM-DD). Defaults to 7 days ago. |
| date_to | string | No | End date (YYYY-MM-DD). Defaults to today. |
| min_price | number | No | Minimum sale price in USD |
| max_price | number | No | Maximum sale price in USD |
| limit | integer | No | Records per page. Maximum 500. Default 50. |
| offset | integer | No | Pagination offset. Default 0. |

**Example request:**
```
GET https://thecardapi.com/api/v1/market/sales?q=Mike+Trout+PSA+10&platform=eBay&listing_type=BestOffer&date_from=2025-04-01&limit=100
x-market-api-key: tca_your_key_here
```

**Example response:**
```json
{
  "data": [
    {
      "id": "ebay_3941827461",
      "title": "2011 Topps Update Mike Trout RC #US175 PSA 10",
      "platform": "eBay",
      "listing_type": "BestOffer",
      "sale_price": 2450.00,
      "sale_date": "2025-04-12",
      "listing_url": "https://www.ebay.com/itm/...",
      "category": "Baseball Cards"
    }
  ],
  "total": 47,
  "page": 1,
  "per_page": 100
}
```

### GET /sales/{id}

Retrieve a single sale record by its ID.

**Example:**
```
GET https://thecardapi.com/api/v1/market/sales/ebay_3941827461
x-market-api-key: tca_your_key_here
```

Returns a single sale object with the same schema as above.

### GET /daily

Aggregate statistics for a specific date.

**Query parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| date | string | Date in YYYY-MM-DD format. Defaults to yesterday. |

**Example response:**
```json
{
  "date": "2025-04-12",
  "total_sales": 218432,
  "total_volume_usd": 4821904.50,
  "platforms": {
    "eBay": 195000,
    "Goldin": 8200,
    "Heritage": 6100,
    "Fanatics-Vault": 5200,
    "REA": 1800,
    "Alt": 1500,
    "Pristine": 632
  }
}
```

### GET /platforms

List all available platforms with last-updated timestamps.

**Example response:**
```json
{
  "platforms": [
    { "name": "eBay", "last_updated": "2025-04-12T23:45:00Z", "active": true },
    { "name": "Goldin", "last_updated": "2025-04-12T22:00:00Z", "active": true },
    { "name": "Heritage", "last_updated": "2025-04-12T18:30:00Z", "active": true }
  ]
}
```

### GET /coverage

Data freshness status.

**Example response:**
```json
{
  "total_records": 847293041,
  "latest_sale_date": "2025-04-12",
  "ingestion_lag_hours": 4.2,
  "platforms_active": 7
}
```

### GET /sales/export/csv

Download filtered sales as a CSV file. Accepts the same query parameters as GET /sales. Limit depends on tier (Free: 10K rows, Starter: 50K rows, Pro: unlimited).

**Example:**
```
GET https://thecardapi.com/api/v1/market/sales/export/csv?q=Shohei+Ohtani&date_from=2025-01-01
x-market-api-key: tca_your_key_here
```

Returns: `Content-Type: text/csv` with headers: id, title, platform, listing_type, sale_price, sale_date, listing_url, category

### POST /webhook

Register a webhook URL to receive new sale notifications matching a filter (Pro and Enterprise tiers).

**Request body:**
```json
{
  "url": "https://your-app.com/webhook",
  "filter": {
    "q": "Mike Trout",
    "min_price": 1000
  }
}
```

### GET /webhook

Get current webhook configuration.

### DELETE /webhook

Remove webhook registration.

---

## MCP Server

The MCP server provides AI-native access to The Card API for use with Claude Desktop, Cursor, Claude Code, and any other MCP-compatible client.

**Configuration (Claude Desktop `claude_desktop_config.json`):**
```json
{
  "mcpServers": {
    "cardapi": {
      "url": "https://thecardapi.com/api/mcp",
      "headers": {
        "Authorization": "Bearer tca_your_key_here"
      }
    }
  }
}
```

**Available MCP tools:**

### search_sales
Search card sales with full-text and filters.
- Parameters: q, platform, listing_type, date_from, date_to, min_price, max_price, limit, offset
- Returns: Array of sale records + total count

### get_sale
Retrieve a single sale record by ID.
- Parameters: id (required)
- Returns: Single sale record

### get_daily
Get aggregate stats for a date.
- Parameters: date (YYYY-MM-DD, optional, defaults to yesterday)
- Returns: Total sales, volume, platform breakdown

### get_platforms
List all platforms with freshness info.
- Parameters: none
- Returns: Array of platform objects with name, last_updated, active status

### get_coverage
Check data freshness and coverage.
- Parameters: none
- Returns: Total records, latest sale date, ingestion lag

### export_csv
Download sales as CSV.
- Parameters: q, platform, listing_type, date_from, date_to, min_price, max_price
- Returns: CSV file contents as string

### get_market_analysis
AI-synthesized market analysis for a card or search term.
- Parameters: q (required), days (optional, default 7)
- Returns: Narrative analysis with price statistics, trend observations, platform breakdown

---

## Sale Record Schema

Every sale record from every platform has the same structure:

```typescript
interface SaleRecord {
  id: string;              // Unique record ID (platform_listingid format)
  title: string;           // Card title as listed (includes player, set, year, grade, variant)
  platform: string;        // "eBay" | "Goldin" | "Heritage" | "Fanatics-Vault" | "REA" | "Alt" | "Pristine"
  listing_type: string;    // "Auction" | "FixedPrice" | "BestOffer"
  sale_price: number;      // True sold price in USD (accepted offer for BestOffer listings)
  sale_date: string;       // YYYY-MM-DD
  listing_url: string;     // Direct link to the original listing
  category: string;        // Card category (e.g., "Baseball Cards", "Basketball Cards", "Pokemon")
}
```

---

## Platform Coverage Details

### eBay
- **Listing types covered:** Auction (hammer price), Fixed Price (buy it now), Best Offer (true accepted price)
- **Why Best Offer matters:** Most price guides show the listing price for Best Offer sales, not the negotiated price. The Card API captures the actual accepted offer — typically 15-35% below asking price.
- **Volume:** Largest platform in the database. Continuous ingestion.
- **Categories:** All 38+ eBay Trading Cards subcategories

### Goldin Auctions
- **Listing types:** Auction only
- **Coverage:** All completed lots

### Heritage Auctions
- **Listing types:** Auction only
- **Coverage:** Sports card lots from all Heritage auction events

### Fanatics-Vault
- **Listing types:** Fixed Price, Best Offer
- **Coverage:** Authenticated collectibles marketplace

### REA (Robert Edward Auctions)
- **Listing types:** Auction only
- **Coverage:** Premium vintage and modern card lots

### Alt
- **Listing types:** Fixed Price, Best Offer
- **Coverage:** Whole card and fractionalized card marketplace

### Pristine Auction
- **Listing types:** Auction only
- **Coverage:** All completed card lots

---

## Card Categories (38+)

Baseball Cards, Basketball Cards, Football Cards, Hockey Cards, Soccer Cards, Pokemon, Magic: The Gathering, Non-Sport Trading Cards, Sports Memorabilia, Golf Cards, Tennis Cards, Boxing Cards, UFC/MMA Cards, Racing Cards, Wrestling Cards, and more.

---

## Pricing Tiers

| Tier | Monthly Price | Sales/day | Historical Lookback | CSV Export |
|------|--------------|-----------|---------------------|------------|
| Free | $0 | 10,000 | 7 days | 10,000 rows |
| Starter | $9 | 50,000 | 7 days | 50,000 rows |
| Pro | $49 | 500,000 | 30 days | Unlimited |
| Enterprise | Custom | Unlimited | Full history | Unlimited |

Additional Enterprise features: S3 bulk data delivery (daily), cursor pagination, dedicated support + SLA.

Free API key signup: https://thecardapi.com (email only, no credit card)

---

## Code Examples

### Python — pull comps for a card

```python
import requests
import statistics

API_KEY = "tca_your_key_here"
BASE = "https://thecardapi.com/api/v1/market"

def get_comps(search: str, days: int = 7) -> list[dict]:
    from datetime import date, timedelta
    date_from = (date.today() - timedelta(days=days)).isoformat()
    all_sales, offset = [], 0
    while True:
        r = requests.get(
            f"{BASE}/sales",
            params={"q": search, "date_from": date_from, "limit": 500, "offset": offset},
            headers={"x-market-api-key": API_KEY},
        )
        r.raise_for_status()
        batch = r.json()["data"]
        all_sales.extend(batch)
        if len(batch) < 500:
            break
        offset += 500
    return all_sales

comps = get_comps("Shohei Ohtani Rookie PSA 10")
prices = [s["sale_price"] for s in comps]
print(f"n={len(comps)}, median=${statistics.median(prices):,.0f}, mean=${statistics.mean(prices):,.0f}")
```

### JavaScript/Node — search and display recent sales

```javascript
const API_KEY = "tca_your_key_here";
const BASE = "https://thecardapi.com/api/v1/market";

async function searchSales(query, options = {}) {
  const params = new URLSearchParams({ q: query, limit: "50", ...options });
  const res = await fetch(`${BASE}/sales?${params}`, {
    headers: { "x-market-api-key": API_KEY },
  });
  if (!res.ok) throw new Error(`API error: ${res.status}`);
  return res.json();
}

const { data, total } = await searchSales("Luka Doncic Prizm", {
  platform: "eBay",
  min_price: "100",
  date_from: "2025-04-01",
});
console.log(`Found ${total} sales:`);
data.forEach(s => console.log(`${s.sale_date} | $${s.sale_price} | ${s.listing_type} | ${s.platform}`));
```

### curl — minimal example

```bash
curl "https://thecardapi.com/api/v1/market/sales?q=Mickey+Mantle&platform=Goldin&limit=10" \
  -H "x-market-api-key: tca_your_key_here"
```

---

## Error Codes

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 400 | Bad request (invalid parameter) |
| 401 | Missing or invalid API key |
| 429 | Rate limit exceeded (daily quota or burst) |
| 500 | Internal server error |

---

## Contact

- Email: hello@thecardapi.com
- API Reference: https://thecardapi.com/docs
- MCP Server docs: https://thecardapi.com/mcp
- Pricing: https://thecardapi.com/pricing
- Data status: https://thecardapi.com/status