# Fast Marketplace

Agent-facing marketplace for merchant discovery and product search across
many merchants. Searches fan out to per-merchant adapters; order placement
uses marketplace-signed hints against the chosen merchant's surface, not
against the marketplace itself.

## Agent endpoints

- `GET https://shop.fast.xyz/commerce/shops` — authoritative list of buyable merchants
- `GET https://shop.fast.xyz/commerce/search?q=...` — fan-out search across all merchants

## Discovery

- `GET https://shop.fast.xyz/.well-known/marketplace.json` — marketplace metadata
- `GET https://shop.fast.xyz/.well-known/api-catalog` — RFC 9727 link catalog
- `GET https://shop.fast.xyz/.well-known/mcp` — MCP server card
- `GET https://shop.fast.xyz/sitemap.xml` — public-URL sitemap

## Order placement

The marketplace does NOT place orders. Treat `/commerce/shops` as a
directory/listing surface only; its `baseUrl` can be a public brand domain,
not the executable adapter URL.

To place an order, first call `/commerce/search`, choose a returned hit,
then call the selected merchant adapter using that hit's `merchantBaseUrl`
and marketplace-signed hint fields: `merchantHandle`, `hintExp`, and
`hintSig`. Pass those as the merchant adapter expects, typically
`X-Marketplace-Handle`, `X-Marketplace-Hint-Exp`, and
`X-Marketplace-Hint`.

## Checkout state contract

Fast Shop chat, widget order cards, signed-in history, resume, and notify
evidence use this bounded public status contract: `pending`, `submitted`,
`processing`, `submission_unknown`, `paid_unconfirmed`,
`self_checkout_opened`, `support_needed`, `placed`, `shipped`, `delivered`,
`refunded`, `failed`, and `cancelled`.

Normalize `canceled` to `cancelled`, `in_progress` to `processing`, and
ambiguous `unknown` or `waiting` states to `submission_unknown`.
`failed`, `cancelled`, `delivered`, and `refunded` are terminal and must not
regress to pending or unknown. `placed` may progress to `shipped` or
`delivered`; `shipped` may progress to `delivered`. `support_needed`,
`paid_unconfirmed`, and `self_checkout_opened` are sticky support states and
must not regress to pending or unknown. Report `refund_status` separately when
present, and do not show raw provider, payment, shipping, adapter, or Zinc errors to buyers.

Self Checkout handoff is different: Fast can report `self_checkout_opened`,
but cannot confirm final merchant completion unless an authoritative status
later returns `placed`, `shipped`, `delivered`, `refunded`, `failed`, or
`cancelled`.