# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/pkmncards/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/pkmncards/advanced-search \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/pkmncards/get-card-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/pkmncards/get-cards-by-pokemon \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/pkmncards/get-cards-by-set \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/pkmncards/get-cards-by-type \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/pkmncards/list-sets \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/pkmncards/search-cards \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"limit":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.