# VOLT

> VOLT is a fictional demonstration storefront (staging, sandbox only). No real payments are processed and no orders are fulfilled. Agents may browse the real 48-product demo catalog, build a cart, and PREPARE a checkout; only a human can confirm a checkout, in the browser.

## Agent documentation

- [OpenAPI document for the VOLT API (public + agent endpoints)](https://volt.webventureslab.com/api/v1/openapi.json)
- [API discovery document (JSON): endpoints, agent auth, scopes, claim labels](https://volt.webventureslab.com/api/v1)
- [UCP merchant profile (UCP 2026-08-25)](https://volt.webventureslab.com/.well-known/ucp)
- [API catalog (RFC 9727 linkset)](https://volt.webventureslab.com/.well-known/api-catalog)
- [ACP-format product feed export (spec-conformant artifact; OpenAI ingestion requires approved merchant onboarding — not claimed)](https://volt.webventureslab.com/api/v1/acp/feed)
- [MCP server (Streamable HTTP, POST only): tools mirror the agent API 1:1](https://volt.webventureslab.com/mcp)

## Rules for agents

- Authentication: `Authorization: Bearer <VOLT agent key>` on every /api/v1/agent/* call. Keys are scoped (catalog:read, cart:write, checkout:prepare), expiring, and revocable. There is no confirm scope.
- Getting a key (self-service authorization): (1) POST /api/v1/agent/keys/request with {scopes, label} — scopes must be a subset of the three above; anything else is refused. You receive {request_id, approval_url, claim_token, approval_email:"sent"}; pending requests expire in 15 minutes. Creating the request emails a 6-digit approval code to the store's customer-contact email address — the code is never returned by this API. If the email cannot be sent, creation fails with 502 approval_email_failed and the request is closed (state "email_failed"). (2) Give the approval_url to the customer: the page shows exactly what is being granted (label, scopes in plain language, 7-day key lifetime, and that the agent will NOT be able to place orders) with Approve / Deny — and deciding ALSO requires the emailed 6-digit code, which is never shown on the page. An agent cannot complete approval itself: holding the approval_url and the claim token is not enough. Five incorrect code entries lock the request (state "locked", terminal). (3) Poll GET /api/v1/agent/keys/claim?request_id=… with the claim token as a Bearer credential (or X-Claim-Token header): before approval it returns {state:"pending"}; after approval it returns the raw key EXACTLY ONCE; after denial, expiry, lock, or email failure it returns that terminal state. Keys can also be issued by the store operator directly.
- Client requirement: identify your client with a descriptive User-Agent header (for example "MyAgent/1.0") on every request. Default signatures of some HTTP libraries — notably Python-urllib's — are blocked by this host's edge bot protection (Cloudflare error 1010) before the request reaches the store; any descriptive User-Agent succeeds. This applies to the discovery documents and llms.txt as well as to the authorized API.
- Compatibility sequencing: when an item depends on another product (a charger for a laptop, a hub for a sensor), verify the pair FIRST with the compatibility endpoint — GET /api/v1/agent/compatibility?a={sku}&b={sku} (MCP: check_compatibility). Verify compatibility BEFORE adding the dependent accessory to the cart; add in dependency order, primary product first.
- Human-approval boundary: agents prepare checkout; humans confirm. No agent credential can create an order.
- Sandbox restrictions: demonstration shipping data only; simulated payment outcomes only; rate limit 120 requests/minute per key.
- Human handoff (Stage 4): after preparing a checkout, POST /api/v1/agent/checkout-sessions/{checkout_session_id}/handoff to mint a single-use, 15-minute customer review URL (returned once; only its hash is stored). The customer approves or cancels on that page — agents still cannot confirm.
- Mutations require an Idempotency-Key header.
- MCP server: POST /mcp (Streamable HTTP). Eras: 2025-11-25 (initialize handshake) and 2026-07-28 (stateless server/discover + tools). Auth is the SAME VOLT demo agent key as the REST agent API — demo keys, NOT OAuth 2.1. tools/call requires a key; tools/list without a key shows the read-only tools.

## Optional

- [Storefront](https://volt.webventureslab.com/)
- [Sitemap (all public storefront URLs)](https://volt.webventureslab.com/sitemap.xml)
- [Health / counts](https://volt.webventureslab.com/api/health)