Stonkfly接入Coinbase实战:AgentKit ActionProvider自定义开发完整指南
Stonkfly接入Coinbase实战:AgentKit ActionProvider自定义开发完整指南
Stonkfly 是一个"果蝇大脑连接组 + 加密交易"实验项目:它把 Coinbase 公开的 BTC-USDC 价格渲染成 RGB 图表,刺激一个含 166,700 个神经元、2560 万条突触连接的完整果蝇脑网络,再通过自定义的 Coinbase AgentKit ActionProvider 把神经输出转化为受风控硬约束的现货订单。本文带你从免费纸面交易跑通,到手把手完成 Coinbase 实盘接入,并拆解 ActionProvider 的自定义开发全流程。🧠
一、先搞懂 Stonkfly 是什么 🪰
Stonkfly 的核心理念很"科幻":不是用 LLM 或价格指标做交易决策,而是让一个保留完整结构的果蝇中枢神经系统(MaleCNS v1.0 图谱)"看"K线图,再固定解码出买/卖/持有建议。
| 模块 | 职责 | 路径 |
|---|---|---|
| 市场观测 | 拉取 Coinbase 公共盘口、渲染图表 | stonkfly/market.py |
| 神经仿真 | C++ 脉冲网络内核,0.1ms 时间步 | stonkfly/neural/ |
| 动作层 | 自定义 AgentKit ActionProvider | stonkfly/actions.py |
| 风控护栏 | 限额、冷却、回撤停单,可拒绝不可替换 | stonkfly/risk.py |
| 执行层 | Paper / Coinbase 双 Broker,FOK 限价单 | stonkfly/broker.py |
| 本地账本 | SQLite 记录订单意图,崩溃可恢复 | stonkfly/ledger.py |
三条设计底线要先记住(详见 docs/model.md):
- 🚫 没有 LLM 选单:神经网络 → 固定解码器 → 动作,链路完全确定
- 🛡️ 风控只是否,不改写:Guard 可以拒绝订单,但绝不能"换一单更好的"
- 📄 纸面交易是默认:不显式开启
--live,永远不会提交真实订单
二、快速上手:5 分钟跑通纸面交易
默认模式使用 Coinbase 真实公开价格 + 模拟成交 + $100 模拟余额,全程无需任何 API Key。
git clone https://gitcode.com/gh_mirrors/st/stonkfly
cd stonkfly
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e '.[test]'
python -m stonkfly prepare # 下载约 1.1GB 上游数据并校验,建议 16GB 内存
python -m stonkfly run --steps 10
日志、神经输入截图和可恢复的大脑状态都写入本地 runs/paper/;按 Ctrl-C 停止后,用同一命令即可继续运行。
💡 环境要求:Python 3.11 + C++17 编译器(macOS/Linux)。更多参数说明见 docs/operations.md。
三、AgentKit ActionProvider 架构拆解 🏗️
这是本文的重点:Stonkfly 没有使用 AgentKit 内置的链上钱包转账,而是自定义了一个 ActionProvider 桥接 Coinbase Advanced 交易所 API。
3.1 三个角色:Provider、Action、Broker
# 自定义 Provider 只暴露一个 Action:预算校验过的现货 FOK 订单
python -c "import ast" # 示意:核心代码在 stonkfly/actions.py
核心实现在 stonkfly/actions.py:
StonkflyActions(ActionProvider):继承 AgentKit 的 ActionProvider,声明仅支持coinbase-advanced网络get_actions():返回唯一的Action,名称为stonkfly_spot_order,参数 schema 是一个严格的Proposal(只允许product+side两个字段,多余字段直接报错)invoke(args):收到神经提案后,依次走guard.plan()(生成带限价/费率的订单计划)→ledger.reserve()(先落库订单意图)→broker.execute()(提交 FOK 限价单)
3.2 一笔订单的完整链路
神经解码(BUY/SELL) → action.invoke → Guard.plan 限额计划
→ SQLite 持久化意图 → 交易所 preview 预览费率
→ verify_balances 余额核对 → before_submit 最终闸门
→ limit_order_fok 提交 → 轮询终态 → 账本一次性结算
值得新手学习的设计细节(见 stonkfly/cli.py 主循环):
- ⏱️ 新鲜度双重校验:每次决策前重新拉取盘口,若价格移动超过 0.5% 直接否决
- 📦 意图先行:订单先写入 SQLite 再发网络请求;响应不明时按同一
client_order_id去交易所对账,绝不盲目重发 - 🧾 费用封顶:preview 阶段就核对
commission_total,超预算直接Veto
四、Coinbase 实盘接入五步法 🔑
确认纸面模式跑通后,再开始实盘配置。所有步骤都需你在本地亲手完成,仓库不会替你连上任何账户。
第 1 步:建立专用组合 在 Coinbase Advanced 创建一个独立组合,只放入 ≤100 USDC,不混入其他资产、其他机器人或手动订单。
第 2 步:创建受限 API Key
创建 ECDSA 签名的组合级 Key,权限严格为:View + Trade,显式关闭 Transfer,且只作用于该组合。账号级 Key 会被程序直接拒绝(stonkfly/broker.py 的 preflight 会逐项检查权限与组合作用域)。
第 3 步:本地保存密钥
把下载的 Key JSON 存为 coinbase-key.json,并执行 chmod 600 coinbase-key.json 收紧权限。切勿把密钥粘贴进任何提交或文档。
第 4 步:配置环境变量
参考 .env.example 复制为 .env:
COINBASE_KEY_FILE=coinbase-key.json
COINBASE_PORTFOLIO_ID=<你的组合UUID>
STONKFLY_LIVE=I_ACCEPT_REAL_TRADES
第 5 步:预检后再实盘
python -m stonkfly run --live --preflight-only # 只读检查权限/余额/订单状态,绝不发单
python -m stonkfly run --live # 确认无误后,由你自己执行
--preflight-only 会完成权限校验、余额初始化和本地账本初始化;全部通过后,再人工执行 --live。双重保险:环境变量 + --live 命令行参数,缺一不可。
五、风控硬限制一览 🛡️
这些护栏定义在 stonkfly/config.py 与 stonkfly/risk.py,是"最多亏多少"的天花板:
| 限制项 | 默认值 | 说明 |
|---|---|---|
| 最大初始资金 | 100 USDC | 专用组合,只允许 USDC 起步 |
| 单笔订单上限 | 10 USDC | 含 2% 费用预留 |
| 每日下单尝试 | 24 次 | 被拒绝的预览也计数 |
| 订单冷却 | ≥60 秒 | 相邻两次尝试的最小间隔 |
| 滑点 / 点差 | 0.5% / 0.5% | 超限立即否决 |
| 报价有效期 | 15 秒 | 过期报价禁止成交 |
| 回撤停单 | 20 USDC | 停止新订单,不会平仓或封顶后续亏损 |
⚠️ 特别注意:回撤停单只是"不再开新仓",已持仓部分依然暴露在价格波动中,需要你自己决定如何管理。
六、运行监控与停止恢复 📋
python -m stonkfly status # 查看模式、余额、持仓、是否停单
touch runs/live/STOP # 软停止:不再产生新决策与提交
- 📁
runs/<name>/目录包含 SQLite 账本、两个交替大脑快照、events.jsonl事件日志、latest-input.png(大脑最近一次"看到"的图表)以及代码/参数指纹 - ⚠️ 若出现结果不明的订单,程序会停摆等待人工对账;确认状态后可用
--resume-reviewed恢复瞬时性故障,但财务类停单(回撤、费用超限)无法用该参数绕过 - 🖥️ Worker 必须常驻你自己的电脑/服务器(它不是托管服务),注意防止休眠
七、新手高频问题 ❓
Q1:它能稳定赚钱吗? 不能保证。仓库明确声明:盈利学习尚未被证明。这是神经科学实验 + 受控执行框架,不是印钞机;实盘有亏光 100 USDC 的可能。
Q2:可以用主账户的全局 API Key 吗?
不行。preflight 会强制校验 Key 必须绑定到指定组合、Transfer 必须关闭,否则直接抛错退出。
Q3:为什么有环境变量了还不发单?
纸面模式(不带 --live)在代码层面永远不会提交订单;STONKFLY_LIVE 只是实盘的双重保险之一。
八、延伸阅读 📚
- 快速开始与实盘配置:README.md、docs/operations.md
- 神经模型与解码细节:docs/model.md
- 当前验证状态(42 个测试全部通过,无真实订单):docs/validation.md
- 测试用例(全部使用内存双替身,不触碰真实账户):tests/
把完整的真实大脑接进真实交易所,Stonkfly 演示的"ActionProvider + 风控 Guard + 持久化账本"三层架构,对任何想在 Agent 框架中安全执行高风险动作的开发者都是不错的参考范式。动手之前,请先从 10 USDC 以内的专用组合开始,敬畏市场。🌱
