BuyWhere Singapore Value Intelligence API

Semantic product search over Singapore e-commerce (BuyWhere), ranked by an auditable value-score derived from Shannon entropy across vendor price distributions - not just "cheapest first."

Available both as a plain HTTP API and as an MCP server (5 tools) for AI agents.

---

Base URL

https://useful-data-source-for-agents-production.up.railway.app

Authentication

All business endpoints require an X-API-Key header: X-API-Key: <your key>

/health requires no authentication.

Pricing

Two ways to pay, same endpoints:

• x402 (pay-per-call, USDC on Base) - currently on Base Sepolia testnet, $0.01/call. A request without payment gets 402 Payment Required with the payment details in the payment-required response header.
• Stripe (metered billing) - for callers provisioned with an API key and a Stripe customer on the account.

---

Endpoints

GET /search

Semantic product search over the BuyWhere Singapore catalog, ranked by composite value-score.

Query params:

• query (required) - natural-language product description
• limit (default 10, 1-50)
• min_value_score (default 0.0, range 0.0-1.0) - filter out products below this score GET /search?query=noise+cancelling+headphones&limit=5&min_value_score=0.5

Response (ProductSearchResponse):

{
  "query": "noise cancelling headphones",
  "result_count": 5,
  "currency": "SGD",
  "products": [
    {
      "product_id": "abc123",
      "title": "Sony WH-1000XM5",
      "category": "electronics",
      "image_url": "...",
      "vendor_offers": ["..."],
      "price_min_sgd": 389.00,
      "price_max_sgd": 429.00,
      "price_mean_sgd": 405.30,
      "shannon_entropy_bits": 1.24,
      "causal_reliability_score": 0.92,
      "value_score": 0.847,
      "value_score_explanation": "..."
    }
  ],
  "computation_ms": 43.2
}

GET /product/{product_id}/value_breakdown

Full auditable decomposition of the value-score formula for one product - entropy component, reliability component, price-rank component, the formula itself, and the recommended vendor/price.

GET /product/{product_id}/price_distribution

Vendor price distribution for one product: entropy (raw and normalized), price spread, coefficient of variation, and a plain-language interpretation of market fragmentation.

GET /health

Liveness probe. Returns { status, upstream_reachable, api_version, timestamp }. No auth required. Not billed (excluded from both Stripe and x402).

---

MCP tools

Connect an MCP-compatible client (Claude, Cursor, etc.) to the streamable HTTP endpoint at: https://useful-data-source-for-agents-production.up.railway.app/mcp

Exposes 5 tools:

• rank_buywhere_products_by_value_score - ranked search with max_price_sgd and category_filter
• fetch_buywhere_vendor_price_distribution - vendor spread for a known product_id
• resolve_buywhere_product_identity - disambiguate a partial/fuzzy product name into candidate product IDs
• compare_buywhere_products_causal_rank - head-to-head comparison of 2-10 products with confounder adjustment
• extract_buywhere_deal_anomalies - z-score based detection of mispriced or outlier listings

---

Value-score: the method

For each product, prices across vendors are treated as a distribution. The composite value_score blends:

• Entropy component - Shannon entropy of the price distribution across vendors (H, in bits) normalized against the maximum possible entropy for that vendor count. Higher entropy = genuine price competition, not vendors clustered at the same number.
• Reliability component - a causal-reliability score per vendor.
• Price-rank component - where this vendor's price sits in the observed range.

Every response includes the raw components (shannon_entropy_bits, entropy_component, reliability_component, price_rank_component) and, on /product/{id}/value_breakdown, the formula string itself - so an agent can cite the reasoning, not just the number.

---

Limits

• /search: limit up to 50 results per call
• MCP compare_buywhere_products_causal_rank: 2-10 product IDs per call