vetta identity wallet

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

A wallet belongs to a persona, 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 for the model and the Wallet API 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

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

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

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

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

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.

{ "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 }