深入Polymarket Copy Trading Bot代码内部:tradeMonitor与tradeExecutor双服务架构深度解析
深入Polymarket Copy Trading Bot代码内部:tradeMonitor与tradeExecutor双服务架构深度解析
Polymarket Copy Trading Bot 是一款 Polymarket 预测市场自动跟单机器人,核心由 tradeMonitor(交易监测)与 tradeExecutor(订单执行)双服务架构驱动:监测服务 7×24 小时发现目标交易员的最新订单,执行服务则按你的资金比例自动计算仓位并下单。本文带你深入源码,彻底搞懂这套架构的分工、协作与容错设计。
一、双服务架构全景:一条以 MongoDB 为队列的流水线
这套机器人最聪明的地方,在于它没有让"发现交易"和"执行交易"耦合在同一个函数里,而是拆成两个独立运行的循环,中间用 MongoDB 作为"任务队列"衔接:
| 服务 | 职责 | 轮询节奏 | 核心文件 |
|---|---|---|---|
| tradeMonitor | 轮询 Polymarket Data API,发现目标交易员的新交易并写入数据库 | 每 FETCH_INTERVAL 秒(默认 1s) |
tradeMonitor.ts |
| tradeExecutor | 扫描数据库中"未处理"的交易,计算仓位并下单 | 每 300ms | tradeExecutor.ts |
Polymarket Data API ──► tradeMonitor ──► MongoDB(状态标记) ──► tradeExecutor ──► Polymarket CLOB 下单
(每秒轮询) (发现新交易) (解耦缓冲队列) (300ms 扫描) (BUY / SELL / MERGE)
这种"生产者-消费者"式的拆分带来了三个好处:
- 频率解耦——监测侧低频省 API 配额,执行侧高频保下单时效;
- 故障隔离——网络抖动只影响单侧循环,另一侧继续运行;
- 可追溯——每笔交易在数据库里都有完整生命周期状态,随时可以审计"为什么这笔单没下出去"。
下面是机器人启动时的真实终端画面,可以看到 MongoDB 连接、健康检查(HEALTH CHECK)、CLOB 客户端初始化,以及 Starting trade monitor... 的启动日志:
启动入口在 src/index.ts:先 connectDB() 连库,再执行健康检查,初始化 CLOB 客户端,最后并发启动两个服务(index.ts 启动流程)。
二、tradeMonitor 监测服务:它如何"发现"一笔新交易
初始化:先看一眼自己和目标交易员
tradeMonitor() 启动时先执行 init(),做两件事(tradeMonitor.ts 初始化):
- 拉取你自己钱包的持仓,计算整体盈亏并展示收益前 5 的仓位;
- 统计每个目标交易员在库中的持仓数量与加权平均盈亏,展示前 3 名仓位。
这一步让你在机器人跑起来的第一时间,就能确认"跟的是谁、我手里有什么"。
轮询与去重:同一笔交易只处理一次
核心函数 fetchTradeData()(tradeMonitor.ts 轮询逻辑)对每个目标交易员做三件事:
- 拉取交易流水:调用
data-api.polymarket.com/activity?user=xxx&type=TRADE; - 过滤过期交易:时间戳早于
TOO_OLD_TIMESTAMP(默认 24 小时)的直接跳过,防止机器人一启动就疯狂补单; - 交易指纹去重:以
transactionHash作为唯一键查库,已存在则跳过,只有真正的新交易才会入库,并打上bot: false(待处理)标记。
同时它还会拉取目标交易员的最新持仓,用 upsert 更新到 user_positions_xxx 集合。这些按交易员隔离的集合由 src/models/userHistory.ts 中的 getUserActivityModel / getUserPositionModel 按钱包地址动态创建,这也是多交易员跟单(见 docs/MULTI_TRADER_GUIDE.md)能互不干扰的底层原因。
首跑保护:历史交易一键标记
首次运行时,库里可能已经积累了历史交易。机器人会把它们统一标记为 bot: true, botExcutedTime: 999(tradeMonitor.ts 首跑逻辑),从此只监测"当下"的新交易——这是防止老手迁移数据时被历史订单"轰炸"的关键设计。
三、tradeExecutor 执行服务:从待办订单到链上成交
每 300ms 扫描一次"待办订单"
执行服务的主循环(tradeExecutor.ts 主循环)每 300ms 调用 readTempTrades(),查询条件是:
type: 'TRADE' AND bot: false AND botExcutedTime: 0
即"尚未开始处理"的交易。开始处理前,它会立刻把 botExcutedTime 置为 1(tradeExecutor.ts 加锁)——相当于给订单上锁,避免并发重复执行同一笔交易。
小单聚合:把碎片订单攒成一笔
Polymarket 单笔订单最低 $1,很多目标交易员会连续拆小单买入。开启聚合后(TRADE_AGGREGATION_ENABLED),执行服务会:
- 按
用户:市场:资产:方向生成聚合键(tradeExecutor.ts 聚合键); - 只把低于 $1 的 BUY 小单放入内存缓冲区,≥ $1 的大单和所有 SELL 单立即执行;
- 等待聚合窗口(默认 300 秒)走完,若合计金额达到 $1 下限,就把多笔小单合并成一个"合成订单"(用加权平均价)一次性下单;金额不足则整组标记跳过(tradeExecutor.ts 聚合判定)。
这个机制既避开了平台最小订单限制,又显著减少了 API 调用与 gas 开销。
仓位计算与下单保护
真正的下单逻辑在 src/utils/postOrder.ts,由执行服务按 BUY / SELL / MERGE 三种策略分发:
- BUY:调用 copyStrategy.ts 的 calculateOrderSize 计算下单金额,支持 PERCENTAGE(按目标交易员金额百分比)、FIXED(固定金额)、ADAPTIVE(自适应比例)三种策略,并可叠加阶梯乘数(按交易员单笔金额分档放大/缩小,详见 docs/TIERED_MULTIPLIERS.md)。随后还有一道 99% 余额安全垫检查,以及滑点保护:若最优卖价比目标交易员的成交价高出 $0.05 以上,直接放弃这笔交易(postOrder.ts 滑点检查);
- SELL:根据目标交易员卖出占其仓位的比例,按同样比例卖出你的仓位。由于 API 返回时对方仓位已减少,代码会用
trade.size / (当前持仓 + 本笔卖出量)还原卖出前仓位(postOrder.ts 卖出比例),并结合自己历史买入量myBoughtSize做精确跟踪(原理见 docs/POSITION_TRACKING.md); - 容错:所有订单采用 FOK 类型,失败时最多重试
RETRY_LIMIT次(默认 3);若识别到"余额不足/授权额度不足"类错误,立即中止重试并提示运行npm run check-allowance。
四、两个服务之间的"交接":一张状态标记表
tradeMonitor 和 tradeExecutor 之间没有任何直接调用,全部靠 MongoDB 中每条交易记录的两个字段协商:
bot |
botExcutedTime |
含义 | 写入方 |
|---|---|---|---|
false |
0 |
新交易,等待执行 | tradeMonitor |
false |
1 |
执行中(已加锁) | tradeExecutor |
true |
0 |
执行完成 | tradeExecutor |
true |
N (≥2) |
重试 N 次后失败 | tradeExecutor |
true |
999 |
历史交易,永久跳过 | tradeMonitor |
这套极简的"数据库状态机"让两个服务可以各自崩溃重启而不会丢单、也不会重复下单——重启后只需重新看一遍状态标记即可续跑。
五、优雅退出与稳定性设计
入口文件实现了完整的优雅停机(index.ts 关闭逻辑):
- 捕获
SIGTERM/SIGINT信号; - 调用
stopTradeMonitor()与stopTradeExecutor(),让两个循环优雅退出; - 等待 2 秒让进行中的下单操作收尾,再关闭数据库连接;
- 未捕获的 Promise 异常只记录日志不退出,尽力恢复运行。
部署到服务器或 Docker 时的完整实践见 docs/DEPLOYMENT.md。
六、核心源码与文档导读
想继续深挖的读者,建议按这个顺序阅读:
| 模块 | 说明 | 路径 |
|---|---|---|
| 启动入口 | 双服务启动与优雅退出 | src/index.ts |
| 监测服务 | API 轮询、去重、首跑标记 | src/services/tradeMonitor.ts |
| 执行服务 | 待办扫描、小单聚合、下单调度 | src/services/tradeExecutor.ts |
| 下单引擎 | BUY/SELL/MERGE 策略、滑点与重试 | src/utils/postOrder.ts |
| 仓位策略 | 三种跟单策略与阶梯乘数 | src/config/copyStrategy.ts |
| 配置中心 | 环境变量校验与默认值 | src/config/env.ts |
| 数据模型 | 按交易员隔离的活动/持仓集合 | src/models/userHistory.ts |
配套文档值得一并翻阅:docs/GETTING_STARTED.md(新手入门)、docs/QUICK_START.md(快速配置)、docs/TIERED_MULTIPLIERS.md(阶梯乘数)、docs/POSITION_TRACKING.md(持仓跟踪原理)、docs/LOGGING_PREVIEW.md(日志效果预览)。
总结
Polymarket Copy Trading Bot 的双服务架构,本质上是把"跟单"这件复杂的事拆成了可靠感知与可靠执行两个独立问题:tradeMonitor 用交易指纹去重和首跑标记保证"每笔新交易只进库一次",tradeExecutor 用状态锁、小单聚合、滑点保护和重试机制保证"每笔进库的交易只被执行一次且尽量安全"。理解这条以 MongoDB 为桥梁的生产者-消费者链路,你就掌握了这个项目最核心的架构思想——它同样适用于任何需要"高频感知 + 异步执行"的自动化交易场景。
