在 Bybit、OKX、Bitget、GateIO、Binance、Kucoin 和 Hyperliquid 上运行的交易机器人

:warning: 请自行承担风险使用 :warning:

概述

Passivbot 是一款用 Python 和 Rust 编写的加密货币交易机器人，旨在尽量减少用户干预。

它在永续期货衍生品市场上运行，代表用户自动创建和取消限价买入与卖出订单。它不试图预测未来的价格走势，也不使用技术指标或跟随趋势。相反，它是一种逆向做市商，在两个方向上为价格变化提供阻力，从而作为价格稳定器“服务于市场”。

订单计划由一个共享的 Rust 协调器计算，该协调器同时用于实盘交易和回测，以确保速度和一致性。此外，还包含一个优化器，它通过迭代数千次不同候选配置的回测来寻找更好的设置，并利用进化算法收敛到最优配置。

策略

受马丁格尔投注策略启发，机器人会进行小额初始建仓，并在亏损时多次加倍加仓，使平均入场价更接近当前价格走势。订单以网格形式排列，随时准备吸收突发的价格波动。每次重新入场后，机器人会迅速根据设定的止盈幅度更新平仓订单。这样一来，即使市场出现小幅反转或“反弹”，也能获利了结，并重新开始新一轮操作。

尾随订单

除了基于网格的开仓和平仓外，Passivbot 还可以配置为使用尾随开仓和尾随平仓。

对于尾随开仓，机器人会等待价格突破指定阈值，然后回撤一定比例后再下达重新入场订单。同样地，对于尾随平仓，机器人会在价格朝着有利方向移动达到阈值后，再回撤一定比例才下达平仓订单。这种方式可以让机器人在市场出现反转迹象时更有效地锁定利润，而不是按照与平均入场价固定的距离来平仓。

网格订单和尾随订单可以结合使用，即机器人可以根据需要以网格订单和/或尾随订单的形式开仓或平仓部分仓位。

寻觅者

“寻觅者”功能会动态选择波动性最大的市场来开仓。波动性定义为最近 1 分钟蜡烛图的归一化相对波幅的平均值，即 mean((ohlcv.high - ohlcv.low) / ohlcv.close)。

解困机制

Passivbot 通过逐步实现小幅亏损来管理表现不佳或“卡住”的仓位。如果有多笔仓位处于卡住状态，机器人会优先处理入场价与当前市场价格差距最小的仓位进行解困。同时，为了限制损失，账户余额不会低于历史最高余额的某个百分比。

安装

要安装 Passivbot 及其依赖项，请按照以下步骤操作。

Passivbot 需要 Python 3.12。较早版本不受支持。

第一步：克隆仓库

首先，将 Passivbot 仓库克隆到本地机器：

git clone https://github.com/enarjord/passivbot.git
cd passivbot

第二步：安装 Rust

Passivbot 的部分组件使用 Rust。请按照以下步骤安装 Rust：

访问 https://www.rust-lang.org/tools/install 按照说明安装 Rustup，即 Rust 的安装和版本管理工具。 安装完成后，请重启终端或命令提示符。

第三步：创建并激活虚拟环境

创建一个虚拟环境来管理依赖项：

Linux/macOS：

python3 -m venv venv

Windows（命令提示符或 PowerShell）：

py -3.12 -m venv venv

激活虚拟环境：

Linux/macOS：

source venv/bin/activate

Windows（命令提示符）：

venv\Scripts\activate

Windows（PowerShell）：

.\venv\Scripts\Activate.ps1

第四步：安装 Passivbot

根据您的使用场景选择合适的安装配置：

• 仅用于实盘的 VPS：python3 -m pip install -e .
• 用于回测/优化/研究的工作站：python3 -m pip install -e ".[full]"
• 用于贡献代码/文档/代码检查工具：python3 -m pip install -e ".[dev]"

所有配置都会构建 Rust 扩展，并注册 passivbot 命令。

典型的仅用于实盘的安装：

python3 -m pip install -e .

第五步（可选）：手动构建 Rust 扩展

Passivbot 会尝试自动构建所需的 Rust 扩展，但您也可以手动进入 passivbot-rust 目录并使用 maturin 工具进行构建：

cd passivbot-rust
maturin develop --release
cd ..

如果检测到 Rust 源代码有更改，则需要重新编译，Passivbot 在启动时会尝试自动完成此操作。如需手动重新编译，可使用上述命令。

第六步：添加 API 密钥

复制 API 密钥模板文件：

cp api-keys.json.example api-keys.json

将您的密钥添加到 api-keys.json 文件中。

第七步：运行 Passivbot

提示：
为确保缓存文件夹名称在 Windows 系统下兼容（即使不在 Windows 系统中），请设置环境变量 WINDOWS_COMPATIBILITY=1。
此设置仅在特定情况下需要，例如在 Docker（Linux）环境中运行，并将 caches 文件夹挂载到 Windows 主机时。

要使用默认设置启动机器人，请运行：

passivbot live -u {account_name_from_api-keys.json}

或者，您可以基于 configs/examples/default_trailing_grid_long_npos10.json 创建一个新的配置文件，然后使用以下命令启动机器人：

passivbot live path/to/config.json

为了保持向后兼容性，旧版直接脚本入口点，如 python3 src/main.py ...、python3 src/backtest.py ... 和 python3 src/optimize.py ... 仍然可用且无需更改。

标准的硬编码默认配置位于 src/config/schema.py 中。示例配置文件 configs/examples/default_trailing_grid_long_npos10.json 完全反映了该默认配置，因此建议新用户以此文件作为起点来创建自己的配置文件。

日志记录

Passivbot 在整个机器人、回测工具及辅助工具中均使用了 Python 的 logging 模块。

• 在 passivbot live 或 passivbot backtest 中使用 --debug-level {0-3}（别名 --log-level）来调整运行时的日志详细程度：0 = 仅显示警告，1 = 信息，2 = 调试，3 = 追踪。
• 在 passivbot live 中使用 --verbose 可强制启用调试日志记录（--log-level debug）。
• 通过在配置文件的顶层添加 "logging": {"level": 2} 来设置默认的日志级别。CLI 标志始终会覆盖该次运行的配置值。
• passivbot live 现在默认会在 logs/ 目录下写入带时间戳的日志文件，并刷新 logs/{user}.log 作为当前运行的稳定别名。可通过 config.logging.persist_to_file、config.logging.dir 以及 config.logging 中的可选轮转设置来控制此行为。
• K 线管理器及其他子系统会继承所选的日志级别，以便一致地检查 EMA 预热、数据获取和缓存行为。

运行多个机器人

支持在同一台机器上对同一交易所运行多个 Passivbot 实例。每个进程共享相同的磁盘 OHLCV 缓存，而 K 线管理器现在使用短生命周期、可自我修复的锁机制，并具备自动清理过期锁的功能，从而避免某个进程卡死导致其他进程被阻塞。无需手动删除锁文件；机器人会在启动时移除过期的锁，并在锁获取超时时记录日志。

Jupyter Lab

Jupyter Lab 需要在与机器人相同的虚拟环境中运行。激活虚拟环境（参见上述安装步骤第 3 步），然后从 Passivbot 的根目录启动 Jupyter Lab：

python3 -m jupyter lab

系统要求

• Python >= 3.12
• 仅进行实盘交易时需运行：python3 -m pip install -e .
• 进行回测、优化、数据下载及使用高级工具时需运行：python3 -m pip install -e ".[full]"
• 对于贡献者工具，则需运行：python3 -m pip install -e ".[dev]"，在此基础上完成全量安装。

预优化配置

即将推出……

更多信息请参阅：https://pbconfigdb.scud.dedyn.io/

文档

有关 Passivbot 的更详细信息，请参阅此处的文档文件：docs/

常用入口：

• 安装指南
• 故障排除
• 回测
• 优化
• 指标参考
• 权益硬止损
• 监控输出

支持

第三方链接、推荐及打赏

Hyperliquid 推荐金库
Passivbot 的长期多头策略配置，在 Hyperliquid 金库中运行： https://app.hyperliquid.xyz/vaults/0x490af7d4a048a81db0f677517ed6373565b42349

Passivbot GUI
Passivbot 的图形用户界面： https://github.com/msei99/pbgui

推荐链接：
欢迎通过以下推荐链接注册账户以示支持： https://accounts.binance.com/register?ref=TII4B07C
https://partner.bybit.com/b/passivbot
https://partner.bitget.com/bg/Y8FU1W
https://www.okx.com/join/PASSIVBOT
https://app.hyperliquid.xyz/join/PASSIVBOT
https://www.kucoin.com/r/broker/CX8QZQJX

关于 Binance 的说明
为支持 Passivbot 的持续开发，请使用符合以下条件的 Binance 账户：

1. 账户创建日期晚于 2024 年 9 月 21 日；
2. 账户要么未通过推荐链接创建，要么使用推荐 ID：“TII4B07C”。
   仅满足上述条件的账户所产生的交易佣金才会归 Passivbot 所有。

BuyMeACoffee：
https://www.buymeacoffee.com/enarjord

捐赠：
若机器人为您带来收益，请考虑捐赠以表达对开发工作的感谢：

• USDT 或 USDC Binance Smart Chain BEP20：
  0x4b7b5bf6bea228052b775c052843fde1c63ec530
• USDT 或 USDC Arbitrum One：
  0x4b7b5bf6bea228052b775c052843fde1c63ec530
• Zcash (ZEC)：
  u1jlans93rrqusqx2wp5020aezyt0q22l4tuy7ezkna06fuyaa2gxzremf50wsj3k83a4cm0cncs6zt9urlpte7a3nzvq992z48jxzem455acmhmhhwfwjcjwl8z79vlznla0r3jln6ety565254h96whnllcmepmpqu3ft9hxtqvkn0m7

比特币 (BTC) 可通过 Strike 支付：
enarjord@strike.me

许可证

本软件为自由且无约束的开源软件，已发布至公共领域。

任何人均可出于任何目的（无论是商业用途还是非商业用途），以源代码形式或编译后的二进制文件形式复制、修改、发布、使用、编译、销售或分发本软件，不受任何限制。

在承认版权法的司法管辖区，本软件的作者特此将其对本软件的所有版权利益永久性地转让给公众。我们作出此项声明，旨在使广大公众受益，同时放弃我们自身及其继承人和继任者的任何权利。我们希望这一声明能够明确表示，我们将永久性地放弃本软件在未来任何时候根据版权法所享有的所有权利。

本软件按“原样”提供，不提供任何形式的明示或暗示担保，包括但不限于适销性、特定用途适用性和非侵权性。在任何情况下，作者均不对因本软件或其使用而产生的任何索赔、损害或其他责任负责，无论此类责任是基于合同、侵权行为或其他原因。

如需更多信息，请参阅 https://unlicense.org/

Passivbot 快速上手指南

Passivbot 是一款基于 Python 和 Rust 开发的加密货币永续合约交易机器人，支持 Bybit、OKX、Bitget、GateIO、Binance、Kucoin 和 Hyperliquid 等交易所。它采用逆势做市策略，不预测价格趋势，而是通过网格挂单和马丁格尔加仓机制提供流动性并稳定价格。

⚠️ 风险提示：本工具涉及真实资金交易，请自行承担风险。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux、macOS 或 Windows
• Python 版本：必须为 Python 3.12（不支持更低版本）
• Rust 环境：需安装 Rust 工具链（用于构建高性能核心组件）
• 网络环境：需能正常访问 GitHub 及对应交易所 API

前置依赖安装

1. 安装 Rust 访问 https://www.rust-lang.org/tools/install 下载并运行安装脚本。安装完成后重启终端。

2. 验证 Python 版本

   python3 --version
   # 必须输出 Python 3.12.x
   

安装步骤

1. 克隆项目代码

将 Passivbot 仓库克隆到本地：

git clone https://github.com/enarjord/passivbot.git
cd passivbot

💡 国内加速建议：如果克隆速度慢，可使用镜像源：

git clone https://gitee.com/mirrors/passivbot.git

(注：若 Gitee 无同步镜像，请配置本地 Git 代理或使用上述官方源)

2. 创建虚拟环境

为避免依赖冲突，强烈建议使用虚拟环境。

Linux/macOS:

python3 -m venv venv
source venv/bin/activate

Windows (CMD/PowerShell):

py -3.12 -m venv venv
venv\Scripts\activate

3. 安装 Passivbot

根据使用场景选择安装模式。对于大多数实盘用户，仅需基础模式：

python3 -m pip install -e .

其他模式参考：

• 回测与优化专用：python3 -m pip install -e ".[full]"
• 开发者贡献模式：python3 -m pip install -e ".[dev]"

安装过程中会自动编译 Rust 扩展模块，请保持网络连接畅通。

4. 配置 API 密钥

复制配置文件模板并填入您的交易所 API 信息：

cp api-keys.json.example api-keys.json

使用文本编辑器打开 api-keys.json，按照格式填入各交易所的 key 和 secret。

基本使用

启动实盘机器人

使用默认配置启动机器人（替换 {account_name} 为您在 api-keys.json 中定义的账户名称）：

passivbot live -u {account_name}

使用自定义配置启动

您可以复制示例配置文件进行修改，然后指定路径启动：

# 复制示例配置（网格 + 追踪订单策略）
cp configs/examples/default_trailing_grid_long_npos10.json my_config.json

# 编辑 my_config.json 调整参数后启动
passivbot live my_config.json

日志与调试

• 默认日志保存在 logs/ 目录下。
• 如需查看更详细的调试信息，可添加参数：

  passivbot live my_config.json --log-level 2
  

• 若需在 Windows 兼容模式下运行（如 Docker 挂载卷场景），可设置环境变量：

  export WINDOWS_COMPATIBILITY=1
  

现在，Passivbot 已开始根据您的配置在选定市场上自动执行交易策略。请密切监控初始运行情况。