# JustTCG — Complete LLM Reference

> This document is a comprehensive reference for AI agents. It covers the JustTCG REST API, MCP server, all endpoints, parameters, response schemas, supported games, pricing plans, and FAQ. Last updated: 2026-05-13.

---

## What is JustTCG?

JustTCG is a dedicated REST API for real-time Trading Card Game (TCG) pricing data. It is built for developers by TCG collectors. Pricing is market-driven: JustTCG determines market values by analyzing real sales data from all major online TCG marketplaces and applying a volume-weighted average. This produces stable, accurate market prices. JustTCG does not publish its specific data sources for business and legal reasons.

**Key properties:**
- Pricing updated continuously from real market sales data
- Coverage: 17+ TCGs, 270,000+ cards, 1M+ variants
- Condition-specific pricing (Near Mint, Lightly Played, Moderately Played, Heavily Played, Damaged, Sealed)
- Print-type filtering (Normal, Foil, 1st Edition, etc.)
- Price history: 7d, 30d, 90d, 180d, 1y trends
- Statistical summaries: 7d, 30d, 90d, 1y, allTime deltas
- Free tier available, no credit card required

---

## Base URLs

| Service | URL | Purpose |
|---|---|---|
| REST API (current) | `https://api.justtcg.com/v1` | Standard HTTP REST API |
| MCP Server | `https://mcp.justtcg.com` | Model Context Protocol server for AI agents |
| Dashboard | `https://justtcg.com/dashboard` | Manage keys and billing |
| Documentation | `https://justtcg.com/docs` | Full interactive docs |

---

## Authentication

All API requests (REST and MCP) require an API key passed in the request header:

```
X-API-Key: your_api_key_here
```

Get your API key from the dashboard: https://justtcg.com/dashboard

---

## MCP Server

JustTCG operates a hosted Model Context Protocol (MCP) server at `https://mcp.justtcg.com`.

MCP (Model Context Protocol) is an open standard created by Anthropic that enables AI agents (Claude, Cursor, Windsurf, and other MCP-compatible hosts) to call external tools and retrieve real-time data. The JustTCG MCP server exposes the full pricing dataset as AI-callable tools.

**Authentication:** Same API key as the REST API, passed as `X-API-Key` header.
**Compatible with:** Claude Desktop, Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible host.
**Tools available:** mirrors the REST API endpoints — query games, sets, and card prices in real-time from within an agentic workflow.

---

## REST API Endpoints

### GET /v1/games
Returns a list of all supported trading card games with statistics.

**No parameters required.**

**Response fields:**
- `id` (string): Game identifier (e.g., `magic-the-gathering`, `pokemon`, `yugioh`)
- `name` (string): Full game name
- `cards_count` (integer): Number of cards in the database
- `variants_count` (integer): Number of card variants (condition/print combinations)
- `sealed_count` (integer): Number of sealed products
- `sets_count` (integer): Number of sets
- `last_updated` (integer): Unix timestamp of last data update
- `game_value_index_cents` (integer): Total value of all cards in cents
- `game_value_change_7d_pct`, `game_value_change_30d_pct`, `game_value_change_90d_pct` (float): % value change over time windows

**Example request:**
```
curl -X GET "https://api.justtcg.com/v1/games" \
  -H "X-API-Key: your_api_key_here"
```

---

### GET /v1/sets
Returns a list of all sets. Filter by game using the `game` query parameter.

**Query parameters:**
- `game` (optional, string): Filter by game ID (e.g., `magic-the-gathering`, `pokemon`, `yugioh`)
- `q` (optional, string): Search sets by name
- `orderBy` (optional, string): `name` or `release_date`. Default: `name`
- `order` (optional, string): `asc` or `desc`. Default: `asc`

**Response fields per set:**
- `id` (string): Set identifier (e.g., `10th-edition-magic-the-gathering`)
- `name` (string): Full set name
- `game_id` (string): Parent game ID
- `game` (string): Parent game name
- `cards_count` (integer): Number of cards in the set
- `variants_count` (integer): Number of variants in the set
- `sealed_count` (integer): Number of sealed products
- `release_date` (string): ISO 8601 release date
- `set_value_usd` (float): Total value of all cards in USD
- `set_value_change_7d_pct`, `set_value_change_30d_pct`, `set_value_change_90d_pct` (float): % value changes

**Example request:**
```
curl -X GET "https://api.justtcg.com/v1/sets?game=magic-the-gathering" \
  -H "X-API-Key: your_api_key_here"
```

---

### GET /v1/cards
Flexible endpoint for card price lookups and search. Behavior depends on which parameters are provided.

**Lookup modes:**
1. **By Card ID** (`cardId`): Direct lookup by JustTCG card ID
2. **By Variant ID** (`variantId`): Direct lookup of a specific card variant
3. **By External ID** (`tcgplayerId`, `mtgjsonId`, `scryfallId`, `tcgplayerSkuId`): Lookup by third-party identifiers
4. **Search** (`q`): Full-text search by card name or text
5. **By Game** (`game`): Browse all cards in a game, with optional `set` filter
6. **By Set** (`set`): Browse all cards in a set
7. **Combined** (`q` + `game` or `set`): Search within a specific game or set

Note: An ID parameter (`cardId`, `variantId`, `tcgplayerId`, etc.) takes precedence over a search query (`q`) if both are provided.

**All query parameters:**

| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `cardId` | string | — | — | JustTCG card ID |
| `variantId` | string | — | — | JustTCG variant ID |
| `tcgplayerId` | string | — | — | TCGplayer product ID |
| `mtgjsonId` | string | — | — | MTGJSON card ID |
| `scryfallId` | string | — | — | Scryfall card ID |
| `tcgplayerSkuId` | string | — | — | TCGplayer SKU ID (ignores condition/printing filters) |
| `q` | string | — | — | Full-text search query |
| `game` | string | — | — | Game ID filter |
| `set` | string | — | — | Set ID filter |
| `number` | string | optional | — | Card number filter (e.g., `15`, `FOTB-EN062`) |
| `condition` | string | optional | `S,NM,LP,MP,HP,DMG` | Comma-separated conditions. Full names: Sealed, Near Mint, Lightly Played, Moderately Played, Heavily Played, Damaged. Abbreviations: S, NM, LP, MP, HP, DMG |
| `printing` | string | optional | — | Print type filter (e.g., `Normal`, `Foil`, `1st Edition`) |
| `updated_after` | string | optional | — | Unix timestamp (seconds). Returns only variants updated at or after this time. Cannot combine with `q`. |
| `priceHistoryDuration` | string | optional | `7d` | Duration of price history: `7d`, `30d`, `90d`, `180d`, or `1y` |
| `include_price_history` | boolean | optional | `true` | Include price history array in response |
| `include_statistics` | string | optional | `7d,30d,90d,1y,allTime` | Comma-separated list of stat timeframes to include |
| `include_null_prices` | boolean | optional | `false` | Include cards with no pricing data |
| `orderBy` | string | optional | `price` | Sort field: `price`, `24h`, `7d`, `30d`, or `90d` |
| `order` | string | optional | `desc` | Sort direction: `asc` or `desc` |
| `limit` | integer | optional | `20` | Results per page. Free: max 20, Starter/Pro: max 100, Enterprise: max 200 |
| `offset` | integer | optional | `0` | Pagination offset |

**Response card object:**
```json
{
  "data": [
    {
      "id": "yugioh-force-of-the-breaker-lich-lord-king-of-the-underworld",
      "name": "Lich Lord, King of the Underworld",
      "game": "YuGiOh",
      "set": "force-of-the-breaker-yugioh",
      "set_name": "Force of the Breaker",
      "number": "FOTB-EN062",
      "tcgplayerId": "25788",
      "rarity": "Secret Rare",
      "details": null,
      "variants": [
        {
          "id": "yugioh-force-of-the-breaker-lich-lord-king-of-the-underworld_near-mint_1st-edition",
          "condition": "Near Mint",
          "printing": "1st Edition",
          "price": 31.22,
          "lastUpdated": 1744774273.765591,
          "priceChange24h": 0
        }
      ]
    }
  ],
  "_metadata": {
    "apiRequestsUsed": 1,
    "apiRequestsRemaining": 99999
  }
}
```

**Example request (by game + filter):**
```
curl -X GET "https://api.justtcg.com/v1/cards?game=pokemon&orderBy=price&order=desc&limit=10&condition=NM" \
  -H "X-API-Key: your_api_key_here"
```

**Example request (search):**
```
curl -X GET "https://api.justtcg.com/v1/cards?q=Charizard&game=pokemon&condition=NM&limit=5" \
  -H "X-API-Key: your_api_key_here"
```

---

## Supported Games

Current games in the JustTCG database (as of May 2026):

| Game ID | Game Name | Approx. Cards |
|---|---|---|
| `digimon-card-game` | Digimon Card Game | 8,451+ |
| `disney-lorcana` | Disney Lorcana | 3,029+ |
| `dragon-ball-super-fusion-world` | Dragon Ball Super: Fusion World | 3,571+ |
| `flesh-and-blood-tcg` | Flesh and Blood TCG | 8,375+ |
| `grand-archive-tcg` | Grand Archive TCG | 3,978+ |
| `gundam-card-game` | Gundam Card Game | 1,368+ |
| `hololive-official-card-game` | hololive OFFICIAL CARD GAME | 1,349+ |
| `magic-the-gathering` | Magic: The Gathering | 107,264+ |
| `one-piece-card-game` | One Piece Card Game | 6,257+ |
| `pokemon` | Pokemon | 28,633+ |
| `pokemon-japan` | Pokemon Japan | 22,895+ |
| `riftbound-league-of-legends-trading-card-game` | Riftbound: League of Legends Trading Card Game | 1,089+ |
| `sorcery-contested-realm` | Sorcery: Contested Realm | 2,959+ |
| `star-wars-unlimited` | Star Wars: Unlimited | 6,690+ |
| `union-arena` | Union Arena | 5,361+ |
| `universus` | UniVersus | 5,772+ |
| `yugioh` | YuGiOh | 45,236+ |

All prices are in USD. English-language cards only, except for Pokémon Japan.

## Known Limitations

Card images are currently not supported. Developers looking to build a personal project (non-commercial) can pair our API with a public domain images API such as the ones provided by Scryfall and MTGJSON. For commercial applications, JustTCG is actively exploring image partnerships to provide a comprehensive solution.

Pricing data is provided "as-is" and does not have warranty of any kind. JustTCG is not liable for any losses incurred by the use of our API.

---

## Pricing Plans

| Plan | Monthly Requests | Daily Requests | Rate Limit | Price |
|---|---|---|---|---|
| Free | 1,000 | 100 | 10 req/min | $0/mo |
| Starter | 10,000 | 1,000 | 50 req/min | Paid |
| Professional | 50,000 | 5,000 | 100 req/min | Paid |
| Enterprise | 500,000 | 50,000 | 500 req/min | Paid |

**Quota resets:**
- Daily limits reset at midnight (00:00) UTC
- Monthly limits reset on the billing cycle date for paid plans, or on the account creation date anniversary for free users

Exceeding rate limits returns `429 Too Many Requests`. Failed requests due to server-side errors do not count against your quota.

---

## JavaScript/TypeScript SDK

Install: `npm install justtcg-js`

```typescript
import { JustTCG } from 'justtcg-js';

// Automatically reads JUSTTCG_API_KEY environment variable
const client = new JustTCG();

// List games
const games = await client.v1.games.list();

// Search cards
const cards = await client.v1.cards.get({
  game: 'pokemon',
  orderBy: 'price',
  order: 'desc',
  limit: 10,
  condition: ['NM', 'LP'],
});
```

Full SDK docs: https://justtcg.com/docs/sdk

---

## FAQ

**Q: Where do you get your prices?**
A: Pricing is market-driven. JustTCG analyzes real sales data from all major online TCG marketplaces and applies a volume-weighted average. Platforms with higher sales volume have greater impact on the final price, providing the most stable and realistic snapshot of a card's true market value. Specific data sources are not published for proprietary reasons.

**Q: How often is the data updated?**
A: Pricing data is updated continuously, with full refreshes occurring throughout the day. Historical trend data (7d, 30d, 90d) reflects that period of real market activity.

**Q: Do you offer a free tier?**
A: Yes. The Free plan allows 1,000 requests per month and 100 per day. No credit card required. Sign up at https://justtcg.com/auth/signup.

**Q: Do you support non-English cards?**
A: Currently, JustTCG supports English-language cards for all games, plus Japanese-language Pokémon cards (`pokemon-japan`). More international markets are on the roadmap.

**Q: Do you provide card images?**
A: JustTCG focuses exclusively on pricing data and does not host images. API responses include external product identifiers (TCGplayer ID, Scryfall ID, MTGJSON ID) which developers can use to construct image URLs from third-party sources.

**Q: What happens if I hit the rate limit?**
A: The API returns `429 Too Many Requests`. Failed requests due to server-side errors (5xx) do not count against your quota.

**Q: When does my quota reset?**
A: Daily limits reset at midnight UTC. Monthly limits reset on your account creation date (Free) or billing cycle date (Paid).

**Q: I'm getting a timeout error (cURL error 28) on deep pagination.**
A: This is a client-side timeout issue. Set a longer timeout (60–90 seconds) in your HTTP client when paginating through large result sets.

---

## Contact & Support

- Support email: support@justtcg.com
- Documentation: https://justtcg.com/docs
- Sign up: https://justtcg.com/auth/signup
- Dashboard: https://justtcg.com/dashboard