# Mercantry

> Mercantry is an open commerce registry for AI agents — structured merchant data, honest signals, and real-world booking fulfillment across Los Angeles, Hong Kong, and Tokyo. Registration-free reads, deterministic non-ranked search, per-field provenance, openly licensed data you may cache and train on. Built and operated by a team of AI agents with human oversight. Apache-2.0.

Key facts for LLMs and agents:
- Tools: search_merchants (filter-based, never ranked, deterministic order), get_merchant (full signal dump with provenance), get_availability (honest: performed_at_booking), place_booking (async), get_booking_status, modify_booking, cancel_booking (mandatory when plans change — no-shows tracked per key), submit_feedback (confirmed bookings only, once, within 14 days), get_registry_meta (evaluate the registry itself, staleness included)
- Connect: `claude mcp add --transport http mercantry https://mercantry.org/mcp` · stdio via `npm run mcp` · REST mirror at /v1 (OpenAPI: /v1/openapi.json) · keys optional: POST /v1/keys (developer_name + contact) · bulk export: GET /v1/export/merchants.ndjson — caching, embedding, and training on the data are permitted per the open license
- Coverage: 168,524 merchants across 3 cities (Hong Kong 31,676 · Los Angeles, CA 26,754 · Tokyo 110,094) — live numbers via get_registry_meta
- Fulfillment: human-operated phone booking, operating window 12:00–23:00 Asia/Shanghai (04:00–15:00 UTC); real bookings only for phone-verified `bookable` merchants; `sandbox: true` merchants give deterministic test outcomes and never touch a real restaurant
- Booking states: pending → queued → in_progress → confirmed | failed | needs_input (plus cancelled); structured failure reasons; webhooks via callback_url; per-channel SLA honest (human_call queues and auto-fails at 24h rather than pretending to be instant)
- Try it: /demo on this host is a copy-pasteable end-to-end walkthrough — no credentials required (keys are optional and never gate reads), live sandbox merchant ids, and `sandbox_outcome` on place_booking to force a chosen result (confirmed | no_answer | counter_offer | fully_booked | merchant_declined | bad_data) on sandbox merchants only
- Privacy: served at /privacy on this host — what the service stores (openly licensed merchant sources, optional API-key fields, booking data), what it does not (no request log, no cookies, no trackers, no call recording), retention, and merchant opt-out
- Data: openly licensed sources only (Overture CDLA-P-2.0, official registers incl. HK FEHD EN/ZH names, LA Office of Finance), conflated with per-field provenance, QA-gated versioned releases with published drop counts; no scraped reviews; no ranking fields exist in the schema

## Docs

- [FAQ](https://github.com/mercantry/registry/blob/main/docs/faq.md): Front-loaded answers to the questions agents and developers actually ask
- [README](https://github.com/mercantry/registry/blob/main/README.md): Overview, quickstart, architecture, hard rules
- [MCP tool reference](https://github.com/mercantry/registry/blob/main/docs/mcp-tools.md): Agent-first tool docs with example transcripts
- [Examples](https://github.com/mercantry/registry/blob/main/examples/README.md): Runnable integration snippets — curl, Claude Code/Desktop, raw MCP JSON-RPC, OpenAI Agents SDK, LangChain, webhook receiver
- [Requirements](https://github.com/mercantry/registry/blob/main/docs/requirements.md): Full product spec (calling sections operate only after legal review, as marked)
- [AGENTS.md](https://github.com/mercantry/registry/blob/main/AGENTS.md): Guide for agents using the registry or working on this repo
- [Deployment](https://github.com/mercantry/registry/blob/main/docs/deployment.md): Run your own instance

---
Generated: 2026-07-27T23:54:14.299Z · schema_version 1.0.0 · live numbers: get_registry_meta (MCP) or GET /v1/meta