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

<div style={{border:"1px solid #C8CFE1",borderRadius:"12px",overflow:"hidden",marginBottom:"24px"}}>
  <div style={{background:"linear-gradient(180deg,#EAE4F5 0%,#F6F3FB 100%)",borderBottom:"1px solid #D5C4F2",padding:"10px 16px",fontSize:"11px",fontWeight:"700",color:"#670DE5",letterSpacing:"0.06em",textTransform:"uppercase"}}>Wallet creation flow</div>

  <div style={{borderBottom:"1px solid #EEF0F9",padding:"9px 16px",display:"flex",alignItems:"center",gap:"10px"}}>
    <span style={{color:"#929EBA",fontSize:"11px",fontWeight:"700",minWidth:"16px",textAlign:"right"}}>1</span>
    <span style={{background:"#EEF0F9",color:"#48526F",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"600",whiteSpace:"nowrap"}}>Operator</span>
    <span style={{color:"#670DE5",fontWeight:"700"}}>→</span>
    <span style={{background:"#EEF0F9",color:"#48526F",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"600",whiteSpace:"nowrap"}}>CLI</span>
    <span style={{fontFamily:"'Geist Mono',ui-monospace,monospace",fontSize:"12px",color:"#141635"}}>polygon-agent wallet create --usdc-limit 50</span>
  </div>

  <div style={{borderBottom:"1px solid #EEF0F9",padding:"9px 16px",display:"flex",alignItems:"center",gap:"10px"}}>
    <span style={{color:"#929EBA",fontSize:"11px",fontWeight:"700",minWidth:"16px",textAlign:"right"}}>2</span>
    <span style={{background:"#EEF0F9",color:"#48526F",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"600",whiteSpace:"nowrap"}}>CLI</span>
    <span style={{color:"#670DE5",fontWeight:"700"}}>→</span>
    <span style={{background:"#EAE4F5",color:"#670DE5",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"700",whiteSpace:"nowrap"}}>Browser</span>
    <span style={{fontSize:"13px",color:"#141635"}}>Approval URL + 6-digit code shown in terminal</span>
  </div>

  <div style={{borderBottom:"1px solid #EEF0F9",padding:"9px 16px",display:"flex",alignItems:"center",gap:"10px"}}>
    <span style={{color:"#929EBA",fontSize:"11px",fontWeight:"700",minWidth:"16px",textAlign:"right"}}>3</span>
    <span style={{background:"#EEF0F9",color:"#48526F",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"600",whiteSpace:"nowrap"}}>Operator</span>
    <span style={{color:"#670DE5",fontWeight:"700"}}>→</span>
    <span style={{background:"#EAE4F5",color:"#670DE5",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"700",whiteSpace:"nowrap"}}>Browser</span>
    <span style={{fontSize:"13px",color:"#141635"}}>Opens URL, reviews limits, enters 6-digit code</span>
  </div>

  <div style={{borderBottom:"1px solid #EEF0F9",padding:"9px 16px",display:"flex",alignItems:"center",gap:"10px"}}>
    <span style={{color:"#929EBA",fontSize:"11px",fontWeight:"700",minWidth:"16px",textAlign:"right"}}>4</span>
    <span style={{background:"#EAE4F5",color:"#670DE5",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"700",whiteSpace:"nowrap"}}>OMS Wallet</span>
    <span style={{color:"#670DE5",fontWeight:"700"}}>→</span>
    <span style={{background:"#EEF0F9",color:"#48526F",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"600",whiteSpace:"nowrap"}}>CLI</span>
    <span style={{fontSize:"13px",color:"#141635"}}>Returns session via encrypted relay (X25519)</span>
  </div>

  <div style={{padding:"9px 16px",display:"flex",alignItems:"center",gap:"10px"}}>
    <span style={{color:"#929EBA",fontSize:"11px",fontWeight:"700",minWidth:"16px",textAlign:"right"}}>5</span>
    <span style={{background:"#EAE4F5",color:"#670DE5",padding:"2px 8px",borderRadius:"4px",fontSize:"11px",fontWeight:"700",whiteSpace:"nowrap"}}>CLI</span>
    <span style={{fontSize:"13px",color:"#141635",marginLeft:"4px"}}>Writes encrypted session to `~/.polygon-agent/wallets/&lt;name&gt;.json`</span>
  </div>
</div>

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

<CardGroup cols={2}>
  <Card title="CLI overview" icon="terminal" href="/payment-services/agentic-payments/cli/index">
    Topology, install, supported chains, safety model.
  </Card>

  <Card title="Balances and funding" icon="wallet" href="/payment-services/agentic-payments/cli/balances-and-funding">
    Check balances and fund the smart wallet.
  </Card>

  <Card title="Agentic Wallets" icon="key" href="/wallets/agentic-wallets">
    smart contract wallet primitives.
  </Card>
</CardGroup>