WhaleScope MCP

WhaleScope MCP — Binance Futures 市场情报

🇮🇩 Bahasa Indonesia | 🇬🇧 English

提供 Binance USDS-M Futures 公开数据（资金费率、未平仓合约、做多／做空比例、主动成交量、K 线、订单簿、波动率），并提供 Binance Spot 对比数据（价格、订单簿、K 线、CVD）的 MCP 服务，可作为 Claude 可调用的工具。所有提供的数据均为公开只读数据——不会下单或交易，也不会访问私人账户数据。

快速部署

此按钮会克隆代码仓库，并在你自己的 Cloudflare 账户中创建 Worker，还会自动创建新的 KV 命名空间和 D1 数据库（Cloudflare 会为你的账户生成新的 id／database_id，无需手动创建）。 并非完全零操作部署——坦诚说明仍需手动完成的部分：点击后，你仍然需要设置密钥（Cloudflare 无法猜出外部服务的值）——完整列表请查看此代码仓库中的 .dev.vars.example，或参阅下文的设置 Vercel 代理。必须设置 PROXY_URL／PROXY_SECRET（全部 46 个工具都需要）。

目标

提供 Binance Futures 市场持仓情况的全景概览——不只是价格，还包括谁在开仓、开什么仓（散户 vs 大户）、杠杆有多拥挤，以及流动性集中在哪些价格——让你能直接在与 Claude 的对话中获取信息，无需另行打开交易所仪表盘。

优势

• 一个入口获取多种信号。 资金费率、未平仓合约、订单簿和订单流——全部通过一个 MCP 连接器获取，无需在多个标签页之间切换。
• 区分散户与巨鲸。 binance_get_top_trader_ratio 提供纯粹的顶级交易者明细（与混合统计的 binance_get_long_short_ratio 分开）——有助于判断散户与巨鲸的持仓是否出现分歧。
• 关键数据采用 Binance 原生数据。 价格、资金费率、K 线、订单簿——全部通过 Binance 原生接口获取（非第三方推算），确保数据精确，尤其适用于小型或流动性较差的交易对。
• 个人使用免费——请参阅费用部分。

优点

• 29 个工具涵盖五种分析视角：市场方向偏向、关键价格区域（订单簿）、成交确认（订单流／主动方）、Futures 与 Spot 对比（杠杆驱动 vs 真实需求），以及全市场扫描（所有交易对中的极端资金费率，或比较多个交易对的指标）——另有复合工具（binance_analyze_pair），可快速概览而无需调用大量工具；配置和历史数据（每个交易对的阈值、基差时间序列）则存储在 Workers KV 中。
• 只读访问 Binance 市场数据——不会下单或交易。唯一会写入状态的工具（binance_set_pair_threshold）只会将你自己的阈值偏好保存到 Workers KV，完全不会接触 Binance 账户或任何外部数据。
• 坦诚说明各工具的局限性（请参阅下文），不会将所有数据包装成完美无缺的样子。
• 个人使用只需免费套餐基础设施（Cloudflare Workers + Vercel Hobby）——100% 使用 Binance 原生数据，不再依赖第三方聚合器。

缺点

• 大多数工具采用请求/响应模式。 Funding/OI/klines/order book/ratio 都是快照或定期历史数据。现有的流式数据有限： binance_get_realtime_liquidations + binance_get_contract_events（通过 VPS 流网关，见下文）——没有价格 / order book 的逐笔推送。
• Liquidation：采样数据，并不完整。 自 2026-08-28 起，提供 binance_get_realtime_liquidations——WebSocket !forceOrder@arr （dstream.binance.com）在新加坡 Oracle VPS 上持续缓冲 （stream-gateway/，位于 Cloudflare 之外——Cloudflare worker 本身仍 被 Binance 的 WAF 拦截）。Binance 将此流限制为每秒每个 symbol 最多 1 个事件，因此这是清算样本，而不是每一笔清算。它仍足以在 binance_detect_mm_activity 中确认止损狩猎集群（第 3 个代理指标， 以价格为锚点，并标注狩猎方向）。没有较早的清算历史数据（缓冲区为 24 小时）。
• 初始设置需要 Vercel 代理（必需）——并非安装即用，需要在开始时手动配置一次。
• 没有链上钱包数据，也没有 Binance Futures USDS-M 以外的交易所数据。

数据来源：单一渠道，100% Binance 原生数据。

• Binance 原生数据，通过 Vercel 中继代理获取。 Binance 域名（fapi.binance.com）在 WAF 层拦截来自 Cloudflare Workers 的流量 （403，影响整个公司——已直接从此 worker 测试验证，并非假设）。 Vercel 使用不同的 IP 池，因此不会受到相同拦截。Cloudflare worker 通过 proxy/ 中的小型代理中继请求（独立的 Vercel 项目， 见 proxy/README.md）。此渠道用于获取 funding rate（当前值和历史值）、 klines/OHLCV、多时间框架偏差、已实现波动率、24 小时统计数据、 order book 深度、aggregate trades、open interest（当前值和历史值）、 long/short ratio（综合和 top-trader）、taker 买卖量比率，以及 spot 价格（代理也会通过 market=spot 参数中继到 Binance Spot API api.binance.com，见 proxy/README.md）。

因此，此 worker 需要 PROXY_URL/PROXY_SECRET（Vercel 代理， 46 个工具均必需）——见下文的 Setup 部分。

缓存和状态，无需额外凭据。 上游响应（funding rate、klines、OI 等——order book 和 aggregate trades 除外，它们需要严格保证 数据新鲜度）会通过 Cloudflare Workers 内置的 Cache API 进行分层缓存 （根据 endpoint 不同，缓存时间为 5 秒至 1 小时），无需任何设置。 每个 pair 的自定义阈值存储在 Workers KV 中（绑定项 CONFIG_KV）。 时间序列（basis+funding+OI，以及 6 个 binance_detect_mm_activity 信号评分） 存储在 D1 中（绑定项 DB）——由 Cron Trigger 每 5 分钟自动为固定的 50 个 pair watchlist 填充（src/shared.ts 中的 SNAPSHOT_WATCHLIST， 按市值排序，例如 BTCUSDT、ETHUSDT、SOLUSDT、BNBUSDT、XRPUSDT 等）。

跨交易所对比，无需额外代理。 whalescope_compare_funding_across_exchanges 直接从 worker 访问 Bybit/OKX/Hyperliquid（已在 Cloudflare edge 实际测试，不会像 Binance 一样遭遇 WAF/地理封锁）——这 3 个交易所无需 凭据或额外设置。

提供的功能

工具	功能	来源
binance_get_funding_rate	最新资金费率 + 基差（标记价格相对于指数价格的偏差）	Binance 原生
binance_get_funding_rate_history	资金费率随时间变化的趋势	Binance 原生
binance_get_spot_price	Binance 现货价格 + 相对于期货标记价格的实际基差（不同于上面的相对于指数价格的基差）。如果交易对仅支持期货（未在现货上线），会明确报错	Binance 原生（现货）
binance_scan_funding_extremes	一次扫描所有期货交易对的资金费率（单次批量调用），返回多空拥挤程度最高的交易对	Binance 原生
binance_get_open_interest	最新未平仓合约量快照	Binance 原生
binance_get_open_interest_history	未平仓合约量增减趋势	Binance 原生
binance_get_long_short_ratio	多空综合比率（混合所有交易者）+ 趋势	Binance 原生
binance_get_top_trader_ratio	仅针对顶级交易者的多空比率（纯粹细分：按账户或持仓规模）	Binance 原生
binance_get_order_book_depth	订单簿快照（买单/卖单）、价差、最大挂单墙	Binance 原生
binance_get_order_book_imbalance	深度 5/10/20 档的买卖盘量不平衡情况，并标注偏向（看涨/看跌/平衡）	Binance 原生
binance_get_agg_trades	颗粒度精细的单笔交易（买入/卖出主动方），用于检测吸收行为	Binance 原生
binance_get_taker_volume_ratio	主动买卖压力（主动成交量），Binance 官方统计数据	Binance 原生
binance_get_klines	各时间周期的 OHLCV 蜡烛图，支持 startTime/endTime（可查询较早历史数据，用于回测，每次调用最多 1500 根蜡烛）	Binance 原生
binance_get_multi_timeframe_bias	同时计算 5 个时间周期（1m/5m/15m/1h/1d）的看涨/看跌/横盘倾向	Binance 原生
binance_get_realized_volatility	根据对数收益率计算的历史实现波动率（15m/1h），用于校准网格宽度	Binance 原生
binance_get_24hr_ticker	24 小时统计摘要（官方滚动窗口）	Binance 原生
binance_get_spot_ticker_24hr	现货版 24 小时统计数据（价格、涨跌幅、VWAP、成交量、交易笔数）——可与上面的期货版本比较	Binance 原生（现货）
binance_get_spot_book_ticker	实时现货最优买价/卖价 + 数量，比完整订单簿更轻量	Binance 原生（现货）
binance_get_spot_order_book	现货订单簿深度（买单/卖单、价差、最大挂单墙）	Binance 原生（现货）
binance_get_spot_klines	各时间周期的现货 OHLCV 蜡烛图，支持 startTime/endTime（每次调用最多 1000 根蜡烛）	Binance 原生（现货）
binance_get_spot_agg_trades	颗粒度精细的现货单笔交易（真实 CVD，而非杠杆数据）	Binance 原生（现货）
binance_get_spot_avg_price	现货移动平均价格（数分钟窗口，比最近成交价更稳定）	Binance 原生（现货）
binance_check_spot_listing	检查交易对是否已在 Binance 现货上线 + 交易状态——在调用其他现货工具前，用于确认状态不确定的交易对	Binance 原生（现货）
binance_analyze_pair	快速查看单个交易对的综合概览：资金费率、未平仓合约量趋势、顶级交易者趋势、主动成交量、订单簿、价格倾向——单次调用即可同时调用 6 个工具	Binance 原生
binance_compare_symbols	同时比较 2-10 个交易对的单项指标（资金费率、24 小时涨跌幅、未平仓合约量、顶级交易者比率、主动成交量比率），并按极端程度排序	Binance 原生
binance_set_pair_threshold	为每个交易对设置自定义资金费率/基差阈值（覆盖默认值 ±0.03%/±0.05%），保存在 Workers KV 中	Workers KV
binance_get_pair_threshold	查看某个交易对已设置的自定义阈值	Workers KV
binance_get_basis_history	基差 + 资金费率 + 未平仓合约量的时序历史数据（Cron 每 5 分钟将快照写入 D1）——固定 50 个交易对的观察列表始终可用；其他交易对则尽力提供，适用于经常查询的交易对——无需反复手动检查，即可检测“基差扩大后回归”	D1 + Cron Trigger
binance_get_orderbook_delta	获取间隔约 1-2 秒的 2 份订单簿快照，比较快照间的挂单墙，以检测真实的虚假挂单（挂单墙消失，且价格未穿越该价位）——不同于只获取单份快照的 binance_get_order_book_depth	Binance 原生
binance_detect_mm_activity	同时根据 6 项做市商/巨鲸信号计算评分 + 等级（弱/中等/强/极强）：吸收、真实双快照虚假挂单、对称止损猎杀 + 未平仓合约量下降代理指标 + 成交量集中度代理指标、基差套利、未平仓合约量背离、资金费率极端——可替代 5-6 次手动工具调用。止损猎杀仍不使用真实清算数据（已永久移除），请参阅已知限制	Binance 原生
binance_market_regime	市场状态分类：TRENDING_UP/DOWN、RANGING、BREAKOUT、ACCUMULATION、DISTRIBUTION——使用 ADX(14)、未平仓合约量趋势、CVD、波动率/成交量激增情况	Binance 原生
binance_backtest_signal	对 binance_detect_mm_activity 信号进行实证验证：根据 D1 中的历史信号（固定观察列表）计算胜率/平均收益/最大回撤；根据历史 K 线按需计算前向收益	D1 + Binance 原生
whalescope_backtest_pipeline_decisions	对保存在 pipeline_decision_log 中的 full_pipeline 决策进行前向测试（Phase 2 入场提醒 + persist=true）：按决策（TRADE/WATCH/NO_TRADE）及评分区间（lt_40 / 40_55 / gte_55）计算胜率/平均收益/触及止损的比例。前向收益根据 K 线按需计算，不使用预计算列，也不会自动调优权重	D1 + Binance 原生
binance_analyze_smart_money	根据 5 个变量计算聪明钱（顶级交易者）与散户（全局账户）的背离评分：顶级交易者比率、全局账户比率、未平仓合约量变化、资金费率、订单簿不平衡情况——输出 LONG_LIQUIDATION_RISK/BULLISH_ACCUMULATION/SHORT_SQUEEZE_RISK/NEUTRAL 状态 + confidenceScore。不同于 binance_detect_mm_activity（吸收/虚假挂单/止损猎杀/基差套利等 6 项信号）——专门关注顶级交易者与散户之间的对比	Binance 原生
whalescope_compare_funding_across_exchanges	比较 Binance/Bybit/OKX/Hyperliquid 上单个交易对的资金费率、最新价格、未平仓合约量、24 小时涨跌幅，并检测背离——用于跨交易所交叉验证做市商检测信号。唯一一个并非仅限 Binance 的工具	Binance 原生 + Bybit + OKX + Hyperliquid
binance_get_tool_catalog	所有工具的列表 + 类别/Token 成本/使用场景，支持按类别筛选——在调用大量单项工具前，先查看此列表。名称和描述自动从工具注册表获取（始终准确），类别和 Token 成本仍需手动维护	半自动
binance_get_adl_risk	按交易对评估自动减仓风险（LOW/MEDIUM/HIGH），每 30 分钟更新一次	Binance 原生
binance_get_insurance_fund_balance	按保证金资产查看保险基金余额的历史快照	Binance 原生
binance_get_mark_price_klines	MARK PRICE（清算/资金费率的参考价格）蜡烛图，而非成交价格	Binance 原生
binance_get_index_price_klines	INDEX PRICE（多个现货交易所的加权价格）蜡烛图，是溢价指数/资金费率的依据	Binance 原生
binance_get_premium_index_klines	PREMIUM INDEX（标记价格相对于指数价格的比率）蜡烛图，是资金费率的主要组成部分	Binance 原生
binance_get_continuous_klines	按底层交易对查看 PERPETUAL/CURRENT_QUARTER/NEXT_QUARTER 合约的蜡烛图	Binance 原生
binance_get_quarterly_settlement_price	季度合约交割/结算价格历史记录（不适用于永续合约）	Binance 原生
binance_get_composite_index_info	查看某个综合指数 symbol（例如 BTCDOMUSDT）的基础资产组成 + 权重	Binance 原生
binance_get_index_constituents	查看构成某个交易对指数价格的交易所、价格和权重列表	Binance 原生
whalescope_full_pipeline	完整的期货网格机器人决策链（最高级别的综合流程）：硬性筛选 → Tier-1 智能分析（聪明钱、做市商综合指标、1h+4h 市场状态、订单簿）→ 计算 Compass 等效网格边界（ATR + 波段高点/低点）→ 针对每个杠杆选项，精确计算符合亏损预算（risk_usd）的资金需求 → 输出 TRADE/WATCH/NO_TRADE 决策 + 可直接复制粘贴的网格机器人参数，支持一次处理 1-20 个 symbol。persist=true（可选）会将精简记录写入 pipeline_decision_log（source=manual 或 dropstab + persist_ref 标签页标识）。Token 成本较高——请参阅 docs/full_pipeline_framework.md	Binance 原生

detail 约定：summary 与 full（节省 token）

以上所有返回数组/历史数据的工具（klines、agg trades、 order book、open interest/funding/basis history、long-short & top-trader ratio）都有可选参数 detail: "summary" | "full"， 默认值为 "summary"。这是 2026-08 token 效率更新中唯一有意更改的默认行为——不是删除参数，只是更改了默认值：

• detail: "summary"（默认值）——仅返回衍生指标（偏向、趋势、CVD、 dominance 等，即工具本身已经计算的指标）+ 最多 10 个最新数据点。 如果你完全不发送 detail，就会使用此模式，包括尚不知道此参数存在的旧版调用方。
• detail: "full" ——返回完整的原始数组/层级，行为与本次更新前相同。

复合工具（binance_analyze_pair、binance_analyze_smart_money、 binance_detect_mm_activity、analyze_futures_grid_risk、 whalescope_full_pipeline）也进行了精简：文本缩短约 8-12 行， structuredContent 成为主要载荷，使用更短、更扁平的键，并移除 空字段（null/undefined）。没有任何信号/指标被删除—— 都仍可通过 structuredContent 或 detail: "full" 获取。

完整详情及重命名字段的映射： docs/tool_response_reference.md。

分析框架：做市商与鲸鱼检测

没有任何工具能直接查看做市商（MM）/鲸鱼的身份或具体仓位—— Binance 的公开数据确实不提供这些信息。可以做的是（这正是此框架的 用途）：结合使用以上多个工具来读取他们的活动痕迹，然后根据 出现的模式计算指示性评分。

检测的四类信号：

信号	主要工具	模式示例
吸收	order book depth、agg trades（futures & spot）、open interest	CVD 持平/上升但价格停滞 = 卖压正在被吸收（累积）；OI 急剧飙升 + 价格横盘 = 新开立了大额仓位
虚假挂单	order book depth、binance_get_orderbook_delta（2-snapshot）	大额挂单出现后，在有机会成交之前便消失，且价格实际上并未穿越该价位；价差突然扩大，随后在几秒内恢复正常
猎杀止损	open interest、agg trades、klines	长影线（任一方向）+ 反转蜡烛图的实体较小，并结合 OI 下跌代理指标 + 按价格统计的激进交易集中度——仍没有真实强平确认（已永久移除，见「不足之处」）
基差套利	spot price、funding rate、open interest	现货-期货基差扩大后迅速回归；资金费率极端 + OI 上升（表明可能在对冲：做空期货 / 做多现货）

经验法则：如果同一时间范围内≥3 个信号一致，则做市商活动的 指示性相当强，值得进一步调查——这是一种启发式检查清单（详见完整文档中的置信度等级），并非经过统计校准的概率。

完整文档：docs/mm_detection_framework.md （v4，最终版）——包含各信号的详细标准、逐步工作流、 实时检查清单，以及工具 → 信号映射。

框架：网格机器人完整流水线（whalescope_full_pipeline）

这是此代码库中层级最高的复合工具——通过一次工具调用执行 网格机器人期货决策链的全部步骤，可同时处理一个或多个交易对 （每次调用最多 20 个），取代约 8 次手动工具调用 （binance_market_regime ×2、binance_analyze_smart_money、 binance_detect_mm_activity、binance_get_order_book_imbalance、 analyze_futures_grid_risk 等），还包括此前完全没有工具支持的网格边界计算。

阶段（2-wave 获取，尽早拒绝）：

┌───────────────────────────────────────────────────────────────┐
│ WAVE 1 (semua symbol, paralel): ticker24hr, funding, klines    │
│ 1h+4h, OI+histori, agg trades, market context                  │
├───────────────────────────────────────────────────────────────┤
│ HARD SCREEN: tradable? volume >= minimum? |funding| <= maks?   │
│ regime 1h/4h != BREAKOUT?                                       │
│   → GAGAL = NO_TRADE, Wave 2 TIDAK PERNAH DIPANGGIL             │
├───────────────────────────────────────────────────────────────┤
│ WAVE 2 (survivor saja, paralel): top-trader ratio, global      │
│ account ratio, OI histori 24 titik, order book depth 50        │
├───────────────────────────────────────────────────────────────┤
│ TIER-1 SCORING: smart money divergence + 6 skor MM composite   │
│ + order book imbalance + CVD + regime → rankingScore 0-100     │
├───────────────────────────────────────────────────────────────┤
│ GRID BOUNDS (Compass-equivalent): ATR + swing high/low →       │
│ upper/lower/SL/TP/gridCount/gridType                            │
├───────────────────────────────────────────────────────────────┤
│ CAPITAL SOLVE: exact (bukan iteratif) per opsi leverage, pilih  │
│ leverage tertinggi SAFE/MODERATE dengan likuidasi aman          │
├───────────────────────────────────────────────────────────────┤
│ KEPUTUSAN: TRADE / WATCH / NO_TRADE + Grid Bot config siap-pakai│
└───────────────────────────────────────────────────────────────┘

完整文档（逐阶段说明、完整示例、已知限制）： docs/full_pipeline_framework.md。

实证验证结果

该框架中的每项技术声明在纳入最终版本前，都会直接在已部署的 worker 上验证 （而非基于假设）。以下是一些修正了初始假设的发现：

初始声明	验证结果
轮询间隔 <500ms 可检测刷新率欺骗	❌ 经由 worker→Vercel→Binance 代理链路，每次调用的实际延迟为 298-898ms（平均约 485ms）——不适用于此用途
顶级交易员比例偏离的通用阈值（固定 >15% 或分级 3-15%）	❌ 从未触发——在 2 小时窗口内测试的 4 个交易对（SOLUSDT、BNBUSDT、LINKUSDT、AVAXUSDT）的实际波动仅为 0.40-2.35 个百分点，远低于任何阈值
顶级交易员比例的历史保留期为“30-90 天”	⚠️ 已修正——Binance 完全不提供 90 天的数据；30 天数据仅提供粗略分辨率（4h/1d），15 分钟分辨率的数据只能追溯约 5 天
市场平静时（BTCUSDT）不会过度触发	✅ 已确认——市场横盘时得分约为 1-1.5/6（Weak 等级），该框架在正常情况下不会误报

完整详情（包括每项声明的原始测试数据）：第 10 节， docs/mm_detection_framework.md。

需要如实了解的局限性

• 多空比率（binance_get_long_short_ratio）是混合的汇总比率，并非单独区分“全局账户（散户）”与“顶级交易者（巨鲸）”。如需获取纯粹的顶级交易者细分数据，请使用 binance_get_top_trader_ratio（该工具直接来自 Binance，与此工具分开）。
• 小型或新上线交易对的资金费率基差可能有噪声——Binance 指数价格是多个现货交易所的加权平均值，其中某个交易所对这类交易对而言可能流动性不足。
• 订单簿深度（binance_get_order_book_depth）是瞬时快照——大额挂单墙可能在几秒内消失（可能存在欺骗性挂单），不要过度解读单个快照。如需检测真实的欺骗性挂单（双快照），请使用 binance_get_orderbook_delta 或 binance_detect_mm_activity（见下文）。
• Binance 不会准确公开“顶级交易者”的阈值，且数据是定期快照，并非逐笔实时数据。
• OI 历史数据（binance_get_open_interest_history）受 Binance 官方接口（/futures/data/openInterestHist）的保留期限限制，如需较长时间范围，请直接查询。
• 没有链上钱包数据。
• 清算数据仅近实时且为采样数据，没有长期历史记录。binance_get_realtime_liquidations 会读取 VPS 流网关中 24 小时的缓冲数据（通过 dstream.binance.com 订阅 !forceOrder@arr——fstream.binance.com 被 VPS IP 黑洞处理）。Binance 每秒每个交易对最多推送 1 条事件，因此这是采样数据，并不完整。没有面向全市场的公开 REST 接口可用于回填历史数据。Cloudflare Worker 本身仍无法直接通过 WS 连接 Binance（WAF）。
• binance_detect_mm_activity：欺骗性挂单检测现在使用真实的双快照（因此比其他工具慢约 1–2 秒，两个快照之间会显式等待 1500ms——见 binance_get_orderbook_delta），不再使用单快照启发式方法。猎杀止损检测现在是对称的（检查上影线和下影线，之前只检查上影线——旧 bug），并增加了 2 个独立代理指标（复用已有数据，不会新增请求）：OI 在蜡烛图出现影线时同时下降 >=2%，和/或激进交易量有 >=30% 集中在该影线的价格区域（取自最近 100 笔 aggTrades，与 CVD 使用的数据相同）。置信度逐级提高：无代理指标生效 = 基础置信度，1 个代理指标 = 较高，2 个代理指标同时生效 = 最高——仍不包含真实的按价格统计的清算数据（这是永久限制，见上文）。此工具中的猎杀止损置信度仍低于其他信号——每个响应的证据文本中都会注明。
• binance_market_regime：波动率/成交量激增是相对于同一抓取窗口计算的（最近 10 根蜡烛与之前 10 根相比），并非相对于长期历史基线。
• D1 时间序列（market_snapshots，由 binance_get_basis_history 读取）始终适用于固定的 50 个观察列表交易对，对其他交易对则尽力提供——非观察列表交易对仅在约 24 小时内被查询 >=3 次，且进入查询频率最高的前 5 个非观察列表交易对时，才会有历史数据（KV 计数器，src/queryFrequency.ts）；满足条件后，5 分钟一次的 cron 才会为该交易对创建快照。signal_history（由 binance_backtest_signal 读取）仍仅适用于观察列表，不会扩展。
• **仅在期货市场上市的交易对（HYPEUSDT、1000PEPEUSDT、PUMPUSDT 等）——由于未在 Binance Spot 上市，market_snapshots 中的 spot_price 和 basis 为 NULL。**资金费率和 Open Interest 仍会正常记录；这类交易对只有 basis 列为空。
• D1 行目前没有清理/保留机制——行数会随时间不断增加（50 个交易对 x 每天约 6,048 行，两个表合计；D1 免费层级每天 500 万次写入和 5GB 存储在很长一段时间内仍有余量，但这并非永久解决方案）。
• KV→D1 迁移（basis 历史）不会回填旧数据——迁移前存储在 Workers KV 中的 basis 历史记录已丢失；部署几小时后，24 小时窗口才会自然重新填满。
• binance_backtest_signal：前向收益率按需通过历史 klines 计算（取最接近目标时间的 1h 蜡烛收盘价），并非真实订单执行模拟——不会计算滑点/手续费/部分成交。样本量较小（少于约 20 个信号）意味着置信度较低，不要根据少量历史数据就断定信号“可靠”（数据只会从此功能部署后开始积累，不会追溯补齐）。
• pipeline_decision_log + whalescope_backtest_pipeline_decisions：Phase 2 入场提醒的每个交易对决策（以及 persist=true）会以精简格式保存 90 天。前向收益率/止损触及情况按需通过 klines 计算——不是预先计算的，也不会自动调优 35/30/20/15 权重或 55 阈值。entry_alert_skip_log 的保留期为 30 天。
• whalescope_compare_funding_across_exchanges：Open Interest 尚未与 4 个交易所的实时数据交叉验证（所有交易所都应该使用基础资产计价，包括使用 oiCcy 字段的 OKX，但尚未直接检查——如果数值看起来不对，请重新核对）。Binance 到其他交易所的交易对映射尽力而为（去掉 USDT 后缀）——未在 Bybit/OKX/Hyperliquid 上市的小型交易对会在对应行显示“失败”，不会导致整个工具调用失败。
• 针对 Binance 代理的速率限制自节流只是尽力而为，并非硬性全局限制——使用每个 isolate 的内存计数器（src/rateLimiter.ts），在连续请求复用同一 isolate 时有效，但此 Worker 按请求无状态运行，因此无法保证跨 isolate 的严格限制。阈值为每分钟 200 次请求，按请求数量计数（并非像 Binance 原始限制那样按端点权重计数）。
• binance_get_tool_catalog 是半自动的——名称和描述始终准确（从工具注册表提取，不会过时）。但类别、token 成本和依赖项仍需手动维护（src/tools/catalog.ts 中的 CATALOG_METADATA）——尚未整理的新工具会显示为 category "uncategorized"，不会被静默省略，但尚未妥善分类。
• binance_analyze_smart_money 使用固定阈值（不是基于每个交易对的统计校准结果）——关于为何应谨慎使用顶级交易者比率的绝对阈值，请参见 docs/mm_detection_framework.md 中的 Section 4.2 和 12。其输出中的 confidenceScore 衡量的是高于阈值的幅度，不是经过校准的统计概率。

设置 Proxy Vercel（必需，仅需设置一次）

上表中标记为“Binance 原生”的工具需要通过 Vercel 中继代理， 因为 Binance 的 WAF 会直接拦截 Cloudflare worker。代理部署详情 见 proxy/README.md，简要步骤如下：

1. 将 proxy/ 文件夹部署为单独的 Vercel 项目（Root Directory = proxy），在 Vercel 中设置环境变量 PROXY_SECRET（自行生成 随机字符串，例如 openssl rand -hex 32）。
2. 在 Cloudflare worker 中设置以下两个密钥：

   npx wrangler secret put PROXY_URL
   npx wrangler secret put PROXY_SECRET
   

   PROXY_URL = Vercel 项目 URL（例如 https://whale-pearl.vercel.app）， PROXY_SECRET = 与 Vercel 中设置的值完全相同的字符串。

如果未设置这两个密钥，标记为“Binance 原生”的工具就会失败，并显示 明确的错误消息（“worker 中尚未设置 PROXY_URL 或 PROXY_SECRET”）。

重要：绝不要将密钥的 VALUE 设为 NAME（例如运行 wrangler secret put 后， 不小心在名称提示中粘贴了值）。wrangler secret list 只会泄露密钥名称， 绝不会泄露值——这种错误会导致真实值通过本应安全的命令泄露。

次级代理／故障转移（可选）

如果主代理遭遇 WAF 拦截、速率限制或 5xx 错误，worker 会自动尝试 次级代理——但前提是已进行配置。未配置时，行为与之前完全相同（仅使用 1 个代理，失败时直接抛出错误）。

1. 使用同一个 proxy/ 文件夹部署第二个 Vercel 实例（可选择不同区域， 例如 Hong Kong 和 Singapore），并设置自己的 PROXY_SECRET （可以与主代理不同）。
2. 设置以下两个额外的密钥：

   npx wrangler secret put PROXY_URL_2
   npx wrangler secret put PROXY_SECRET_2
   

只有与 tier 健康状态／凭据相关的错误（401 密钥错误、403 WAF 拦截、 429 速率限制、5xx）才会触发故障转移——请求本身的错误（400 symbol 错误、 404）不会触发，因为这些错误在任何 tier 上都会以相同方式失败。故意将 401 纳入其中（与之前版本不同），因为每个代理 tier 都有自己的密钥—— 主代理密钥错误不代表次级代理的密钥也错误。

直接回退（最后一层，默认自动启用）

如果主代理和次级代理（若已配置）都失败，worker 会自动直接请求 fapi.binance.com／api.binance.com，完全不使用代理，作为最后的补救措施。 无需进行任何设置（默认启用）——如果要关闭，请在 worker 的环境变量中设置 DISABLE_DIRECT_FALLBACK=true（不是密钥，而是普通变量）。详情请参阅 src/binanceProxyClient.ts 中的“DIRECT FALLBACK”注释，以及关于为何在当前 生产环境下这一层可能仍会遭遇 WAF 拦截的说明（Binance 已证实会直接拦截 此 Cloudflare worker）——不过，在本地运行 wrangler dev 时仍然有用 （IP 池与生产环境的 Cloudflare 边缘节点不同），也可作为防护措施，以应对 拦截策略发生变化的情况。

设置 Workers KV（必需，仅需设置一次——仅当自行 fork／部署此仓库时）

此仓库 wrangler.toml 中的 KV namespace id 与创建它的 Cloudflare 账户绑定——如果你 fork／clone 并部署到自己的账户，必须创建新的 namespace：

npx wrangler kv namespace create WHALESCOPE_CONFIG

将生成的 id 复制到 wrangler.toml 中的 [[kv_namespaces]]，替换旧的 id 值（保留原有的 binding，即 CONFIG_KV；worker 代码引用的是该 binding 名称，而不是 id）。如果未执行此操作，binance_set_pair_threshold 和 binance_get_pair_threshold 就会失败，并显示明确的错误（“worker 中尚未绑定 CONFIG_KV”）。

设置 Workers D1（必需，仅需一次——如果你要自行 Fork/部署此仓库）

与上面的 KV 一样，此仓库 wrangler.toml 中的 database_id 绑定到创建它的 Cloudflare 账户。如果要 Fork/部署到自己的账户：

npx wrangler d1 create whalescope-mcp-db

将显示的 database_id 复制到 wrangler.toml 的 [[d1_databases]] 中（保持 binding 为 DB），然后运行 migration：

npx wrangler d1 migrations apply whalescope-mcp-db --remote

否则，binance_get_basis_history 和 binance_backtest_signal 会明确报错（“D1 数据库（binding DB）尚未绑定到 worker”），而每 5 分钟运行一次的 Cron Trigger basis+MM 信号快照会在每个 tick 静默失败（记录到 Workers Logs，不会导致其他 /mcp endpoint 失败）。

管理员：使用日志（可选）

公开 Worker 很容易被找到（已列入 MCP Server Registry）——因此提供了一个小型 endpoint，用于查看有哪些用户连接。这不是 MCP 工具（特意设为独立的 HTTP endpoint，绝不会出现在 tools/list 中）——如果将其做成普通工具，任何连接到此服务的人都能查看其他访客的 IP，这与其目的相矛盾。

1. 设置 secret（未设置时，endpoint 始终返回 403——此功能默认禁用，安全）：

   npx wrangler secret put ADMIN_SECRET
   

2. 访问：

   curl "https://<worker-url>/admin/usage?key=<ADMIN_SECRET>&hours=24"
   

   返回 JSON：请求总数、唯一 IP 数量、排名前 20 的 IP（+ 国家、计数）、最近 20 条原始请求。默认时间窗口为 24 小时，可通过 hours 更改。

监控与告警

此后端有几个可能静默失败的环节（Vercel/VPS 代理停机、WS stream gateway 断开、Cron Trigger 被平台取消）。目前，所有告警都通过 Telegram 发送（需要设置 TELEGRAM_BOT_TOKEN + TELEGRAM_CHAT_ID——否则告警只会记录到 Workers Logs）：

检查	Cron	告警条件
checkHeartbeat（heartbeatCron.ts）	每天 3 次（07/15/23 WIB）	连续 8 小时没有 TRADE/WATCH 信号——发送一条消息，区分“市场平静 + 后端正常”、“每个 tick 有 >30% 的交易对失败 = 后端异常”和“没有数据 = cron 已停止”
checkEntryAlertCronFreshness（heartbeatCron.ts）	挂载在 */5 上	40 分钟内没有已完成的 entry-alert tick（检测被平台取消的 tick）——冷却 1 小时
checkStreamGatewayHealth（infraHealthCron.ts）	挂载在 */5 上	VPS stream gateway :8081/health 无法访问、与 Binance 的 WS 断开，或缓冲区过期超过 5 分钟——冷却 1 小时
checkMarketSnapshotFreshness（infraHealthCron.ts）	挂载在 */5 上	20 分钟内没有新的 market_snapshots 行（*/5 快照 cron 停止写入）——冷却 1 小时
checkD1Capacity（infraHealthCron.ts）	每天 3 次（随 HEARTBEAT_CRON 一起运行）	market_snapshots + signal_history（两个未做 pruning 的表）合计超过 500 万行——冷却 24 小时

所有检查都由 KV 控制（条件持续期间，每个冷却周期最多发送 1 次告警），可以安全地每 5 分钟运行一次。

仍未实现的内容（需要配置 dashboard，而非编写代码）：

• 外部 uptime monitor，用于监控 worker / + relay https://<vps>/health——使用 UptimeRobot / Cloudflare Health Checks（免费，5 分钟间隔）。这是最快发现 VPS/relay 完全停机的方式；上述内部检查仅作为有延迟的后备措施。
• Cloudflare 通知，用于 Workers 错误率飙升 / CPU 限制——observability（[observability] enabled = true）只会收集数据，不会配置告警规则。

安全性：DNS Rebinding 防护（可选）

Endpoint /mcp 会在处理请求前验证 Origin 标头 -- 默认允许 https://claude.ai/https://claude.com（以及完全不带 Origin 标头的请求，这涵盖了大多数 MCP 客户端到服务端的请求， 包括将此 worker 用作自定义连接器的方式）。不允许的其他 Origin 请求会收到 403 响应。这取代了 SDK 内置选项（enableDnsRebindingProtection/ allowedHosts/allowedOrigins），这些选项已在 @modelcontextprotocol/sdk 中标记为 @deprecated -- SDK 现在建议使用 外部中间件，本项目正是这样做的。

如果你有自己的 Web 应用，需要从浏览器直接调用 /mcp，请添加其来源：

npx wrangler secret put ALLOWED_ORIGINS
# contoh value: https://app-kamu.com,https://staging.app-kamu.com

（以逗号分隔，逗号后不加空格也可以 -- 会自动去除空格。）

数据存储在 D1（request_log）中，每次 Cron 运行时都会自动清理超过 30 天的记录（此表不像 market_snapshots/signal_history 那样受固定 观察列表限制，因此如果确实有外部流量，可能会持续增长）。

自动部署设置（GitHub Actions → Cloudflare Workers）

此仓库已有 .github/workflows/deploy.yml 中的工作流，每当有推送到 main 分支时，都会自动运行 wrangler deploy。

设置步骤（仅需一次）

1. 创建 Cloudflare API Token

1. 打开 https://dash.cloudflare.com/profile/api-tokens
2. 点击 "Create Token"
3. 使用 "Edit Cloudflare Workers" 模板
4. 将范围设为你的账户，然后创建 Token
5. 复制显示的 Token（只会显示一次）

2. 将 Token 添加为 GitHub Secret

1. 在 GitHub 上打开此仓库 → Settings → Secrets and variables → Actions
2. 点击 New repository secret
3. Name：CLOUDFLARE_API_TOKEN
4. Value：步骤 1 中的 Token
5. 保存

3. 触发部署

有新推送到 main 后，部署就会自动运行。若要在没有新推送的情况下 手动触发，请打开 GitHub 仓库中的 Actions 选项卡 → 选择工作流 "Deploy to Cloudflare Workers" → Run workflow。

4. 检查部署结果

工作流完成后（查看 Actions 选项卡），worker 将在以下地址上线：

https://whalescope-mcp.<subdomain-cloudflare-kamu>.workers.dev

打开该 URL — 应该会显示状态为 "ok" 的 JSON。

设置自定义域名（whalescope-mcp.jaringan.dev）

这无法通过 GitHub Actions 完成 — 需要在 Cloudflare 控制面板中手动 操作一次：

1. 打开 https://dash.cloudflare.com → 选择你的账户
2. 打开 Workers & Pages → 选择 worker whalescope-mcp
3. 打开 Settings → Domains & Routes 选项卡
4. 点击 Add → Custom Domain
5. 输入 whalescope-mcp.jaringan.dev
6. 如果域名 jaringan.dev 已位于同一 Cloudflare 账户的区域中， Cloudflare 会自动创建所需的 DNS 记录。如果该域名注册在其他账户/ 注册商，你需要手动添加 CNAME 记录，并将其指向 Cloudflare 显示的目标。

自定义域名启用后，就可以通过 https://whalescope-mcp.jaringan.dev（而不再是 .workers.dev 域名）访问 worker。

在 Claude 中注册为自定义连接器

1. 打开 Claude（claude.ai）→ Settings → Connectors
2. 选择 Add custom connector
3. 输入 URL：https://whalescope-mcp.jaringan.dev/mcp （如果尚未设置自定义域名，则使用 https://whalescope-mcp.<subdomain>.workers.dev/mcp — 注意末尾必须带上 /mcp 路径）
4. 保存，然后为所需的对话启用该连接器

使用示例

Connector 激活后，只需通过普通对话提出请求即可——Claude 会根据问题 决定调用哪个工具（以及调用几次）：

• “现在 BTCUSDT 的资金费率怎么样，有拥挤迹象吗？” → binance_get_funding_rate
• “现在整个市场中，资金费率最极端的交易对是什么？” → binance_scan_funding_extremes
• “全面检查 ETHUSDT 概况——资金费率、OI、订单簿、价格偏向” → binance_analyze_pair（复合工具，1 次调用替代 6 个独立工具）
• “最近 SOLUSDT 有做市商活动的迹象吗？” → 组合使用多个工具（订单簿、agg trades、OI、klines）， 按照上文的分析框架 进行分析——只需说出交易对，Claude 就会运行检测工作流
• “比较 BTC、ETH、SOL 和 BNB 的资金费率” → binance_compare_symbols
• “现在在 BTCUSDT 和 ETHUSDT 上开 Futures Grid Bot 值得吗？亏损预算 为 $20？” → whalescope_full_pipeline（最高级别的复合工具，1 次调用 即可运行硬性筛选 → Tier-1 情报 → 网格边界 → 风险规模计算 → TRADE/WATCH/NO_TRADE 决策 + 可直接复制粘贴的 Grid Bot 参数， 同时适用于两个交易对）

由于所有工具都只有读取权限，可以放心询问任何市场数据，不必担心触发 下单或交易——这个 Worker 完全不具备此类能力。

向 Claude 注册前手动测试（建议）

npm test（vitest）+ npm run typecheck 是此仓库中的自动化检查 ——但它们仅覆盖纯逻辑（评分函数、D1/KV 封装、通过伪造的 McpServer 测试工具处理程序），不包括真实的 Workers fetch/ scheduled 处理程序（没有 @cloudflare/vitest-pool-workers）。 验证新增或更改的工具仍然需要通过 wrangler dev + curl JSON-RPC 手动完成。

npm install
npx wrangler dev

在另一个终端中，以下是 Binance 原生工具的示例：

curl -X POST http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "binance_get_funding_rate",
      "arguments": { "symbol": "BTCUSDT" }
    }
  }'

如果这能返回有效的 BTCUSDT 资金费率和基差数据，则说明 Vercel 代理路径正常工作。

审计与结果

令牌效率

MCP 工具响应会直接进入 Claude 的上下文窗口——这与普通 REST API 不同，后者的响应大小相对来说“免费”。本仓库曾有几个工具在无意中消耗了大量令牌；现已修复，并在运行中的 worker 上完成验证（2026-08-12）：

发现的问题	修复前	修复后
binance_get_klines/spot_klines — structuredContent.candles 总是附带完整数组	limit=500 时约 14,400 个令牌（57.7KB），在最大 limit=1500 时最多约 43,000 个令牌	通过参数 includeCandles 选择启用（默认 false）——默认只返回摘要（趋势、波段高点/低点、最近 15 根 K 线）
6 个历史数据工具（OI 历史、long/short ratio、top trader ratio、funding rate 历史、taker volume ratio、liquidation 历史）——文本表格的行数不受限制	limit=500 时每次调用 20-29KB（约 5,000-7,250 个令牌）	文本中截断为最近 15 行——摘要（均值/趋势/占比）仍基于已获取的全部数据计算，而非仅基于展示的数据
最长的 5 个工具描述（funding_rate、top_trader_ratio、spot_price、klines、spot_klines）	总计 16,869 个字符	15,671 个字符（约减少 7%，每个会话一次性加载工具列表时节省约 300 个令牌）
binance_scan_funding_extremes — structuredContent.crowdedLong/crowdedShort 重复了文本表格中已有的数组	limit=50 时约 2.9KB（最大值）	仅保留 topSymbolLong/topSymbolShort（每一侧最极端的 1 个交易对）——完整表格仍保留在文本中

随时重新验证：

npm run token-audit

直接调用已部署的 worker，测量工具架构大小、不同 limit 下的响应大小，以及若干代表性工具的“信息密度比”（数据与模板文字之比），并模拟一次真实的多轮对话。这不属于 npm test/CI 的一部分（因为会调用运行中的 worker）——可在需要检查工具描述/响应格式变更对令牌消耗的影响时手动使用。令牌估算采用 chars/4 的启发式算法（Claude 没有以 package 形式发布官方 tokenizer），因此数值是近似值，适用于相对比较（变更前与变更后），而非精确的令牌数量。

安全性

• 验证交易对符号输入。 symbolSchema（所有需要 symbol 参数的工具都会使用）限制为最多 20 个字符，且只接受 [A-Z0-9_]。此前没有限制——由于符号会直接用作 Workers KV 键的一部分（threshold:${symbol}、 basis_history:${symbol}），长度或字符不受限制的输入可能会超出 KV 键 512 字节的上限，或插入字符（冒号、换行符）扰乱键的构造。20 个字符的上限经过真实数据验证（目前 Binance Futures 中最长的符号为 17 个字符），正则表达式也特意允许下划线，以便带日期/季度的合约（例如 BTCUSDT_260925）仍然有效。
• 仅可读取账户。 没有工具会下单/交易或访问个人账户数据——唯一会写入状态的工具（binance_set_pair_threshold）也只会将阈值偏好存储在 worker 自己的 Workers KV 中。
• 凭据始终通过 Wrangler secret 设置，绝不会硬编码或写入 wrangler.toml/git——安全设置 secret 的方法请参见设置 Vercel 代理（仅需一次）中的明确警告。
• 已手动扫描本仓库，确认没有提交任何真实 API 密钥、secret 或凭据——仅包含占位符/示例（例如设置文档中的代理 URL whale-pearl.vercel.app 只是示例名称，并非真实端点）。

费用

• Cloudflare Workers：免费层每天提供 100.000 次请求——对于个人交易分析用途来说绰绰有余。
• Vercel（代理中继）：免费层 Hobby 计划为无服务器函数提供每月数百万次调用——个人使用不会产生费用。 请注意：必须对 PROXY_SECRET 保密，因为任何知道 URL + secret 的人都可以代表你使用此代理额度。

个人使用时，你很可能永远不会在这两个平台上产生费用。

免责声明

本项目是开源且公开的——任何人都可以通过此 GitHub 仓库查看、克隆和修改源代码、架构及文档（包括 docs/ 中的分析框架）。不会存储或处理任何个人账户数据——所有工具都以只读方式访问 Binance 公共 API。

• 这不是财务建议。 所有数据和解读（资金费率、OI、订单簿、MM 检测框架等）仅供参考——它们是对公开数据的处理结果，绝非交易建议。数据的准确性、完整性或时效性均不作保证——根据这些数据做出决定前，请查看需要了解的诚实限制，了解各工具的具体限制。
• 用户责任。 任何部署、使用或修改此 Worker 的人，都必须对自身使用所产生的结果和后果承担全部责任——包括基于这些工具输出所做出的交易决策。
• 遵守 Binance API 使用条款。 此 Worker 会调用 Binance 公共端点（Futures 和 Spot）。个人／非商业用途符合 Binance 的一般适用条款；商业性地重新分发数据或大规模使用前，建议先查阅 Binance API 使用条款——相关责任不由本项目承担。
• 许可证：MIT。 允许使用、修改和重新分发（包括用于商业用途），但须保留版权声明和 MIT 许可证。软件按“原样”提供，不作任何保证——与上述免责声明一致。