Binance-Agent是币安Agent OS迷你黑客松参赛的AI门控合约交易代理，通过确定性规则预过滤结合Claude AI二次验证信号，支持测试网/主网切换、干跑模式与Docker部署，本文档包含项目介绍、安装与使用指南。
Binance-Agent是币安Agent OS迷你黑客松Track A参赛的AI门控合约交易代理，通过确定性规则预过滤结合Claude AI二次验证交易信号，仅双通过才执行按比例风险计算的订单，默认干跑模式降低实盘误操作风险。
Binance-Agent是币安Agent OS迷你黑客松Track A（交易工作流赛道）的参赛作品，定位为AI门控的币安合约交易代理。其核心用途是为币安合约交易者提供一套兼顾规则确定性与AI灵活性的自动化交易方案：先通过确定性规则预过滤交易信号，再由Claude AI结合实时衍生品数据验证信号有效性，仅双通过才执行下单，降低人工盯盘成本与信号误判风险。项目基于币安Agent OS Skill Hub生态构建，使用官方binance-cli对接交易所，是黑客松交易工作流赛道的典型实践作品。
本项目主要解决三类交易场景痛点：一是纯规则策略易被市场假信号误导，缺乏对复杂衍生品数据的综合判断能力；二是纯AI交易策略缺乏确定性风控边界，容易出现非预期的大额亏损；三是人工盯盘效率低下，难以持续跟踪多交易对的衍生品数据变化。通过“确定性预过滤+AI二次验证”的混合机制，既保留了规则策略的交易纪律性，又引入了AI对复杂市场环境的判断能力，同时配套比例仓位风控、默认干跑、AI不可用时自动闭门等机制，进一步降低实盘操作风险。
本项目适用于三类核心场景：一是币安合约交易者需要在测试网验证AI门控交易策略的实盘表现与风控逻辑，避免直接在主网承担真实资金风险；二是量化开发者研究确定性规则与AI验证结合的混合交易系统架构实现，参考其预过滤-验证-下单的流程设计与风险控制逻辑；三是参与Binance Agent OS相关活动的开发者，参考其Skill Hub CLI的集成方案与AI工具调用在交易场景的落地方式。项目默认开启干跑模式，适合作为交易策略的验证与调试工具使用。
项目安装需遵循以下步骤：1. 先安装币安Agent OS官方binance-cli工具，可通过官方提供的安装脚本一键安装；2. 复制项目根目录的.env.example为.env文件，配置必填的ANTHROPIC_API_KEY（AI顾问功能必需）；3. 若需实盘下单功能，需额外配置币安API密钥，默认环境为testnet（测试网），测试网密钥可在demo.binance.com的API管理页面获取；4. 执行npm install安装项目依赖。此外也支持Docker部署，可通过docker build构建镜像后挂载data目录持久化事件日志运行。
项目使用流程如下：1. 执行npm run dev启动开发模式，默认DRY_RUN=true为干跑模式，仅打印模拟交易日志，不实际下单；2. 观察控制台输出与data/events.jsonl的决策日志，确认预过滤、AI验证逻辑符合预期；3. 测试无误后修改.env文件将DRY_RUN=false，即可开启测试网或主网真实下单，下单仓位按比例风险计算，止损触发时亏损恰好为预设的账户余额百分比。Docker部署时需挂载data目录以持久化事件日志，否则容器重启后会丢失历史决策记录。
项目有多个明确的安全与实现特性：一是AI顾问不可用（无密钥、网络错误、超时）时自动闭门不交易，不会出现无验证下单的情况；二是市场数据始终从币安生产环境公开接口读取，无需API密钥即可获取准确的衍生品数据，保证信号判断的准确性；三是所有交易决策（监控、信号、验证、下单）均以JSON Lines格式持久化到events.jsonl事件日志，AI顾问不会读取历史日志，每次判断均为独立的全新决策，避免历史数据干扰；四是订单执行环境可灵活切换testnet（测试网）或prod（主网），支持在测试网验证完整订单流程后再切换到主网。
项目本身为开源免费作品，使用时仅需自行承担币安交易所的交易手续费，测试网环境使用虚拟资金，无真实资金成本。
不可以，AI顾问是交易信号验证的核心环节，必须配置有效的ANTHROPIC_API_KEY才能正常运行；若AI顾问不可用（无密钥、网络错误、超时），代理会自动停止交易，不会执行下单操作。
项目默认开启DRY_RUN干跑模式，仅打印模拟交易日志不实际下单；实盘时采用比例仓位计算，止损触发时亏损恰好为预设的账户余额百分比，同时建议先在测试网验证完整流程后再切换主网。
支持，可通过.env文件的WATCHLIST参数自定义监控的交易对，默认监控BTCUSDT、ETHUSDT、SOLUSDT；POLL_INTERVAL_MS参数可调整轮询间隔，默认为60000毫秒（60秒）。