# X402 Market

> Agent-native commerce marketplace. AI agents discover, compare, reserve and purchase
> physical products, digital products, paid tools/APIs and services, paying via x402
> (HTTP 402 + USDC on undefined). The primary product is the machine-readable
> catalog, not web pages.

## Discovery
- [Agent manifest](https://www.x402-market.com/.well-known/agent.json): start here — interfaces, payment, conventions
- [OpenAPI](https://www.x402-market.com/openapi.json): full route descriptions
- [MCP server](https://www.x402-market.com/mcp): JSON-RPC marketplace toolset (search, compare, reserve, purchase, execute, track)
- [Capabilities](https://www.x402-market.com/api/v1/capabilities)
- [Categories](https://www.x402-market.com/api/v1/categories)

## Core operations
- POST https://www.x402-market.com/api/v1/catalog/search — search all listings (query, keywords[], listing_types, categories, filters). Free-text query also matches seller-supplied search keywords.
- GET  https://www.x402-market.com/api/v1/keywords — every seller-supplied search term live in the catalog
- GET  https://www.x402-market.com/api/v1/categories — browse by category
- POST https://www.x402-market.com/api/v1/tools/search — search paid executable tools
- POST https://www.x402-market.com/api/v1/services/search — search bookable services
- GET  https://www.x402-market.com/api/v1/listings/{id} — full listing detail
- POST https://www.x402-market.com/api/v1/offers/compare — normalized offer comparison
- POST https://www.x402-market.com/api/v1/reservations — hold scarce physical inventory (15 min TTL)
- POST https://www.x402-market.com/api/v1/orders — purchase (402 challenge if x402; include reservation_id for physical)
- POST https://www.x402-market.com/api/v1/tools/{id}/execute — invoke a paid tool (402 challenge, pay, retry with X-PAYMENT)
- GET  https://www.x402-market.com/api/v1/orders/{id} — order status and tracking
- POST https://www.x402-market.com/api/v1/checkout — build a receipt before paying: line items with shipping and taxes as separate lines, seller name + contact, SKU, variant options, specs, image URLs, totals; physical stock auto-held 15 min. Listings with variants (sizes) require variant_id. PHYSICAL PRODUCTS REQUIRE destination {name, line1, city, state, postal_code, email or phone} — collect from your owner BEFORE checkout; refusals return missing_fields + an example. Pickup (where supported): fulfillment:"pickup" + {name, email or phone}.
- POST https://www.x402-market.com/api/v1/checkout/{id}/confirm — 402 for the full total → pay → retry with X-PAYMENT → order
- GET  https://www.x402-market.com/checkout/{id} — human-viewable receipt tile (OpenGraph-tagged) for owner authorization / screenshots
- POST https://www.x402-market.com/api/v1/estimates — durable quote: full receipt math, NO inventory hold, no destination needed, valid 7 days; persists at /api/v1/estimates/{id} across sessions
- POST https://www.x402-market.com/api/v1/estimates/{id}/send — deliver to the owner: email | ntfy push | webhook
- POST https://www.x402-market.com/api/v1/estimates/{id}/checkout — convert to a payable checkout (re-priced; destination required for physical)

## Shopping sessions — multi-seller cart, ONE transaction
- POST   https://www.x402-market.com/api/v1/sessions — open a session {destination?}; send your Agent-ID header
- POST   https://www.x402-market.com/api/v1/sessions/{id}/cart — add {listing_id, variant_id?, quantity?} from ANY seller; the stock is HELD for your session (nobody can oversell you)
- GET    https://www.x402-market.com/api/v1/sessions/{id}/cart — full multi-seller receipt: per-seller items + shipping + each seller's OWN sales tax rate, marketplace fee, one grand total
- DELETE https://www.x402-market.com/api/v1/sessions/{id}/cart/{cart_item_id} — remove; the hold returns to stock
- POST   https://www.x402-market.com/api/v1/sessions/{id}/heartbeat — keep-alive (every session call also resets the clock)
- POST   https://www.x402-market.com/api/v1/sessions/{id}/checkout — one payable checkout for the WHOLE cart (destination required if physical)
- POST   https://www.x402-market.com/api/v1/cart-checkout/{id}/confirm — 402 with ONE payment leg (grand total → marketplace ESCROW wallet; extra.escrow discloses per-seller allocations) → pay ONCE (one blockchain write, one gas fee) → retry with X-PAYMENT → one order per item, session closed
- GET    https://www.x402-market.com/cart/{id} — human-viewable multi-seller receipt tile for owner authorization
- DELETE https://www.x402-market.com/api/v1/sessions/{id} — cancel; all carted inventory returns to stock
- Session rules: 15-minute idle timeout, reset by every call — a dropped agent can reconnect and resume within 15 minutes; after that the session closes and its inventory holds are released automatically.

## Human-readable API documentation
/docs.html — every supplier + agent call with curl examples.

## Payments (dual layer)
Humans: seller-direct PayPal — each seller's OWN PayPal commercial credentials capture the payment (card, fiat, PYUSD, balance); platform fee rides on top of gross; sellers without connected PayPal are not live for human checkout. Agents: x402 direct split in PYUSD ONLY (locked for seamless PayPal on/off-ramp) on the seller's active chains — ethereum, arbitrum, solana; seller leg + fee leg in extra.split. Bitcoin: NOT supported by x402 (no BTC scheme); a seller's BTC address, if set, appears as off_protocol info only.

## Human layer (dual checkout) + chat embeds
Every listing has a real human page at /p/{listing_id} (SEO: OG meta + JSON-LD Product), browsable by category at /shop. Humans check out with PayPal (fiat, credit card, PYUSD, or PayPal balance); agents check out over x402 — same inventory, same sessions. Iframe-embeddable tiles for chat surfaces: /embed/product/{listing_id} and /embed/checkout/{checkout_id} (frame-ancestors *). Sitemap: /sitemap.xml

## Dynamic product attributes
Listings carry seller-defined fields: any column a seller's system tracks rides along in the listing JSON as `attributes` (searchable via free-text `query`). Suppliers can also install a local database connector (daemon) that AI-maps their own product database and writes agent sales straight back into it.

## Seller search + location filters
POST /api/v1/catalog/search accepts state, zip, seller_name (top-level or in filters) — product-NAME matches rank above keyword matches. GET /api/v1/sellers/search?name=&state=&zip= returns seller contact info + ALL their active listings. MCP: marketplace_find_seller.

## Report a problem
POST /api/v1/complaints {subject, message, seller_id?, order_id?, contact?} — agents pass Agent-ID (MCP: marketplace_report_problem). Filed reports land in the marketplace admin's inbox.

## KYC
Purchases may require a KYC-verified agent. Agents created at [agent-x402.services](https://agent-x402.services) carry owner KYC (Plaid) from creation. Unverified agents get HTTP 403 KYC_REQUIRED with a kyc_link to hand to their owner; once completed, retry the same request.

## Skills
- GET https://www.x402-market.com/skills/{skill_id}/manifest.json
- GET https://www.x402-market.com/skills/{skill_id}/skill.md
Load skill detail only after selecting a capability.

## Payment & fees
- Prices are gross + shipping + a 5% marketplace fee (rounded up), each a separate line item in checkout receipts.
- Pay in PYUSD on arbitrum, ethereum, solana, or stellar. The 402 lists per-network options with extra.split: seller leg → seller wallet, fee leg → marketplace wallet. Pay both legs on one network, retry with X-PAYMENT.

## Conventions
- Idempotency-Key header required on state-changing POSTs.
- Optional headers: Agent-ID, Agent-Capabilities.
- HTTP 402 responses contain machine-readable payment requirements; pay and retry with X-PAYMENT.

## Supplier ingestion (auth: Bearer supplier api_key)
- POST https://www.x402-market.com/api/v1/suppliers/register — get a seller_id + api_key
- POST https://www.x402-market.com/api/v1/integrations — auto-configured connectors: shopify | woocommerce | rest (custom ERP) | csv | webhook
- POST https://www.x402-market.com/api/v1/integrations/{id}/test — preview source records mapped to the canonical schema
- POST https://www.x402-market.com/api/v1/integrations/{id}/sync — pull now (pull connectors also poll every 15 min)
- POST https://www.x402-market.com/api/v1/integrations/{id}/csv — upload a CSV body; columns auto-detected
- POST https://www.x402-market.com/webhooks/{provider}/{integration_id} — push product events (shopify | generic)
- POST https://www.x402-market.com/api/v1/supplier/products — direct push: bulk upsert canonical products (variants + image URLs)
- POST https://www.x402-market.com/api/v1/supplier/inventory — [{sku, quantity, variant_id?}]
- POST https://www.x402-market.com/api/v1/supplier/prices — [{sku, price, variant_id?}]
- PUT  https://www.x402-market.com/api/v1/supplier/profile — contact info, shipping settings (free | flat_per_item | by_weight | dynamic), and sales tax rate (items default to taxable; toggle per item)
- GET  https://www.x402-market.com/api/v1/supplier/transactions — search sales by date range, amount, or SKU (grand totals included)
- GET  https://www.x402-market.com/api/v1/supplier/taxes — itemized taxes collected for a period + grand total (auth: supplier key)
- POST https://www.x402-market.com/api/v1/supplier/listings/{id}/images — upload an image (binary or base64); stored on CDN, listed as a URL
- PUT  https://www.x402-market.com/api/v1/supplier/notifications — free sale alerts: webhook (HMAC-signed), own-Gmail email (OAuth), ntfy phone push, receipt-printer queue (CloudPRNT)

## For humans
- [Landing page](https://www.x402-market.com/) — supplier onboarding and developer overview