# 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

These values describe only the checkout or order-placement confirmation step,
not the full order-status lifecycle after an order has been placed.

Adapter checkout can be asynchronous. Treat `submitted`, `pending`,
`processing`, `in_progress`, and `submission_unknown` as non-terminal:
checkout is still processing, and agents must not say the order is confirmed.
Only `placed` means the order placement is confirmed. It does not mean the
order has finished later fulfillment stages; after `placed`, the order may
still progress through separate order-status semantics such as `shipped` or
`delivered`. `failed` and `cancelled` mean checkout did not complete or
was cancelled; report `refund_status` separately when present.

Self-checkout handoff is different: Fast returns a hosted checkout link for the
buyer to complete outside chat, and Fast does not track the resulting merchant
order lifecycle after the handoff.