Polygon Agent Kit

Prerequisites

• - Node.js 20+
• Install globally: INLINECODE0
• Entry point: INLINECODE1
• Storage: ~/.polygon-agent/ (AES-256-GCM encrypted)

Architecture

Environment Variables

Required

Variable	When
INLINECODE5	Wallet creation, swaps
INLINECODE6

Balance checks |

Optional

Variable	Default
INLINECODE7	INLINECODE8
INLINECODE9

Same as connector URL origin |

Complete Setup Flow

CODEBLOCK0

Commands Reference

Setup

Wallet

Operations

Agent (ERC-8004)

ERC-8004 contracts (Polygon mainnet):

• - IdentityRegistry: INLINECODE16
• ReputationRegistry: INLINECODE17

Key Behaviors

• - Dry-run by default — all write commands require --broadcast to execute
• Smart defaults — --wallet main, --chain polygon, auto-wait on INLINECODE21
• Fee preference — auto-selects USDC over native POL when both available
• fund — reads walletAddress from the wallet session and sets it as toAddress in the Trails widget URL. Always run polygon-agent fund to get the correct URL — never construct it manually or hardcode any address. The returned JSON contains fundingUrl and walletAddress so you can confirm the pre-filled recipient before sharing.
• deposit — picks highest-TVL pool via Trails getEarnPools. If session rejects, re-create wallet with INLINECODE30
• 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

CRITICAL: Wallet Approval URL

When wallet create outputs a URL in the url or approvalUrl field, you MUST send the COMPLETE, UNTRUNCATED URL to the user. The URL contains cryptographic parameters (public key, callback token) that are required for session approval. If any part is cut off, the approval will fail.

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

Callback Modes

The wallet create command automatically starts a local HTTP server and opens a Cloudflare Quick Tunnel (*.trycloudflare.com) — no account or token required. The cloudflared binary is auto-downloaded to ~/.polygon-agent/bin/cloudflared on first use if not already installed. The connector UI POSTs the encrypted session back through the tunnel regardless of where the agent is running. The tunnel and server are torn down automatically once the session is received.

Timing: The approvalUrl is only valid while the CLI process is running. Open it immediately and complete wallet approval within the timeout window (default 300s). Never reuse a URL from a previous run — the tunnel is torn down when the CLI exits.

Manual fallback (if cloudflared is unavailable): The CLI omits callbackUrl so the connector UI displays the encrypted blob in the browser. The CLI then prompts:

After approving in the browser, the encrypted blob will be shown.
Paste it below and press Enter:
> <paste blob here>

Troubleshooting

File Structure