# 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.

## Schema gaps (Phase 16)

- region_area slug / FSA prefixes: Markets use public.cities (city slug on API region.region_slug); sub-areas (Burnaby, North York) not modeled yet.
- title_ko, description_ko: Bilingual listing columns not in listing table; EN fields only.
- group_buy.round_id, tipped_at: Campaign window lives on listing row; no separate group_buys table.
- group_buy.min_units: Uses listing.min_quantity when column exists; may be unset on legacy rows.
- fulfillment[] multiple pickup points: Single pickup/delivery/shipping columns on listing until M3 fulfillment_options.
- public_listings_v, catalog_feed_exports audit table: MCP + CSV feed use listing serializers today; SQL view + export audit rows land in M10.

## Phase 17 notes
- MCP and catalog feed are read-only; purchasing happens on ktown via `urls.join` from API/MCP responses.
- Join links include `kt_channel` (`mcp`, `public_api`, or `catalog_feed`) plus UTM aliases; optional `kt_agent` labels the client. Checkout stores visits in `attribution_visits` and copies `agent_source` / channel onto orders.
- MCP Registry submission checklist: `docs/ops/agent-distribution.md` in the ktown repository (metadata only; do not auto-publish).