Build an AI Shopping Assistant with BuyWhere US

BuyWhere already gives AI agents a clean product-search surface for Singapore. The next step is building the same workflow so your agent can handle US shopping queries without rewriting your tools from scratch.

In this tutorial, you will wire BuyWhere into an agent in two ways:

MCP for tool-based agent workflows
REST for direct search and cross-region comparisons

The result is a simple shopping assistant that can answer prompts like:

Find the best US deals on AirPods Pro
Compare Nintendo Switch pricing in the US vs Singapore
Show me in-stock monitors under $300 from US retailers

What you will build

A minimal shopping assistant that:

uses BuyWhere's MCP integration path once the public hosted endpoint is verified live
calls GET /v1/search for explicit search flows
filters results with region=us, country=US, and currency=USD
compares the same query across US and SG without changing providers

Prerequisites

A BuyWhere API key from buywhere.ai/api-keys-keys
Python 3.10+ for the LangChain example
Node.js 20+ for the TypeScript example

Step 1: Verify the current MCP endpoint before connecting

If your agent platform supports remote MCP, verify the current hosted endpoint in the live docs before hardcoding it into your config.

As of this draft revision, the safest public sources are:

Treat the config below as a template until launch-day endpoint verification is complete.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "buywhere": {
      "url": "https://<verified-buywhere-mcp-endpoint>",
      "headers": {
        "Authorization": "Bearer bw_live_xxx"
      }
    }
  }
}

Cursor

Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "buywhere": {
      "url": "https://<verified-buywhere-mcp-endpoint>",
      "headers": {
        "Authorization": "Bearer bw_live_xxx"
      }
    }
  }
}

Once connected, your agent can use BuyWhere's product-search tools directly instead of manually managing HTTP calls.

Step 2: Query the REST API for explicit search control

For app logic, analytics, or fallback flows, use the REST API directly.

The most useful starting point is GET /v1/search.

Example: US search

curl "https://api.buywhere.ai/v1/search?q=airpods%20pro&region=us&currency=USD&limit=5" \
  -H "Authorization: Bearer $BUYWHERE_API_KEY"

Useful query params for launch-week integrations:

q: free-text query
region: us, sg, or sea
country: one or more country codes such as US or SG
min_price and max_price: price filters
platform: source filter
currency: normalized output currency
region_boost: local, none, or only

Step 3: Build a TypeScript search helper

type BuyWhereSearchItem = {
  id: string;
  name: string;
  price: number;
  currency: string;
  platform: string;
  merchant_name: string;
  availability: string;
  product_url: string;
};

type BuyWhereSearchResponse = {
  total: number;
  items: BuyWhereSearchItem[];
};

export async function searchBuyWhereUS(query: string) {
  const url = new URL("https://api.buywhere.ai/v1/search");
  url.searchParams.set("q", query);
  url.searchParams.set("region", "us");
  url.searchParams.set("currency", "USD");
  url.searchParams.set("limit", "5");

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${process.env.BUYWHERE_API_KEY}`,
    },
  });

  if (!response.ok) {
    throw new Error(`BuyWhere search failed: ${response.status}`);
  }

  return (await response.json()) as BuyWhereSearchResponse;
}

Step 4: Build a LangChain tool in Python

import os
import requests
from langchain_core.tools import tool

BASE_URL = "https://api.buywhere.ai/v1/search"
API_KEY = os.environ["BUYWHERE_API_KEY"]


@tool
def search_buywhere(query: str, region: str = "us", currency: str = "USD") -> dict:
    """Search BuyWhere's catalog for products in a specific region."""
    response = requests.get(
        BASE_URL,
        params={
            "q": query,
            "region": region,
            "currency": currency,
            "limit": 5,
        },
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=20,
    )
    response.raise_for_status()
    return response.json()

This is enough for an agent that can:

search US products by default
switch to Singapore when a user asks for local pricing
compare both markets from the same tool

Step 5: Add a cross-region comparison flow

One of the cleanest launch demos is a single prompt that compares two markets.

def compare_us_vs_sg(query: str) -> dict:
    us = requests.get(
        BASE_URL,
        params={"q": query, "country": "US", "currency": "USD", "limit": 3},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=20,
    ).json()

    sg = requests.get(
        BASE_URL,
        params={"q": query, "country": "SG", "currency": "SGD", "limit": 3},
        headers={"Authorization": f"Bearer {API_KEY}"},
        timeout=20,
    ).json()

    return {"us": us["items"], "sg": sg["items"]}

That gives your agent a straightforward prompt pattern:

Compare the top 3 US offers with the top 3 Singapore offers and explain which market currently looks better for this product.

Step 6: Example prompt

Once the tool is wired in, your agent can answer prompts like:

Find the best US listings for the Sony WH-1000XM5 under $300.
Then compare those prices with Singapore results and tell me
whether importing makes sense.

The important part is that the agent does not need different providers for different regions. It uses the same API surface and changes only the filters.

Why this workflow matters

For agent builders, the hard part is not generating text. It is getting consistent, structured commerce data into the loop.

BuyWhere's value here is operational:

one MCP endpoint for agent tool use
one REST search surface for custom app logic
one set of filters for region and country targeting
one integration path that can grow from Singapore into broader catalog coverage

Next steps

Add price-threshold rules for budget-aware shopping agents
Persist user preferences such as preferred retailer or region
Combine BuyWhere search with your own checkout, affiliate, or lead-routing logic
Add a second tool that compares US and SG automatically for high-consideration items

If you want the fastest path, start with MCP. If you want tighter app-level control, start with GET /v1/search. Most teams will end up using both.