MangroveAI

---

这是什么

一个本地 AI 交易 Agent，可以：

• 通过 MangroveAI API，将自然语言目标（“ETH 动量策略”）转化为经过回测和排名的交易策略。
• 在 APScheduler cron 作业上运行实盘策略。模拟交易和实盘交易使用相同的评估路径。
• 通过 MangroveMarkets 执行实盘 DEX 兑换——通过 1inch 在 10 条 EVM 链上路由（Ethereum、Base、Arbitrum、Polygon、Optimism、BNB、Avalanche、zkSync Era、Gnosis、Linea；Agent 默认使用 Base）。在客户端签名；路由服务不会接触你的密钥。
• 也可在 Kraken 上交易，支持两种连接模式：自带密钥（/setup-kraken — 使用最低权限的 API 密钥，该密钥保留在你的设备上并直接连接 Kraken）或无密钥 OAuth（/connect-kraken — 在浏览器中授权一次，无需管理密钥）。
• 将每次评估和交易（DEX 和 CEX）记录到本地 SQLite，保留完整的审计记录。

你将获得

• 119 个工具（截至 2026 年 10 月；Claude Code 中的 /mcp 于 2026-10-20 显示 119 个）。这是由 Agent 转发的托管 MangroveAI 目录及本地工具组成的目录。对端点运行 list_tools，即可查看实时目录。
• 7 个 Agent 技能，位于 .claude/skills：audit-security、check-alignment、connect-kraken、setup-kraken、setup-robinhood、tool-spec、trading-bot。Claude Code 插件会接入其中四个。
• 与 MCP 服务配套的 REST API（FastAPI），由同一个 Agent 提供。
• Claude Code 插件安装方式，参见作为 Claude Code 插件安装。
• **适用于 Codex 和任何 MCP 客户端。**本地 MCP 端点为 http://127.0.0.1:9080/mcp/。参见在 Codex 中使用。
• 位于 https://api.mangrovedeveloper.ai/mcp/ 的托管 MangroveAI MCP 服务（可流式传输的 HTTP，无需身份验证即可响应 initialize）。
• **定价：**在 https://mangrovedeveloper.ai 获取免费 API 密钥，或使用 USDC 按次调用并通过 x402 付费。
• **非托管式：**可在 Kraken（自带密钥或使用 OAuth）、Robinhood 和覆盖 10 条 EVM 链的 1inch 上执行操作。密钥和钱包都保留在你的设备上。

面向 Agent 构建者的更多信息：https://mangrove.ai/agents/ 和 https://mangrove.ai/llms.txt

完整的平台文档和交易知识库位于 **https://mangrove.io/docs**（知识库：https://mangrove.io/knowledge-base）——Agent 的 kb_search 工具会查询同一知识库。

Agent 执行的真实主网兑换（已于 2026 年 4 月验证）：0x5c126e...c5565

---

在 AI 客户端中使用 Mangrove Agent

请先阅读用户指南，了解安装、选择名称、稍后继续使用以及切换客户端。

告诉 Claude Code、Codex、Grok Build 或 Perplexity Computer：

安装 https://github.com/MangroveTechnologies/mangrove-agent，并按照其中的 AI 客户端安装说明操作。

**对于负责安装的 Agent：**请遵循 AI 客户端设置。 在执行环境中安装服务，加载完整的 Agent 指令，发现其工具，并在报告成功之前调用免费的 status 工具。Perplexity Computer 可以使用提供的命令行客户端；此安装无需创建 Perplexity Project、配置自定义云连接器或安装其他桌面应用。

Agent 的共享身份和运行指令位于 SAGE.md。 首次运行时，系统会询问你要为 Agent 取什么名字。该选择会保存在本地，并在各客户端间重复使用；没有默认的个人名称。 AGENTS.md 会将 Codex 和兼容客户端指向此处；CLAUDE.md 会将其导入 Claude Code。Codex 和 Grok Build 的启动辅助工具、MCP 配置模板，以及完整的 Perplexity/网页指令包都记载在 AI 客户端设置中。每个客户端的工具访问权限都需单独配置并验证。

使用 setup.sh 安装（API 密钥或 x402）

克隆仓库并运行 ./scripts/setup.sh。选择现有的 MangroveAI API 密钥或钱包付款（x402，无需注册）。该脚本会保护本地访问权限， 启动 Agent，并在 Claude 的 CLI 可用时注册 Claude。对于 x402，最后一个菜单会显示钱包操作步骤，供你自行运行；脚本绝不会自动创建或导入钱包，也不会付款。 参见完整的设置和钱包流程。

安装为 Claude Code 插件（需要 API 密钥）

对于现有的 API 密钥插件流程，请告诉你的 Claude Code Agent *“安装这个交易机器人：https://github.com/MangroveTechnologies/mangrove-agent”*，或自行运行：

claude plugin marketplace add MangroveTechnologies/mangrove-agent
claude plugin install mangrove-agent@mangrove

在 Claude Code 会话中，同样可以运行 /plugin marketplace add MangroveTechnologies/mangrove-agent，然后运行 /plugin install mangrove-agent@mangrove。Claude Code 会要求你提供 MangroveAI API key（可在 https://mangrovedeveloper.ai 免费获取），并将其作为敏感设置保存。切勿将密钥粘贴到聊天中。

开启一个新会话。首次启动时，插件会安装 Python 依赖并在后台启动 Agent（约需 1-3 分钟）。然后说 “带我了解一下” 或 “为我构建一个 ETH 动量策略”。

• 需要： Python 3.11+ 和 bash shell（macOS、Linux，或 Windows 上的 WSL / Git Bash）。
• 数据存放位置： ~/.mangrove-agent/ 保存配置、SQLite 数据库（钱包、策略、交易）和钱包主密钥。插件更新不会影响这些数据。持有资金后请备份；只要钱包中还有资金，就切勿删除此目录。
• 网络： Agent 仅监听 127.0.0.1:9080。不要同时在 9080 端口运行通过 git clone 安装的 Agent。
• 日志： ~/.mangrove-agent/agent-data/agent.log（服务）和 bootstrap.log（安装/启动）。

想修改代码？请改用下面的方式克隆仓库。两种方式运行的是同一个 Agent。

在 Codex 中使用

仓库附带 Codex marketplace 文件 .agents/plugins/marketplace.json。在终端中添加 marketplace：

codex plugin marketplace add MangroveTechnologies/mangrove-agent

根据 OpenAI 的 Codex 插件文档，随后可在 ChatGPT 桌面应用的 Plugins Directory 中安装插件（重启应用，打开 Plugins Directory，选择 mangrove marketplace，然后安装 mangrove-agent）。文档中没有列出 CLI 安装命令。若要在单个项目中启用它，请将以下内容添加到该仓库的 .codex/config.toml：

[plugins."mangrove-agent@mangrove"]
enabled = true

你也可以跳过 marketplace，使用 .codex/config.toml.example 中的模板，让 Codex 连接本地 MCP 服务（http://127.0.0.1:9080/mcp/）。请参阅 AI 客户端设置。

开始使用（git clone）

这个仓库就是你自己的交易 Agent：在自己的机器上运行，密钥不会离开本机；它也是 Mangrove API 的参考使用方——克隆它、按自己的需要修改，并将其扩展为自己的交易系统。

1. 在用户指南中选择 AI 客户端。 Claude Code、Codex、Grok Build 和 Perplexity Computer 均支持安装。MangroveAI API key 为可选项；全新且无人值守的设置会暂缓钱包付款，直到你完成配置。
2. 按照 SETUP.md 中的说明手动安装前置条件并完成设置。较详细的 Claude 操作指南为可选内容；其他客户端不需要 Claude 或 Node.js 即可运行 Python Agent。
3. 按照 tutorials/trading-app/ 开始引导式教程——通过循序渐进的章节，从“我刚刚克隆了仓库”到“我已运行纸上策略”，再到（可选的）“我完成了一笔真实兑换”。

第 01-05 章不会动用真实交易资金。付费 API 调用仍可能消耗 API 密钥额度或需要 x402 付款，包括纸上交易模式。第 06-08 章介绍可选的真实交易。

已经熟悉操作？继续阅读——本 README 其余部分是参考资料。

连接你的 Kraken 账户

Agent 可在 Kraken（CEX）和链上进行交易。有两种接入方式——根据你希望如何管理访问权限来选择：

	使用自己的密钥 — /setup-kraken	无密钥 OAuth — /connect-kraken
工作方式	创建一个最小权限的 Kraken API 密钥（仅限交易和查询，禁用提现）；SDK 会在你的机器上直接与 api.kraken.com 通信	在浏览器中授权一次（Kraken Connect / OAuth2）；无需创建、复制或存储 API 密钥
谁持有访问权限	你——密钥不会离开你的机器，也不会接触 Mangrove 服务	Mangrove 平台持有 OAuth 授权，并代表你提交请求
适合人群	坚持自主托管的人；以及愿意创建 API 密钥的人	最快的接入方式；不想管理密钥的人
撤销方式	在 Kraken 设置中删除密钥	在 Kraken 设置中撤销应用授权

在会话中只需说 “设置 Kraken” 或 “无密钥连接 Kraken”，相应的技能就会引导你完成操作——包括 BYOK 密钥所需的准确权限。成交记录会同步到与你的 DEX 兑换共用的本地 SQLite 交易日志中（cex_status、cex_balances、cex_sync_fills）。

---

前置条件

有关市场列表和其他受所有权保护的操作，请参阅 市场钱包授权。Claude 可以准备操作并展示给你审批，然后由本地 Agent 签名并提交到 MangroveMarkets。这需要明确配置市场，并备份 Base 或 XRPL 钱包。支付结算属于单独的集成。

工具	安装	用途
VSCode（可选）	https://code.visualstudio.com/download	带集成终端的编辑器。也可以使用现有终端或 AI 客户端的执行环境。
Python 3.11+	https://www.python.org/downloads/	Agent 是一个 Python FastAPI 进程。最低版本为 3.11。
Git for Windows（仅限 Windows）	https://git-scm.com/download/win	提供 Git Bash，让本仓库中的 *.sh 脚本在 macOS / Linux 上也能正常运行。通过命令面板将 VSCode 的默认终端设为 Git Bash。
AI 客户端	Claude、Codex、Grok 或 Perplexity 设置	支持命令执行或 MCP 访问的客户端。Claude Code 为可选项。
MangroveAI API 密钥	在 https://mangrovedeveloper.ai 免费获取	setup.sh 的可选项：选择 API 密钥访问或 x402 钱包支付。

Docker 为可选项——请参阅下方的备用安装方式。裸机是主要安装方式，因为 Agent 原生运行时，keyring 库可以直接访问操作系统密钥链。

---

快速开始 — 裸机（推荐）

一条命令即可选择 API 密钥或 x402 访问方式、创建 venv、安装依赖、启动本地 Agent、在可用时注册 Claude，并验证经过身份验证的本地访问。

git clone https://github.com/MangroveTechnologies/mangrove-agent.git mangrove-agent
cd mangrove-agent
./scripts/setup.sh

首次运行可能需要几分钟来安装依赖和发现网络。再次运行会保留配置和本地状态；代码或配置变更后，也可以重启服务。若要将其他客户端连接到已运行的 Agent，无需重新运行设置。

完成后：

• Agent 运行于 http://localhost:9080（pid 位于 agent-data/bare.pid，日志位于 agent-data/bare.log）。我们在外部绑定 9080，因为 :8080 经常被 VSCode Helper 和其他开发工具占用。
• ./scripts/verify_quickstart.sh --bare 已通过：已检查本地身份验证和必需的本地工具。不可用的远程工具会单独报告。
• 可用且未跳过时，会保存 Claude 注册信息；其他客户端可使用命令客户端或通过自身的 MCP 连接。

设置完成后，请使用你选择的客户端继续操作，参阅用户指南。Claude 用户可以运行 ./scripts/chat.sh 开启会话；该会话会禁用 shell／文件工具，仅使用 Mangrove MCP；详见受限聊天。在 x402 模式下，申请付费数据或回测前，请先完成打印出的付款钱包说明。API 密钥用户无需付款钱包即可进行模拟交易。模拟交易不会让上游 API 调用变成免费。

./scripts/setup.sh 的实用标志

./scripts/setup.sh --yes                          # preserve settings; fresh install uses x402
./scripts/setup.sh --auth api-key                  # keep existing key or enter a new one (hidden)
./scripts/setup.sh --auth x402                     # explicitly switch to wallet payments
./scripts/setup.sh --foreground                    # run uvicorn in your terminal (Ctrl+C to stop)
./scripts/setup.sh --no-mcp                        # skip Claude Code registration
./scripts/setup.sh --no-verify                     # skip the post-start verify pass
./scripts/setup.sh --docker                        # use Docker instead of bare-metal
BARE_PORT=9085 ./scripts/setup.sh                  # use a different port (9080 busy/squatted)

BARE_PORT 会在整个流程中生效（服务 + 健康检查 + MCP 注册 + 验证）。如果 9080 已被占用，setup.sh 会拒绝启动，并提示你释放该端口或设置 BARE_PORT——不会静默绑定失败，也不会误报成功。

---

备用快速开始 — Docker

如果主机上无法运行 Python（例如受企业限制或有可复现性要求），Docker 也能以相同方式运行。代价是：容器无法访问操作系统密钥链，因此 Fernet 主密钥会存储在 ./agent-data/master.key（权限设为 600，且已加入 gitignore），而不是 Keychain／Secret Service／Credential Manager。

git clone https://github.com/MangroveTechnologies/mangrove-agent.git mangrove-agent
cd mangrove-agent
./scripts/setup.sh --docker

状态会持久化在 ./agent-data/ 目录中（该目录会绑定挂载到容器内）。挂载目录可避免 macOS／Windows 上单文件绑定挂载的陈旧问题；此前该问题曾在重建后导致数据库行丢失。

---

你的第一笔交易

本节是快速导览。完整操作指南见 tutorials/trading-app/；如果你想看更简短的参考，可以再回到这里。

首次连接。 你选择的客户端会加载共享策略、发现工具并调用免费状态接口。如果安装中没有保存的名称，它会提示你选择一个。启动时不会自动获取付费市场数据、运行回测或配置钱包。想要导览时，请提出请求；付费示例需要先取得相应权限。

模拟交易（在 x402 模式下调用付费 API 需要支付钱包）。

“为我制定一个 ETH 1h 策略。”

Agent 会调用 MangroveAI 的 build_strategy_for_regime：服务会读取当前市场状态，在该状态下搜索 Strategy Engine 已完成的运行结果，并应用固定筛选门槛（交易次数超过 10 次、Sharpe 至少为 1、IRR 至少为 10%、表现优于基准）；然后从入场条件符合该状态的结果中随机挑选一个，将其保存为草稿，并用最近 90 天的数据进行回测。若要根据该状态允许的信号组合出策略，请提出要创建一个新策略。

“将它晋升为模拟交易。”

系统会按策略的时间周期将策略加入 cron 计划。评估会触发，并记录模拟成交。无需承担资金风险。

实盘交易（可选，需要资金）。

对于 Robinhood，请使用捆绑的 setup-robinhood 技能和 执行场所设置。它使用经纪商 OAuth， 无需本地交易钱包。

对于 DEX 执行，钱包设置和实盘交易的说明见教程第 06 章和第 07 章：

• 通过 create_wallet / stash-secret.sh + import_wallet 创建或导入钱包。
• 在终端中通过 ./scripts/reveal-secret.sh <vault_token> 保存密钥（切勿在聊天中操作）。
• 运行 ./scripts/confirm-backup.sh <address> 以解除备份限制。
• 在 Base 上存入 1–5 USDC。
• 使用资金分配区块将策略晋升为实盘状态（confirm=true、slippage_pct ≤ 0.0025）。
• 实盘评估会在同一个 cron 计划中触发；策略决定交易时，mangrovemarkets SDK 会通过 1inch 路由，Agent 在本地签名并广播交易，然后记录交易哈希。

安全模型概览

• 你的私钥绝不会进入此聊天。 create_wallet 返回的是 vault_token，而不是明文。密钥需通过单独的 CLI（reveal-secret.sh）显示，且只会打印到你的终端。
• Harness 钩子会阻止粘贴密钥。 如果你尝试将密钥粘贴到 Claude Code，.claude/hooks/block-wallet-secrets.sh 会拒绝该提示，并显示说明信息。钩子位于 .claude/settings.json 中——设备所有者可以更改此配置。
• 实盘交易必须经过明确的备份确认。 在将钱包密钥保存到 Agent 之外后，运行 ./scripts/confirm-backup.sh <addr> 设置标记。对于未设置该标记的钱包，execute_swap 和 update_strategy_status → live 会拒绝执行。
• 主密钥保留在本地。 裸机环境：OS 密钥链。Docker：./agent-data/master.key（权限设为 600，并加入 gitignore）。

---

Agent 能做什么

Agent 有两类工具。运行 list_tools 可查看实时、权威的目录。

1. MangroveAI 工具（唯一可信来源）。 策略、回测、信号、市场数据、链上数据、知识库和 Strategy Engine 的所有内容都由 MangroveAI 提供。Agent 不会保留这些工具的副本：启动时，它会读取 MangroveAI 的实时 MCP 目录，并将每次调用转发到 MangroveAI 的 /mcp/ 端点；在 x402 钱包模式下按次付费，或使用你的 API 密钥。MangroveAI 添加或更改工具时，Agent 无需修改代码即可获取这些更新。

类别（示例，非固定列表）	MangroveAI 工具
策略构建	load_skill、build_strategy_for_regime、list_backtest_markets、save_strategy、update_strategy、verify_strategy、list_strategies、get_strategy
回测	run_backtest + get_backtest（已保存的策略）、get_backtest_trades、list_backtests、get_benchmark、screen_candidates
扫描结果	find_sweep_runs
信号与市场状态	list_signals、get_signal、search_signals、match_signals、query_signal_behavior、get_market_regime
市场、链上、DeFi、社交数据	get_ohlcv、get_market_data、get_trending、get_token_holders、get_smart_money_sentiment、get_chain_tvl、get_social_sentiment 等
知识库	kb_search、kb_glossary_get、kb_get_document、query_knowledge
市场	search_marketplace、get_marketplace_strategy
你的 MangroveAI 持仓与交易	list_positions、list_trades

2. 本地工具（仅你的设备能执行的操作）。 这些工具保留在 Agent 中，因为它们需要你的密钥、钱包或本地记录。

类别	工具
发现（免费）	status、list_tools
命名（本地，需要身份验证）	set_agent_name
支付演示	hello_mangrove（x402）
钱包与投资组合	create_wallet、import_wallet、list_wallets、get_balances、portfolio_value、portfolio_pnl、portfolio_tokens、portfolio_defi、portfolio_history
Kraken（CEX）	cex_status、cex_connect_kraken、cex_balances、cex_validate_order、cex_sync_fills
DEX（1inch）	list_dex_venues、get_swap_quote、execute_swap、get_tx_status、get_spot_price、get_gas_price、get_token_search、get_allowances、get_token_info、get_dex_chart
本地执行记录	agent_list_strategies、agent_get_strategy、agent_update_strategy_status、agent_evaluate_strategy、agent_list_evaluations、agent_list_trades、agent_list_all_trades
x402 支出预算	x402_spend_status、x402_spend_reset

本地工具还提供 /api/v1/agent/* 下的 REST 端点，并调用相同的服务层。MangroveAI 工具没有本地 REST 副本；请通过 Agent 的 MCP 端点调用，或直接调用 MangroveAI。需要身份验证的路由使用 X-API-Key，其值应为 server/src/config/local-config.json 中 API_KEYS 的第一项（由 setup.sh 生成的唯一密钥）。这是 Agent 自己的本地密钥，不是你的 MangroveAI API 密钥。/health、status 和 list_tools 无需密钥，因此即使密钥错误，看起来也一切正常，直到首次经过身份验证的调用返回 401。

回测与 Strategy Engine。 回测在 MangroveAI 上运行，绝不会在 Agent 中运行。对于已保存的策略，run_backtest 会提交回测任务，任务完成后，get_backtest 会读取结果。若要搜索 Strategy Engine 已经测量过的内容，请使用 find_sweep_runs。目前 MCP 不提供创建和启动新扫描的功能。深入了解：知识库中的 SIEVE 指南和 实验参考。

---

工作原理

┌─────────────────────────────────────────────────────────────┐
│  Your machine                                               │
│                                                             │
│  Claude Code ─MCP──┐                                        │
│  Python/curl ─REST─┤                                        │
│                    ▼                                        │
│  ┌─ mangrove-agent (single FastAPI process, port 9080) ──┐     │
│  │   • auth middleware (X-API-Key)                   │     │
│  │   • service layer (one for REST + MCP)            │     │
│  │   • APScheduler (in-process cron, SQLite jobstore)│     │
│  │   • local Fernet-encrypted wallets                │     │
│  └───────────────────────────────────────────────────┘     │
│           │                        │                        │
│           ▼                        ▼                        │
│  ┌── SQLite: agent.db ─┐  ┌── OS Keychain (Fernet key) ─┐  │
│  └─────────────────────┘  └──────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
              │                      │
              ▼                      ▼
    MangroveAI /mcp/ +        mangrovemarkets SDK
    mangroveai SDK            (DEX swap, portfolio,
    (every MangroveAI tool,    wallet)
     strategy evaluation)

策略评估在 mangroveai.execution.evaluate() 中进行——Agent 不会重新实现信号逻辑、风险门槛、头寸规模计算或冷却机制。它负责协调：获取策略 → 调用 SDK → 将返回的 OrderIntent[] 分派给执行器 → 记录日志。

对于实盘交易，Agent 会在进程内解密你的钱包密钥，使用 mangrovemarkets 返回的未签名交易进行签名，广播已签名的字节，并将密钥清零。SDK 永远不会接触你的密钥。

---

架构文档

文档	内容
docs/api-reference.md	我们调用的 Mangrove API 接口
docs/user-stories.md	18 个用户故事 + 4 个流程图
docs/specification.md	API 契约、Pydantic 模型、SQLite 架构、错误代码
docs/architecture.md	系统图、时序图、文件树
docs/implementation-plan.md	分 24 项任务的阶段性构建计划

开发

扩展 Agent——添加新端点、MCP 工具、信号或策略——请遵循 docs/contributing.md 中说明的服务层模式。策略创建和回测说明会通过 MCP load_skill 工具从 MangroveAI 实时加载。Agent 不会附带服务器技能或策略生成器的副本。贡献者技能保留在 .claude/skills/ 中。

测试

docker run --rm -v "$(pwd)/server:/app" -w /app -e ENVIRONMENT=test \
  $(docker compose build -q app && docker compose images -q app) \
  pytest tests/

也可以在运行中的容器内执行：

docker compose exec app pytest tests/

除了 2 个选择启用的实盘兑换测试会被跳过之外，其他测试都应通过。

要运行选择启用的实盘兑换测试：

# Testnet (Base Sepolia)
ENABLE_SEPOLIA_TEST=1 BASE_SEPOLIA_PRIVATE_KEY=0x... pytest tests/e2e/test_live_swap.py::test_sepolia_live_swap

# Mainnet — real funds; we tested at 0.10 USDC
ENABLE_MAINNET_TEST=1 BASE_MAINNET_PRIVATE_KEY=0x... pytest tests/e2e/test_live_swap.py::test_mainnet_live_swap

部署

v1 仅支持本地部署（Docker Compose）。云部署（使用持久化存储和 Cloud SQL 的 Cloud Run）已列入路线图，尚未发布。

项目结构

mangrove-agent/
├── .claude/                  # Claude Code framework (skills, agents, rules)
├── server/
│   ├── src/
│   │   ├── app.py            # FastAPI factory
│   │   ├── config/           # Per-env JSON configs
│   │   ├── api/routes/       # REST routes — one file per resource
│   │   ├── mcp/              # MCP tool registration
│   │   ├── models/           # Pydantic domain + DB models
│   │   ├── services/         # Business logic (wallet, strategy, executor, scheduler, trade_log, …)
│   │   └── shared/           # auth, db/sqlite.py, crypto/fernet.py, clients/mangrove.py, errors, logging
│   └── tests/                # unit / integration / e2e
├── docs/                     # Design docs (requirements, spec, architecture, plan)
├── scripts/verify_quickstart.sh
├── docker-compose.yml
├── .mcp.json.example         # Drop-in Claude Code MCP config
└── SAGE.md                   # Shared identity and operating instructions

许可证

MIT

Robinhood 执行场所

Mangrove 策略可以通过 Robinhood 官方 MCP 服务，将 Robinhood 用作经纪商执行场所。请参阅连接、资产分配和故障恢复说明。