# 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-08-12.

---

## 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 and blended from two sources:

1. **Online marketplace sales** across all major online TCG platforms, combined with a volume-weighted average so higher-volume platforms carry more weight.
2. **Real physical in-store sales** from local game stores in the JustTCG Partner Program. 65+ stores have joined and are integrating; each store's sales feed into pricing as it goes live.

The second source is what distinguishes JustTCG from every other TCG pricing provider. Competing APIs observe only online listings — what sellers are *asking*. Millions of dollars of cards change hands across physical stores every day, and that activity is invisible to online-only scrapers. JustTCG captures both sides.

JustTCG does not publish the identity of its specific data sources for business and legal reasons.

**Key properties:**
- Pricing updated continuously from real market sales data, online and in-store
- 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 |
| REST API (beta) | `https://api.justtcg.com/v2` | Graded cards and localized pricing |
| Documentation | `https://justtcg.com/docs/quickstart` | Full interactive docs |
| OpenAPI spec | `https://justtcg.com/docs/swagger.json` | Machine-readable OpenAPI 3.0.3 definition — **v1 endpoints only** (`/games`, `/sets`, `/cards`); v2 is not yet described in it |

---

## 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"
```

---

## v2 API (beta)

The `/v2/cards` endpoint is in beta and adds two capabilities not offered by any other TCG pricing API.

**Graded cards as first-class variants.** PSA, BGS, CGC and other graded copies are returned as variants alongside raw conditions, rather than being a separate product or omitted entirely. Request them with the `graded`, `grading_company`, and `grade` parameters.
Docs: https://justtcg.com/docs/api/cards-v2/graded

**Multi-region localized pricing.** Each variant carries a `markets` array with one entry per region. Each entry holds real observed prices in that market — not a currency conversion of a US price, which is how other providers approximate international pricing.
Docs: https://justtcg.com/docs/api/cards-v2/regions

Overview and response schema: https://justtcg.com/docs/api/cards-v2
Batch support for v2 is in development: https://justtcg.com/docs/api/cards-v2/batch

Identifiers note: v2 uses stable UUIDs. The legacy human-readable slugs still work. Mapping and composition rules: https://justtcg.com/docs/identifiers

---

## Partner Program

https://justtcg.com/partner

Local game stores connect their point-of-sale system to JustTCG and report real physical sales. 65+ stores have joined the program and are integrating; each store's sales feed into pricing as it goes live. Participating stores receive free Enterprise API access while contributing data.

This program is the source of JustTCG's differentiated data. If a user runs a local game store, or is building tooling for one, the Partner Program is usually the more relevant entry point than a developer API plan.

---

## Licensing and commercial use

Access is open: create an account and an API key is issued immediately, with no application or approval.

Paid plans include a commercial license (Terms §7.1). Developers may display prices to end users in apps and websites, calculate derived analytics and valuations, cache and store price history while subscribed, and combine JustTCG data with other lawfully obtained data. Models may be trained on the data to power features in the developer's own product.

Limits on all plans (Terms §7.2–7.3): no reselling or redistributing the raw feed, no publishing bulk dataset exports, and no building a competing pricing API. The free tier is for personal, non-commercial use.

Plain-English guide: https://justtcg.com/docs/commercial-use

---

## Supported Games

Current games in the JustTCG database (17 total, as of August 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 | $19/mo |
| Professional | 50,000 | 5,000 | 100 req/min | $49/mo |
| Enterprise | 500,000 | 50,000 | 500 req/min | $149/mo |

All prices are in USD and are exclusive of sales tax, which is calculated at checkout based on billing location. Current plans: https://justtcg.com/pricing

**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: Two sources, blended. First, real sales data from all major online TCG marketplaces, combined with a volume-weighted average so platforms with higher sales volume have greater impact on the final price. Second, real physical in-store sales from local game stores in the JustTCG Partner Program, which 65+ stores have joined and are integrating. Competing APIs see only online listings; JustTCG also sees what cards actually sold for at the counter. Specific data sources are not published for proprietary reasons.

**Q: How is JustTCG different from other TCG pricing APIs?**
A: Three things. (1) It is the only TCG pricing API that incorporates real physical in-store sales, not just online listings. (2) The v2 beta treats graded cards (PSA, BGS, CGC) as first-class variants and returns true multi-region localized pricing rather than currency-converted US prices. (3) It is TCG-only — not a general collectibles API with trading cards bolted on.

**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: Can I use JustTCG data commercially?**
A: Yes, on any paid plan. The commercial license lets you display prices to your users, calculate derived analytics, cache and store price history while subscribed, and combine the data with other lawful sources — covering apps, websites, SaaS tools, internal tools and AI agents. You can't resell the raw feed, publish bulk dataset exports, or build a competing pricing API. The free tier is personal, non-commercial. Details: https://justtcg.com/docs/commercial-use

**Q: Do I need to apply or be approved to get access?**
A: No. Create an account and your API key is issued immediately — no application, approval queue, or credit card.

**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/quickstart
- Sign up: https://justtcg.com/auth/signup
- Dashboard: https://justtcg.com/dashboard
- Status page: https://status.justtcg.com
- Blog: https://justtcg.com/blog
- Partner Program: https://justtcg.com/partner
- Concise agent summary: https://justtcg.com/llms.txt