Polygon Agent

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

---

Content truncated.