# AgentsPrice

> Best-price intelligence across major sellers, built for autonomous agents. One request returns the lowest available price for a category, the venue offering it, how many sellers were compared, the savings versus the highest-priced venue, and a live link to buy. Every price is sourced; on upstream failure the API returns real-but-stale data (flagged) or an error, never an estimate.

## How to call it

- Base URL: `https://agentsprice.com`
- Auth: send a key as `Authorization: Bearer ap_live_…` or `?api_key=ap_live_…`. Keys are metered per minute and per month. Every response to a billable endpoint includes a `quota` object with the plan and remaining monthly calls.
- Free key, self-serve: `POST /v1/keys/free` (or the `get_free_key` MCP tool) mints your own key instantly — no account, no card — good for 1,000 verified calls/month (10/min). Copy it from the response (shown once). Higher volume or arbitrary (non-catalog) search needs a paid plan or pay-per-call via x402.
- No-key endpoints: `GET /api/board` (live deals feed) and the `list_live_deals` MCP tool need no key — the zero-friction way to try it.

## MCP server

- Endpoint: `https://agentsprice.com/mcp` (streamable-http, stateless JSON). Any MCP client can connect directly.
- Registry name: `com.agentsprice/agentsprice`. The manifest is published at `/server.json` and `/.well-known/mcp`.
- Tools: `best_price(category, query, api_key)` — keyed and metered, same data and trust fields as `/api/best-price`. `list_live_deals()` — public, no key, mirrors `/api/board`.

## Agent discovery (/.well-known/)

- `GET /.well-known/agent.json` — agent card: capabilities, skills, auth, MCP endpoint, categories, pricing.
- `GET /.well-known/mcp` — the MCP server manifest (streamable-http endpoint + registry name).
- `GET /.well-known/ai-plugin.json` — plugin-style manifest for plugin-aware hosts.
- `GET /llms.txt` — this document.
- `GET /.well-known/agentsprice-attestation` — the Ed25519 public key and verify recipe for the signed attestations on `/v1/reference`.

## Primary endpoint

`GET /api/best-price?category={category}&q={optional search}`

Returns: `{ category, query, fetched_at, count, quota, errors[], deals[] }`

Each deal: `{ id, name, symbol, category, best_price, unit, best_seller, sellers_compared, save_pct, high_price, buy_url, earning, real, source }`. May also include `stale: true` with `as_of` when serving last-good data after an upstream failure, or `demo: true` / `real: false` for clearly-badged sample categories. Rx deals additionally carry `rx: true`, `prescription_required: true`, `treats`, `retail_ref` + `retail_multiple` (a Medicare Part D reference), and a `note` with the disclaimer.

Trust fields an agent should read before acting:
- `real` — `true` means a live, sourced price. `false` means sample/demo data; do not transact on it.
- `stale` + `as_of` — the price is real but from an earlier successful fetch; weigh freshness accordingly.
- `source` — where the price came from (e.g. "CoinGecko (live)", "Google Shopping (live)", "NADAC (CMS acquisition cost)").
- `sellers_compared` — confidence signal for the comparison.
- `best_seller` — only trusted first-party / brand retailers are quoted; marketplace 3rd-party and used listings are filtered out.
- `buy_url` — a live link to act on; may be an affiliate-tracked redirect to the same merchant.

## Categories

- `crypto` — live, multi-exchange spot prices (CoinGecko). No upstream key needed.
- `electronics`, `gaming`, `home`, `fashion`, `tools` — live retail prices via Google Shopping. Filtering: trusted first-party/brand retailers only, exact model-token matching (no variant cross-matches), bundles and used listings excluded, and a market-reference sanity check so the quoted price is competitive. If no trusted listing is found for a product it is omitted; otherwise the category falls back to clearly-badged sample data. Around 20 products per category, listed cheapest-first.
- `rx` — common NON-controlled prescription generics priced from CMS NADAC (the acquisition cost), each with a Medicare Part D average-spend reference (`retail_ref`) showing how far below the system price the drug itself sits. Informational only, not medical advice; a prescription is required; controlled substances are excluded; `buy_url` opens a coupon comparison. This is price transparency, not a pharmacy.
- `travel` — live round-trip airfare across popular routes via Google Flights, cheapest-first, with Google's typical price range as the reference. Each row carries the airline, stops, and sellers compared.
- `all` — aggregates every available adapter.

## Reference / attestation

`GET /v1/reference?item={item}&category={optional}&max_age_seconds={optional}&nonce={optional}` — returns ONE verified reference price for the item, or a `stale` / `unavailable` status. When `status` is `verified` the response carries an `attestation` object and an Ed25519 `signature` over it, so an agent can verify OFFLINE that AgentsPrice asserted this exact price at this time and that it was not altered in transit (non-repudiation). Demo data never qualifies as a verified reference. Keyed and metered.

To verify: the signed bytes are `json.dumps(attestation, sort_keys=True, separators=(',',':'), ensure_ascii=False)`; `signature.value` is base64 Ed25519 over those bytes; the public key is `signature.public_key` and is also published at `GET /.well-known/agentsprice-attestation` (with a copy-paste verify snippet). Pass a `nonce` to bind the attestation to your request. The response also includes a `log` block with the entry's `seq` in the transparency log (below).

## Transparency log (public, no key)

Every signed attestation is appended to an append-only, Merkle-backed log, so the full history is tamper-evident and independently auditable ("Certificate Transparency, for prices"). Hashing: leaf = `SHA-256(0x00 || canonical_record)`, node = `SHA-256(0x01 || left || right)`, built left-to-right with a lone right node promoted; `canonical_record = json.dumps(record, sort_keys=True, separators=(',',':'), ensure_ascii=False)`.

- `GET /v1/log` — signed checkpoint (tree head): `{ log_id, tree_size, root_hash, timestamp, signature }`. The signature is Ed25519 over the canonical `{log_id,tree_size,root_hash,timestamp}` using the same published key.
- `GET /v1/log/entries?start={seq}&limit={n}` — paginated log entries (max 200), each `{ seq, ts, attestation_id, leaf_hash, record }`.
- `GET /v1/log/proof?seq={seq}` — RFC6962-style inclusion proof: `{ leaf_hash, audit_path[], root_hash }`. Verify by folding `leaf_hash` up the path (side `right` → `SHA-256(0x01||acc||sibling)`, `left` → `SHA-256(0x01||sibling||acc)`); the result must equal the checkpoint `root_hash`.

## Errors (deterministic)

- `401` — missing or invalid API key.
- `429` — `{ "error": "rate limit exceeded", per_min, retry_after_seconds }` or monthly quota exhausted (`limit`, `period`).
- `404` — no data source for the requested category.

## Other endpoints

- `GET /api/board` — public, no key. The website's live-deals feed (electronics, gaming, home, fashion, tools), cached, returning only real deals: `{ generated_at, live, count, deals[], errors[] }`. Use for a quick unauthenticated read of what is live now; use `/api/best-price` for keyed, metered, per-category queries.
- `GET /api/challenge?q={query}` — public, no key. Throw any product, coin, or generic drug at it; returns the best price plus an `efficiency` block that honestly accounts for the fetch-and-compare work one call replaced (`sellers_compared`, `latency_ms`, `you_saved_usd` vs the worst seller, `est_minutes_saved`). Dollar savings are real; lookups/time are labelled estimates. The zero-friction way to benchmark us before wiring a key.
- `GET /api/monetization` — snapshot of which referral/affiliate links and billing are currently active.
- `GET /api/checkout?plan={pro|business|api}` — creates a real Stripe Checkout session when billing is configured; otherwise reports `configured: false`.

## Plans

- free — 1,000 calls/month, 10/minute
- pro — 50,000 calls/month, 60/minute
- business — 500,000 calls/month, 240/minute

## Principles

- Sourced. Every price has a named source and stale/demo flags.
- Actionable. Every deal includes a live buy link.
- Decision-ready. Returns the ranked answer, not raw data to clean.
- Predictable. Stable schema, typed fields, deterministic errors, quota in every response.