zerion-trading

Zerion — Trading

执行链上交易操作：兑换、跨链桥接、发送。所有命令都会一次性构建、签名并广播交易，使用当前 Agent 令牌作为签名密码。

Setup

如果 zerion 命令因 command not found 而失败，请安装一次：

npm install -g zerion-cli

需要 Node.js ≥ 20。有关身份验证，请参阅 zerion umbrella skill。所有交易都需要 API key + Agent 令牌。 按次付费（--x402、--mpp）不适用于此处。

When to use

• “将 X 兑换为 Y” / “转换代币” / “交易”
• “将 X 跨链桥接到 Y 链”（跨链）
• “向地址发送代币”（原生 ETH/SOL 或 ERC-20）

交易前检查余额 → zerion-analyze。设置 Agent 令牌 → zerion-agent-management。链下签名（许可、EIP-712）→ zerion-sign。

Pre-flight

zerion wallet list                       # confirm wallet exists, see active policies
zerion agent list-tokens                 # confirm agent token is set

如果没有 Agent 令牌，CLI 会在下次尝试交易时提供内联创建令牌提示（仅限 TTY）。在 CI / 管道环境中，请预先使用 zerion agent create-token --passphrase-file <0600-path> 创建令牌——参见 zerion-agent-management。

Swap (same-chain)

在同一条链上将一种代币兑换为另一种。跨链转换请使用 bridge。

# zerion swap <chain> <amount> <from-token> <to-token>
zerion swap base 1 USDC ETH
zerion swap ethereum 0.1 ETH USDC
zerion swap arbitrum 100 USDC DAI
zerion swap monad 1 USDC MON

# Solana same-chain swap
zerion swap solana 0.1 SOL USDC

# Specific wallet (overrides defaultWallet)
zerion swap base 1 USDC ETH --wallet <name>

# Custom slippage (default 2%, max 3%)
zerion swap base 1 USDC ETH --slippage 3

# Confirmation timeout (default 120s)
zerion swap base 1 USDC ETH --timeout 300

可接受的代币格式：符号（ETH、USDC、SOL）、0x 地址（EVM）、Solana mint，或完整搜索匹配结果。符号有歧义时，优先使用明确地址。

# List swap-available tokens for a chain
zerion swap tokens                       # all chains
zerion swap tokens base                  # filter to Base
zerion swap tokens solana                # filter to Solana
zerion swap tokens monad                 # filter to Monad

Bridge (cross-chain)

在不同链之间转移（并可选择兑换）代币。若只需转账，请在两侧使用相同代币；若要跨链桥接并兑换，请传入不同的 to-token。

提供方选择：

标志	行为
(无), 多个报价	列出所有报价（提供方、输出、时间、费用）后退出。不会签署交易。
(无), 单个报价	自动执行唯一可用路线（无需选择）。
--cheapest	执行输出最高的报价（与旧版自动执行行为一致）。
--fast	执行耗时最低的报价（estimated_time_seconds）。如果没有报价包含时间数据，则回退到 --cheapest。

规则：

• 不允许同时使用 --fast 和 --cheapest。
• 支持的标志形式：裸 --fast（必须放在命令行末尾，以免 parseFlags 将后续位置参数当作其值）、--fast=true / --fast=false，以及 --no-fast（等同于 --fast=false）。--cheapest 也支持相同形式。其他形式（例如 --fast=cheapest、--fast arbitrum）会报错，返回 invalid_flag_value。
• --slippage 会经过验证：必须是介于 0 到 100 之间的数字。--slippage=abc、--slippage=2abc、--slippage=-5、--slippage=200 都会因 invalid_slippage 而被拒绝。采用严格数字解析，不接受部分字符串匹配。

# zerion bridge <from-chain> <from-token> <amount> <to-chain> <to-token> [--fast | --cheapest]

# List all bridge providers (no execution) — agent can compare and choose
zerion bridge base USDC 5 arbitrum USDC

# Same-token bridge — execute the cheapest (highest output) route
zerion bridge base USDC 5 arbitrum USDC --cheapest
zerion bridge ethereum USDC 100 polygon USDC --cheapest
zerion bridge base USDC 10 monad USDC --cheapest

# Execute the fastest route (lowest estimated_time_seconds)
zerion bridge base USDC 5 arbitrum USDC --fast

# Bridge + swap on destination
zerion bridge base USDC 5 arbitrum ETH --cheapest
zerion bridge base USDC 5 monad MON --cheapest

# Native token bridge
zerion bridge base ETH 0.001 optimism ETH --cheapest

# Bridge EVM → Solana (mnemonic wallet has both accounts → no extra flag needed)
zerion bridge ethereum USDC 50 solana USDC --cheapest

# Bridge Solana → EVM
zerion bridge solana USDC 50 ethereum USDC --cheapest

# Cross-format bridge to a different local wallet
zerion bridge ethereum USDC 50 solana USDC --to-wallet <sol-wallet> --cheapest
zerion bridge solana USDC 50 ethereum USDC --to-wallet <evm-wallet> --cheapest

# Bridge to a raw destination address (must match the target chain's format)
zerion bridge ethereum USDC 50 solana USDC --to-address <solana-pubkey> --cheapest
zerion bridge solana USDC 50 ethereum USDC --to-address 0x... --cheapest

# Slippage / timeout flags work the same as swap (strategy flag still last)
zerion bridge base USDC 5 arbitrum ETH --slippage 3 --timeout 300 --cheapest

Cross-chain destination rules

对于 Solana ↔ EVM 跨链桥接（地址格式不同），目标接收方按以下优先级解析：

1. --to-address <addr> — 原始收款地址。必须符合目标链的格式（EVM 使用 0x…，Solana 使用 base58 公钥）。EVM 支持 ENS 名称。
2. --to-wallet <name> — 使用本地钱包在目标链上的对应账户。
3. 回退 — 如果源钱包在目标链上有账户，则使用该钱包本身（任何由助记词派生的钱包都符合此条件）。

目标钱包必须拥有符合目标链要求的账户。仅支持 EVM 的钱包无法在 solana 上收款；仅支持 Solana 的钱包无法在 EVM 链上收款。

如果 API 返回 swap cannot be performed with the given parameters，表示当前不存在所请求交易对的路线。请确认代币在两条链上都有实现（zerion search <symbol>），尝试其他金额，并确认两条链都支持跨链桥接（zerion chains）。

发送（转账）

支持原生代币、ERC-20 和原生 SOL 转账。未传入 --chain 时，会根据收款地址格式自动推断链（0x… → 默认 ethereum，base58 → solana）。

# EVM: native + ERC-20
zerion send ETH 0.01 --to 0x... --chain base
zerion send USDC 10 --to vitalik.eth --chain ethereum
zerion send MON 0.5 --to 0x... --chain monad
zerion send USDC 10 --to 0x... --chain monad

# Solana: native SOL (chain auto-detected from base58 recipient)
zerion send SOL 0.1 --to 2Nsnn…
zerion send SOL 0.1 --to 2Nsnn… --chain solana   # explicit form

接受的收款方：0x 地址（EVM）、ENS 名称（发送时解析）、Solana base58 公钥。Solana 上的 SPL 代币暂不支持通过 CLI 发送——请先运行 zerion swap solana <amount> <token> SOL 将其兑换为 SOL。

代币搜索（将符号解析为地址）

zerion search <query>                    # by name, symbol, or address
zerion search PEPE --chain ethereum
zerion search MON --chain monad
zerion search "uniswap" --limit 5

链验证

zerion chains                            # full chain catalog

使用此命令可在传入 --chain / --to-chain / --from-chain 前，确认支持相应的链 ID。

输出和全局标志

标志	描述
--wallet <name>	源钱包（默认：来自配置）
--to-wallet <name>	bridge 的目标钱包（Solana ↔ EVM）
--to-address <addr>	bridge 的目标地址（格式必须与目标链匹配）
--to <addr>	send 的收款地址
--slippage <pct>	滑点容差（默认 2%，最大 3%）
--timeout <sec>	确认超时时间（默认 120s）
--json / --pretty / --quiet	输出模式（默认 JSON）

交易前安全检查清单

1. 确认 Agent 令牌绑定到正确的钱包 — zerion agent list-tokens 会显示钱包绑定信息。
2. 确认策略允许此操作 — zerion agent list-policies（例如，--deny-transfers 会阻止原始 send；--chains base 会阻止在其他链上兑换）。
3. 滑点 — 默认值为 2%。稳定币交易对使用较低滑点（0.5%），低流动性代币使用较高滑点（3-5%）。
4. 跨链超时 — 桥接可能需要 1-5 分钟。对于较慢的路由，请使用 --timeout 300。

常见错误

代码	原因	解决方法
no_agent_token	交易需要 Agent 令牌	使用 zerion-agent-management skill
policy_denied	活跃策略阻止了此操作	检查 agent show-policy <id>；修改策略或使用不受限制的令牌
unsupported_chain	链无效	运行 zerion chains
insufficient_balance	<from-token> 余额不足	运行 zerion portfolio --wallet <name> 进行检查
quote_failed	代币或链之间没有可用路由	尝试其他交易对或链
slippage_exceeded	价格变动超过 --slippage	提高滑点或重试
tx_timeout	未能在 --timeout 时间内完成确认	增加超时时间，并在区块浏览器上检查交易哈希
invalid_destination	缺少跨链目标地址或格式错误	传入与 --to-chain 格式匹配的 --to-wallet <name> 或 --to-address <addr>