Skip to main content
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"
FlagDefaultPurpose
--namenoneProject name written to builder.json
--forcefalseRecreate 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
FlagDefaultPurpose
--namemainWallet name (multiple wallets supported)
--chainpolygonChain to deploy on
--print-urlfalsePrint approval URL and exit (headless)
--timeout300Seconds to wait for browser approval
--native-limitnonePOL spending cap
--usdc-limitnoneUSDC spending cap
--usdt-limitnoneUSDT spending cap
--token-limitnoneOther token cap, repeatable: --token-limit WETH:0.1
--contractnoneWhitelist a contract address, repeatable
--defifalseWhitelist DeFi contracts (swaps, yield) in addition to defaults
--usdc-to / --usdc-amountnoneOne-off USDC transfer at creation
--access-keynoneOverride 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.