# ktown

> ktown is a Vancouver-first group-buy marketplace for Korean sellers in Canada (CAD).

## Group-buy rules
- Sellers set a minimum unit count (`min_units`) and optional maximum; buyers join without being charged until the minimum is reached.
- When the minimum is met, cards on file are charged (automatic capture). If the minimum is not met by the close date, nobody is charged.
- Listings have a close date (`closes_at` / `end_date`); fulfillment follows seller pickup, local delivery, or shipping options.
- Currency is CAD. Prices in the public API use `amount_minor` (cents).

## Public read API (agents)
- OpenAPI: https://ktown.io/api/v1/public/openapi.json
- Human docs: https://ktown.io/api/v1/public/docs
- List listings: GET https://ktown.io/api/v1/public/listings
- One listing: GET https://ktown.io/api/v1/public/listings/{id}
- Sellers: GET https://ktown.io/api/v1/public/sellers
- Storefront: GET https://ktown.io/api/v1/public/sellers/{handle}
- Schema gaps (null fields): GET https://ktown.io/api/v1/public/schema-gaps

## Agent distribution (Phase 17)
- MCP (Streamable HTTP, read-only): https://ktown.io/api/mcp
  - Tools: `search_listings`, `get_listing`, `get_seller` (same data as the public API).
- MCP Server Card (SEP-2127): https://ktown.io/api/mcp/server-card
- AI Catalog (domain discovery): https://ktown.io/.well-known/ai-catalog.json
- Stripe Agentic Commerce catalog feed (CSV, discovery-only, disable_checkout=true): GET https://ktown.io/api/v1/public/catalog-feed.csv
- Human guide: https://ktown.io/docs/agent-discovery

## Structured data
- Listing pages include schema.org JSON-LD (Product + Offer).
- Seller storefronts include Organization / LocalBusiness JSON-LD.
- Sitemap: https://ktown.io/sitemap.xml

## Key pages
- English home: https://ktown.io/en
- Korean home: https://ktown.io/ko
- Browse listings: https://ktown.io/en/listings

## Privacy
The public API never exposes buyer data, exact private pickup addresses, or seller email/phone.