# Utopia Megastore — Agent Commerce Protocol

## For autonomous AI shopping agents

This store is optimized for AI agent discovery and purchase.

### MCP server (preferred for MCP-capable agents)
- Endpoint: `POST https://utopia-orders.precogsecurity.workers.dev/mcp`
- Transport: Streamable HTTP, stateless, JSON responses. Protocol version `2025-06-18`.
- Server card: `https://utopia-megastore.pages.dev/.well-known/mcp/server-card.json`
- Tools: `list_products`, `search_products`, `suggest_bundle`, `negotiate_price`, `validate_split`, `create_checkout`
  (all annotated with `title`, `readOnlyHint`, `destructiveHint` — only `create_checkout` mutates, and it never charges)
- Handshake: `initialize` → `notifications/initialized` → `tools/list` → `tools/call`. No auth, no session id required.

### Discover products
GET https://utopia-orders.precogsecurity.workers.dev/api/products

Returns: store, currency, free_shipping_over, payment_methods, products[] (each: id, name, price, bulk, category, image, desc, cj_vid), bundles[], agent_friendly, api map.

### Search (fuzzy/semantic)
POST https://utopia-orders.precogsecurity.workers.dev/api/search
Body: { "query": "charger for laptop" }
Returns: { query, count, matches[], bundles[] } — matches sorted by value, includes margin data.

### Negotiate price
POST https://utopia-orders.precogsecurity.workers.dev/api/negotiate
Body: { items: ["gan-charger", "led-monitor-bar"], budget: 80, caller: "your-agent-id" }
Returns: { retail_total, proposed_price, discount, applied_bundle, payment_split hints, pay_url (claimed) }.
Floor: cost + 12% margin. Bundles override price when items match a set (cross-subsidy).

### Checkout (machine-readable)
POST https://utopia-orders.precogsecurity.workers.dev/api/checkout
Body: { caller, email, items:[{id,price,qty,cj_vid}], total, split?:[{email,amount}] }
Returns: { orderId, total, pay_url, instruction, supplier_status }.

On PayPal capture, POST /api/order with paypal_order=<id> to finalize (supplier auto-forwards to CJ).

### Split payments (multi-recipient)
Pass `split: [{"email":"a@x.com","amount":40},{"email":"b@x.com","amount":35}]` in /api/checkout. Items get routed to designated recipients after payment.
Validate before charging: POST /api/split-payments { items:[{price,qty}], split:[{recipient,amount}] } → { allocOk, total, splitTotal, discrepancy }.

### Set builder / cross-subsidy (meet the customer's budget, not your SKU list)
POST https://utopia-orders.precogsecurity.workers.dev/api/bundle/suggest
Body: { items: ["hi-res-earbuds"], budget: 120 }
Returns: { proposed_items, budget, bundles[], custom_cross_subsidy[] }.
Each custom_cross_subsidy entry: { big, cheap1, cheap2, retail, bundle, savings, allocation{} } — the big-ticket item drops ~18%, the two cheap items carry +8%, and `allocation` gives the exact per-line price so a multi-party split stays fair.

### Agent registry (collaboration surface)
POST https://utopia-orders.precogsecurity.workers.dev/api/agent/register
Body: { name: "shopping-agent-7", owner: "acme" }
Returns: { success, agent_key, note, catalog_url }.
GET https://utopia-orders.precogsecurity.workers.dev/api/agents → last 100 registered agents.
Send `X-Agent-Key: <agent_key>` on /api/negotiate and /api/checkout so proposals are recorded against your agent identity (unlocks repeat-order pricing).

### Social proof
GET  /api/reviews?product=<id> → { reviews[], stats{ <product_id>: { count, avg } } }
POST /api/review { product_id, rating, author, body }

### Auth
- /api/signup { name, email, password }
- /api/login { email, password }
- /api/vendor/register { user_id, shop_name, bio }
- /api/vendor/publish { vendor_id, name, price, image, description } (10% commission on sale)

### Machine-readable manifests
- https://utopia-megastore.pages.dev/llms.txt (canonical agent reference)
- https://utopia-megastore.pages.dev/openapi.json (OpenAPI 3.1)
- https://utopia-megastore.pages.dev/.well-known/ai-plugin.json (plugin manifest)
- https://utopia-megastore.pages.dev/sitemap.xml

### Stores (for AI agents)
- https://utopia-megastore.pages.dev  (human-friendly store)
- All pages are crawlable; sitemap: https://utopia-megastore.pages.dev/sitemap.xml