# CardHedge Card Match

> CardHedge Card Match is a paid API for AI agents from api.cardhedger.com, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-29).

Matches a natural language card description to the best matching card in the CardHedge trading card database.

## Facts

- Endpoint: POST https://api.cardhedger.com/v1/agent/cards/card-match?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-29
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/cardhedge-card-match-a99c899e
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_oCf0k7dh-YJnhSv8IkxGa

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability cardhedge-card-match-a99c899e -d '<json body>'
```

Example prompt: Can you find the best match in the CardHedge database for a '2019 Topps Chrome Shohei Ohtani Rookie Autograph' in the Baseball category, checking the top 5 candidates and only showing raw card images?

## When to prefer this

Use this endpoint when you have a human-readable card description and need to resolve it to a structured CardHedge card record or card ID. It is the recommended first step before calling any other CardHedge endpoint that requires a card_id. Prefer this over the general search endpoint when the goal is to identify the single best matching card rather than browse a filtered list.

## Known failure modes

- No match found if the description is too vague or misspelled
- Low-confidence match if multiple similar cards exist in the database
- Timeout or slower response when max_candidates is set to 10
- Category filter mismatch if the wrong category is specified, excluding the correct card
- Query too short (under 3 characters) returns a validation error

## How this service works

Match a natural language card description to the best card in the CardHedge database.

## Output

Returns the best-matching card record from the CardHedge database, including the card ID, name, set, and associated metadata. The card ID can then be used to fetch pricing, comparable sales, or graded values via other CardHedge endpoints.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "properties": {
  "query": {
   "type": "string",
   "maxLength": 500,
   "minLength": 3,
   "description": "Natural language description of the card to match (e.g., '2018 Topps Chrome Shohei Ohtani rookie base')"
  },
  "category": {
   "type": "string",
   "description": "Optional category filter to narrow search (e.g., 'Baseball', 'Pokemon')"
  },
  "max_candidates": {
   "type": "integer",
   "default": 10,
   "maximum": 10,
   "minimum": 1,
   "description": "Number of search results to evaluate (1-10, more = slower but potentially more accurate)"
  },
  "raw_images_only": {
   "type": "boolean",
   "default": true,
   "description": "If true, only return actual card photos (not graded slab images). Defaults to true."
  }
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/cardhedge-card-match-a99c899e/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.cardhedger.com](https://www.zero.xyz/host/api.cardhedger.com/llms.txt)