Stonkfly接入Coinbase实战:AgentKit ActionProvider自定义开发完整指南

原创2026-10-24 21:15:501,645 阅读

Stonkfly接入Coinbase实战:AgentKit ActionProvider自定义开发完整指南

Stonkfly 是一个"果蝇大脑连接组 + 加密交易"实验项目:它把 Coinbase 公开的 BTC-USDC 价格渲染成 RGB 图表,刺激一个含 166,700 个神经元、2560 万条突触连接的完整果蝇脑网络,再通过自定义的 Coinbase AgentKit ActionProvider 把神经输出转化为受风控硬约束的现货订单。本文带你从免费纸面交易跑通,到手把手完成 Coinbase 实盘接入,并拆解 ActionProvider 的自定义开发全流程。🧠

Stonkfly 果蝇连接组模拟接入 Coinbase 加密交易实验示意图

一、先搞懂 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:

  1. StonkflyActions(ActionProvider):继承 AgentKit 的 ActionProvider,声明仅支持 coinbase-advanced 网络
  2. get_actions():返回唯一的 Action,名称为 stonkfly_spot_order,参数 schema 是一个严格的 Proposal(只允许 product + side 两个字段,多余字段直接报错)
  3. 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 只是实盘的双重保险之一。

八、延伸阅读 📚

把完整的真实大脑接进真实交易所,Stonkfly 演示的"ActionProvider + 风控 Guard + 持久化账本"三层架构,对任何想在 Agent 框架中安全执行高风险动作的开发者都是不错的参考范式。动手之前,请先从 10 USDC 以内的专用组合开始,敬畏市场。🌱

登录后查看全文
stonkfly