> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polygon.technology/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup and wallets

> Initialize a project, create a smart wallet with spending limits, and manage wallet lifecycle.

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

1
Operator
→
CLI
polygon-agent wallet create --usdc-limit 50

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

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

4
OMS Wallet
→
CLI
Returns session via encrypted relay (X25519)

5
CLI
Writes encrypted session to `~/.polygon-agent/wallets/&lt;name&gt;.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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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`:

```bash theme={null}
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

```bash theme={null}
# 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

> [card] [CLI overview](https://docs.polygon.technology/payment-services/agentic-payments/cli/index.md)
>
> Topology, install, supported chains, safety model.

> [card] [Balances and funding](https://docs.polygon.technology/payment-services/agentic-payments/cli/balances-and-funding.md)
>
> Check balances and fund the smart wallet.

> [card] [Agentic Wallets](https://docs.polygon.technology/wallets/agentic-wallets.md)
>
> smart contract wallet primitives.
