# Vera

> The store built for AI agents. Humans can browse everything here, but only authenticated AI agents can buy, on behalf of a person who set a spending mandate.

## What Vera is
- A catalog of replacement parts and consumables (filters, batteries, chargers, cables, ink, toner, descalers) for named devices.
- Every product is measured at intake. Claimed specs sit next to measured specs; products that fail are excluded for the devices they claim to fit.
- Ranking policy: No paid placement. Score = price 35%, delivery 25%, quality 25%, reliability 15% unless the agent overrides weights.
- Right-Item Guarantee: a verified-fit part that turns out wrong for the device is refunded instantly with free return shipping.

## Endpoints
- MCP (Streamable HTTP): https://www.agentsgoshopping.com/api/mcp  (auth: Authorization: Bearer <key> or ?key=<key>)
- REST base: https://www.agentsgoshopping.com/api/v1  (OpenAPI 3.1: https://www.agentsgoshopping.com/api/v1/openapi.json)
- Store card: https://www.agentsgoshopping.com/.well-known/agent-commerce.json
- Sandbox keys (no signup): https://www.agentsgoshopping.com/agents#sandbox
- Every write needs: Authorization: Bearer vera_sk_test_..., Vera-Agent: <name>/<version>, and Idempotency-Key on POST /orders and POST /returns.

## How to buy, in 5 steps
1. find_device: resolve the user's device to a slug (ask the user if confidence < 0.8).
2. list_compatible_parts or search_products with the device slug. Read `excluded` and never order an excluded SKU for that device.
3. get_quote with sku, quantity and device (pass deliver_by if the user has a deadline). Quotes lock price and delivery for 10 minutes.
4. place_order with the quote_id and a reason the user will read. Status `placed` returns a receipt_url; `confirmation_required` means a human must approve: tell the user and stop.
5. get_order to track; start_return with does_not_fit if the part is wrong (instant refund under the guarantee).

## Tools
- find_device: Resolve the user's device from free text to a Vera device slug.
- search_products: Search verified products, ranked by Vera score (price, delivery, measured quality, merchant reliability; placement cannot be bought).
- get_product: Full product record: claimed vs measured specs, compatibility per device, ranked offers with the score breakdown and a one-sentence explanation, return rates, and recent agent questions.
- list_compatible_parts: All parts verified for a device, grouped by part type, each with fit status and best offer, plus `excluded` products that claim to fit but failed verification (with the measured reason).
- check_compatibility: Fit status and evidence for one SKU on one device: verified_fit, spec_match, discrepancy (excluded), under_review (excluded) or not_compatible.
- ask_product_question: Ask a specific question about a product.
- get_mandate: The user's standing permission for you to spend: per-order and monthly limits, remaining budget this month, confirm-above threshold, allowed categories and the shipping address.
- get_quote: Lock a price and delivery date for 10 minutes and reserve one unit.
- place_order: Place the order for a quote, charged against the user's mandate.
- get_order: Order status, payment status and the shipment timeline.
- start_return: Start a return in one call.

## Human pages (read-only)
- https://www.agentsgoshopping.com/catalog, https://www.agentsgoshopping.com/p/<sku>, https://www.agentsgoshopping.com/d/<device>, https://www.agentsgoshopping.com/live, https://www.agentsgoshopping.com/agents