# AgentHub Commerce

> AI-native commerce platform connecting merchants to AI shopping agents via open protocols.

## Overview

AgentHub Commerce is a neutral, SMB-first commerce layer that makes small and medium businesses discoverable and purchasable by AI agents. It implements four open protocols for full agent interoperability.

## Protocols Supported

- **UCP (Universal Commerce Protocol)** v2026-04-08: Product discovery, checkout, cart, order management
- **A2A (Agent-to-Agent)** v1.0.0: Inter-agent communication, task delegation, streaming
- **MCP (Model Context Protocol)** v1: Tool discovery for AI agents (22 tools)
- **AP2 (Agent Payments Protocol)** v0.1.0: Secure payment mandates and settlements

## Discovery Endpoints

- `/.well-known/ucp` — UCP platform profile and capabilities
- `/.well-known/agent-card.json` — A2A agent card (skills, endpoint, identity)
- `/.well-known/agent-commerce.json` — Unified agent commerce manifest
- `/.well-known/jwks.json` — Public keys for JWT verification
- `/agent` — Agent portal (HTML or JSON via content negotiation)

## MCP Tools (22 available via POST /mcp)

### Product Commerce
- `search_products` — Search product catalog by text, category, brand, price range, location
- `create_checkout` — Initialize a checkout session
- `update_checkout` — Update buyer info, shipping address, or payment method
- `complete_checkout` — Place the order
- `get_order` — Retrieve an order by ID
- `list_orders` — List orders for a buyer or merchant
- `get_merchant_profile` — Retrieve a merchant's UCP profile and capabilities
- `negotiate_capabilities` — Run UCP intersection negotiation between client and server
- `apply_discount` — Apply a discount code to a checkout
- `select_fulfillment` — Choose pickup, delivery, or shipping for a checkout
- `reorder` — Re-create a checkout from a previous order

### Service Commerce
- `search_services` — Search services by text, category, or service type
- `check_availability` — Get available time slots for a service
- `book_service` — Create a booking (scheduler-routed when the merchant has connected one)
- `cancel_booking` — Cancel an existing booking
- `get_providers` — List service providers and their schedules

### Location & Fulfillment
- `set_buyer_location` — Set buyer location for nearby search and delivery validation
- `get_fulfillment_options` — Get available fulfillment options for the current checkout

### Platform & Onboarding
- `register_merchant` — Onboard a new merchant via the 7-step wizard
- `get_onboarding_status` — Check onboarding progress for a merchant
- `manage_merchant` — Merchant CRUD operations (hub admin)
- `get_platform_stats` — Platform-wide analytics (hub admin)

## Agent Authentication

- **API Key**: `X-API-Key` header for merchant endpoints
- **OAuth2 Bearer**: `Authorization: Bearer <token>` header
- **Agent Registration**: `POST /api/v1/agent/register` for autonomous agents
- **Device Flow**: OAuth2 device authorization for delegated user access

## Quick Start for Agents

1. Fetch `/.well-known/agent-commerce.json` for full capability manifest
2. Choose your protocol: MCP for tool-based, A2A for task-based, UCP REST for direct API
3. Search products: MCP `search_products` or `GET /ucp/v1/catalog/search`
4. Create checkout: MCP `create_checkout` or `POST /ucp/v1/checkout-sessions`
5. Complete order: MCP `complete_checkout` with buyer info and payment

## Catalog

Live catalog data is available — query directly rather than caching from this file:

- `POST /mcp` — call `search_products` or `search_services` for current inventory
- `/.well-known/agent-commerce.json` — full capability manifest with current counts
- `GET /ucp/v1/catalog/search` — direct REST query

## Links

- API Documentation: /docs
- Agent Portal: /agent
- Shopping Chat: /chat
- Merchant Onboarding: /onboard