Polygon Agent CLI

Polygon Agentic CLI

Prerequisites

• Node.js 22+
• Install globally: npm install -g @polygonlabs/agent-cli (reinstall to update)
• Entry point: 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 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:

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

Architecture

The CLI uses the OMS (Open Money Stack) V3 embedded-wallet model (@polygonlabs/oms-wallet). By default, wallet login opens the agentconnect login page (POLYGON_AGENT_LOGIN_UI, default https://agentconnect.polygon.technology), where the user chooses Google or email (email sends a 6-digit code to the user's inbox, entered on the page). This works whether the browser is on this machine or a different one, so there is no separate headless mode. --local falls back to the legacy loopback flow (raw Google sign-in URL plus a localhost callback; browser must be on this same machine; Google only). --remote is deprecated and is now a no-op that prints a notice. Once the user signs in, the wallet is created or unlocked and the session credential is stored encrypted on disk. There is no on-chain permission scoping.

The wallet address is the same across all EVM chains. Sessions last ~1 week before re-login is needed.

Environment Variables

OMS credentials (optional)

No setup step is required. The CLI ships a default OMS publishable key, and wallet login automatically provisions a dedicated Builder project and access key on first login, saving it to ~/.polygon-agent/builder.json.

Set it via env, or persist once with setup so every command reads it from ~/.polygon-agent/builder.json:

agent setup --oms-publishable-key <key>

--oms-project-id <proj_...> is also accepted but optional — it's kept only as legacy display metadata. Plain setup (no key) still works for manual or --force re-provisioning.

Optional overrides

Complete Setup Flow

# Step 1: Log in in the browser
agent wallet login
# → opens the agentconnect login page; choose Google or email (email sends
#   a 6-digit code to the user's inbox, entered on the page)
# → works whether the browser is on this machine or elsewhere, so there is
#   no separate headless mode
# → --local falls back to the legacy loopback flow (Google only, browser
#   must be on this machine)
# → session saved to ~/.polygon-agent/oms/main/; prints the walletAddress
# → no setup step needed: the CLI ships a default OMS publishable key, and
#   login auto-provisions a Builder project + access key to
#   ~/.polygon-agent/builder.json

# Step 1b: Choose transaction mode (asked once)
# → if the login output includes a `modePrompt` field, ask the user whether to
#   enable auto mode (writes broadcast immediately, no preview), then run:
agent mode auto      # or: agent mode dry-run
# → dry-run (default) previews every write; auto broadcasts immediately.
#   Never enable auto mode without the user's explicit answer.

# Step 2: Fund wallet
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 3: Verify balances
agent balances

# Step 4: Register agent on-chain (ERC-8004, Polygon mainnet only)
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:

IMPORTANT — x402 calls: If the user asks to use x402 to fetch data or call a service (web search, scraping, news, LLM inference, email, on-chain wallet analytics, multi-chain RPC, 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 agent wallet list — if no wallet exists, log in: agent wallet login and sign in on the login page (Google or email), then fund the wallet before continuing. No setup step is needed first.
3. Run 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

agent setup [--name <name>] [--force]
  [--oms-publishable-key <key>] [--oms-project-id <proj_...>]  # save OMS credentials (project id optional/legacy)
agent mode [auto|dry-run]   # show or set the persisted transaction mode

Wallet

Valid --chain values for operations: polygon (default/mainnet), amoy (Polygon testnet), mainnet (Ethereum), arbitrum, optimism, base. ERC-8004 agent operations only support polygon. The embedded wallet address is the same on every chain.

agent wallet login [--name <n>] [--local] [--no-fund] [--force]
# Opens the agentconnect login page; choose Google or email. Works whether the browser is local or remote, so there is no separate headless mode.
# --local falls back to the legacy loopback flow (raw Google URL + localhost callback; browser must be on this machine; Google only). --remote is deprecated (now a no-op with a notice).
agent wallet logout [--name <n>]   # clears the local session
agent wallet list
agent wallet address [--name <n>]
agent wallet remove [--name <n>]

Operations

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

Every write command accepts --broadcast (execute) and --dry-run (force preview); with neither, the persisted agent mode decides.

Agent identity & reputation (ERC-8004)

agent register --name <n> [--agent-uri <uri>] [--metadata <k=v,k=v>] [--broadcast|--dry-run]
agent identity --agent-id <id> [--key <metadata-key>]   # agent payment wallet + optional metadata
agent reputation --agent-id <id> [--tag1 <tag>] [--tag2 <tag>]
agent reviews --agent-id <id> [--tag1 <t>] [--tag2 <t>] [--include-revoked]
agent feedback --agent-id <id> --value <score> [--tag1 <t>] [--tag2 <t>] [--endpoint <e>] [--feedback-uri <uri>] [--broadcast|--dry-run]

ERC-8004 contracts (Polygon mainnet):

• IdentityRegistry: 0x8004A169FB4a3325136EB29fA0ceB6D2e539a432
• ReputationRegistry: 0x8004BAa17C55a88189AE136b182e5fdA19dE9b63

Key Behaviors

• Transaction mode — in the default dry-run mode, write commands preview and require --broadcast to execute. agent mode auto persists always-broadcast; --dry-run on any command forces a preview regardless of mode. After the first wallet login, if the login JSON contains a modePrompt field, relay that question to the user and run agent mode auto or agent mode dry-run per their answer before continuing. Never enable auto mode without the user's explicit answer.
• Smart defaults — --wallet main, --chain polygon
• 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; the relayer pays gas in whichever fee token the wallet can afford
• fund — returns the agentconnect dashboard funding URL (wallet and chain prefilled) as the fundingUrl. Always run 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. 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.
• x402-pay — probes endpoint for 402, the wallet funds a builder EOA with the exact token amount, the EOA signs the EIP-3009 payment. Chain auto-detected from the 402 response
• call — submit arbitrary pre-encoded calldata: agent call --to <addr> --data 0x... [--value <amt>] [--prefer-native-fee] [--broadcast]. The wallet can call any contract (no permission scoping in the V3 model)
• send-native --direct — bypasses ValueForwarder contract for direct EOA transfer
• No permission scoping — the V3 embedded wallet can call any contract and spend any amount it holds; there are no per-contract whitelists or spend limits. Guard spending in agent logic, not at the wallet layer.
• Session expiry — ~1 week from login; on expiry, re-run wallet login

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.

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

File Structure

~/.polygon-agent/
├── .encryption-key       # AES-256-GCM key (auto-generated, 0600)
├── config.json           # transaction mode (auto | dry-run)
├── builder.json          # publishableKey, omsProjectId, polymarket/EOA keys (encrypted)
├── wallets/<name>.json   # OMS wallet pointer: walletAddress, loginMethod
└── oms/<name>/           # OMS SDK session storage + encrypted credential key