# Villa Market — shopping for AI agents

> Villa Market, a Thai supermarket, sells groceries online through the Villa Commerce API. An agent can search what Villa sells at a branch with that branch's prices, keep a basket, get the total from Villa's own calculator, place an order and hand the shopper a payment link.

## Connect
- MCP (Streamable HTTP): https://agent.villamarket.ai/mcp/
- Server card: https://agent.villamarket.ai/.well-known/mcp.json
- Individuals: sign in at https://agent.villamarket.ai, create a personal key and send it as `Authorization: Bearer <key>`. You shop as yourself; nothing is shared with a merchant.
- Merchants (marketplaces and shops): send your merchant key as `X-Partner-Key` with your shopper's sign-in; your shoppers' paid orders earn you a royalty. Guide: https://developers.villamarket.ai/docs

## Tools
- `search_products` — Semantic product search. Returns cprcode + name hits.
- `get_product` — Fetch one product by cprcode. Optionally include branch price + inventory.
- `get_inventory` — Branch inventory snapshot, optionally filtered to cprcodes.
- `list_branches` — Villa branches that take online orders (code, name, lat/lon, address).
- `resolve_fulfilment` — Nearest online branch to lat/lon (straight line), else the branch sharing the postcode.
- `list_categories` — Top-level categories of what Villa sells online, with counts.
- `list_products` — Browse what Villa sells online (product mirror). With branch_code, only products priced there, with that price.
- `get_basket` — The shopper's basket on this platform. Needs a verified Cognito idToken.
- `add_basket_line` — Add a line to the shopper basket. Quantity merges; branch_code switches the basket's branch.
- `set_basket_quantity` — Set a line's quantity; 0 removes it.
- `empty_basket` — Empty the shopper basket.
- `create_quote` — Villa's calculator (calculatecost2 GetCost) for the basket, or for `lines`.
- `apply_coupon` — Re-quote with couponCodeList. Same rules as create_quote.
- `create_order` — Place the basket (or `lines`) as an order. Re-priced by Villa's calculator at
- `create_payment_link` — A fresh payment link for one of the shopper's unpaid orders.
- `start_payment` — Where the shopper pays: the order's payment link. PAN never hits this API.
- `get_order` — One of the shopper's orders. Status is payment.isPaid + payment.status.
- `list_orders` — The shopper's orders on this platform, newest first.

## Rules
- Prices, fees and totals come only from the tools; `grandTotal` from `create_quote` is the bill.
- Place an order only after the shopper confirms it; the shopper pays on the payment link.
- Sandbox: orders are recorded, nothing is delivered, payment links take no money.

## Optional
- GraphQL: https://developers.villamarket.ai/graphql (schema https://developers.villamarket.ai/schema.graphql)
- Developer guide: https://developers.villamarket.ai/docs
- Talk to Villa's own agent: https://agent.villamarket.ai