# 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:

/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