Setup and wallets

Two commands set up a working CLI: polygon-agent setup creates an EOA and authenticates with OMS, then polygon-agent wallet create provisions the smart wallet that holds the operating balance. The smart wallet is where spending limits live: per-token caps, contract allowlists, and DeFi permissions are scoped at creation. The EOA never holds funds. Wallet sessions last six months. After expiry, re-run wallet create to refresh the session.

How it works

Wallet creation flow

1Operator→CLIpolygon-agent wallet create —usdc-limit 50

2CLI→BrowserApproval URL + 6-digit code shown in terminal

3Operator→BrowserOpens URL, reviews limits, enters 6-digit code

4OMS Wallet→CLIReturns session via encrypted relay (X25519)

5CLIWrites encrypted session to ~/.polygon-agent/wallets/<name>.json

The browser approval step is one-time per session. After approval, the CLI runs autonomously for six months against the configured spending limits.

Commands

setup

polygon-agent setup --name "my-project"

Flag	Default	Purpose
`--name`	none	Project name written to `builder.json`
`--force`	`false`	Recreate config even if already set up

Creates an EOA and access key. Stored encrypted at ~/.polygon-agent/builder.json. Run this once per machine per project.

wallet create

polygon-agent wallet create \
  --name main \
  --chain polygon \
  --usdc-limit 50 \
  --native-limit 0.5

Flag	Default	Purpose
`--name`	`main`	Wallet name (multiple wallets supported)
`--chain`	`polygon`	Chain to deploy on
`--print-url`	`false`	Print approval URL and exit (headless)
`--timeout`	`300`	Seconds to wait for browser approval
`--native-limit`	none	POL spending cap
`--usdc-limit`	none	USDC spending cap
`--usdt-limit`	none	USDT spending cap
`--token-limit`	none	Other token cap, repeatable: `--token-limit WETH:0.1`
`--contract`	none	Whitelist a contract address, repeatable
`--defi`	`false`	Whitelist DeFi contracts (swaps, yield) in addition to defaults
`--usdc-to` / `--usdc-amount`	none	One-off USDC transfer at creation
`--access-key`	none	Override the stored OMS project access key

For yield workflows, pass --defi at creation so the smart wallet can interact with Aave v3, Morpho, and ERC-4626 vaults without re-approval. To allow specific contracts only, list them with repeated --contract flags.

wallet import

polygon-agent wallet import --code 123456 --rid <relay-id>
polygon-agent wallet import --ciphertext '@./session.ciphertext'

Imports a session created on another machine, either via the 6-digit code + relay ID flow or via an exported ciphertext blob. Useful for moving a wallet between an operator machine and a server.

wallet list, address, remove

polygon-agent wallet list
polygon-agent wallet address --name main
polygon-agent wallet remove --name old-wallet

list enumerates all wallets. address prints the smart-wallet address for the named wallet. remove deletes the local session; the onchain wallet is unaffected.

Headless approval

For server environments without a browser, use --print-url:

polygon-agent wallet create --print-url --usdc-limit 100

The CLI prints the approval URL and exits immediately. Open the URL on any machine, enter the 6-digit code shown in terminal output, then run polygon-agent wallet import --code <code> --rid <rid> on the server to pick up the session.

Worked example

# One-time per machine
polygon-agent setup --name "treasury"

# Smart wallet with caps
polygon-agent wallet create \
  --name treasury \
  --chain polygon \
  --usdc-limit 1000 \
  --usdt-limit 1000 \
  --defi

# Confirm
polygon-agent wallet list
polygon-agent wallet address --name treasury

After approval, the wallet can spend up to 1,000 USDC and 1,000 USDT plus interact with any DeFi contract whitelisted by --defi.

Implementation

CLI overview

Topology, install, supported chains, safety model.

Balances and funding

Check balances and fund the smart wallet.

Agentic Wallets

smart contract wallet primitives.

Agentic Payments

Agentic Services

Use Cases

Polygon Agent CLI

x402 Protocol

How it works

Commands

setup

wallet create

wallet import

wallet list, address, remove

Headless approval

Worked example

Implementation

CLI overview

Balances and funding

Agentic Wallets

​How it works

​Commands

​setup

​wallet create

​wallet import

​wallet list, address, remove

​Headless approval

​Worked example

​Implementation

CLI overview

Balances and funding

Agentic Wallets

How it works

Commands

setup

wallet create

wallet import

wallet list, address, remove

Headless approval

Worked example

Implementation