# Pkmncards — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse Pokémon trading card game cards with detailed metadata, high-quality images, and advanced filtering by set, Pokémon name, or card type. Filter across thousands of cards from different sets to find exactly what you're looking for.

**Category:** Entertainment | **Website:** [pkmncards.com/](https://pkmncards.com/) | **Docs:** [parse.bot/marketplace/db9263f0-5bf7-4e47-9605-85ca8436d032/pkmncards-com-api](https://parse.bot/marketplace/db9263f0-5bf7-4e47-9605-85ca8436d032/pkmncards-com-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### advanced_search

Perform a filtered search using specific card attributes like name, color, type, stage, rarity, set, and format. Constructs a query from the provided filters and returns matching cards. At least one filter parameter should be provided. Internally paginates through up to 5 pages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `card_type` | string | No | Card type (e.g., Pokémon, Trainer, Supporter, Item, Energy) |
| `color` | string | No | Pokémon color/energy type (e.g., Lightning, Fire, Water, Grass, Psychic, Fighting, Darkness, Metal, Fairy, Dragon, Colorless) |
| `format_name` | string | No | Format name to filter by (e.g., Standard, Expanded) |
| `name` | string | No | Card name to search for |
| `rarity` | string | No | Card rarity (e.g., Common, Uncommon, Rare, Double Rare, Ultra Rare, Promo) |
| `set_name` | string | No | Set name to filter by |
| `stage` | string | No | Evolution stage (e.g., Basic, Stage 1, Stage 2) |
| `text` | string | No | Card text to search for |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/advanced_search \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"card_type":"<string>","color":"<string>","format_name":"<string>","name":"<string>","rarity":"<string>","set_name":"<string>","stage":"<string>","text":"<string>"}'
```

### get_card_detail

Get full details for a single card by its slug. Returns comprehensive card information including name, HP, color, type, stage, attacks, weakness, resistance, retreat cost, set info, rarity, illustrator, images, and flavor text. Returns input_not_found if the card slug does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `card_slug` | string | Yes | The URL slug of the card (e.g., 'pikachu-ex-ascended-heroes-asc-277') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/get_card_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"card_slug":"<string>"}'
```

### get_cards_by_pokemon

Retrieve cards by Pokémon species name. Returns up to 100 cards featuring the specified Pokémon across all sets. Constructs a pokemon: search query internally.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pokemon_name` | string | Yes | Pokémon species name (e.g., 'Pikachu', 'Charizard', 'Eevee') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/get_cards_by_pokemon \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pokemon_name":"<string>"}'
```

### get_cards_by_set

Retrieve all cards belonging to a specific set by its slug. Internally paginates through up to 10 pages of results. Returns full card data including name, HP, color, type, stage, attacks, weakness, resistance, retreat cost, set info, rarity, and images.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `set_slug` | string | Yes | The URL slug of the set (e.g., 'ascended-heroes', 'surging-sparks', 'prismatic-evolutions') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/get_cards_by_set \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"set_slug":"<string>"}'
```

### get_cards_by_type

Filter cards by Pokémon type/color. Returns up to 100 cards of the specified type across all sets. Constructs a color: search query internally.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pokemon_type` | string | Yes | Pokémon type/color name (e.g., 'Lightning', 'Fire', 'Water', 'Grass', 'Psychic', 'Fighting', 'Darkness', 'Metal', 'Fairy', 'Dragon', 'Colorless') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/get_cards_by_type \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pokemon_type":"<string>"}'
```

### list_sets

List all available Pokémon TCG sets/expansions organized by series. Returns a hierarchical structure of series containing their respective sets with names, abbreviations, slugs, and URLs. No pagination — one request returns all series and sets.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/list_sets \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### search_cards

Search for Pokémon cards using keywords or specific search syntax supported by pkmncards.com (e.g., 'Pikachu', 'color:fire', 'name:Charizard stage:basic'). Internally paginates through multiple pages, with the limit parameter controlling how many pages to fetch (each page contains up to 20 cards).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `limit` | integer | No | Maximum number of pages to scrape (each page contains up to 20 cards) |
| `query` | string | Yes | Search query string supporting pkmncards.com search operators such as name:, color:, stage:, type:, rarity:, set:, format:, pokemon:, series: |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-pkmncards-com-api-db9263f0/search_cards \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","query":"<string>"}'
```