# A2R Marketplace

> Agent-first e-commerce platform. AI agents can autonomously discover products, compare prices, and complete purchases via the Universal Commerce Protocol (UCP).

## What is A2R?

A2R (Agent-to-Retail) is a commerce platform built for AI agents as first-class participants. Instead of scraping websites or navigating UIs, agents interact through structured APIs and the UCP protocol to browse catalogs, search semantically, manage carts, and checkout — all programmatically.

## Agent Discovery

- UCP Agent Manifest: `/.well-known/agent.json`
- OpenAI Plugin Manifest: `/.well-known/ai-plugin.json`
- OpenAPI Specification: `/openapi.json`

## Quick Start for Agents

1. **Register** — `POST /api/agents/register` with `{ "name": "YourAgent", "description": "What your agent does" }`
2. **Receive API key** — Returned once on registration. Use in `X-Agent-Key` header.
3. **Browse products** — `GET /api/products?query=wireless+headphones&limit=10`
4. **Search by embedding** — `POST /api/search/tokens` with a 384–1536 dim vector
5. **Add to cart** — `POST /api/cart/add` (auto-escalates to `read_cart` permission)
6. **Checkout** — `POST /api/checkout/complete` (auto-escalates to `read_cart_checkout`)

## API Endpoints (Read — No Auth Required)

- `GET /api/products` — Browse products with optional query, category, and limit filters
- `GET /api/products/{product_id}` — Get full product details
- `GET /api/categories` — List all product categories
- `POST /api/search/tokens` — Semantic search using embedding vectors (384–1536 dimensions)

## API Endpoints (Write — API Key Required)

- `POST /api/cart/add` — Add product to cart (requires `read_cart` permission)
- `GET /api/cart/{session_id}` — View cart contents
- `POST /api/checkout/complete` — Complete purchase (requires `read_cart_checkout` permission)

## Authentication

- **Type**: API key via `X-Agent-Key` header
- **Registration**: `POST /api/agents/register`
- **Permissions auto-escalate**: `read_only` → `read_cart` → `read_cart_checkout`
- No friction — permissions upgrade automatically based on agent actions

## Rate Limits

- Read: 60 requests/minute, 1000 requests/hour
- Write: 20 requests/minute, 200 requests/hour

## UCP Protocol

The Universal Commerce Protocol (UCP) enables structured agent-to-agent communication. Send `AgentMessage` objects to `/api/ucp/message` for any commerce capability including discovery, cart, checkout, inventory, reviews, and fulfillment.

## Data

- 1M+ products with semantic embeddings
- Real e-commerce data sourced from Harvard Open e-Commerce dataset
- Hybrid search: vector similarity + BM25 keyword matching via VireeDB

## Contact

- Website: https://api.viree.ai
- Agent Discovery: https://api.viree.ai/.well-known/agent.json