v2 Wire · v2.0.0-2026-09-15

BuyWhere Agent DX — v2-first wire reference

The v2 wire is the primary surface for AI agents calling BuyWhere. Every buyer-context tool requires deliver_to and returns a shopping_job_id plus a resolved outbound_url. v1 tools remain callable through 2026-12-31Z and are documented at the bottom of this page.

Get API key MCP setup Raw markdown

Why this changed

Why deliver_to is now required

In v1, deliver_to was optional. In practice, 94% of agent calls omitted it, forcing the catalog to scan every market (SG, MY, ID, TH, VN, US) and either time out or return rankings that were not useful for the buyer’s actual location. The v2 wire makes deliver_to mandatory on every buyer-context tool so the catalog can scope the search, return local-availability labels, and emit a shopping_job_id that lets the agent resume the purchase funnel on the merchant site. Agents that omit deliver_to on a v2 tool receive -32602 INVALID_ARGUMENT so the failure is loud, not silent.

deliver_to format

ISO 3166-1 alpha-2 country code (e.g. "SG", "US", "MY", "TH", "VN", "ID")

Tool selection

Which v2 tool fits which intent

User intent	v2 tool
find X / search for X / show X	search_products_v2
cheapest X / best price for X	find_best_price_v2
deals on X / discounts on X	get_deals_v2
compare A vs B / A vs B vs C	compare_products_v2
details on product <id> / tell me more	get_product_v2

list_categories, find_similar, and ingest_products remain v1-only — they are not buyer-context tools and do not require deliver_to.

v2 wire setup

Wire your agent to the v2 surface

The v2 wire is exposed at POST https://api.buywhere.ai/mcp via JSON-RPC 2.0. Both streamable-http and the legacy sse transports are supported. The MCP server-card at /.well-known/mcp/server-card.json is the authoritative machine-readable copy of these tools.

{
  "mcpServers": {
    "buywhere": {
      "command": "npx",
      "args": ["-y", "@buywhere/mcp-server"],
      "env": {
        "BUYWHERE_API_KEY": "bw_live_your_key_here",
        "BUYWHERE_WIRE_VERSION": "v2"
      }
    }
  }
}

v2 tools

Five v2 tools, one REQUIRED field

v2 · Tool 1

`search_products_v2`

REQUIRED deliver_to

Search the catalog by keyword. Returns ranked, deliverable-first results with schema.org/Product entities.

Required

q
deliver_to

Request

{
  "q": "wireless headphones",
  "deliver_to": "SG",
  "limit": 10,
  "category": "Headphones",
  "min_price": 50,
  "max_price": 800,
  "sort": "best_value"
}

Response

{
  "data": [
    {
      "id": "bw_sg_12345",
      "title": "Sony WH-1000XM5",
      "price": 429.0,
      "currency": "SGD",
      "domain": "hifisolutions.sg",
      "url": "https://hifisolutions.sg/products/sony-wh-1000xm5",
      "buywhere_score": 0.92,
      "availability": "in_stock",
      "deliver_to": "SG"
    }
  ],
  "meta": {
    "total": 124,
    "limit": 10,
    "offset": 0,
    "shopping_job_id": "9f3a4b1e-7c2d-4a8e-b651-2c0a4f7b9d3e"
  }
}

v2 · Tool 2

`find_best_price_v2`

REQUIRED deliver_to

Find the single cheapest deliverable listing for a product across covered storefronts. Returns shopping_job_id and a resolved outbound_url.

Required

q
deliver_to

Request

{
  "q": "iphone 17 pro 256gb",
  "deliver_to": "SG",
  "category": "Smartphones"
}

Response

{
  "data": {
    "id": "bw_sg_98765",
    "title": "Apple iPhone 17 Pro 256GB",
    "lowPrice": 1599.0,
    "priceCurrency": "SGD",
    "offerCount": 6,
    "merchant": "Best Denki",
    "outbound_url": "https://api.buywhere.ai/v2/outbound/9f3a4b1e-7c2d-4a8e-b651-2c0a4f7b9d3e?to=best-denki-sg"
  },
  "shopping_job_id": "9f3a4b1e-7c2d-4a8e-b651-2c0a4f7b9d3e",
  "deliver_to": "SG"
}

v2 · Tool 3

`get_deals_v2`

REQUIRED deliver_to

Discounted products sorted by discount percentage. Carries a shopping_job_id envelope so the agent hands the user a single outbound_url.

Required

deliver_to

Request

{
  "deliver_to": "US",
  "min_discount_pct": 20,
  "category": "Laptops",
  "limit": 20
}

Response

{
  "data": [
    {
      "id": "bw_us_55432",
      "title": "Lenovo IdeaPad 5 14"",
      "price": 549.0,
      "originalPrice": 799.0,
      "discountPercentage": 31.3,
      "priceCurrency": "USD",
      "availability": "in_stock",
      "outbound_url": "https://api.buywhere.ai/v2/outbound/4b1e9f3a-2c0a-4f7b-9d3e-7c2d8e651a4f?to=lenovo-us"
    }
  ],
  "shopping_job_id": "4b1e9f3a-2c0a-4f7b-9d3e-7c2d8e651a4f",
  "deliver_to": "US"
}

v2 · Tool 4

`compare_products_v2`

REQUIRED deliver_to

Compare 2 to 10 products side-by-side. Each row carries the buyer's deliver_to availability state.

Required

ids
deliver_to

Request

{
  "ids": ["bw_sg_12345", "bw_sg_67890", "bw_sg_24680"],
  "deliver_to": "SG"
}

Response

{
  "data": [
    {
      "id": "bw_sg_12345",
      "title": "Sony WH-1000XM5",
      "price": 429.0,
      "currency": "SGD",
      "availability": "in_stock",
      "buywhere_score": 0.92,
      "deliver_to": "SG"
    }
  ],
  "shopping_job_id": "8a2c4d6e-1f3b-4a5d-9c7e-2b8d0f4a6c8e",
  "deliver_to": "SG"
}

v2 · Tool 5

`get_product_v2`

REQUIRED deliver_to

Retrieve full details for a specific product. Adds an outbound_url resolver so the agent can return a direct handoff to the merchant.

Required

id
deliver_to

Request

{
  "id": "bw_sg_12345",
  "deliver_to": "SG"
}

Response

{
  "data": {
    "id": "bw_sg_12345",
    "title": "Sony WH-1000XM5",
    "description": "Industry-leading noise cancellation...",
    "price": 429.0,
    "currency": "SGD",
    "availability": "in_stock",
    "merchant": "Hifi Solutions",
    "outbound_url": "https://api.buywhere.ai/v2/outbound/2c8d0f4a-6a8c-4e2b-9d4f-1a3c5e7b9d2f?to=hifisolutions-sg",
    "structured_specs": { "/* ... */": null }
  },
  "shopping_job_id": "2c8d0f4a-6a8c-4e2b-9d4f-1a3c5e7b9d2f",
  "deliver_to": "SG"
}

Sunset clock

When v1 leaves the wire

Date	Event
2026-09-15Z	v2 wire live; v2 tools exposed on /mcp tools/list with REQUIRED deliver_to.
2026-10-01Z	v1 tools deprecated; server-card prepends [DEPRECATED — use v2] to each v1 description.
2026-12-31Z	v1 tools return HTTP 410 Gone with migration notice.

v1 (deprecated) — collapsible reference

The v1 tools remain callable until 2026-12-31Z. New agent work should target the v2 wire above. The v1 tools match v2 request bodies exceptdeliver_to is optional and the response does not include shopping_job_id or outbound_url.

v1 tool	Parameters
search_products	query, category, min_price, max_price, source, deliver_to?, limit
get_product	product_id
find_best_price	product_name, category, deliver_to?
get_deals	category, min_discount_pct=10, deliver_to?, limit=20
compare_products	ids (CSV string), deliver_to? — v2 expects an array of 2-10
list_categories	currency
find_similar	product_id
ingest_products	product_url

v1 wire version: 1.0.0. Server-card version remains 1.0.0; the v2 marker lives in the top-level x-buywhere-v2 extension field.

Empty results

When a v2 tool returns zero products

Empty results are still 200 OK. The response includes ameta.emptiness_reason enum so your agent can distinguish “no catalog data” from “query mismatch” from “API degraded.” The field appears only when the result array is empty; non-empty responses never carry it.

`emptiness_reason`	What it means	What your agent should do
no_data	Region has zero products indexed.	Treat as authoritative; no retry.
no_match	Region has products, but query/filters excluded all of them.	Widen query or drop filters; do not retry the same query.
api_error	Downstream error caused the engine to fall back to empty.	Retry once with a short backoff (≤2s); surface as ambiguous if still empty.
quota	Rate-limit guardrail tripped.	Wait for the rate-limit window; do not retry-storm.
region_unsupported	Country code is not in the supported set.	Re-issue with a supported region.
category_unsupported	Category slug is unknown or in transition.	Drop category or consult /v1/categories.
deliver_to_missing	You omitted deliver_to/country_code, but the catalog has matches elsewhere.	Re-issue with deliver_to set to the buyer's country.
invalid_deliver_to	deliver_to is not a supported ISO code (MCP v2 only).	Use a supported code from the hint field.

Confidence field

Every empty result also carries meta.confidence of high or low. When confidence is low, your agent should retry once after a short backoff; otherwise, treat the reason as authoritative.

Diagnostic block

meta.diagnostic includes engine_status, indexed_for_region, category_recognized, rate_limit_remaining, and deliver_to_present. See the full reference in Error Reference → Empty-Result Envelope.

Acceptance contract

This page mirrors the MCP server-card

The README at /agent-dx is the canonical copy of this document. The MCP server-card at /.well-known/mcp/server-card.jsonmirrors these descriptions word-for-word. Changes to either surface MUST be made in lockstep. Atlas (BUY-72482) verifies live parity on every heartbeat.

MCP setup MCP server-card