# SilphCo API — for agents

Base: `https://silphcoanalytics.xyz/api/v3`

This file is the followable copy of
https://silphcoanalytics.xyz/docs/api/getting-started#for-agents
(the HTML page is for humans).

## Do this first

1. Load the skill: https://silphcoanalytics.xyz/skill-api.md
2. Quote a card:

```
GET https://silphcoanalytics.xyz/api/v3/quote?q=42382
```

`42382` is TCGPlayer productId for Base Set Charizard (`base1-4`). A name works too:
`GET /api/v3/quote?q=base+set+charizard`.

3. Read the envelope:
   - `data.status` is identity: `resolved` / `ambiguous` / `unmapped`
   - When resolved, speak `data.label` (**Midprice** or **Last**) and `data.price_usd`;
     check `data.price_basis` before treating it as a live market price
   - `ambiguous` → `data.candidates` (up to 5). Ask which printing.

Playground quote needs no key (1 req/s). MCP and chart-series need a dashboard
Bearer key from https://silphcoanalytics.xyz/dashboard (free tier works).

## Same three jobs as the site

| Job | REST | MCP |
|-----|------|-----|
| Quote | `GET /quote?q=` or `POST /quote {ids}` | `quote` (`ids` list) |
| Screen | `GET /sets/{id}/trending-cards` | REST only |
| History | `GET /cards/{id}/chart-series` (keyed) | REST only |

The quote is midprice when its `status` is `ok` or `thin` and `midprice_usd > 0`.
Otherwise it is tape Last, then book Ask. The global `/trending` leaderboard is
shelved (HTTP 410).

## MCP (for tool-using agents)

Same product jobs as REST, as typed tool calls.

1. Free dashboard key (`sk_live_...`): https://silphcoanalytics.xyz/dashboard
2. Point a Streamable-HTTP client (custom headers, follows redirects — bare
   `/api/v3/mcp` 307s) at `https://silphcoanalytics.xyz/api/v3/mcp/` with
   `Authorization: Bearer <key>` on every request. No anonymous MCP — `401`.
3. First call: `quote` (`{"ids": ["42382"]}`) — same quote data as REST `/quote`.

Ten public tools: `search` (`q` name/id search or `ids` batch resolve),
`quote` (`ids` list, optional shared grade/finish/edition), `get_prices`,
`get_sales`, `get_listings`, plus the cohort tools `batch_grade_ladder`,
`compare_set_finish`, `pin_cohort`, `get_cohort`, `rank_set_sales`. The
`ids`-list tools batch — don't loop; bound `get_prices` with
`limit`/`since` (unbounded returns the full series). Tool failures are
JSON-RPC 200 with `result.isError: true` — check `isError`, not status.

**Identity then finish:** `search(q="Nidoking")` → `quote` / `get_listings` /
`batch_grade_ladder` with `finish=reverse_holo` (not inside `search.q`).

**δ-era commons:** `batch_grade_ladder(era=delta_species, rarity=Common,
finish=reverse_holo)` or `pin_cohort` → `batch_grade_ladder(cohort_handle=…)`.

**Gem-rate questions:** `batch_grade_ladder` on the cohort (or pin first) —
no separate gem-rank public tool.

Client config + curl handshake: https://silphcoanalytics.xyz/docs/reference/mcp.md

## Next

- MCP setup: https://silphcoanalytics.xyz/docs/reference/mcp
- OpenAPI: https://silphcoanalytics.xyz/openapi-public.json
- Human recipes (sidecar `/prices`, `/sales`, `/listings`): https://silphcoanalytics.xyz/docs/api/getting-started#recipes