zerion

Zerion

面向 14 条 EVM 链和 Solana 上加密钱包的统一 API + CLI。zerion 二进制文件通过 npm 分发；此技能是所有 Zerion 功能的入口。功能和合作伙伴文档位于嵌套文件中，并按需加载。

设置——操作前先检查

技能会调用 zerion 二进制文件。每个设置步骤都可重复执行，因此请先检查，只处理缺少的部分：

zerion --version     # needs 1.11.0+ — older CLIs ignore --quote and run the swap or bridge instead of pricing it
zerion wallet list   # which wallets exist, and whether the user's address is one of them

• 未找到 zerion，或版本低于 1.11.0 → 执行 npx -y zerion-cli@latest init -y。该命令会安装或升级 CLI 和此技能，保留现有登录状态和钱包，并且不会阻塞。
• 没有 API 密钥——init 报告 "next": "zerion login --browser"，或命令失败并提示 missing_api_key → 在后台运行 zerion login --browser：它最多等待 5 分钟，让用户批准。立即向用户显示它输出到 stderr 的 URL，并在等待期间继续进行只读研究。
• 用户提供的钱包地址未显示在 wallet list 中 → 以只读方式注册：zerion wallet add <address> --name <name>。这不需要私钥、口令或 Agent 令牌——所有交易都会发送到 app.zerion.io，由用户签名。
• 命令失败并提示 unsupported_node → 用户的 Node.js 版本过旧（最低要求见下文）。按照错误提示告知用户升级；不要修补依赖项，也不要构建变通软件包。
• 无法运行 shell 命令 → 如实说明，不要猜测。
• 沙盒 Agent（例如 Codex 的默认沙盒）：init 和 login 需要网络访问，并会在工作区外写入内容（全局 npm 安装、~/.zerion），因此请申请相应权限，不要绕过限制。

需要 Node.js ≥ 22.12（或 Node 20 上的 ≥ 20.19）。npm 软件包名为 zerion-cli；安装后的二进制文件为 zerion。

身份验证

有三种模式。分析时任选一种；交易始终使用 API 密钥。

A) API 密钥（推荐）

zerion login --browser               # approve in the browser; the key is saved to config
export ZERION_API_KEY="zk_dev_..."   # or set one you already have

在 dashboard.zerion.io 获取密钥。开发密钥以 zk_dev_ 开头。限额：120 次请求/分钟，5K 次请求/天。

B) x402 按次付费（无需注册，仅限分析）

通过 x402 协议按次支付 $0.01 USDC。支持 EVM（Base）或 Solana。

export WALLET_PRIVATE_KEY="0x..."     # EVM (Base) — 0x-prefixed hex
export WALLET_PRIVATE_KEY="5C1y..."   # Solana — base58 keypair
zerion portfolio <address> --x402

# Or enable globally
export ZERION_X402=true

同时使用两条链：

export EVM_PRIVATE_KEY="0x..."
export SOLANA_PRIVATE_KEY="5C1y..."
export ZERION_X402_PREFER_SOLANA=true   # optional

C) MPP 按次付费（仅限分析，EVM Tempo）

通过 MPP 在 Tempo 上按次支付 $0.01 USDC。

export TEMPO_PRIVATE_KEY="0x..."      # or reuse WALLET_PRIVATE_KEY
zerion portfolio <address> --mpp

# Or enable globally
export ZERION_MPP=true

交易命令（swap、bridge、send）始终使用 API 密钥，不受 ZERION_X402 / ZERION_MPP 影响。本地签名也需要 Agent 令牌；只读钱包可在 Web 应用中签名，无需令牌。

功能 — 按需加载

执行以下任何功能前，请先阅读对应文件，了解完整的命令、标志、边缘情况和示例。

任务	阅读
钱包分析：投资组合、持仓、历史记录、PnL、自选列表	capabilities/analyze.md
链上交易：兑换、跨链桥、发送	capabilities/trading.md
在浏览器中进行人工审核：只读钱包、审核阈值、--review	capabilities/trading.md § "Signing routes & web-app handoff"
将多项操作打包到一个签名会话／一次审核中（--prepare + bundle）	capabilities/bundle.md
链下签名：EIP-191 消息、EIP-712 类型化数据	capabilities/sign.md
钱包管理：创建、导入、添加只读钱包、列出、充值、审核阈值、备份、导出密钥、删除	capabilities/wallet.md
Agent 令牌 + 自主交易安全策略	capabilities/agent-management.md
0x Swap API v2（直接集成、Permit2/AllowanceHolder、免 Gas）	capabilities/swap-0x.md
退出 DeFi 持仓：提现、取消质押、赎回、领取奖励、还款	capabilities/defi-exit.md

组合多项功能的请求 — 将请求拆分为多个步骤，并阅读每个步骤对应的文件。“退出我的所有持仓并在 Blast 上卖出代币，然后把所有资产转到 Ethereum”对应 analyze.md（查明资产情况）→ defi-exit.md（协议操作）→ trading.md（在 Blast 上兑换，然后跨链）→ bundle.md（每个步骤使用一个签名会话）。

配合规则：

• 本地签名需要 Agent 令牌 → 如果用户没有令牌，请先参阅 capabilities/agent-management.md。只读钱包（wallet add）会在 Web 应用中签署每笔交易，无需令牌。
• 交易前先运行分析，核实余额和持仓。

每项链上任务都必须遵循的规则

这些规则适用于任何会以交易结束的操作——无论是单次兑换、退出 DeFi 持仓，还是“在 Blast 上卖出所有资产并转到 Ethereum”。

读取状态

• 用户的请求决定操作范围；CLI 是该范围内现有资产及其数量的准确信息来源。不要仅仅因为读取结果中出现了用户未提及的持仓或代币，就对其采取操作。如果用户指定的资产不存在，请告知用户。使用 --chain、--defi 或 --positions 限定读取范围，而不是导出整个投资组合。
• 对于任何要交易的数量，都要在链上读取精确的原始余额（eth_call → balanceOf），绝不要使用 positions 返回的四舍五入数值——向上取整的数量会在最后一个 wei 处导致交易回滚。如果已设置 $ETH_RPC_URL，就使用它；否则按顺序尝试 zerion chains --json 中该链的 rpcUrls，跳过任何返回错误或其 eth_chainId 与该链的 chainIdHex 不匹配的端点。这些都是公共端点，无需密钥。发送类似浏览器的 User-Agent，因为某些公共端点会拒绝默认值。如果没有任何端点响应，请说明无法读取该链，而不要自行选择 RPC。
• 告知用户某条链无法执行某项操作前，先检查 zerion chains。 Gas 与所得款项——生成任何签名链接之前
• 对每项操作，合计所有步骤的 Gas（approve、claim 和 swap 都会消耗 Gas）：在真实调用上使用 eth_estimateGas × 当前费用 × CLI 输出中的原生代币价格。将结果与扣除 swap 费用和价格影响后实际回到钱包的金额比较。
• 使用 zerion swap <chain> <amount> <from> <to> --quote 为兑换报价，使用 zerion bridge … --quote 为跨链转移报价（它会列出所有路线，且绝不会执行，即使只有一条路线也一样）。即使钱包尚未持有输入代币（例如 claim 将发放的代币），这两个命令也能使用：它会报告 enoughBalance: false，并给出一个不包含网络 Gas 和协议费用的参考价格，因此要为这两项预留空间。不要导入 CLI 内部模块，也不要用他人的地址报价来获取更完整的数字。
• 所得款项明显高于 Gas → 继续操作。Gas 与所得款项相当或更高 → 停止并询问：用美元列出每项的 Gas、所得款项和剩余金额，在一条消息中列出所有不合算的项目，然后等待。不要悄悄跳过，也不要悄悄继续。
• 使用 eth_call 证明每笔交易都会转移价值，并跳过无操作（说明跳过的项目及原因）。如果某个代币没有可用交易场所：说明这一点并停止——不要对持续失败的报价重试。

构建交易

• Swap、bridge 和 transfer 都通过 zerion swap / bridge / send 执行——这些命令会报价、定价、设置滑点并处理授权。绝不要将 swap、transfer 或 approve 编码为原始 calldata，也绝不要自行调用 DEX 或聚合器 API：报价和交易必须来自同一条路线。
• 只有命令未覆盖的协议专属调用（withdraw、unstake、redeem、claim、repay）才手动构建——参见 capabilities/defi-exit.md。
• 每次执行 swap、bridge 和 send 时，都要明确传入 --wallet <name>，包括用于生成 bundle 的 --prepare 执行。绝不要依赖默认钱包。（bundle 本身会从每个组的 address 获取签名者。）
• 卖出全部余额：按略低于链上精确数量的金额报价（截断，绝不向上取整），并接受剩余的零头。
• 除非用户另有说明，否则滑点设置为：稳定币兑换稳定币使用 --slippage 0.3，其他情况使用 --slippage 1。
• 使用 zerion bundle 批量处理相关交易，让用户只需签名一次（capabilities/bundle.md）。如果某个步骤要花费前一步带来的代币，就不能将它加入同一批次：--prepare 和 bundle 检查的是钱包当前余额，而非未来流入的资金。先发送前一步，等待其在链上确认，然后再准备下一步。 签名
• 对于网页应用路线（只读钱包、审核阈值、--review），签名链接不会执行任何操作——用户的签名就是批准。在同一条消息中展示方案和链接；不要停下来先询问。上面的 Gas 检查是唯一的例外。对于本地路线，CLI 会立即签名并广播，因此运行前必须确认方案无误。
• 分享网页应用链接时，告诉用户会发生什么：链接会打开 app.zerion.io，在用户进行任何操作之前显示完整的审核信息（签名地址、余额变化、费用、安全检查），然后在尚未连接钱包时提示其连接钱包。连接的钱包必须拥有该签名地址，因为交易只能由该地址发起。
• swap、bridge、send 和 bundle 会将链接输出到 stderr，然后阻塞等待签名，最长 300 s。在后台运行它们，几秒内读取链接，并立即展示。
• swap、bridge 和 send 会在签名前向 stderr 输出 Signing route: <route> — <reason>；bundle 会输出 Bundle route: <route>。没有这类行 → 命令还没执行到那一步；请修复命令。
• timeout 或 rejected 仅表示 CLI 停止了监听——用户可能之后才签名。重新生成任何内容之前，先在链上检查（余额、授权额度、近期交易）。不要等待 Zerion 的索引器；它会延迟几分钟。
• 链接属于输出它的那次运行。该次运行结束后，不要再次分享它的链接：CLI 已不再监听结果，但交易仍包含在链接中，因此仍可能被签名。如果链上没有显示交易成功，请重新运行命令以生成新链接，并告知用户只签署新链接——同时签署两者可能会导致操作执行两次。
• 多步骤流程：某一步一旦在链上确认，就立即为下一步报价并发送其链接，不要等用户询问。
• 绝不要自行编写 app.zerion.io 链接。只有 CLI 能生成有效链接——交易包含在 URL 片段中。如果命令失败，请修复命令。

范围

• 只做用户要求的事。你发现的其他事项——值得退出的其他头寸、闲置余额——都只是建议：列出来，然后等待。不要为用户未选择的事项生成链接；选择一项不代表也选择了其他事项。
• 分别标明贷款和杠杆头寸：解除其中一项会改变健康因子，并可能危及其余头寸。

签名路径 — 交易不一定在本地签名

每笔交易和每条消息的签名都采用以下两种路径之一，系统会在签名前自动决定：

• 本地签名（默认） — CLI 使用 Agent 令牌作为口令进行签名并广播。一次完成，无需人工干预。
• 网页应用交接 — CLI 将交易编码到 app.zerion.io 链接中，打开浏览器，并阻塞等待人工在网页应用中签名（默认等待 300 s）。URL 也会打印到 stderr，因此无头 Agent 可以将其交给用户，而不必依赖浏览器自动打开。

出现以下任一情况时会触发交接——执行交易前请务必了解这一点，因为这会影响命令能否在无人值守的情况下完成：

触发条件	设置方式
只读钱包（无密钥材料）	zerion wallet add <address|ens> --name <name>
卖出金额的 USD 价值超过钱包的审核阈值——仅适用于交易	zerion wallet set-review-threshold <wallet> <usd|off>
显式强制审核	在命令中使用 --review

消息没有 USD 价值，因此 sign-message / sign-typed-data 会忽略阈值——此处仅适用只读钱包和 --review 触发条件（capabilities/sign.md）。

每笔交易中，CLI 都会将 Signing route: <route> — <reason> 打印到 stderr；JSON 输出中则包含 signedVia: "local" | "web-app"，因此你始终可以判断采用了哪条路径。交接会以 completed / rejected / failed / timeout 结束（或在按下 Ctrl-C 时以 aborted 结束），并在同一 JSON 中通过 status 报告：只有 completed 会以 0 退出，其他结果都会以非零状态退出，并输出结构化的 stderr 错误——请据此规划无人值守运行。

例外情况是 consolidate --execute：它始终在本地签名，不会查询签名路径，因为归集操作包含 N 笔相互独立的交易，而阈值是针对单笔交易设置的上限。因此它需要密钥材料——在只读钱包上，每一行操作都会失败。若要通过审核流程处理整个归集操作，请改用 zerion bundle --group "$(zerion consolidate <chain> <token> --prepare)"。

详情请参阅 capabilities/trading.md；有关只读钱包和阈值的信息，请参阅 capabilities/wallet.md。

合作伙伴集成 — 选择启用

这些集成基于核心 CLI 提供专用工作流。用户必须指明合作伙伴名称（或描述与某个合作伙伴对应的工作流）。然后读取 partners/<name>.md。

合作伙伴	功能	阅读
Bankr	Twitter/X 原生交易机器人模式	partners/bankr.md
Li.Fi Earn	跨链收益路由	partners/lifi-earn.md
Monad addresses	Monad 链地址工具	partners/monad-addresses.md
Moonpay (onramp)	法币 → 加密货币入金	partners/moonpay-onramp.md
Moonpay (Iron)	Iron 稳定币工作流	partners/moonpay-iron.md
Moonpay (Predict)	预测市场集成	partners/moonpay-predict.md
Sendai ideas	加密货币创意发现与验证、竞争对手分析、DeFi TVL 研究	partners/sendai-ideas.md
Somnia (blockchain)	Somnia L1 运维	partners/somnia-blockchain.md
Somnia (reactivity)	Somnia 响应式智能合约	partners/somnia-reactivity.md
Trails (cross-chain swap)	跨链兑换路由	partners/trails-crosschainswap.md
Trails (deposit)	跨链存款工作流	partners/trails-deposit.md
Umbra	私密（隐身地址）转账	partners/umbra-privatetxn.md
Uniswap LP	流动性头寸管理	partners/uniswap-lp.md
Uniswap x402	使用 x402 按调用付费进行兑换	partners/uniswap-x402.md
Vaults.fyi (deposit)	金库存款	partners/vaultsfyi-deposit.md
Vaults.fyi (market intel)	收益市场情报	partners/vaultsfyi-market-intel.md
Vaults.fyi (rebalance)	自动再平衡头寸	partners/vaultsfyi-rebalance.md
Vaults.fyi (risk monitor)	风险仪表板	partners/vaultsfyi-risk-monitor.md
Vaults.fyi (strategist)	多策略收益 Agent	partners/vaultsfyi-strategist.md
Vaults.fyi (watchlist)	金库观察列表	partners/vaultsfyi-watchlist.md
Vaults.fyi (yield optimizer)	收益优化	partners/vaultsfyi-yield-optimizer.md
Yellow	多方链下结算室	partners/yellow-settlement-room.md
Consolidate	将一条链上的所有代币归集到一个目标代币	partners/consolidate.md
Treasury liquidation	清空一个钱包在所有链上的资产，和／或将整个多链投资组合归集为一种代币	partners/treasury-liquidation.md

**规则：**切勿预先加载合作伙伴文档。只有在用户明确提及合作伙伴，或询问与某个合作伙伴唯一对应的工作流时，才读取相关文档。

如需编写新的合作伙伴集成，请读取 partner-skill-creator.md。

输出约定

所有命令均将 JSON 输出到 stdout（默认设置，便于 Agent 使用）。错误会以结构化 JSON 输出到 stderr：

{ "error": { "code": "missing_api_key", "message": "..." } }

标志：--json（默认）、--pretty（TTY 时自动启用）、--quiet。

支持的链

Zerion 支持 60+ 条链，并会持续增加。各链的功能有所不同：有些支持兑换 和 跨链桥 和 转账，另一些仅支持转账或读取。因此，zerion chains（或使用 zerion chains --json 查看 supportsTrading / supportsBridge / supportsSending 标志，以及每条 EVM 链的 chainId、chainIdHex 和公共 rpcUrls）才是权威信息来源。

⚠️ 绝不要根据下方静态列表告知用户某条链不受支持。 这只是一个快照，会随着新增链而过时。如果你需要的链未列在此处，或不确定它是否支持某项操作，请运行 zerion chains 并检查标志，不要就此停止。（这份仅包含 14 条链的列表曾导致一个 Agent 错误地报告称，robinhood、monad、hyperevm 及其他约 20 条已上线的链“无法通过 Zerion 转移”。）

实时目录快照（请使用 zerion chains 验证）：0g、abstract、ape、arbitrum、astar-zkevm、aurora、avalanche、base、berachain、binance-smart-chain、blast、bob、celo、cronos-zkevm、cyber、degen、ethereum、fantom、fraxtal、gravity-alpha、hyperevm、ink、katana、lens、linea、lisk、manta-pacific、mantle、megaeth、metis-andromeda、mode、monad、okbchain、opbnb、optimism、plasma、polygon、polygon-zkevm、polynomial、rari、re-al、redstone、robinhood、ronin、scroll、sei、solana、somnia、soneium、sonic、swellchain、taiko、tempo、tomochain、tron、unichain、wonder、world、xdai、xinfin-xdc、zero、zkcandy、zklink-nova、zksync-era、zora。

Solana 支持同链兑换，以及与 EVM 链之间的双向跨链桥。跨格式跨链桥（Solana ↔ EVM）需要通过 --to-wallet <name> 或 --to-address <addr> 显式指定目标，且目标格式必须与目标链匹配。

命令格式：

• 同链兑换：zerion swap <chain> <amount> <from-token> <to-token>
• 跨链桥：zerion bridge <from-chain> <from-token> <amount> <to-chain> <to-token>

完整标志参考请参阅 capabilities/trading.md。

使用 zerion chains 查看包含元数据的实时目录。

常见错误代码

代码	原因	解决方法
missing_api_key	未设置 ZERION_API_KEY	设置环境变量，或使用 --x402 进行分析
no_agent_token	没有用于交易/签名的 Agent 令牌	请参阅 capabilities/agent-management.md
no_wallet	未指定钱包，且没有默认钱包	使用 --wallet <name>，或设置 defaultWallet 配置
wallet_not_found	本地保险库中不存在该钱包	运行 zerion wallet list 检查
unsupported_chain	--chain 的值无效	运行 zerion chains 查看有效 ID
readonly_chain_mismatch	只读钱包的地址格式与显式请求的链不匹配	EVM（0x…）只读钱包无法在 Solana 上签名，反之亦然。读取命令无需使用 --chain
api_error 401	API 密钥无效	在 dashboard.zerion.io 检查密钥
api_error 429	请求频率受限	等待、降低频率，或切换到 x402

密钥管理

Keystore 钱包通过 Open Wallet Standard（OWS）保险库 ~/.ows/ 使用 AES-256-GCM 加密。私钥绝不会离开设备；使用本地路由时，签名在本地完成。Zerion API 无法看到密钥。

只读钱包完全不含密钥材料——仅在 ~/.zerion/readonly-wallets.json 中保存名称和地址——因此只能通过上述 Web 应用交接流程进行签名。

~/.zerion/config.json（模式为 0o600）用于存储 Agent 令牌、审核阈值、默认钱包、默认链和滑点设置。

资源

• API 文档：developers.zerion.io
• 控制面板：dashboard.zerion.io
• x402 协议：x402.org
• CLI 源码：github.com/zeriontech/zerion-ai