# Card Hedge Agent API

> Pay-per-call trading card data for autonomous agents. 20 endpoints (19 priced in USD + 1 free); pay via x402 (USDC on Base, settled through Stripe) on each 402 challenge. No account, no API key, no pre-loaded balance. (An MPP/Tempo rail is built but not currently enabled.)

## Agent Guide

- [Agent API Guide](https://api.cardhedger.com/docs/agent-api-guide) — How to pay, endpoint list with prices, examples, error reference, acceptable use, and **resolving a card_id** (which endpoints need one vs. which produce one)
- [llms-full.txt](https://api.cardhedger.com/llms-full.txt) — Full-text companion to this file: the complete agent guide plus a generated reference of all 20 endpoints (method, price, velocity tier) in one document.

## Pricing Manifest (machine-readable)

- [GET /v1/agent/pricing](https://api.cardhedger.com/v1/agent/pricing) — JSON catalog of all 20 agent endpoints (19 paid + 1 free), prices (USD), and payment protocol details. Unauthenticated.

## OpenAPI Spec

- [GET /openapi.json](https://api.cardhedger.com/openapi.json) — Full OpenAPI 3.0 schema for the human/keyed customer API. The agent surface is NOT here — it has its own scoped spec at `/v1/agent/openapi.json` (below).
- [GET /v1/agent/openapi.json](https://api.cardhedger.com/v1/agent/openapi.json) — OpenAPI 3.0 schema scoped to ONLY the `/v1/agent/*` surface (the 20 agent endpoints + the free pricing manifest, plus just their referenced components). Unauthenticated.
- [GET /v1/agent/docs](https://api.cardhedger.com/v1/agent/docs) — Interactive Scalar API reference for the agent surface, driven by the scoped schema above. Unauthenticated.

## MCP Tool Server (agent-scoped)

- [/mcp/agent](https://api.cardhedger.com/mcp/agent) — Native MCP streamable-HTTP server with 21 tools: 19 paid `agent_<suffix>` tools + free `agent_set_search` + free `agent_pricing_manifest`. Speaks the x402 v2 MCP transport binding: an unpaid `tools/call` returns a `PaymentRequired` envelope as an `isError` tool result (in `structuredContent` and stringified `content`); pay by retrying the call with the signed payload in request `_meta["x402/payment"]`; the receipt returns in result `_meta["x402/payment-response"]`. No API key required to connect; `tools/list`, `agent_set_search`, and `agent_pricing_manifest` are free. Auto-paying clients (Cloudflare `withX402Client`, Vercel `withPayment()`, MCPay) handle the loop. Distinct from the keyed `/mcp` server, which serves subscription customers via `X-API-Key`.