polygon-agent-cli

Polygon Agentic CLI

Prerequisites

• Node.js 20+
• Install globally: npm install -g @polygonlabs/agent-cli (reinstall to update)
• Entry point: polygon-agent <command>
• Storage: ~/.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-agent CLI system-wide so it runs from any terminal, may need sudo on some setups, re-running the same command updates it, and npm uninstall -g @polygonlabs/agent-cli removes it. Mention once on first install.

If a command fails with "Unknown argument" or "command not found"

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

Architecture

Wallet	Created by	Purpose	Fund?
EOA	setup	Auth with Sequence Builder	NO
Ecosystem Wallet	wallet create	Primary spending wallet	YES

Environment Variables

Access key — one key, many names

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

Optional overrides

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

Complete Setup Flow

# 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

Use-Case Skills

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:

1. Fetch and read the discovery skill: GET https://agentconnect.polygon.technology/polygon-discovery/SKILL.md
2. Run polygon-agent wallet list — if no wallet exists, run through the wallet creation flow: polygon-agent setup (if not already done), then polygon-agent wallet create to open a browser session and establish a secure encrypted wallet session. Enter the 6-digit code when prompted, then fund the wallet before continuing.
3. Run polygon-agent balances — confirm USDC is available before proceeding; x402 calls will fail with an EOA funding error if the wallet is empty

Do not guess endpoints or search the web for x402 providers. The discovery skill documents the correct, working endpoints with exact URL formats.

---

Commands Reference

Setup

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

Wallet

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>]

Operations

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 contracts (Polygon mainnet):

• 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
• balances --chains — comma-separated chains (max 20); two or more return JSON with multiChain: true and a chains array (same wallet address on each)
• Fee preference — auto-selects USDC over native POL when both available
• 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.md
• Gas reserve — when using deposit 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 them
• 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
• Session expiry — 6 months from creation
• One-pass session setup — if the user's intent involves DeFi (deposit, yield, swap, Aave, Morpho), include any additional contracts (Morpho vaults etc.) in the initial wallet create call. Never create a bare session and then ask the user to re-approve when a deposit is later attempted.

Wallet Creation Flow (v2 Relay)

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>

CRITICAL: Wallet Approval URL

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.

• 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

Presenting Results to the User

CLI 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.

---

Troubleshooting

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

File Structure

~/.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)