Useful Data Source For Agents Doing Product Price Sdk

BuyWhere Singapore バリューインテリジェンス API

シンガポールの E コマース（BuyWhere）を対象としたセマンティック商品検索です。ベンダー間の価格分布におけるシャノンエントロピーから算出した、監査可能なバリュースコアでランキングします。「最安値順」ではありません。

AI エージェント向けに、シンプルな HTTP API と MCP サーバー（5 つのツール）の両方を提供します。

---

ベース URL

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

認証

すべてのビジネスエンドポイントには、X-API-Key ヘッダーが必要です。 X-API-Key:

/health に認証は不要です。

料金

同じエンドポイントで、2 通りの支払い方法を利用できます。

• x402（呼び出しごとの支払い、Base 上の USDC） - 現在は Base Sepolia テストネットで、1 回の呼び出しにつき $0.01 です。支払いなしでリクエストすると、支払いの詳細を含む 402 Payment Required が payment-required レスポンスヘッダーに返されます。
• Stripe（従量課金） - API キーが発行され、アカウントに Stripe の顧客が登録されている呼び出し元向けです。

---

エンドポイント

GET /search

BuyWhere Singapore のカタログを対象としたセマンティック商品検索です。複合バリュースコアでランキングします。

クエリパラメーター：

• 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

1 つの商品について、バリュースコアの計算式を完全かつ監査可能な形で分解します。エントロピー成分、信頼性成分、価格順位成分、計算式そのもの、おすすめのベンダーと価格を確認できます。

GET /product/{product_id}/price_distribution

1 つの商品のベンダー間の価格分布を返します。エントロピー（未加工値と正規化値）、価格幅、変動係数、市場の分断状況をわかりやすく説明した情報が含まれます。

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 は、以下を組み合わせて算出します。

• エントロピー成分 - ベンダー間の価格分布におけるシャノンエントロピー（H、ビット単位）を、そのベンダー数に対する最大エントロピーで正規化したものです。エントロピーが高いほど、各ベンダーの価格が同じ価格帯に集中しているのではなく、実際に価格競争が行われていることを示します。
• 信頼性成分 - ベンダーごとの因果的信頼性スコアです。
• 価格順位成分 - このベンダーの価格が、観測された価格範囲のどこに位置するかを示します。

すべてのレスポンスに未加工の各成分（shannon_entropy_bits、entropy_component、reliability_component、price_rank_component）が含まれます。また、/product/{id}/value_breakdown では formula 文字列そのものも含まれるため、エージェントは数値だけでなく、その根拠も提示できます。

---

制限

• /search：1 回の呼び出しにつき最大 50 件
• MCP compare_buywhere_products_causal_rank：1 回の呼び出しにつき 2～10 個の商品 ID