Polygon Agent

Polygon Agentic CLI

先决条件

• Node.js 20+
• 全局安装：npm install -g @polygonlabs/agent-cli（重新安装即可更新）
• 入口点：polygon-agent <command>
• 存储位置：~/.polygon-agent/（采用 AES-256-GCM 加密）

给 Agent 的说明：首次安装时，告知用户这是一次全局 npm 安装——它会将 polygon-agent CLI 安装到系统范围，使其可在任何终端中运行；某些环境可能需要 sudo；再次运行相同的命令即可更新；运行 npm uninstall -g @polygonlabs/agent-cli 可将其移除。仅在首次安装时说明一次。

如果命令因“Unknown argument”或“command not found”而失败

此技能与 CLI 版本绑定——不同版本的命令和标志可能有所不同。检查当前版本，与最新版本比较；如果版本较旧，请升级：

polygon-agent --version                        # currently installed
npm view @polygonlabs/agent-cli version        # latest published
npm install -g @polygonlabs/agent-cli@latest   # upgrade

架构

钱包	创建方式	用途	需要注资？
EOA	setup	使用 Sequence Builder 进行身份验证	否
Ecosystem Wallet	wallet create	主要支出钱包	是

环境变量

访问密钥——一个密钥，多种名称

SEQUENCE_PROJECT_ACCESS_KEY、SEQUENCE_INDEXER_ACCESS_KEY 和 TRAILS_API_KEY 都是同一个密钥——即在 setup 期间创建的 Sequence 项目访问密钥。CLI 会将它们视为别名，并自动依次尝试使用。

运行 setup 后，密钥会存储在 ~/.polygon-agent/builder.json 中。每次调用 CLI 时，都会将其载入环境变量——无需运行 export。在未设置环境变量的全新 Agent 会话中，只需运行命令，CLI 就会从磁盘读取凭据。

仅在需要覆盖已存储的值时（例如，指向其他项目）才手动设置这些变量：

export SEQUENCE_PROJECT_ACCESS_KEY=<key>  # also covers TRAILS_API_KEY and indexer calls

可选覆盖项

变量	默认值
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

完整设置流程

# Step 1: Setup (creates EOA + Sequence project, stores access key to disk)
polygon-agent setup --name "MyAgent"
# → saves privateKey (not shown again), eoaAddress, accessKey to ~/.polygon-agent/builder.json
# → all subsequent commands auto-load the access key from disk — no export needed

# Step 2: Create ecosystem wallet (opens browser, waits for 6-digit code)
# Aave V3 Pool is auto-whitelisted in all sessions. For Morpho or other DeFi vaults,
# add --contract flags as needed.
polygon-agent wallet create --usdc-limit 50 --native-limit 5 \
  --contract 0xc2132D05D31c914a87C6611C10748AEb04B58e8F \
  --contract 0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619 \
  --contract 0x781fb7f6d845e3be129289833b04d43aa8558c42 \
  --contract 0xf5c81d25ee174d83f1fd202ca94ae6070d073ccf \
  --contract 0x3f33f9f7e2d7cfbcbdf8ea8b870a6e3d449664c2
# → opens https://agentconnect.polygon.technology/link?rid=<rid>&...
# → user approves in browser, browser shows a 6-digit code
# → enter the 6-digit code in the terminal when prompted
# → session saved to ~/.polygon-agent/wallets/main.json
# → notify the user and send them to https://agentconnect.polygon.technology/?rid=<rid>
#   so they can fund their wallet with access to the session

# Step 3: Fund wallet
polygon-agent fund
# → reads walletAddress from session, builds Trails widget URL with toAddress=<walletAddress>
# → ALWAYS run this command to get the URL — never construct it manually or hardcode any address
# → send the returned `fundingUrl` to the user; `walletAddress` in the output confirms the recipient

# Step 4: Verify balances
polygon-agent balances

# Step 5: Register agent on-chain (ERC-8004, Polygon mainnet only)
polygon-agent agent register --name "MyAgent" --broadcast
# → mints ERC-721 NFT, emits Registered event containing agentId
# → retrieve agentId: open the tx on https://polygonscan.com, go to Logs tab,
#   find the Registered event — agentId is the first indexed parameter
# → use agentId for reputation queries, reviews, and feedback

用例技能

对于特定工作流，请在尝试执行任务之前获取并加载相关子技能：

用例	技能 URL
Polymarket 预测市场交易	https://agentconnect.polygon.technology/polygon-polymarket/SKILL.md
DeFi——兑换、存款、取款、收益	https://agentconnect.polygon.technology/polygon-defi/SKILL.md
x402 发现与按次付费 API	https://agentconnect.polygon.technology/polygon-discovery/SKILL.md

IMPORTANT——x402 调用： 如果用户要求使用 x402 获取数据（Twitter/X 个人资料、网络搜索、新闻、AI 图像、代码审查等），请在发出任何请求之前按顺序执行以下步骤：

1. 获取并阅读发现技能：GET https://agentconnect.polygon.technology/polygon-discovery/SKILL.md
2. 运行 polygon-agent wallet list——如果不存在钱包，则执行钱包创建流程：如果尚未运行 polygon-agent setup，先运行该命令；然后运行 polygon-agent wallet create 以打开浏览器会话并建立安全的加密钱包会话。出现提示时输入 6 位代码，然后再继续之前为钱包注资。
3. 运行 polygon-agent balances——确认有可用的 USDC 后再继续；如果钱包为空，x402 调用会因 EOA 注资错误而失败

不要猜测端点，也不要在网上搜索 x402 服务提供商。发现技能文档列出了正确且可用的端点及其精确 URL 格式。

---

命令参考

设置

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

钱包

有效的 --chain 值：polygon（默认／主网）、amoy（Polygon 测试网）、mainnet（Ethereum）、arbitrum、optimism、base。ERC-8004 Agent 操作仅支持 polygon。

polygon-agent wallet create [--name <n>] [--chain polygon] [--timeout <sec>] [--print-url]
  [--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 --code <6-digit-code> --rid <rid> [--name <n>]
polygon-agent wallet import --ciphertext '<blob>|@<file>' [--name <n>]  # legacy
polygon-agent wallet list
polygon-agent wallet address [--name <n>]
polygon-agent wallet remove [--name <n>]

操作

polygon-agent balances [--wallet <n>] [--chain <chain>] [--chains <csv>]
polygon-agent send --to <addr> --amount <num> [--symbol <SYM>] [--token <addr>] [--decimals <n>] [--broadcast]
polygon-agent send-native --to <addr> --amount <num> [--broadcast] [--direct]
polygon-agent send-token --symbol <SYM> --to <addr> --amount <num> [--token <addr>] [--decimals <n>] [--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 withdraw --position <addr> --amount <num|max> [--chain <chain>] [--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）

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>] [--tag2 <tag>]
polygon-agent agent reviews --agent-id <id> [--tag1 <t>] [--tag2 <t>] [--revoked]
polygon-agent agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--feedback-uri <uri>] [--broadcast]

ERC-8004 合约（Polygon 主网）：

• IdentityRegistry：0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• ReputationRegistry：0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

关键行为

• 默认试运行 — 所有写入命令都必须使用 --broadcast 才会执行
• 智能默认值 — --wallet main、--chain polygon，wallet create 会自动等待
• balances --chains — 使用逗号分隔的链（最多 20 条）；传入两条或更多链时，会返回包含 multiChain: true 和 chains 数组的 JSON（每条链使用相同的钱包地址）
• 费用偏好 — 如果 USDC 和原生 POL 均可用，则自动优先选择 USDC
• fund — 返回 https://wallet.polygon.technology 作为 fundingUrl。始终运行 polygon-agent fund 来获取 URL 和钱包地址；切勿硬编码或手动构造。
• deposit — 通过 Trails getEarnPools 选择 TVL 最高的池并直接存入。所有会话中都会自动将 Aave V3 Pool（0x794a61358d6845594f94dc1db02a252b5b4814ad）加入白名单。完整的存款参考：https://agentconnect.polygon.technology/polygon-defi/SKILL.md
• Gas 储备 — 使用 deposit 或任何会花费代币的命令时，始终在钱包中至少预留 0.1 USDC 或 0.1 POL 用于 Gas。切勿尝试花费全部余额。deposit 命令会自动预留 0.1，但 Agent 在为 send、swap 或直接合约调用构造金额时也必须遵守同样的规则。
• withdraw — --position = aToken 或 ERC-4626 金库；--amount = max 或底层资产单位（Aave / 金库）。试运行 JSON 包含 poolAddress / vault。广播时，会话必须与 --chain 指定的链相同，且在中继器会与池 / 金库及底层代币交互时，必须将它们加入白名单
• x402-pay — 探测端点是否返回 402，智能钱包以精确的代币金额为构建器 EOA 提供资金，EOA 签署 EIP-3009 付款。链会根据 402 响应自动检测
• send-native --direct — 绕过 ValueForwarder 合约，直接进行 EOA 转账
• 会话权限 — 如果没有 --usdc-limit 等参数，会话将获得最基本的默认权限，可能无法进行交易
• 会话有效期 — 自创建之日起 6 个月
• 一次性会话设置 — 如果用户的意图涉及 DeFi（存款、收益、兑换、Aave、Morpho），请在初始 wallet create 调用中加入其他合约（如 Morpho 金库等）。切勿先创建一个基本会话，然后在用户之后尝试存款时再要求其重新批准。

钱包创建流程（v2 Relay）

wallet create 使用 Cloudflare Durable Object 中继器和一个 6 位数的带外验证码 — 无需 cloudflared 隧道。浏览器使用通过中继器协商的 X25519 密钥加密已批准的会话；在终端中输入的 6 位数验证码就是解密密钥。

--print-url 标志： 在无头或非交互式环境（CI、远程 Shell）中使用此标志，此类环境下 wallet create 无法阻塞并等待验证码。CLI 会打印批准 URL 并立即退出。请另外完成此流程：

polygon-agent wallet import --code <6-digit-code> --rid <rid>

重要：钱包批准 URL

当 wallet create 在 url 或 approvalUrl 字段中输出 URL 时，请将完整且未截断的 URL发送给用户。该 URL 包含批准会话所需的中继器请求 ID。

• 请勿缩短、概述 URL，或在 URL 中添加 ...
• 请勿将 URL 拆分到多条消息中
• 原样输出 CLI 返回的 URL

向用户展示结果

CLI 命令会输出 JSON（非 TTY）。运行命令后，始终将结果呈现为格式化的 Markdown——绝不要在对话中粘贴原始 JSON。

命令	展示方式
balances	Markdown 表格：Token / Balance 列。在表格上方显示钱包地址和链。
send / send-token / send-native	单行摘要：金额、符号、收款方。如果已广播，将交易哈希显示为代码片段，并将区块浏览器 URL 显示为链接。
swap	摘要：X FROM → Y TO，并注明链。如果已广播，显示存款交易哈希和区块浏览器链接。
deposit	摘要：金额、资产、协议、资金池地址。如果已广播，显示交易哈希和区块浏览器链接。
withdraw	摘要：kind（aave / erc4626）、持仓、金额、资金池或金库。如果已广播，显示交易哈希和区块浏览器链接。
fund	将 fundingUrl 显示为可点击链接，并简要提示用户打开链接。
wallet create / wallet list	以小型表格或项目列表显示钱包名称、截断后的地址和链。
agent register	显示 Agent 名称，以及作为代码片段的交易哈希和 Polygonscan 链接。提醒用户从 Logs 选项卡中的 Registered 事件获取 agentId。
agent wallet	显示 agentId、钱包地址，以及是否已设置钱包。
agent metadata	显示 agentId、键和值的解码结果。
agent reputation	以小型表格显示评分和标签明细。

试运行结果——始终明确标示这是一次模拟。以 ⚡ Dry run 为前缀，并显示将要执行的操作。提醒用户使用 --broadcast 重新运行以执行操作。

错误——提取 error 字段，并以清晰的句子呈现，而不是 JSON 块。如果适用，请附上 Troubleshooting 表格中的相关修复方法。

---

故障排除

问题	修复方法
Builder configured already	添加 --force
Missing SEQUENCE_PROJECT_ACCESS_KEY	先运行 setup
Missing wallet	运行 wallet list，然后重新运行 wallet create
Session expired	重新运行 wallet create（有效期为 6 个月）
Fee option errors	设置 POLYGON_AGENT_DEBUG_FEE=1，并确保钱包中有资金
Timed out waiting for wallet approval	添加 --timeout 600
Invalid code: hash mismatch	输入的 6 位代码错误——请重试（允许尝试 3 次）
Relay request not found	会话已过期或已使用——重新运行 wallet create（或 wallet create --print-url）
存款会话被拒绝	使用 --contract <tokenAddress> --contract <depositAddress> 重新创建钱包（两者都必须提供：代币授权 + 资金池调用）
withdraw / 广播：链错误或会话拒绝	使用 wallet create --chain <same as --chain>，并通过 --contract 指定该链上的资金池/金库和底层 ERC-20；如果过严的 --usdc-limit 阻止了手续费转账，请省略该参数
Stored explicit session is missing pk	重新链接：运行 wallet create 后执行 wallet import --code …
Trails 小组件中的收款方错误	运行 polygon-agent fund（不要手动构造 URL）
x402-pay：没有 402 响应	端点不需要 x402 付款，或 URL 有误
x402-pay：付款代币不匹配	402 响应中的链/代币与钱包不一致——检查 --wallet 是否指向正确的链
x402-pay：EOA 资金补充失败	钱包余额不足以支付款项——运行 balances，并在需要时补充资金

文件结构

~/.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 (deleted after successful import)