Skip to content
AlumiaDocs

Search docs

Find pages, headings, and concepts. Press ⌘K or Ctrl+K to toggle.

Agent Wallet

Request spend, approve with step-up, and manage virtual card lifecycle.

Open in ChatGPTOpen in Claude

Agent Wallet lets teams give agents controlled purchasing power without handing out shared cards. The flow is request first, approve with fresh step-up, then issue and manage a virtual card tied to the approved spend.

1. Open Agent Wallet

Open /<orgSlug>/billing and switch to Agent Wallet. Admin operators can also review wallet activity from /admin/agent-wallet.

The wallet view shows spend requests, issued cards, authorization status, and recent wallet activity. If the wallet is not enabled for the org, the page explains the missing setup state before any card controls appear.

2. Create a spend request

Create a spend request for the agent, project, or session that needs purchasing power. Include:

  • amount and currency
  • reason for the spend
  • optional merchant category or merchant country constraints
  • the agent, project, or session context that explains why the request exists

The API equivalent is:

POST /api/v1/agent-wallet/spend-requests

Requests are stored without sensitive caller metadata, and approval remains separate from creation. This keeps an agent from silently granting itself card access.

3. Approve with step-up

An approver with billing permissions reviews the request and approves it. Approval requires a browser session with fresh step-up, such as TOTP or a passkey. If step-up has expired, Alumia sends the approver through /auth/step-up before retrying the approval.

The API path used by the dashboard is:

POST /api/v1/agent-wallet/spend-requests/[id]/approve

API-key sessions cannot bypass this approval gate. Complete the approval in the dashboard so the session can prove both billing permission and fresh authentication.

4. Issue a virtual card

After approval, issue a virtual card tied to the approved amount and controls. The dashboard uses:

POST /api/v1/agent-wallet/cards

Card details are revealed only through a stepped-up browser session:

POST /api/v1/agent-wallet/cards/[id]/reveal

Use the card for the approved purchase. Stripe Issuing authorizations and webhooks update the card and spend request status asynchronously as merchants authorize, capture, reverse, or decline charges.

5. Manage the card lifecycle

From the card list, operators can:

  • freeze a card temporarily
  • cancel a card permanently
  • inspect authorization decisions
  • compare captured spend against the approved request
  • investigate webhook-delivered status changes

If the purchase fails, check the authorization reason first. Common causes are amount overages, merchant category mismatches, merchant country restrictions, or a card that was frozen after approval.

Verify

For a safe sandbox run, create a small spend request, approve it after step-up, issue a sandbox virtual card, and simulate an authorization from the Agent Wallet sandbox controls. The wallet activity should show the request, card, and authorization in order.