> ## 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](/docs/cli/identity), 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](/docs/identity/wallet) for the model and the [Wallet API](/docs/api/wallet) 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 }
```