Back to Details

zerion-trading

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zerion — Trading

Zerion — 交易

Execute on-chain trading actions: swap, bridge, send. All commands build, sign, and broadcast a transaction in one shot using the active agent token as the signer passphrase.
执行链上交易操作：兑换、跨链桥接、转账。所有命令会一次性完成交易构建、签名与广播，使用当前生效的agent token作为签名密码。

Setup

安装设置

If a 
zerion
command fails with 
command not found
, install once:
bash
npm install -g zerion-cli
Requires Node.js ≥ 20. For auth see the 
zerion
umbrella skill. All trading needs an API key + agent token. Pay-per-call (
--x402
, 
--mpp
) does NOT apply here.
如果执行
zerion
命令时提示
command not found
，请安装一次：
bash
npm install -g zerion-cli
要求Node.js ≥ 20。认证相关请查看
zerion
umbrella skill。所有交易都需要API密钥+agent token。按次付费（
--x402
、
--mpp
）不适用于此场景。

When to use

使用场景

  • "Swap X for Y" / "convert tokens" / "trade"
  • "Bridge X to chain Y" (cross-chain)
  • "Send tokens to address" (native ETH/SOL or ERC-20)
For balance checks before trading → 
zerion-analyze
. For setting up an agent token → 
zerion-agent-management
. For off-chain signing (permits, EIP-712) → 
zerion-sign
.
  • "将X兑换为Y" / "转换代币" / "交易"
  • "将X桥接到Y链"（跨链）
  • "向地址转账"（原生ETH/SOL或ERC-20代币）
交易前查询余额请使用→ 
zerion-analyze
。设置agent token请使用→ 
zerion-agent-management
。链下签名（许可、EIP-712）请使用→ 
zerion-sign
。

Pre-flight

预检查

bash
zerion wallet list                       # confirm wallet exists, see active policies
zerion agent list-tokens                 # confirm agent token is set
If no agent token, the CLI offers an inline create-token prompt on the next trade attempt (TTY only). In CI / piped contexts, see 
zerion-agent-management
.
bash
zerion wallet list                       # 确认钱包存在，查看生效策略
zerion agent list-tokens                 # 确认已设置agent token
如果没有agent token，CLI会在下次尝试交易时提供内置的创建token提示（仅TTY环境支持）。在CI/管道环境中，请查看
zerion-agent-management
。

Swap (same-chain)

兑换（同链）

Convert one token to another on the same chain. For cross-chain conversion use 
bridge
.
bash
undefined
在同一条链上将一种代币转换为另一种。跨链转换请使用
bridge
命令。
bash
undefined

zerion swap <chain> <amount> <from-token> <to-token>

zerion swap <链名> <数量> <源代币> <目标代币>

zerion swap base 1 USDC ETH zerion swap ethereum 0.1 ETH USDC zerion swap arbitrum 100 USDC DAI
zerion swap base 1 USDC ETH zerion swap ethereum 0.1 ETH USDC zerion swap arbitrum 100 USDC DAI

Solana same-chain swap

Solana同链兑换

zerion swap solana 0.1 SOL USDC
zerion swap solana 0.1 SOL USDC

Specific wallet (overrides defaultWallet)

指定钱包（覆盖默认钱包）

zerion swap base 1 USDC ETH --wallet <name>
zerion swap base 1 USDC ETH --wallet <名称>

Custom slippage (default 2%, max 3%)

自定义滑点（默认2%，最大3%）

zerion swap base 1 USDC ETH --slippage 3
zerion swap base 1 USDC ETH --slippage 3

Confirmation timeout (default 120s)

确认超时时间（默认120秒）

zerion swap base 1 USDC ETH --timeout 300

Tokens accepted as: symbol (`ETH`, `USDC`, `SOL`), 0x address (EVM), Solana mint, or full search match. Prefer the explicit address when the symbol is ambiguous.

```bash
zerion swap base 1 USDC ETH --timeout 300

代币支持以下格式：符号（`ETH`、`USDC`、`SOL`）、0x地址（EVM链）、Solana铸币地址或完整搜索匹配项。当符号存在歧义时，建议使用明确的地址。

```bash

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
undefined
zerion swap tokens # 所有链 zerion swap tokens base # 筛选Base链 zerion swap tokens solana # 筛选Solana链
undefined

Bridge (cross-chain)

跨链桥接

Move (and optionally swap) tokens between chains. Bridge with the same token on both sides for a pure transfer; pass a different 
to-token
for bridge + swap.
bash
undefined
在不同链之间转移（可选同时兑换）代币。如果两端使用同一种代币则为纯转账；传入不同的
to-token
则为桥接+兑换。
bash
undefined

zerion bridge <from-chain> <from-token> <amount> <to-chain> <to-token>

zerion bridge <源链> <源代币> <数量> <目标链> <目标代币>

Same-token bridge between EVM chains

EVM链间同代币桥接

zerion bridge base USDC 5 arbitrum USDC zerion bridge ethereum USDC 100 polygon USDC
zerion bridge base USDC 5 arbitrum USDC zerion bridge ethereum USDC 100 polygon USDC

Bridge + swap on destination

桥接+目标链兑换

zerion bridge base USDC 5 arbitrum ETH
zerion bridge base USDC 5 arbitrum ETH

Native token bridge

原生代币桥接

zerion bridge base ETH 0.001 optimism ETH
zerion bridge base ETH 0.001 optimism ETH

Bridge EVM → Solana (mnemonic wallet has both accounts → no extra flag needed)

EVM → Solana桥接（助记词钱包同时拥有两类账户→无需额外参数）

zerion bridge ethereum USDC 50 solana USDC
zerion bridge ethereum USDC 50 solana USDC

Bridge Solana → EVM

Solana → EVM桥接

zerion bridge solana USDC 50 ethereum USDC
zerion bridge solana USDC 50 ethereum USDC

Cross-format bridge to a different local wallet

跨格式桥接到另一个本地钱包

zerion bridge ethereum USDC 50 solana USDC --to-wallet <sol-wallet> zerion bridge solana USDC 50 ethereum USDC --to-wallet <evm-wallet>
zerion bridge ethereum USDC 50 solana USDC --to-wallet <Solana钱包名> zerion bridge solana USDC 50 ethereum USDC --to-wallet <EVM钱包名>

Bridge to a raw destination address (must match the target chain's format)

桥接到原始目标地址（必须匹配目标链的格式）

zerion bridge ethereum USDC 50 solana USDC --to-address <solana-pubkey> zerion bridge solana USDC 50 ethereum USDC --to-address 0x...
zerion bridge ethereum USDC 50 solana USDC --to-address <Solana公钥> zerion bridge solana USDC 50 ethereum USDC --to-address 0x...

Slippage / timeout flags work the same as swap

滑点/超时参数与兑换命令用法相同

zerion bridge base USDC 5 arbitrum ETH --slippage 3 --timeout 300
undefined
zerion bridge base USDC 5 arbitrum ETH --slippage 3 --timeout 300
undefined

Cross-chain destination rules

跨链目标规则

For Solana ↔ EVM bridges (different address formats), the destination receiver is resolved in this priority order:
  1. --to-address <addr>
    — raw recipient. Must match the target chain's format (
    0x…
    for EVM, base58 pubkey for Solana). ENS names allowed for EVM.
  2. --to-wallet <name>
    — local wallet whose corresponding account on the target chain is used.
  3. Fallback — the source wallet itself, if it has an account on the target chain (true for any mnemonic-derived wallet).
The destination wallet must have an account that satisfies the target chain. EVM-only wallets cannot receive on 
solana
; Solana-only wallets cannot receive on EVM chains.
If the API returns 
swap cannot be performed with the given parameters
, the route doesn't currently exist for the requested pair. Verify the token has implementations on both chains (
zerion search <symbol>
), try a different amount, and confirm both chains support bridging (
zerion chains
).
对于Solana ↔ EVM桥接（地址格式不同），目标接收方按以下优先级解析：
  1. --to-address <地址>
    — 原始接收地址。必须匹配目标链格式（EVM为
    0x…
    ，Solana为base58公钥）。EVM支持ENS名称。
  2. --to-wallet <名称>
    — 使用本地钱包在目标链上对应的账户。
  3. 回退方案 — 如果源钱包在目标链上有账户（所有助记词衍生钱包均满足此条件），则使用源钱包自身。
目标钱包必须拥有符合目标链要求的账户。仅支持EVM的钱包无法接收Solana链上的资产；仅支持Solana的钱包无法接收EVM链上的资产。
如果API返回
swap cannot be performed with the given parameters
，则当前请求的代币/链对暂无可用路由。请验证代币在两条链上均有部署（
zerion search <符号>
），尝试调整金额，并确认两条链均支持桥接（
zerion chains
）。

Send (transfer)

转账

Native + ERC-20 + native SOL transfers. 
--chain
is auto-inferred from the recipient address format when not passed (
0x…
→ ethereum default, base58 → solana).
bash
undefined
支持原生代币、ERC-20代币和原生SOL转账。未指定
--chain
时，会根据接收地址格式自动推断（
0x…
→默认以太坊，base58→Solana）。
bash
undefined

EVM: native + ERC-20

EVM：原生代币 + ERC-20代币

zerion send ETH 0.01 --to 0x... --chain base zerion send USDC 10 --to vitalik.eth --chain ethereum
zerion send ETH 0.01 --to 0x... --chain base zerion send USDC 10 --to vitalik.eth --chain ethereum

Solana: native SOL (chain auto-detected from base58 recipient)

Solana：原生SOL（链信息从base58接收地址自动检测）

zerion send SOL 0.1 --to 2Nsnn… zerion send SOL 0.1 --to 2Nsnn… --chain solana # explicit form

Recipients accepted: 0x address (EVM), ENS name (resolved at send time), Solana base58 pubkey. SPL token sends on Solana are not yet supported via the CLI — convert to SOL first with `zerion swap solana <amount> <token> SOL`.
zerion send SOL 0.1 --to 2Nsnn… zerion send SOL 0.1 --to 2Nsnn… --chain solana # 显式指定链

接收方支持：0x地址（EVM）、ENS名称（转账时解析）、Solana base58公钥。目前CLI暂不支持Solana上的SPL代币转账——请先通过`zerion swap solana <数量> <代币> SOL`转换为SOL。

Token search (resolve symbols → addresses)

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

bash
zerion search <query>                    # by name, symbol, or address
zerion search PEPE --chain ethereum
zerion search "uniswap" --limit 5
bash
zerion search <查询词>                    # 按名称、符号或地址搜索
zerion search PEPE --chain ethereum
zerion search "uniswap" --limit 5

Chain validation

链验证

bash
zerion chains                            # full chain catalog
Use this to confirm a chain ID is supported before passing 
--chain
/ 
--to-chain
/ 
--from-chain
.
bash
zerion chains                            # 完整链目录
在指定
--chain
/
--to-chain
/
--from-chain
前，请使用此命令确认链ID是否受支持。

Output & global flags

输出与全局参数

FlagDescription
--wallet <name>
Source wallet (default: from config)
--to-wallet <name>
Destination wallet for 
bridge
(Solana ↔ EVM)
--to-address <addr>
Destination address for 
bridge
(chain-format must match destination chain)
--to <addr>
Recipient address for 
send
--slippage <pct>
Slippage tolerance (default 2%, max 3%)
--timeout <sec>
Confirmation timeout (default 120s)
--json
/ 
--pretty
/ 
--quiet
Output mode (JSON default)
参数描述
--wallet <名称>
源钱包（默认：配置中的钱包）
--to-wallet <名称>
bridge
命令的目标钱包（Solana ↔ EVM）
--to-address <地址>
bridge
命令的目标地址（格式必须匹配目标链）
--to <地址>
send
命令的接收地址
--slippage <百分比>
滑点容忍度（默认2%，最大3%）
--timeout <秒>
确认超时时间（默认120秒）
--json
/ 
--pretty
/ 
--quiet
输出模式（默认JSON）

Pre-trade safety checklist

交易前安全检查清单

  1. Confirm the agent token is bound to the right wallet — 
    zerion agent list-tokens
    shows wallet bindings.
  2. Confirm policy allows the action — 
    zerion agent list-policies
    (e.g. 
    --deny-transfers
    blocks raw 
    send
    ; 
    --chains base
    blocks swaps on other chains).
  3. Slippage — defaults to 2%. Tight (0.5%) for stable pairs, loose (3-5%) for low-liquidity tokens.
  4. Cross-chain timeout — bridges can take 1-5 min. Use 
    --timeout 300
    for slower routes.
  1. 确认agent token绑定到正确的钱包 — 
    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
    。

Common errors

常见错误

CodeCauseFix
no_agent_token
Trading needs an agent token
zerion-agent-management
skill
policy_denied
Action blocked by an active policyCheck 
agent show-policy <id>
; revise or use unrestricted token
unsupported_chain
Invalid chain
zerion chains
insufficient_balance
Not enough of 
<from-token>
zerion portfolio --wallet <name>
to check
quote_failed
No route between tokens / chainsTry a different pair or chain
slippage_exceeded
Price moved beyond 
--slippage
Increase slippage or retry
tx_timeout
Confirmation didn't land within 
--timeout
Bump timeout, check tx hash on explorer
invalid_destination
Cross-chain destination missing or wrong formatPass 
--to-wallet <name>
or 
--to-address <addr>
matching the 
--to-chain
format
代码原因解决方法
no_agent_token
交易需要agent token使用
zerion-agent-management
技能
policy_denied
操作被生效策略阻止查看
agent show-policy <ID>
；修改策略或使用无限制token
unsupported_chain
无效链使用
zerion chains
查看支持的链
insufficient_balance
<源代币>
余额不足		使用
zerion portfolio --wallet <名称>
查看余额
quote_failed
代币/链之间无可用路由尝试其他代币对或链
slippage_exceeded
价格波动超出
--slippage
设置		提高滑点或重试
tx_timeout
未在
--timeout
时间内完成确认		增加超时时间，在区块链浏览器上查看交易哈希
invalid_destination
跨链目标缺失或格式错误指定
--to-wallet <名称>
或
--to-address <地址>
，需匹配
--to-chain
的格式