Qbot 比特币套利机会检测与自动交易bitcoin-arbitrage 模块原理解读与实战指南【免费下载链接】Qbot[updating ...] AI 自动量化交易机器人(完全本地部署) AI-powered Quantitative Investment Research Platform. online docs: https://ufund-me.github.io/Qbot ✨ :news: qbot-mini: https://github.com/Charmve/iQuant项目地址: https://gitcode.com/GitHub_Trending/qbot/Qbot本文围绕 Qbot 仓库中 bitcoin-arbitrage 模块展开讲解它如何从多家交易所的实时订单簿中挖掘跨市场套利机会、如何配置并运行该检测器与自动交易机器人并深入 arbitrer.py 核心源码剖析其订单深度加权利润计算算法、观察者Observer分发机制与交易安全护栏的实现细节。读完后你将能够独立部署该模块、看懂它输出的每条套利日志并理解其自动下单前的全部风控校验逻辑。模块定位与整体架构Qbot 是一个 AI 自动量化交易机器人平台qbot/engine/trade/trading目录汇集了多种交易子系统的集成。其中的 bitcoin-arbitrage 模块源自一个经典的比特币跨所套利项目MIT 许可Copyright (c) 2013 Maxime Biais其功能是从受支持的交易所获取订单簿order book计算各市场之间的套利机会并且会把订单簿深度market depth考虑在内——而不是只看盘口最优价。按 README 的说明模块的交易所支持范围分为两层用于获取行情数据的交易所公开 APIBitstamp (USD, EUR)Paymium (EUR)Bitfinex (USD, EUR)bitFlyer (USD, EUR)Kraken (USD, EUR)OkCoin (CNY)Gemini (USD)BTCC (CNY)GDAX (USD, EUR)CEX.io (USD, EUR)Binance (USD)支持自动化下单的交易所私有 APIBitstamp (USD)Paymium (EUR)从源码结构看模块采用经典的“行情层 / 决策层 / 执行与通知层”三层结构对应 arbitrage/ 目录下的几个关键区域层级目录 / 文件职责行情层public_markets/每家交易所一个模块如_kraken.py、_bitstamp.py统一实现Market基类的get_depth()决策层arbitrer.pyArbitrer类并发拉取深度、两两比对市场、计算加权套利利润执行/通知层observers/Logger、TraderBot真实下单、TraderBotSim模拟、Emailer、XMPPMessager、HistoryDumper等观察者资金账户层private_markets/PrivateBitstampUSD、PrivatePaymium封装余额查询与买入卖出辅助层fiatconverter.py法币汇率转换使不同计价货币的市场可以横向比较此外还有 setup.py、requirements.txt、tests 相关测试 与 docs/add-new-exchange.md 等配套文件。安装与配置模块对运行环境的要求很简单Python3。在 Debian、Ubuntu 及其衍生发行版上可按 README 安装sudo apt-get install python3 python3-pip python-nose如果你希望使用XMPPMessager观察者通过 Jabber/XMPP 推送套利提醒需要额外安装 sleekxmpppip3 install sleekxmpp配置文件采用“示例文件复制 手工编辑”的方式从仓库根目录执行cp qbot/engine/trade/trading/bitcoin-arbitrage/arbitrage/config.py-example qbot/engine/trade/trading/bitcoin-arbitrage/arbitrage/config.py随后编辑config.py设置你要监控的市场markets和观察者observers。完整的参数模板见 config.py-example其核心配置项如下markets [ BitFlyerEUR, BitFlyerUSD, BitfinexEUR, BitfinexUSD, BitstampEUR, BitstampUSD, CampBXUSD, CEXEUR, CEXUSD, GDAXEUR, GDAXUSD, GeminiUSD, KrakenEUR, KrakenUSD, OKCoinCNY, PaymiumEUR, ] # observers if any # [Logger, DetailedLogger, TraderBot, TraderBotSim, HistoryDumper, Emailer] observers [Logger] market_expiration_time 120 # in seconds: 2 minutes refresh_rate 60 #### Trader Bot Config # Access to Private APIs paymium_username FIXME paymium_password FIXME paymium_address FIXME # to deposit btc from markets / wallets bitstamp_username FIXME bitstamp_password FIXME # SafeGuards max_tx_volume 10 # in BTC min_tx_volume 1 # in BTC balance_margin 0.05 # 5% profit_thresh 1 # in EUR perc_thresh 2 # in % #### Emailer Observer Config smtp_host FIXME smtp_login FIXME smtp_passwd FIXME smtp_from FIXME smtp_to FIXME #### XMPP Observer xmpp_jid FROMjabber.org xmpp_password FIXME xmpp_to TOjabber.org各参数在源码中的实际作用可对照源码验证参数默认示例值源码中的作用markets市场类名列表由 Arbitrer.init_markets 动态import对应的public_markets/market名小写模块并实例化名称非法时打印提示并忽略observers[Logger]由Arbitrer.init_observers同样动态加载observers/名小写中的同名类refresh_rate60 秒Arbitrer.loop()主循环中time.sleep(config.refresh_rate)的轮询间隔market_expiration_time120 秒Market.get_depth 中若订单簿更新超过该时长将其置为无效全部 0 价 0 量并告警防止用过期数据套利max_tx_volume10 BTC单笔自动交易数量上限在get_profit_for与TraderBot.opportunity中两处截断min_tx_volume1 BTC低于最小成交量的机会不执行自动交易balance_margin0.05交易可用余额保留 5% 余量见下节风控逻辑profit_thresh1 EUR机会利润低于该阈值时TraderBot直接丢弃perc_thresh2 %机会收益率低于该百分比时TraderBot直接丢弃smtp_*/xmpp_*FIXMEEmailer/XMPPMessager观察者使用的推送凭据README 中的醒目警告务必重视模块内包含真实交易机器人如果你不清楚自己在做什么不要把 API 密钥写入 config.py。示例文件中的FIXME占位符也正是为了避免误触发的设计——保持它们为FIXME时自动交易路径无法正常工作。核心工作流从订单簿到套利通知Arbitrer 是整个模块的引擎。loop()方法L238-L243实现了无限主循环update_depths()用ThreadPoolExecutor(max_workers10)并发拉取所有市场订单簿wait(futures, timeout20)限时等待tickers()以 VERBOSE 级别输出各市场最新 tickertick()执行一轮机会检测并把结果分发给所有观察者休眠refresh_rate秒后进入下一轮。tick()的核心逻辑是两两市场比对对 depths 中的每一对(kmarket1, kmarket2)若市场 1 的卖一价低于市场 2 的买一价asks[0].price bids[0].price说明存在跨所价差随即调用arbitrage_opportunity()做深度级利润测算并向每个 observer 回调opportunity(profit, volume, buyprice, kask, sellprice, kbid, perc, weighted_buyprice, weighted_sellprice)。检测前后分别调用begin_opportunity_finder()/end_opportunity_finder()这为TraderBot这类需要“一轮内收集所有候选、只执行最优一笔”的观察者提供了钩子。订单深度加权利润算法真正体现“考虑市场深度”的部分是 get_profit_for 与 arbitrage_depth_opportunityget_max_depth(kask, kbid)先确定扫描深度上限——只扫描“买盘价仍不低于卖一价”以及“卖盘价仍低于买一价”的档位区间避免无意义的深度扫描get_profit_for(mi, mj, kask, kbid)对买入侧前mi1档、卖出侧前mj1档累计可成交数量max_amount min(买侧累计量, 卖侧累计量, max_tx_volume)然后按数量加权计算加权买入均价w_buyprice与加权卖出均价w_sellpriceL88-L90 的加权递推公式最终profit sell_total * w_sellprice - buy_total * w_buypricearbitrage_depth_opportunity在(i, j)深度组合空间内遍历保留利润最大的(best_i, best_j)组合并返回(利润, 成交量, 买一价, 卖一价, 加权买价, 加权卖价)六元组。这意味着日志中报告的利润与成交量都是按订单簿深度足额成交后的真实可执行口径估算的而非盘口价差的理论值。跨货币市场的可比性FiatConverter不同市场的订单簿以 USD、EUR、CNY 等不同计价货币报价直接比较会得出错误结论。Market 基类 在每次ask_update_depth()成功后都会调用convert_to_usd()把全部档位价格统一换算为 USD。换算由 FiatConverter 完成它抓取欧洲央行ECB每日欧元参考汇率 XMLeurofxref-daily.xml用xml.sax解析出各货币对 EUR 的汇率每 6 小时更新一次update_delay 60 * 60 * 6换算公式为price / rate_from * rate_toL59-L63。同时Market基类还内置了行情时效性保护get_depth()检查距上次更新的时长超过self.update_rate60 秒就触发重新拉取若超过config.market_expiration_time示例值 120 秒直接把订单簿置为[{price: 0, amount: 0}]并记录Market: %s order book is expired警告——这一机制保证了过期行情绝不会进入tick()的比对逻辑。私有市场与订单语义private_markets/market.py 中的Market基类定义了交易侧接口buy(amount, price)/sell(amount, price)注释明确“订单价格始终以 USD 计价”内部再经FiatConverter折算回本地计价货币、deposit()、withdraw(amount, address)和get_info()并以TradeException作为交易异常类型。PrivateBitstampUSD与PrivatePaymium分别实现这两个支持自动下单的交易所。CLI 的get-balance命令就是利用这条私有路径来核对账户配置的。观察者机制与自动交易风控Observer 抽象基类 只要求子类实现抽象方法opportunity(...)并预留begin_opportunity_finder(depths)/end_opportunity_finder()两个可选钩子。示例配置注释列出了全部可选观察者[Logger, DetailedLogger, TraderBot, TraderBotSim, HistoryDumper, Emailer]另有 README 提到的XMPPMessager需要 sleekxmpp。各观察者的分工Logger / DetailedLogger仅记录机会日志是最安全的默认配置observers [Logger]HistoryDumper把每轮 depths 落盘为 JSON 文件供replay-history命令离线回放分析README TODO 中提到希望改进其历史存储例如引入 RedisEmailer机会出现时发送 SMTP 邮件XMPPMessager通过 XMPP 推送消息TraderBotSim / TraderBot模拟 / 真实自动下单。TraderBot 是模块中唯一直接对接私有 API 执行交易的观察者其opportunity()方法L41-L111实现了多层安全护栏阈值过滤profit config.profit_thresh或perc config.perc_thresh的机会直接丢弃客户端可用性检查买卖两个市场必须都已在self.clients中注册私有客户端当前源码中clients字典默认是空的L13-L16 留有 TODO 提示“move that to the config file”否则会告警Cant automate this trade, client not available余额约束通过update_balance()刷新两侧余额用get_min_tradeable_volume()计算可交易量——买入侧usd_bal / ((1 balance_margin) * buyprice)、卖出侧btc_bal / (1 balance_margin)再取与max_tx_volume的较小值最小量检查折算后成交量若小于min_tx_volume放弃并打印两侧余额明细交易冷却trade_wait 120秒距上一笔自动交易不足 2 分钟的机会同样被拒绝。通过全部检查的机会被暂存到potential_trades在end_opportunity_finder()中按利润排序execute_trade()只执行利润最高的一笔self.clients[kask].buy(volume, buyprice)加self.clients[kbid].sell(volume, sellprice)并更新last_trade时间戳。运行机会监控、余额查询与测试按 README 的说明模块提供以下运行入口均通过python3 -m arbitrage调用 ArbitrerCLI1. 运行套利机会监控器watch默认命令python3 -m arbitrage -v-v开启 VERBOSE 级别日志init_logger 中对应自定义的 level 15-d则为 DEBUG。示例输出展示了机会日志的典型格式——利润计价货币 可成交数量 买卖两侧价格与交易所 近似收益率2013-03-12 03:52:14,341 [INFO] profit: 30.539722 EUR with volume: 10 BTC - buy at 29.3410 (MtGoxEUR) sell at 29.4670 (Bitcoin24EUR) ~10.41% 2013-03-12 03:52:14,356 [INFO] profit: 66.283642 EUR with volume: 10 BTC - buy at 29.3410 (MtGoxEUR) sell at 30.0000 (PaymiumEUR) ~22.59%2. 查询交易所余额也是验证账户配置正确性的好办法python3 -m arbitrage -m Paymium get-balance python3 -m arbitrage -m Paymium,BitstampUSD get-balance对应 ArbitrerCLI.get_balance按逗号拆分-m参数逐个加载private_markets/市场小写中的Private市场名类并打印余额未指定-m时以退出码 2 报错。3. 列出受支持的公开市场 / 帮助python3 -m arbitrage list-public-markets python3 -m arbitrage -hlist-public-markets的实现get_market_list采用运行时扫描遍历public_markets/下所有不以_开头的模块用inspect找出继承自Market的类并输出类名——这就是为什么config.py里填写的市场名必须与类名完全一致如KrakenEUR而非kraken_eur。CLI 还内置generate-config命令可自动打印出包含全部市场名的配置骨架。4. 历史回放replay-historycommand参数支持watch | replay-history | get-balance | list-public-markets见 argparse 定义。replay-history 目录会按文件名排序读取该目录下HistoryDumper落盘的 JSON 深度快照逐份还原self.depths并调用tick()重放一遍机会检测——用于离线复盘某一时段的跨所价差而不必实时轮询交易所。5. 运行测试nosetests arbitrage/测试代码位于 arbitrage/test/ 目录包含arbitrage_test.py与arbitrage_speed_test.py。命令行参数速查ArbitrerCLI.main 定义了如下参数可组合使用参数含义-d / --debugDEBUG 级别日志-v / --verboseVERBOSE 级别日志-o / --observers覆盖配置的观察者列表逗号分隔如-o Logger,Emailer-m / --markets覆盖配置的市场列表逗号分隔如-m BitstampEUR,KrakenEURcommand子命令默认watch如何扩展一个新的交易所仓库中提供了 docs/add-new-exchange.md 作为扩展指引入口该文件目前仅为标题占位。从源码结构看扩展模式是非常规整的模板化流程公开行情在public_markets/下以_前缀新建交易所底层模块参照 _kraken.py、_bitstamp.py实现其 REST 订单簿接口的解析再为每个计价货币新建一个不带_前缀的适配模块如krakenusd.py、krakeneur.py继承 public_markets/market.py 的Market基类并实现update_depth()私有交易若该交易所支持自动下单在private_markets/中实现buy/sell/get_info/withdraw等接口参照 paymium.py并在TraderBot.clients中注册由于list-public-markets与init_markets都是运行时按模块/类名动态发现的新增文件后无需修改任何注册表即可被python3 -m arbitrage list-public-markets自动列出。已知局限与 TODOREADME 末尾的 TODO 清单如实反映了该模块的当前边界使用前应当了解测试与文档仍待完善计划新增交易所如 icbit计划为受支持交易所Kraken、Bitfinex、Paymium引入 WebSocket 客户端用推送替代 REST 轮询HistoryDumper的历史存储方式待改进例如 Redis尚未解决跨市场法币划转问题Coupons / Ripple / 稳定币 / 反向操作等方向尚未支持其他加密货币与三角套利。另外需要注意的技术前提模块通过 ECB 每日汇率把各市场统一换算为 USD 后比较因此 CNY 计价市场OKCoinCNY、BTCC CNY与欧美市场之间的“价差”会受到 ECB 参考汇率与市场实际汇率偏差的干扰FiatConverter中虽有bank_fee 0.007的字段带 TODO 注释但从源码结构看它尚未参与利润计算。也就是说Logger输出的利润是未扣除交易手续费、转账成本与法币划转损耗的毛口径用于自动交易前请务必结合profit_thresh/perc_thresh阈值自行留足安全边际。小结bitcoin-arbitrage 模块是 Qbot 中一个结构清晰、可独立运行的跨所套利子系统Arbitrer以线程池并发轮询订单簿并做美元归一化tick()两两比对市场并以深度加权口径测算可执行利润观察者机制把“检测”与“执行/通知”解耦而TraderBot在下单前叠加了阈值、余额余量、最小量与冷却时间四重护栏。以observers [Logger]起步做纯监控再逐步验证get-balance私有接口、最后才考虑启用自动交易是 README 警告之外最稳妥的使用路径。【免费下载链接】Qbot[updating ...] AI 自动量化交易机器人(完全本地部署) AI-powered Quantitative Investment Research Platform. online docs: https://ufund-me.github.io/Qbot ✨ :news: qbot-mini: https://github.com/Charmve/iQuant项目地址: https://gitcode.com/GitHub_Trending/qbot/Qbot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考