From polygon-agent-cli
CLI for Polygon blockchain operations: wallet setup, token swaps, bridging, yield management (Aave, ERC-4626), on-chain identity, reputation, and x402 micropayments. Uses Sequence wallets and Trails DeFi.
How this skill is triggered — by the user, by Claude, or both
Slash command
/polygon-agent-cli:polygon-agent-cliThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
- Node.js 20+
npm install -g @polygonlabs/agent-cli (reinstall to update)polygon-agent <command>~/.polygon-agent/ (AES-256-GCM encrypted)Note for the agent: on first install, tell the user this is a global npm install — installs the
polygon-agentCLI system-wide so it runs from any terminal, may need sudo on some setups, re-running the same command updates it, andnpm uninstall -g @polygonlabs/agent-cliremoves it. Mention once on first install.
This skill is versioned with the CLI — commands and flags drift across releases. Check your version, compare to latest, and upgrade if behind:
polygon-agent --version # currently installed
npm view @polygonlabs/agent-cli version # latest published
npm install -g @polygonlabs/agent-cli@latest # upgrade
| Wallet | Created by | Purpose | Fund? |
|---|---|---|---|
| EOA | setup | Auth with Sequence Builder | NO |
| Ecosystem Wallet | wallet create | Primary spending wallet | YES |
SEQUENCE_PROJECT_ACCESS_KEY, SEQUENCE_INDEXER_ACCESS_KEY, and TRAILS_API_KEY are all the same key — the Sequence project access key created during setup. The CLI treats them as aliases and falls back through all of them automatically.
After setup runs the key is stored in ~/.polygon-agent/builder.json. Every CLI invocation bootstraps it into the environment — no export is needed. In a fresh agent session with no environment variables set, simply run commands and the CLI reads credentials from disk.
Only set these manually to override the stored value (e.g. to point at a different project):
export SEQUENCE_PROJECT_ACCESS_KEY=<key> # also covers TRAILS_API_KEY and indexer calls
| Variable | Default |
|---|---|
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 |
# 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
For specific workflows, fetch and load the relevant sub-skill before attempting the task:
| Use Case | Skill URL |
|---|---|
| Polymarket prediction market trading | https://agentconnect.polygon.technology/polygon-polymarket/SKILL.md |
| DeFi — swap, deposit, withdraw, yield | https://agentconnect.polygon.technology/polygon-defi/SKILL.md |
| x402 discovery & pay-per-call APIs | https://agentconnect.polygon.technology/polygon-discovery/SKILL.md |
IMPORTANT — x402 calls: If the user asks to use x402 to fetch data (Twitter/X profiles, web search, news, AI images, code review, etc.), follow these steps in order before making any request:
- Fetch and read the discovery skill:
GET https://agentconnect.polygon.technology/polygon-discovery/SKILL.md- Run
polygon-agent wallet list— if no wallet exists, run through the wallet creation flow:polygon-agent setup(if not already done), thenpolygon-agent wallet createto open a browser session and establish a secure encrypted wallet session. Enter the 6-digit code when prompted, then fund the wallet before continuing.- Run
polygon-agent balances— confirm USDC is available before proceeding; x402 calls will fail with an EOA funding error if the wallet is emptyDo not guess endpoints or search the web for x402 providers. The discovery skill documents the correct, working endpoints with exact URL formats.
polygon-agent setup --name <name> [--force]
Valid --chain values: polygon (default/mainnet), amoy (Polygon testnet), mainnet (Ethereum), arbitrum, optimism, base. ERC-8004 agent operations only support 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]
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 contracts (Polygon mainnet):
0x8004A169FB4a3325136EB29fA0ceB6D2e539a4320x8004BAa17C55a88189AE136b182e5fdA19dE9b63--broadcast to execute--wallet main, --chain polygon, auto-wait on wallet createbalances --chains — comma-separated chains (max 20); two or more return JSON with multiChain: true and a chains array (same wallet address on each)fund — returns https://wallet.polygon.technology as the fundingUrl. Always run polygon-agent fund to get the URL and wallet address — never hardcode or construct manually.deposit — picks highest-TVL pool via Trails getEarnPools and deposits directly. Aave V3 Pool (0x794a61358d6845594f94dc1db02a252b5b4814ad) is auto-whitelisted in all sessions. Full deposit reference: https://agentconnect.polygon.technology/polygon-defi/SKILL.mddeposit or any command that spends tokens, always reserve at least 0.1 USDC or 0.1 POL in the wallet for gas. Never attempt to spend the full balance. The deposit command enforces a 0.1 reserve automatically, but the agent must apply the same rule when constructing amounts for send, swap, or direct contract calls.withdraw — --position = aToken or ERC-4626 vault; --amount = max or underlying units (Aave / vault). Dry-run JSON includes poolAddress / vault. Broadcast needs session on the same chain as --chain, with pool/vault + underlying token whitelisted where the relayer touches themx402-pay — probes endpoint for 402, smart wallet funds builder EOA with exact token amount, EOA signs EIP-3009 payment. Chain auto-detected from 402 responsesend-native --direct — bypasses ValueForwarder contract for direct EOA transfer--usdc-limit etc., session gets bare-bones defaults and may not transactwallet create call. Never create a bare session and then ask the user to re-approve when a deposit is later attempted.wallet create uses a Cloudflare Durable Object relay and a 6-digit out-of-band code — no cloudflared tunnel required. The browser encrypts the approved session with an X25519 key negotiated via the relay; the 6-digit code is the decryption key entered in the terminal.
--print-url flag: Use this in headless or non-interactive environments (CI, remote shells) where wallet create can't block waiting for the code. The CLI prints the approval URL and exits immediately. Complete the flow separately:
polygon-agent wallet import --code <6-digit-code> --rid <rid>
When wallet create outputs a URL in the url or approvalUrl field, send the complete, untruncated URL to the user. The URL contains the relay request ID required for session approval.
... to the URLCLI commands output JSON (non-TTY). After running a command, always render the result as formatted markdown — never paste raw JSON into the conversation.
| Command | How to present |
|---|---|
balances | Markdown table: Token / Balance columns. Show wallet address and chain above the table. |
send / send-token / send-native | One-liner summary: amount, symbol, recipient. If broadcast, show tx hash as a code span and explorer URL as a link. |
swap | Summary: X FROM → Y TO with chain. If broadcast, show deposit tx hash + explorer link. |
deposit | Summary: amount, asset, protocol, pool address. If broadcast, show tx hash + explorer link. |
withdraw | Summary: kind (aave / erc4626), position, amount, pool or vault. If broadcast, show tx hash + explorer link. |
fund | Show the fundingUrl as a clickable link with a brief instruction to open it. |
wallet create / wallet list | Wallet name, truncated address, chain in a small table or bullet list. |
agent register | Show agent name and tx hash as a code span with Polygonscan link. Remind user to retrieve agentId from the Registered event on the Logs tab. |
agent wallet | Show agentId, wallet address, and whether a wallet is set. |
agent metadata | Show agentId, key, and decoded value. |
agent reputation | Format score and tag breakdown as a small table. |
Dry-run results — always make it visually clear this was a simulation. Prefix with ⚡ Dry run and show what would happen. Remind the user to re-run with --broadcast to execute.
Errors — extract the error field and present it as a clear sentence, not a JSON blob. Include the relevant fix from the Troubleshooting table if applicable.
| Issue | Fix |
|---|---|
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 (6-month expiry) |
Fee option errors | Set POLYGON_AGENT_DEBUG_FEE=1, ensure wallet has funds |
Timed out waiting for wallet approval | Add --timeout 600 |
Invalid code: hash mismatch | Wrong 6-digit code entered — retry (3 attempts allowed) |
Relay request not found | Session expired or already used — re-run wallet create (or wallet create --print-url) |
| Deposit session rejected | Re-create wallet with --contract <tokenAddress> --contract <depositAddress> (both required: token approve + pool call) |
withdraw / broadcast: wrong chain or session rejects | Use wallet create --chain <same as --chain> and --contract for pool/vault + underlying ERC-20 on that chain; omit tight --usdc-limit if it blocks fee transfers |
Stored explicit session is missing pk | Re-link: wallet import --code … after wallet create |
| Wrong recipient in Trails widget | Run polygon-agent fund (do not construct the URL manually) |
x402-pay: no 402 response | Endpoint doesn't require x402 payment, or URL is wrong |
x402-pay: payment token mismatch | Chain/token in the 402 response differs from wallet — check --wallet points to the right chain |
x402-pay: EOA funding failed | Wallet lacks sufficient balance to cover the payment amount — run balances and fund if needed |
~/.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)
npx claudepluginhub 0xpolygon/polygon-agent-cliUses Circle CLI for onchain stablecoin operations: paying for APIs, sending USDC, bridging, checking balances. Also acts as a rescue when agents hit paywalls or rate limits.
Performs DeFi operations on Polygon: token swaps, cross-chain bridging, and yield deposits into Aave v3 and Morpho vaults using Polygon Agent CLI. Dry-run by default.
Interact with a local AgentLayer wallet runtime: check balances, transfer tokens, swap, DeFi operations, or x402 payments. Prefers wallet tools over shell commands and previews writes before execution.