Useful Data Source For Agents Doing Product Price Sdk

BuyWhere Singapore 价值情报 API

在新加坡电商平台（BuyWhere）上进行语义商品搜索，并根据商家价格分布的 Shannon 熵计算可审计的价值评分进行排序，而不只是“价格最低优先”。

既可作为普通 HTTP API 使用，也可作为 MCP 服务（提供 5 个工具）供 AI Agent 使用。

---

基础 URL

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

身份验证

所有业务端点都需要 X-API-Key 请求头： X-API-Key:

/health 无需身份验证。

定价

两种付费方式，使用相同的端点：

• x402（按次付费，使用 Base 上的 USDC）——目前运行在 Base Sepolia 测试网，每次调用 $0.01。未付款的请求会收到 402 Payment Required，付款详情包含在 payment-required 响应头中。
• Stripe（按用量计费）——适用于已配置 API 密钥且账号关联了 Stripe 客户的调用方。

---

端点

GET /search

在 BuyWhere 新加坡商品目录中进行语义商品搜索，并按综合价值评分排序。

查询参数：

• query（必填）- 自然语言商品描述
• limit（默认值 10，范围 1-50）
• min_value_score（默认值 0.0，范围 0.0-1.0）- 筛除评分低于此值的商品 GET /search?query=noise+cancelling+headphones&limit=5&min_value_score=0.5

响应（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

对单个商品的价值评分公式进行完整、可审计的分解，包括熵分量、可靠性分量、价格排名分量、公式本身，以及推荐的商家和价格。

GET /product/{product_id}/price_distribution

单个商品的商家价格分布：熵（原始值和归一化值）、价格差距、变异系数，以及对市场碎片化程度的通俗解释。

GET /health

存活探针。返回 { status, upstream_reachable, api_version, timestamp }。无需身份验证。不计费（不计入 Stripe 和 x402）。

---

MCP 工具

将兼容 MCP 的客户端（Claude、Cursor 等）连接到以下可流式传输的 HTTP 端点： https://useful-data-source-for-agents-production.up.railway.app/mcp

提供 5 个工具：

• rank_buywhere_products_by_value_score - 按价值评分排序的搜索，支持 max_price_sgd 和 category_filter
• fetch_buywhere_vendor_price_distribution - 查询已知 product_id 的商家价格分布
• resolve_buywhere_product_identity - 将不完整或模糊的商品名称解析为候选商品 ID
• compare_buywhere_products_causal_rank - 对 2-10 个商品进行正面对比，并调整混杂因素
• extract_buywhere_deal_anomalies - 基于 z 分数检测价格错误或异常的商品信息

---

价值评分：计算方法

对于每种商品，会将各商家的价格视为一个分布。综合 value_score 由以下部分构成：

• 熵分量 - 商家价格分布的 Shannon 熵（H，单位为比特），并根据商家数量下的最大可能熵进行归一化。熵越高，表示存在真正的价格竞争，而非商家价格都聚集在同一数值附近。
• 可靠性分量 - 每个商家的因果可靠性评分。
• 价格排名分量 - 该商家的价格在观测范围内所处的位置。

每个响应都会包含原始分量（shannon_entropy_bits、entropy_component、reliability_component、price_rank_component），并且 /product/{id}/value_breakdown 会提供 formula 字符串本身，让 Agent 可以引用推理依据，而不只是评分数值。

---

限制

• /search：每次调用的 limit 最多为 50 个结果
• MCP compare_buywhere_products_causal_rank：每次调用接受 2-10 个商品 ID