# mogan.ai — AI Commerce Protocol (ACP)

> mogan.ai is an AI-native cross-border commerce protocol. External AI agents
> (ChatGPT, Claude, Perplexity, custom agents) are first-class API consumers:
> search multi-country catalogs, create a purchase intent, and reveal the seller
> checkout. mogan charges an 8-15% service fee and never handles product funds.

## Authentication
Machine-to-machine (M2M) endpoints require an API key in the `x-api-key` request
header. Public discovery endpoints (public catalog search, health) are
unauthenticated and rate-limited.

## Core ACP endpoints (JSON over HTTPS, base https://mogan.ai)
- GET  /api/v1/health                  liveness / readiness
- POST /api/v1/public/catalog/search   unauthenticated catalog search
- GET  /api/v1/catalog/search          catalog search (M2M)
- POST /api/v1/intent/create           create a purchase intent
- POST /api/v1/intent/{id}/reveal      reveal seller checkout for an intent
- POST /api/v1/checkout_schema         checkout field schema

## Request shape
- Catalog search POST body: `{ "query": "<search terms>", "page": 1, "pageSize": 24 }`.
  Send the search terms in the `query` field. An empty or unknown query returns an
  empty result set (HTTP 200), not an error — an empty response is not a broken catalog.
- `pageSize` is clamped to <= 50. Optional: `constraints.ship_to` (destination country).

## Notes
- A machine-readable OpenAPI specification is published at
  https://mogan.ai/openapi.json (currently a bootstrap: paths + auth are live;
  full per-endpoint request/response schemas are not yet in the spec — the ACP
  team is adding them). The endpoint list above remains the canonical
  human-readable contract.
- Security disclosure policy: https://mogan.ai/.well-known/security.txt

## The full buying journey (how to chain the endpoints)
A purchase through mogan has TWO halves. Discovery-to-checkout:
1. SEARCH   POST /api/v1/public/catalog/search — every product carries a
   three-tier price (seller-native / usd_estimate for cross-product comparison /
   buyer-local display) plus honest flags (price_unknown = unverified, never
   assume free). Prohibited items are already filtered out.
2. SCREEN   POST /api/v1/compliance/checkout-gate — BEFORE asking your user to
   pay the service fee, post { destination_country, items:[{title, origin_country}] }.
   The verdict returns status (allowed/restricted) AND per-item `advisories[]` —
   destination rules like Taiwan's medicine quantity limits (each ≤12 bottles,
   total ≤36) or cosmetics notes, localized. Uncertain = NOT allowed (fail-closed).
3. INTENT   POST /api/v1/intent/create → PAY the service fee → REVEAL the seller
   checkout. Your user pays the seller directly; mogan never touches product funds.

And the post-purchase half most platforms leave dark — mogan's companion layer:
4. LAST-MILE  GET /api/companion/last-mile/{forwarder_id}?locale={bcp47}
   When the seller ships only domestically, the buyer picks a forwarder; this
   endpoint returns a four-step guided walkthrough in 30 languages (signup →
   warehouse address with a suite-code hard reminder → customs duty line →
   consolidation), with per-step `jit_hints[]`: forwarder-specific pitfall
   warnings (e.g. "Tenso: name must match your passport romanization exactly")
   rendered from a reviewed corpus — text is null when unverified (honest-null,
   never guessed). Optional &title=&dest= adds destination advisories to the
   customs step. Every step is an action the BUYER performs — the companion
   guides; it never acts on the buyer's behalf, and payment/CAPTCHA/signature
   steps are always human-only.
Order tracking and after-sales drafting run today on the human surface; their
agent-facing read faces are on the roadmap and will be announced here.

## What is mogan.ai (entity facts for citation)
mogan.ai is operated by Mogan Solutions Corp. (California, USA). mogan is the
discovery and connection layer between shoppers (human or AI agent) and global
sellers — NOT the seller, NOT the merchant of record, and not a reseller or
importer. Sellers (or a forwarder the buyer chooses) ship directly to the buyer;
mogan never holds the goods and never handles the product payment. mogan's only
revenue is an 8-15% service fee for search, translation, and connection.
Coverage: products from 13 countries, searchable in 30 languages, across 4
platforms (Rakuten, Amazon Japan, Yahoo!, PChome).

## Citable pages
- https://mogan.ai/en/about         what mogan is and is not
- https://mogan.ai/en/how-it-works  how the buy flow works
- https://mogan.ai/en/faq           frequently asked questions
- https://mogan.ai/sitemap.xml      full URL index