ClassyGitdnevend

spec.md

spec.md

lead-trade-radar — 数据口径与行为规范

本文件是行为唯一来源。代码注释里的 §x 指这里的章节。改动口径先改这里,再改代码和测试。


§1 目标与边界

监控币安「合约带单」的带单员,把他的每一笔已成交委托整理成一条 Telegram 消息,供人手动跟单。

  • 不下单、不持有交易 API Key、不计算建议仓位。
  • 只读币安公开的站内接口,无需登录。
  • 单人先跑通,配置结构从一开始就支持多人。

§2 数据源

币安没有公开的带单员 API,只有网页/App 调用的站内接口(BAPI)。实测(2026-11-14):

能力 端点 说明
订单历史 POST /bapi/futures/v1/friendly/future/copy-trade/lead-portfolio/order-history 主数据源,已成交委托,一笔一行
已平仓位 POST .../lead-portfolio/position-history 含开/平时间、均价、盈亏、杠杆、ROI
资金划转 POST .../lead-portfolio/transfer-history 入金/出金
带单员详情 GET .../lead-portfolio/detail?portfolioId= 昵称、状态、保证金余额、是否公开持仓
X 推文 GET https://api.fxtwitter.com/2/profile/<handle>/statuses 第三方公开镜像,无需鉴权;仅在配置 xHandle 时使用

风险与对策:

  1. 命名空间会轮换。public 下的 order-history 已失效(返回非标准响应),friendly 可用。适配器按候选列表依次尝试,只有 404/202 才换下一个。
  2. 字段会变。所有响应过 zod 校验,缺字段抛 SchemaChangedError,不会把缺失值当 0。
  3. 没有 SLA。每轮独立失败,失败不推进游标,下一轮重拉同一窗口。
  4. 请求头必须带 clienttype: web、origin、referer(带 portfolioId)和浏览器 UA,否则被判非法请求。
  5. 需要代理(国内 DNS 污染),Node 用 NODE_USE_ENV_PROXY=1 + HTTPS_PROXY。
  6. X 官方接口需要登录态、查询 ID 会轮换,推文改走公开镜像 fxtwitter。它是第三方服务,没有 SLA; 拉取失败只记日志并保留待补标记,不影响交易信号。

§2.1 订单字段

order-history 每条:symbol、side(BUY/SELL)、positionSide(LONG/SHORT/BOTH)、executedQty、avgPrice、totalPnl、orderTime、orderUpdateTime。没有 orderId。

  • orderTime:下单时间,同一委托稳定。
  • orderUpdateTime:最后成交时间,用于增量窗口与排序。
  • 时间戳单位毫秒(UTC)。

§3 订单分类

双向持仓(positionSide 为 LONG/SHORT):

  • BUY + LONG / SELL + SHORT = 加仓方向;SELL + LONG / BUY + SHORT = 减仓方向。
  • 方向取 positionSide。

单向持仓(positionSide = BOTH):只能靠 totalPnl 区分:

  • totalPnl = 0 → 按 side 开仓(BUY 开多,SELL 开空)。
  • totalPnl ≠ 0 → 反向平仓(BUY 平空,SELL 平多)。

开/加/减/平由账本前后持仓决定:加仓方向且下单前为 0 → 开仓;否则加仓;减仓方向且下单后为 0 → 平仓;否则减仓。账本未知时,加仓一律记为「加仓」,不谎称开仓。

§4 推定持仓账本

带单员可能隐藏持仓(positionShow=false),持仓表返回空。本系统用订单流重建:

  • 每个 (symbol, direction) 一个账本。
  • 锚点 = position-history 里该组合最近一次平仓的 closed 时间;此时净持仓必为 0。
  • 只累计 orderUpdateTime > 锚点 的订单:加仓 +qty,减仓 -qty。
  • 减仓量超过账本累计 → 说明启动前已有存量仓(或漏过一笔减仓),标记 unknownBaseline,不再报告绝对持仓; 若这条减仓订单与平仓记录几乎同刻(±2s),按全平收尾处理,直接归零。
  • 本轮均价 = 自上次归零以来所有加仓的成交量加权均价。
  • 账本记录 lastOrderAt(已应用的最新订单时间)和 lastIncreaseAt(最近加仓时间)。 每轮先应用订单、再用平仓记录校准:校准条件是该记录比上次锚点新、不早于 lastOrderAt、 且不早于 lastIncreaseAt。这样同一轮的平仓订单不会被锚点提前抹掉,漏单造成的漂移能被同轮记录拉回 0, 同一毫秒平仓后反手开的新仓也不会被清零;反手订单晚一轮到达时,因为时间戳恰好等于锚点, 按加仓处理照常入账。

边界:账本是推定值,不是交易所权威数据。启动时若带单员有存量仓且锚点缺失,第一条消息只报单笔方向,不报总量。

§5 增量、去重与补量

  • 轮询间隔默认 60 秒(低于 30 秒配置直接拒绝;站内接口容易触发 WAF)。
  • 每轮窗口:[lastSeen - 120s, now]。重叠 2 分钟,防止边界漏单。
  • lastSeen 只在整轮成功后推进;失败则下一轮重拉。
  • 委托身份:接口没有 orderId,symbol|side|positionSide|orderTime 只是「可能是同一委托」的归组键, 不能用来去重——实测同一毫秒会有 3 笔独立委托(ETH 平仓),按 4 字段去重会吃掉真实订单。 真正的幂等键是完整指纹:归组键|executedQty|avgPrice。
  • 补量:每笔委托保存一份当前快照(数量/均价/盈亏)。某归组键在后续轮询中出现 「组大小不变 + 只有一笔新快照 + 只有一笔旧快照消失」时,判定为同一委托补量,只把差额计入账本、只推送差额; 组变大说明来了新的同毫秒委托,该笔全额计入。
  • 升级前已入库、但没有快照的订单会在下一轮补齐,不会被误判成补量。
  • 已入库的订单永不重推;进程重启不补发历史。
  • 发送失败留在 outbox,下一轮补发;发送成功但落库失败可能重复一次(至少一次语义)。
  • Telegram 4xx(chat_id 错、被踢、文本超长)是永久失败:标记 sent_at = -1 跳过,不堵住队列。

§6 信号

每笔订单一条信号,字段:

字段 来源
交易员昵称 配置 label
动作 §3
方向 §3
成交量 / 均价 订单
名义额 executedQty × avgPrice
保证金占比 名义额 / detail.marginBalance
推定持仓 §4,未知时不显示
平仓盈亏 订单 totalPnl
杠杆 / ROI / 持有时间 同 symbol + direction 且在 ±120 秒内匹配到的 position-history 记录
现价 fapi/v1/ticker/price;只用于下一条
加仓前浮盈亏 现价相对「下单前本轮均价」的变动;多空统一成“赚为正”
摊平标记 加仓且加仓前浮动 ≤ -5%
流动性 按订单方向取对手盘,累计 0.1% 价格带内的名义;本单占比 <10% 好、<50% 一般、≥50% 差
短线警告 同币种历史平仓中位持有时间 <60 分钟(<15 分钟标「极短线」),样本 ≥3 笔
延迟 detectedAt − orderUpdateTime

另外三类消息:

  • 资金划转:transfer-history 新增记录时推一条。若当时存在推定持仓,升级为风险提示:
    • 入金 →「持仓中补保证金」:他能加保证金扛单,跟随者没有等价操作。
    • 出金 →「持仓中提取保证金」:缓冲变薄,跟随者的强平距离更近。
  • 健康告警:连续 3 次拉取失败(附 fetch failed 的底层 cause,如 ECONNREFUSED / ENOTFOUND)、带单员状态变化(如项目关闭)。恢复后再发一条「已恢复」(带中断时长和上次错误), 避免告警后一直悬着。项目关闭的告警用稳定去重键,只发一次;该项目写入 disabled_reason,重启后不再排程。
  • X 推文:配置了 xHandle 的交易员,在一条 order / transfer 信号真正送达后, 补推他 X 上「上次已推之后」的新推文。见 §6.1。

§6.1 X 推文

  • 只保留原创、自引线程和引用帖;他与别人的来回回复、转推都不推。
  • 推文 ID 是 19 位十进制数,超出 JS 安全整数,游标按字符串存、用 BigInt 比较。
  • 首次运行只把游标对齐到当前最新一条,不补历史;之后只推 ID 大于游标的推文。
  • 单次最多 xMaxTweetsPerPush 条(默认 10);超出的更早推文跳过并记日志。
  • 多条合并成一条消息,按推文边界拆成多条,单条上限 3800 字;超长单条只截断正文,时间与链接保留。
  • 同一轮里信号先发、推文后发;推文写入同一 outbox,发送失败下轮补发。
  • 拉取失败只记日志、保留 pending_since,5 分钟后重试;不影响交易信号送达。
  • fxtwitter 实测会偶发瞬时 404:客户端内部先做 2 次短重试(400ms/800ms),仍失败才进入冷却。

§7 渲染

纯文本(不用 HTML,避免昵称转义失败)。时间统一 Asia/Shanghai。

🟢 熬鹰资本 · 开多 NVDAUSDT
均价 162.7878 · 1,582.28 NVDA · 名义 $257,566
≈ 他保证金 0.78× · 推定持仓 1,582.28
流动性 一般 · 0.1% 深度 $667,651 · 本单占 39%
2026-11-14 02:51:48 · 延迟 12s

短线品种在开/加仓时多一行:

⚠️ 极短线:该币历史中位持仓 8m,手动跟单延迟会吃掉大部分
✅ 熬鹰资本 · 平多 BTCUSDT
14.837 BTC · 68,108.64 → 69,984.80
+27,837 USDT · 10x · ROI 27.0% · 持有 7h38m
2026-11-13 21:38:50 · 延迟 45s

浮亏加仓(摊平):

⚠️ 🟢 熬鹰资本 · 加多 ETHUSDT(摊平)
均价 1,850.00 · 120 ETH · 名义 $222,000
≈ 他保证金 0.68× · 推定持仓 420
加仓前推定 -8.3% · 现价 1,696.45
流动性 好 · 0.1% 深度 $8,120,000 · 本单占 3%
2026-11-14 14:03:00 · 延迟 18s

持仓中的资金划转:

⚠️ 熬鹰资本 · 持仓中补保证金
转入 150,000 USDT(现货账户 → 带单账户)
当前推定持仓:NVDAUSDT 多 3,206.99(成本 $522,073)
他补保证金能扛,跟随者没有这一步;同样的仓位,你会更早被强平。

动作图标:开 🟢 / 加 ➕ / 减 ➖ / 平 ✅。摊平信号在图标前加 ⚠️,标题后缀「(摊平)」。

§7.1 X 推文

🐦 熬鹰资本 · @thankUcrypto 新推文 2 条

2026-11-14 01:01:50
MSTR被移出指数前,买了点PUT。
今天一看,旅游经费赚回来了。 。
(1 张图)
https://x.com/thankUcrypto/status/2121287435242058003

2026-11-14 21:19:03
周末的暴跌可以抄,周末的阴跌不能碰。
暴跌是突然的清算,阴跌是有纪律的出货,阴跌抄底你抄了,人家机构出得更舒服,何必呢?
https://x.com/thankUcrypto/status/2121593758101942747

超过单条上限时自动拆分,标题变为「新推文(1/2)」「新推文(2/2)」。媒体只提示「(N 张图)」或 「(含视频)」,不在 Telegram 内展开;链接预览保持关闭。

§8 持久化

SQLite(node:sqlite),表:trader(含 disabled_reason)、lead_order、closed_position、ledger、order_snapshot、signal、health、tweet_state。PRAGMA user_version 做迁移版本,busy_timeout=5000。

  • 订单先入库再渲染,信号先入库再发送;订单、信号、账本、快照在同一个事务里提交。
  • signal.sent_at 为 null 表示待发;-1 表示永久失败已跳过;shadow 模式下写入时即标记为已处理, 将来打开推送不会补发历史。
  • order_snapshot 保存每笔委托的当前快照,用于补量差额计算;不再用「每归组键一行游标」。
  • trader.disabled_reason 非空表示该项目已停止(如带单项目关闭),重启后直接跳过,不会每 5 秒重启刷告警。
  • 预览入口(npm run once)默认写 var/preview.sqlite,绝不碰生产库,避免把真实订单标记成已处理。

§9 推送

Telegram Bot API sendMessage,纯文本。

  • 只重试明确未送达的错误:429 和请求发出前的连接失败(ECONNREFUSED / ENOTFOUND / EAI_AGAIN / UND_ERR_CONNECT_TIMEOUT)。
  • 超时、连接重置、5xx 不重试,交给 outbox 下一轮补发(幂等键保证不重复)。
  • 同一轮先发交易信号,再发 X 推文;推文与信号共用 outbox,按 created_at、rowid 升序,失败下轮补发。
  • 只有 order / transfer 信号真正送达才触发推文;健康告警和推文自身不触发。
  • 推文消息的永久失败(4xx)与普通信号一致:标记 sent_at = -1 跳过,不堵队列。

§10 多交易员

config/traders.yaml 的 traders 数组,每人独立:轮询间隔、账本、游标、失败计数、outbox。

  • 新增一人:复制一段配置,填 portfolioId(带单页 URL 末尾数字)。
  • 可选 xHandle:填了之后,该交易员的 order / transfer 信号送达时,补推他 X 上的新推文; xMaxTweetsPerPush 控制单次最多条数(默认 10)。推文游标按交易员独立持久化。
  • 首次启动自动 bootstrap(回补 bootstrapDays 天,静默入库),不会把历史刷屏。
  • 多人的首轮自动错开,避免同时打接口。

§11 验收

  1. npm run typecheck、npm test 全绿(49 个测试)。
  2. 回放 14 天真实订单:拉取 60 笔(含 3 笔同毫秒 ETH 委托),锚定后只剩 NVDA LONG 3206.99 一个未平仓; BTC 动作序列为 open→close→open→add→close。
  3. 平仓消息的入场价、杠杆、ROI、持有时间来自 position-history,与订单的 totalPnl 对得上; 平仓记录与平仓订单同毫秒到达时仍判定为「平仓」。
  4. 同一委托补量只记差额:1,582.28 → 2,000 只加 417.72,不重复计账。
  5. 可跟性:0.1% 深度按方向取对手盘;本单占 39% 判「一般」;中位持仓 <60 分钟出短线警告。
  6. 拔掉代理跑一轮:不推进游标、不产生假信号、连续 3 次后出告警(告警不等恢复就发)。
  7. shadow 48 小时:与 trade-history 交叉核对漏单为 0,统计首次发现延迟 p50/p90。
  8. 信号后推文:首次运行静默建立基线;一条信号后只推新增推文,重复运行不重发; 推文接口故障时信号照常送达,恢复后补推。

§12 已知限制

  1. 发布延迟由币安决定,本系统只能测量并显示,不能消除。
  2. order-history 单次最多 100 条、可回溯约 30 天;trade-history 约 6000 条。极端高频带单员可能超窗口。
  3. 一个仓位分多笔平掉时,多笔订单会匹配到同一条 position-history,杠杆/ROI 相同,盈亏按订单各自计算。
  4. 推定持仓在「启动前已有存量仓」时不准确,这是数据源限制。
  5. X 推文依赖第三方镜像 fxtwitter:失效时只记日志,不单独发告警;图片/视频只有数量提示, 不展开媒体;引用帖只显示他自己的正文和原帖链接,不展开被引用内容。