Back to Details

polygon-agent-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Polygon Agent CLI

Polygon Agent CLI

Prerequisites

前置要求

  • Node.js 20+
  • Run via npx: 
    npx @polygonlabs/agent-cli <command>
  • Storage: 
    ~/.polygon-agent/
    (AES-256-GCM encrypted)
  • Node.js 20+
  • 通过npx运行：
    npx @polygonlabs/agent-cli <command>
  • 存储路径：
    ~/.polygon-agent/
    （AES-256-GCM加密）

Session Initialization

会话初始化

Before running any commands, use the Read tool to check 
~/.polygon-agent/builder.json
:
  • If it exists — extract 
    accessKey
    from the JSON and export as plain shell vars (no 
    $()
    subshells):
    bash
    export SEQUENCE_PROJECT_ACCESS_KEY=<accessKey>
export SEQUENCE_INDEXER_ACCESS_KEY=$SEQUENCE_PROJECT_ACCESS_KEY
export TRAILS_API_KEY=$SEQUENCE_PROJECT_ACCESS_KEY
  • If it doesn't exist — the user hasn't completed setup yet. Proceed to Phase 1 (
    setup
    ) which will create the file.
运行任何命令前，使用读取工具检查
~/.polygon-agent/builder.json
：
  • 如果文件存在 — 从JSON中提取
    accessKey
    ，导出为普通shell变量（不要使用
    $()
    子shell）：
    bash
    export SEQUENCE_PROJECT_ACCESS_KEY=<accessKey>
export SEQUENCE_INDEXER_ACCESS_KEY=$SEQUENCE_PROJECT_ACCESS_KEY
export TRAILS_API_KEY=$SEQUENCE_PROJECT_ACCESS_KEY
  • 如果文件不存在 — 用户尚未完成设置，请进入阶段1（
    setup
    ）创建该文件。

Architecture

架构

WalletCreated byPurposeFund?
EOA
setup
Auth with Sequence BuilderNO
Ecosystem Wallet
wallet create
Primary spending walletYES
钱包创建方式用途需要充值？
EOA
setup
Sequence Builder身份验证否
Ecosystem Wallet
wallet create
主要消费钱包是

Environment Variables

环境变量

Required

必填

VariableWhen
SEQUENCE_PROJECT_ACCESS_KEY
Wallet creation, swaps, balance checks, Trails
One key, three names — 
SEQUENCE_INDEXER_ACCESS_KEY
and 
TRAILS_API_KEY
are the same value as 
SEQUENCE_PROJECT_ACCESS_KEY
. Set them all once:
bash
export SEQUENCE_PROJECT_ACCESS_KEY=<access-key-from-setup>
export SEQUENCE_INDEXER_ACCESS_KEY=$SEQUENCE_PROJECT_ACCESS_KEY
export TRAILS_API_KEY=$SEQUENCE_PROJECT_ACCESS_KEY
变量名适用场景
SEQUENCE_PROJECT_ACCESS_KEY
钱包创建、兑换、余额查询、Trails操作
一个密钥，三处使用 — 
SEQUENCE_INDEXER_ACCESS_KEY
和
TRAILS_API_KEY
的值与
SEQUENCE_PROJECT_ACCESS_KEY
完全相同，只需统一设置一次：
bash
export SEQUENCE_PROJECT_ACCESS_KEY=<access-key-from-setup>
export SEQUENCE_INDEXER_ACCESS_KEY=$SEQUENCE_PROJECT_ACCESS_KEY
export TRAILS_API_KEY=$SEQUENCE_PROJECT_ACCESS_KEY

Optional

选填

VariableDefault
SEQUENCE_ECOSYSTEM_CONNECTOR_URL
https://agentconnect.polygon.technology/
SEQUENCE_DAPP_ORIGIN
Same as connector URL origin
TRAILS_TOKEN_MAP_JSON
Token-directory lookup
POLYGON_AGENT_DEBUG_FETCH
Off — logs HTTP to 
~/.polygon-agent/fetch-debug.log
POLYGON_AGENT_DEBUG_FEE
Off — dumps fee options to stderr
变量名默认值
SEQUENCE_ECOSYSTEM_CONNECTOR_URL
https://agentconnect.polygon.technology/
SEQUENCE_DAPP_ORIGIN
与连接器URL的源站相同
TRAILS_TOKEN_MAP_JSON
代币目录查询表
POLYGON_AGENT_DEBUG_FETCH
关闭 — 开启后会将HTTP日志写入
~/.polygon-agent/fetch-debug.log
POLYGON_AGENT_DEBUG_FEE
关闭 — 开启后会将手续费选项输出到stderr

Complete Setup Flow

完整设置流程

bash
undefined
bash
undefined

Phase 1: Setup (creates EOA + Sequence project, returns access key)

阶段1：设置（创建EOA + Sequence项目，返回访问密钥）

polygon-agent setup --name "MyAgent"
polygon-agent setup --name "MyAgent"

→ save privateKey (not shown again), eoaAddress, accessKey

→ 保存privateKey（不会再次展示）、eoaAddress、accessKey

Phase 2: Create ecosystem wallet (auto-waits for browser approval)

阶段2：创建生态钱包（自动等待浏览器授权）

export SEQUENCE_PROJECT_ACCESS_KEY=<accessKey> polygon-agent wallet create --usdc-limit 100 --native-limit 5
export SEQUENCE_PROJECT_ACCESS_KEY=<accessKey> polygon-agent wallet create --usdc-limit 100 --native-limit 5

→ IMPORTANT: The command outputs an 
approvalUrl
. You MUST send the COMPLETE,

→ 重要提示：命令会输出一个
approvalUrl
。你必须将完整、未截断的URL发送给用户，等待用户在浏览器中打开并完成授权。

UNTRUNCATED URL to the user and wait for them to open it in a browser and approve.

在用户确认授权（或CLI自动检测到回调）前，不要进入下一步。钱包地址仅在授权完成后才会生成。

Do NOT proceed to the next step until the user confirms approval (or the CLI

阶段3：钱包充值

automatically detects the callback). The wallet address is only available after approval.

—

Phase 3: Fund wallet

—
polygon-agent fund
polygon-agent fund

→ reads walletAddress from session, builds Trails widget URL with toAddress=<walletAddress>

→ 从会话中读取walletAddress，构建Trails部件URL，toAddress参数自动设为<walletAddress>

→ ALWAYS run this command to get the URL — never construct it manually or hardcode any address

→ 必须运行此命令获取URL，不要手动构造或硬编码任何地址

→ send the returned 
fundingUrl
to the user; 
walletAddress
in the output confirms the recipient

→ 将返回的
fundingUrl
发送给用户，输出中的
walletAddress
可确认收款方信息

Phase 4: Verify (SEQUENCE_INDEXER_ACCESS_KEY is the same as your project access key)

阶段4：验证（SEQUENCE_INDEXER_ACCESS_KEY与你的项目访问密钥相同）

export SEQUENCE_INDEXER_ACCESS_KEY=$SEQUENCE_PROJECT_ACCESS_KEY polygon-agent balances
export SEQUENCE_INDEXER_ACCESS_KEY=$SEQUENCE_PROJECT_ACCESS_KEY polygon-agent balances

Phase 5: Register agent on-chain (ERC-8004, Polygon mainnet)

阶段5：在链上注册Agent（ERC-8004，Polygon主网）

polygon-agent agent register --name "MyAgent" --broadcast
polygon-agent agent register --name "MyAgent" --broadcast

→ mints ERC-721 NFT, emits agentId in Registered event

→ mint ERC-721 NFT，在Registered事件中返回agentId

→ use agentId for reputation queries and feedback

→ 可使用agentId查询声誉和反馈

undefined
undefined

Commands Reference

命令参考

Setup

设置

bash
polygon-agent setup --name <name> [--force]
bash
polygon-agent setup --name <name> [--force]

Wallet

钱包

bash
polygon-agent wallet create [--name <n>] [--chain polygon] [--timeout <sec>] [--no-wait]
  [--native-limit <amt>] [--usdc-limit <amt>] [--usdt-limit <amt>]
  [--token-limit <SYM:amt>]  # repeatable
  [--usdc-to <addr> --usdc-amount <amt>]  # one-off scoped transfer
  [--contract <addr>]  # whitelist contract (repeatable)
polygon-agent wallet import --ciphertext '<blob>|@<file>' [--name <n>] [--rid <rid>]
polygon-agent wallet list
polygon-agent wallet address [--name <n>]
polygon-agent wallet remove [--name <n>]
bash
polygon-agent wallet create [--name <n>] [--chain polygon] [--timeout <sec>] [--no-wait]
  [--native-limit <amt>] [--usdc-limit <amt>] [--usdt-limit <amt>]
  [--token-limit <SYM:amt>]  # 可重复
  [--usdc-to <addr> --usdc-amount <amt>]  # 一次性限定范围转账
  [--contract <addr>]  # 合约白名单（可重复）
polygon-agent wallet import --ciphertext '<blob>|@<file>' [--name <n>] [--rid <rid>]
polygon-agent wallet list
polygon-agent wallet address [--name <n>]
polygon-agent wallet remove [--name <n>]

Operations

操作

bash
polygon-agent balances [--wallet <n>] [--chain <chain>]
polygon-agent send --to <addr> --amount <num> [--symbol <SYM>] [--broadcast]
polygon-agent send-native --to <addr> --amount <num> [--broadcast] [--direct]
polygon-agent send-token --symbol <SYM> --to <addr> --amount <num> [--broadcast]
polygon-agent swap --from <SYM> --to <SYM> --amount <num> [--to-chain <chain>] [--slippage <num>] [--broadcast]
polygon-agent deposit --asset <SYM> --amount <num> [--protocol aave|morpho] [--broadcast]
polygon-agent fund [--wallet <n>] [--token <addr>]
polygon-agent x402-pay --url <url> --wallet <n> [--method GET] [--body <str>] [--header Key:Value]
bash
polygon-agent balances [--wallet <n>] [--chain <chain>]
polygon-agent send --to <addr> --amount <num> [--symbol <SYM>] [--broadcast]
polygon-agent send-native --to <addr> --amount <num> [--broadcast] [--direct]
polygon-agent send-token --symbol <SYM> --to <addr> --amount <num> [--broadcast]
polygon-agent swap --from <SYM> --to <SYM> --amount <num> [--to-chain <chain>] [--slippage <num>] [--broadcast]
polygon-agent deposit --asset <SYM> --amount <num> [--protocol aave|morpho] [--broadcast]
polygon-agent fund [--wallet <n>] [--token <addr>]
polygon-agent x402-pay --url <url> --wallet <n> [--method GET] [--body <str>] [--header Key:Value]

Agent (ERC-8004)

Agent (ERC-8004)

bash
polygon-agent agent register --name <n> [--agent-uri <uri>] [--metadata <k=v,k=v>] [--broadcast]
polygon-agent agent wallet --agent-id <id>
polygon-agent agent metadata --agent-id <id> --key <key>
polygon-agent agent reputation --agent-id <id> [--tag1 <tag>]
polygon-agent agent reviews --agent-id <id>
polygon-agent agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--broadcast]
ERC-8004 contracts (Polygon mainnet):
  • IdentityRegistry: 
    0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
  • ReputationRegistry: 
    0x8004BAa17C55a88189AE136b182e5fdA19dE9b63
bash
polygon-agent agent register --name <n> [--agent-uri <uri>] [--metadata <k=v,k=v>] [--broadcast]
polygon-agent agent wallet --agent-id <id>
polygon-agent agent metadata --agent-id <id> --key <key>
polygon-agent agent reputation --agent-id <id> [--tag1 <tag>]
polygon-agent agent reviews --agent-id <id>
polygon-agent agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--broadcast]
ERC-8004合约（Polygon主网）：
  • IdentityRegistry: 
    0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
  • ReputationRegistry: 
    0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

Key Behaviors

核心特性

  • Dry-run by default — all write commands require 
    --broadcast
    to execute
  • Smart defaults — 
    --wallet main
    , 
    --chain polygon
    , auto-wait on 
    wallet create
  • Fee preference — auto-selects USDC over native POL when both available
  • fund
     — reads 
    walletAddress
    from the wallet session and sets it as 
    toAddress
    in the Trails widget URL. Always run 
    polygon-agent fund
    to get the correct URL — never construct it manually or hardcode any address. The returned JSON contains 
    fundingUrl
    and 
    walletAddress
    so you can confirm the pre-filled recipient before sharing.
  • deposit
     — picks highest-TVL pool via Trails 
    getEarnPools
    . Important: 
    --usdc-limit
    restricts the USDC session to 
    transfer
    calls only, which blocks the 
    approve
    call that deposit requires. To use 
    deposit
    , omit 
    --usdc-limit
    and instead whitelist USDC via 
    --contract 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
    (unrestricted). Also add the protocol pool address via 
    --contract <depositAddress>
    .
  • x402-pay
     — probes endpoint for 402, smart wallet funds builder EOA with exact token amount, EOA signs EIP-3009 payment. Chain auto-detected from 402 response
  • send-native --direct
     — bypasses ValueForwarder contract for direct EOA transfer
  • Session permissions — without 
    --usdc-limit
    etc., session gets bare-bones defaults and may not transact
  • 默认试运行 — 所有写入操作都需要添加
    --broadcast
    才会实际执行
  • 智能默认值 — 默认
    --wallet main
    、
    --chain polygon
    ，
    wallet create
    命令默认等待授权
  • 手续费偏好 — 当USDC和原生POL都可用时，自动选择USDC支付手续费
  • fund
    命令     — 从钱包会话读取
    walletAddress
    ，自动设置为Trails部件URL的
    toAddress
    参数。必须运行
    polygon-agent fund
    获取正确的URL，不要手动构造或硬编码任何地址。返回的JSON包含
    fundingUrl
    和
    walletAddress
    ，你可以在分享前确认预填的收款方信息。
  • deposit
    命令     — 通过Trails的
    getEarnPools
    接口选择TVL最高的池子。重要提示：
    --usdc-limit
    会将USDC会话限制为仅允许
    transfer
    调用，会阻止deposit所需的
    approve
    调用。要使用
    deposit
    功能，请不要设置
    --usdc-limit
    ，改为通过
    --contract 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
    （无限制）将USDC加入白名单，同时通过
    --contract <depositAddress>
    添加协议池子地址。
  • x402-pay
    命令     — 探测端点是否返回402，智能钱包将精确金额的代币转入builder EOA，EOA签署EIP-3009支付。链信息会从402响应中自动识别
  • send-native --direct
     — 绕过ValueForwarder合约，直接通过EOA转账
  • 会话权限 — 如果没有设置
    --usdc-limit
    等参数，会话仅具备基础默认权限，可能无法执行交易

CRITICAL: Wallet Approval URL

重要提示：钱包批准URL

When 
wallet create
outputs a URL in the 
url
or 
approvalUrl
field, you MUST send the COMPLETE, UNTRUNCATED URL to the user. The URL contains cryptographic parameters (public key, callback token) that are required for session approval. If any part is cut off, the approval will fail.
  • Do NOT shorten, summarize, or add 
    ...
    to the URL
  • Do NOT split the URL across multiple messages
  • Output the raw URL exactly as returned by the CLI
当
wallet create
命令在
url
或
approvalUrl
字段输出URL时，你必须将完整、未截断的URL发送给用户。URL包含会话授权所需的加密参数（公钥、回调令牌），任何部分被截断都会导致授权失败。
  • 不要缩短、摘要URL，也不要在URL中添加
    ...
  • 不要将URL拆分到多条消息中
  • 完全按照CLI返回的原始内容输出URL

Callback Modes

回调模式

The 
wallet create
command automatically starts a local HTTP server and opens a Cloudflare Quick Tunnel (
*.trycloudflare.com
) — no account or token required. The 
cloudflared
binary is auto-downloaded to 
~/.polygon-agent/bin/cloudflared
on first use if not already installed. The connector UI POSTs the encrypted session back through the tunnel regardless of where the agent is running. The tunnel and server are torn down automatically once the session is received.
Timing: The 
approvalUrl
is only valid while the CLI process is running. Open it immediately and complete wallet approval within the timeout window (default 300s). Never reuse a URL from a previous run — the tunnel is torn down when the CLI exits.
Manual fallback (if cloudflared is unavailable): The CLI omits 
callbackUrl
so the connector UI displays the encrypted blob in the browser. The CLI then prompts:
text
After approving in the browser, the encrypted blob will be shown.
Paste it below and press Enter:
> <paste blob here>
The blob is also saved to 
/tmp/polygon-session-<rid>.txt
for reference. To import later:
bash
polygon-agent wallet import --ciphertext @/tmp/polygon-session-<rid>.txt
wallet create
命令会自动启动本地HTTP服务器，并开启Cloudflare Quick Tunnel（
*.trycloudflare.com
） — 无需账户或令牌。如果系统未安装
cloudflared
二进制文件，首次使用时会自动下载到
~/.polygon-agent/bin/cloudflared
。无论Agent运行在什么环境，连接器UI都会通过隧道将加密会话回传。收到会话后，隧道和服务器会自动关闭。
时效说明：
approvalUrl
仅在CLI进程运行期间有效，请立即打开并在超时窗口（默认300秒）内完成钱包授权。不要重复使用之前运行生成的URL — CLI退出时隧道就会被销毁。
手动降级方案（如果cloudflared不可用）：CLI会省略
callbackUrl
，连接器UI会在浏览器中展示加密blob。随后CLI会提示：
text
在浏览器中完成授权后，会展示加密blob。
请将其粘贴到下方后按回车：
> <paste blob here>
Blob也会保存到
/tmp/polygon-session-<rid>.txt
供后续参考。如需后续导入，运行：
bash
polygon-agent wallet import --ciphertext @/tmp/polygon-session-<rid>.txt

Troubleshooting

故障排查

IssueFix
Builder configured already
Add 
--force
Missing SEQUENCE_PROJECT_ACCESS_KEY
Run 
setup
first
Missing wallet
wallet list
, re-run 
wallet create
Session expired
Re-run 
wallet create
(24h expiry)
Fee option errors
Set 
POLYGON_AGENT_DEBUG_FEE=1
, ensure wallet has funds
Timed out waiting for callback
Add 
--timeout 600
callbackMode: manual
(no tunnel)		cloudflared unavailable — paste blob from browser when prompted; blob saved to 
/tmp/polygon-session-<rid>.txt
404
on 
*.trycloudflare.com
CLI timed out and tunnel is gone — re-run 
wallet create
, open the new 
approvalUrl
immediately
"Auto-send failed"
in browser		Copy the ciphertext shown below that message; run 
wallet import --ciphertext '<blob>'
Deposit session rejected
--usdc-limit
blocks 
approve
calls — omit it and use 
--contract 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 --contract <depositAddress>
instead
Wrong recipient in Trails widgetRun 
polygon-agent fund
(do not construct the URL manually); 
walletAddress
in the output confirms the pre-filled 
toAddress
问题解决方案
Builder configured already
添加
--force
参数
Missing SEQUENCE_PROJECT_ACCESS_KEY
先运行
setup
命令
Missing wallet
运行
wallet list
检查，重新执行
wallet create
Session expired
重新执行
wallet create
（会话有效期24小时）
Fee option errors
设置
POLYGON_AGENT_DEBUG_FEE=1
，确认钱包有足够余额
Timed out waiting for callback
添加
--timeout 600
参数
callbackMode: manual
（无隧道）		cloudflared不可用 — 按照提示粘贴浏览器返回的blob；blob已保存到
/tmp/polygon-session-<rid>.txt
访问
*.trycloudflare.com
返回
404
CLI已超时，隧道已销毁 — 重新执行
wallet create
，立即打开新生成的
approvalUrl
浏览器中提示
"Auto-send failed"
复制提示下方展示的密文；运行
wallet import --ciphertext '<blob>'
存入会话被拒绝
--usdc-limit
会阻止
approve
调用 — 不要设置该参数，改用
--contract 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359 --contract <depositAddress>
参数
Trails部件中的收款方错误运行
polygon-agent fund
获取URL（不要手动构造URL）；输出中的
walletAddress
可确认预填的
toAddress

File Structure

文件结构

text
~/.polygon-agent/
├── .encryption-key       # AES-256-GCM key (auto-generated, 0600)
├── builder.json          # EOA privateKey (encrypted), eoaAddress, accessKey, projectId
├── wallets/<name>.json   # walletAddress, session, chainId, chain
└── requests/<rid>.json   # Pending wallet creation requests
text
~/.polygon-agent/
├── .encryption-key       # AES-256-GCM密钥（自动生成，权限0600）
├── builder.json          # EOA privateKey（加密）、eoaAddress、accessKey、projectId
├── wallets/<name>.json   # walletAddress、session、chainId、chain
└── requests/<rid>.json   # 待处理的钱包创建请求