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

# vetta identity wallet

> Provision, fund, cap and drain a persona's wallet, and pay for paywalled resources.

A wallet belongs to a [persona](https://vetta.sh/docs/cli/identity.md), so every command takes `--identity`. Reached as `vetta identity wallet <command>` — three words, where `wallet` is a sub-group rather than a positional argument. See [Wallet](https://vetta.sh/docs/identity/wallet.md) for the model and the [Wallet API](https://vetta.sh/docs/api/wallet.md) for the wire shapes.

Dollar flags (`--usd`, `--per-tx-cap-usd`, …) take a decimal such as `0.50`; the CLI converts once to the integer micro-USD the API speaks.

## Commands

| Command | Description |
| - | - |
| `vetta identity wallet show` | Read the wallet with its live balance. |
| `vetta identity wallet create` | Provision the wallet with its spending policy. |
| `vetta identity wallet policy` | Change the per-transaction, daily or low-balance caps. |
| `vetta identity wallet freeze` | Stop all spending. |
| `vetta identity wallet unfreeze` | Resume spending under the saved policy. |
| `vetta identity wallet fund` | Fund from the test faucet or the organization's treasury. |
| `vetta identity wallet transfer` | Send funds to an address or a sibling persona. |
| `vetta identity wallet sweep` | Drain the wallet and retire it. |
| `vetta identity wallet transactions` | List transactions. |
| `vetta identity wallet receipts` | List the payments made for paywalled resources. |
| `vetta identity wallet quote` | Read what a paywalled URL asks for, without paying. |
| `vetta identity wallet pay` | Pay for and fetch a paywalled URL. |

`--identity` takes either an `idn_` id or the persona's name; the API resolves both. A persona holds at most one live wallet per network, and every command takes `--network` to say which: `base-testnet` (the default when omitted) or `base`, or the CAIP-2 value (`eip155:84532`, `eip155:8453`). No command ever falls back to the other network's wallet. On a deployment with no custody provider bound, every command answers `501 feature_not_configured`.

## create / policy

```bash theme={"system"}
vetta identity wallet create --identity ava --network base-testnet --per-tx-cap-usd 0.50 --daily-cap-usd 20
vetta identity wallet policy --identity ava --per-tx-cap-usd 1
```

| Flag | Description |
| - | - |
| `--network` | Which wallet: `base-testnet` (default) or `base`; the CAIP-2 value is also accepted. On `create` it is the network the wallet is provisioned on. |
| `--per-tx-cap-usd` | The most one transaction may spend. |
| `--daily-cap-usd` | A rolling daily ceiling. |
| `--low-balance-usd` | Balance below which the wallet is reported as low. |

`create` is idempotent per network: re-running answers the existing wallet on that network, and a persona may hold a `base-testnet` and a `base` wallet side by side.

## show / freeze / unfreeze / sweep

```bash theme={"system"}
vetta identity wallet show --identity ava
vetta identity wallet show --identity ava --network base
vetta identity wallet freeze --identity ava
vetta identity wallet unfreeze --identity ava
vetta identity wallet sweep --identity ava --to 0x…
```

| Flag | Description |
| - | - |
| `--to` | Where `sweep` sends the balance; omitted means the organization's treasury (`501 feature_not_configured` until one is provisioned). |

`sweep` retires the wallet; a later `create` provisions a fresh one.

## fund / transfer

```bash theme={"system"}
vetta identity wallet fund --identity ava --usd 1 --source faucet
vetta identity wallet transfer --identity ava --to 0x… --usd 0.25 --purpose "API credit"
```

| Flag | Description |
| - | - |
| `--usd` | The amount (required). |
| `--source` | `faucet` (default; testnet only, grants the faucet's fixed 1 USDC) or `treasury` (`501 feature_not_configured` until the organization has one). |
| `--to` | An address or a sibling persona's `idn_` id (required on `transfer`); a sibling is paid into its wallet on the same network as the sender's. |
| `--purpose` | Why the transfer is made (required on `transfer`). |

## transactions / receipts

```bash theme={"system"}
vetta identity wallet transactions --identity ava --kind pay --direction out
vetta identity wallet receipts --identity ava --origin https://api.example.com
```

| Flag | Description |
| - | - |
| `--kind` | `fund`, `transfer`, `pay` or `sweep`. |
| `--direction` | `in` or `out`. |
| `--origin` | The paywalled resource's origin. |
| `--since` | RFC 3339 timestamp. |
| `--limit` / `--after` | Pagination. |

`receipts` is `transactions --kind pay`.

## quote / pay

```bash theme={"system"}
vetta identity wallet quote --identity ava --url https://api.example.com/report
vetta identity wallet pay --identity ava --url https://api.example.com/report --max-usd 0.25
```

| Flag | Description |
| - | - |
| `--url` | The paywalled URL (required). |
| `--method` | `GET` (default), `POST`, `PUT`, `PATCH` or `DELETE`. |
| `--max-usd` | The most `pay` may spend on this request; the per-transaction cap still applies. |

`quote` has no side effects. `pay` refuses with `validation_failed` when the wallet's balance or caps cannot meet the price; the organization's credits are never used. Both print the API's `wallet_quote` / `wallet_payment` objects in micro-USD.

```json theme={"system"}
{ "object": "wallet_quote", "url": "https://api.example.com/report", "payable": true, "network": "eip155:84532", "asset": "usdc", "amount_micro_usd": 100000, "pay_to": "0x…", "description": "Weekly market report", "max_timeout_seconds": 60 }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.