> ## 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. # Cards > Prepaid virtual cards an identity buys with organization credits, with a single audited credential reveal. Cards belong to an **identity** — any number per identity. A card is **prepaid**: bought once for a load between the bounds the quote reports ($1 to $150), paid for from the organization's credits before the issuer is asked, and never reloaded. An agent can see and use a card only when its session selected the identity that owns it; there is no separate card-to-agent assignment — the identity grant is the assignment. ## Lifecycle ``` pending_payment → issuing → active → cancelled ↘ failed → retry (→ issuing) | refund → refunded ``` 1. Price a load with `POST /v1/identities/{id}/cards/quote`. The quote is the load plus the issuer's fee, in micro-USD (`50 USD` load → e.g. `50500000` price). 2. Buy the card with `POST /v1/identities/{id}/cards`. Credits are debited first; a short balance answers `insufficient_credits` and nothing is ordered. The card is `issuing` until the issuer fulfils, then `active` — reading an `issuing` card asks the issuer for its current state. 3. Reveal the number and PIN with `GET /v1/identities/{id}/cards/{cid}/credentials` — the one route that returns them. Every reveal is audited and never cached. 4. Log spend against the card with `POST /v1/identities/{id}/cards/{cid}/transactions`; the card refuses a spend that would exceed its load. A prepaid card has no live authorization feed; this ledger is what the identity and its agents record. Credentials live in a table no list or detail read joins; the `card` object carries `brand` and `last4` only. `cancel` retires an active card locally; `refund` returns the credits of a card the issuer never delivered; `retry` re-runs a failed issuance on the same debit. ## Agent tools | Tool | What it does | Policy | | ------------------- | --------------------------------------------------------------------------------- | ------- | | `card.list` | The identity's cards, optionally by status. Grants replace per-agent assignments. | allow | | `card.show` | One card — never a credential. | allow | | `card.quote` | Price a load before buying. | allow | | `card.transactions` | A card's logged spend. | allow | | `card.spend` | Record what the agent spent on a card. Moves no money. | allow | | `card.issue` | Buy a card — debits credits. | **ask** | | `card.credentials` | Reveal a card's number and PIN — audited. | **ask** | | `card.cancel` | Retire an active card. | **ask** | The three `ask` tools go through the ordinary human-in-the-loop proposal: the session pauses on the proposal and the operator approves or declines it, exactly as for any other guarded tool mutation. `retry` and `refund` are operator actions with no agent tool. ## In a blueprint ```ts theme={"system"} identities: [ { name: "Ava", cards: [{ label: "Ads", load_micro_usd: 50_000_000 }] }, ], ``` `naive up` matches by `label`: a live (`pending_payment`, `issuing` or `active`) card with that label is unchanged; a missing or spent-out (`failed`, `cancelled`, `refunded`) one is issued. `naive up --dry-run` quotes instead of issuing and reports the credits it would debit. ## What this replaces Earlier card programs offered a managed virtual card with a cardholder, top-ups, and an external checkout for funding. Vetta ships the prepaid card only: funding is the organization's credits (no checkout, no payment polling), a card is loaded once (no top-up — issue another), and the cardholder and managed-card program are not part of the launch. Assigning a card to an agent is replaced by the identity grant. Quote, issue, reveal, cancel, refund and log spend.