# Utopia Megastore — AI Agent Reference

> Utopia Megastore: curated tech & desk gear, sourced to order, shipped worldwide. Built for both humans and autonomous AI shopping agents. All endpoints return structured JSON.

Store URL: https://utopia-megastore.pages.dev/
Order API: https://utopia-orders.precogsecurity.workers.dev
Currency: USD. Free shipping over $60. Margin: 30-40% (transparent). 3-7 day dispatch after payment.

## Quick start for AI agents
- **MCP (Model Context Protocol): POST https://utopia-orders.precogsecurity.workers.dev/mcp** — Streamable HTTP, stateless, protocol 2025-06-18. 6 annotated tools: `list_products`, `search_products`, `suggest_bundle`, `negotiate_price`, `validate_split`, `create_checkout`. Server card: https://utopia-megastore.pages.dev/.well-known/mcp/server-card.json
- GET https://utopia-orders.precogsecurity.workers.dev/api/products  → full structured catalog (15 products + 4 bundles + pricing + CJ vids)
- POST https://utopia-orders.precogsecurity.workers.dev/api/search  { "query": "..." }  → fuzzy/semantic matches sorted by value
- POST https://utopia-orders.precogsecurity.workers.dev/api/checkout  {...}  → returns PayPal invoice link for human (or agent) approval
- POST https://utopia-orders.precogsecurity.workers.dev/api/agent/register  { "name", "owner" }  → get an agent_key for logged negotiations + repeat-order discounts
- Authentication: none required for public endpoints (orders need name+email)

## Products (per /api/products)
Each product: id, name, price, bulk (multi-quantity discount string), category, image URL, desc, cj_vid (supplier variant ID for fulfillment).
Categories: Audio, Keyboards, Lighting, Charging, Smart Home, Accessories, Productivity, Photography.
Bundles ("sets"): desk-setup-pro ($179, items: keyboard+monitor+mat+cable), wfh-starter ($129: stand+mouse+webcam), audio-charge-kit ($159: earbuds+speaker+charger), productivity-starter ($148: stream deck+numpad+smart plug). Big items get cheaper when bundled.

## Payment
- PayPal (cards, Google Pay, Apple Pay, Venmo, crypto on request)
- To pay: call /api/search to find best set, then /api/checkout with chosen items. Returns PayPal invoice URL. Agent should surface URL to human (or agent) for approval; payment capture triggers supplier auto-forward to CJ Dropshipping (USPS shipping).

## Split payments / multi-party (agents)
- Pass `split` array in /api/checkout: [{ "email", "amount" }] to split across recipients (each pays share, goods routed to designated recipient).
- Validate a split before charging: POST /api/split-payments { items:[{price,qty}], split:[{recipient,amount}] } → { allocOk, total, splitTotal, discrepancy }.
- Agent-to-agent negotiation supported: propose a bundle + target price; server replies with best price given margin floor (cost +12%).

## Agent registry (collaboration surface)
- POST /api/agent/register { name, owner } → { success, agent_key, note, catalog_url }
- GET  /api/agents → last 100 registered agents { id, name, owner, registered_at }
- Send `X-Agent-Key: <agent_key>` on /api/negotiate and /api/checkout to have proposals recorded against your agent identity (unlocks repeat-order pricing).

## Set builder / cross-subsidy
- POST /api/bundle/suggest { items: string[], budget?: number }
  → { proposed_items, budget, bundles[], custom_cross_subsidy[] }
  Each custom_cross_subsidy entry: { big, cheap1, cheap2, retail, bundle, savings, allocation{} }.
  Rule: pairing 2 low-cost items with 1 big-ticket item lowers the big item (~18% off) while the cheap items carry a small uplift (+8%). Net effect is a lower total; allocation shows exactly what each line pays so multi-party splits stay fair.

## Machine-readable endpoints
- GET  /api/products   → { store, currency, products[], bundles[], api{} }
- POST /api/search     → { query } → { matches: [...], bundles: [...] }
- POST /api/negotiate  → { items[], budget, caller } → { retail_total, proposed_price, discount, applied_bundle, pay_url }
- POST /api/checkout   → { caller, email, items[], total, split[] } → { orderId, pay_url, instruction, supplier_status }
- POST /api/split-payments → validate multi-recipient allocation
- POST /api/bundle/suggest → set builder with cross-subsidized pricing
- POST /api/agent/register / GET /api/agents → agent registry
- POST /api/order      → { name, email, items[], total, payment_method, shipping_address, phone } → { success, orderId, supplier }
- POST /api/signup     → create user account
- POST /api/login      → authenticate
- POST /api/member     → join free membership
- POST /api/vendor/register → apply as vendor
- POST /api/vendor/publish → submit a product for review
- GET  /api/reviews    → social proof: { reviews[], stats{ product_id: {count, avg} } }
- POST /api/review     → { product_id, rating, author, body }
- GET  /api/stats      → orders, revenue, users, vendors, members, forwarded, commissions

## Machine-readable store index
- https://utopia-megastore.pages.dev/sitemap.xml
- https://utopia-megastore.pages.dev/robots.txt (allow all, sitemap referenced)
- https://utopia-megastore.pages.dev/openapi.json (OpenAPI 3.1 spec for the agent API)
- https://utopia-megastore.pages.dev/.well-known/ai-plugin.json (plugin manifest)
- Schema.org Store JSON-LD on homepage.

## Expressing intent
Agents should quote a target total price; system will suggest the cheapest bundle combination reaching that target, or offer upgrades (e.g. RGB lamp + charger).

## Fulfilment facts an agent may need to verify
- Supplier: CJ Dropshipping, ships from CN, USPS last-mile to US.
- Order lifecycle: created → supplier_status 'forwarded' (accepted by CJ) → tracking.
- Every order is persisted in D1 and visible via GET /api/stats (aggregate) — no PII is exposed publicly.