Agent Card

Agent Card provides virtual payment card capabilities for autonomous agents, enabling real-world financial transactions through the ACP CLI.

Agent Card is powered by Alchemy, whose infrastructure handles card issuance, transaction processing, and settlement.

Features

• Single-use virtual cards — each card authorizes a specific amount and is consumed on use
• 30-minute validity — cards expire 30 minutes after issuance; spend immediately or discard
• Synchronous issuance — card number, CVV, and expiry returned inline, no checkout step
• Account-scoped payment method — attach a card once, issue many spend requests against it
• Spend limit control — cap how much the account can issue in total
• Per-agent ownership — multiple agents can share one account without seeing each other's cards
• Guided setup via nextStep — every response carries a breadcrumb telling the caller exactly which step to run next
• 3DS verification codes — fetch one-time codes when a merchant runs a 3DS challenge mid-checkout
• Email-based authentication — secure access via magic link

How It Works

1. Signup — run acp card signup or navigate to the Card section in the Identity tab in your agent dashboard. Key in your user email. Multiple agents can share a single user email; issued cards remain scoped to the agent that created them.
2. Verification — a magic link is sent to the inbox. Open the email and click the link, then poll acp card signup-poll until verification completes.
3. Profile — set first name, last name, and phone (E.164) via acp card profile set.
4. Payment method — run acp card payment-method to start a Stripe setup flow. The saved payment method is account-scoped and reused for every future issuance; re-running the command replaces the saved method.
5. Spend limit — run acp card limit set --amount <cents> to cap how much the account can issue in total (inspect with acp card limit).
6. Issue a card — run acp card issue --amount <cents> with the amount. A single-use virtual card is issued synchronously against the saved payment method and remaining limit.
7. Spend — use the card number, expiry, and CVV at any merchant that accepts card payments. Cards are valid for 30 minutes from issuance, so charge the card promptly.
8. 3DS challenges (conditional) — if checkout asks for a 3DS verification code, run acp card 3ds to retrieve it. The card network pushes the code to the account; this command lists codes received in the last ~5 minutes.

Cards are single-use and issued synchronously. There is no top-up, no checkout step, and no refund flow — issuance draws directly against the saved payment method and the remaining spend limit.

Guided Setup: nextStep

Every mutating response — and every actionable 4xx from POST /card/request — returns a nextStep breadcrumb so agents, CLI, and FE clients can walk the flow without introspecting profile fields:

nextStep: {
  action: 'signup' | 'pollSignup' | 'updateProfile' | 'addPaymentMethod'
        | 'completePaymentMethod' | 'setLimit' | 'issueCard',
  endpoint: string,   // "METHOD /agents/<agentId>/card/..." — directly callable
  hint: string,       // human-readable, safe to surface to the user
  missing?: string[], // only on `updateProfile` — exact fields still null
} | null              // null when account is locked or already at terminal state

• endpoint has the real agent ID substituted — callers can pass it straight to fetch / curl with no placeholder resolution.
• Error bodies include it too: if POST /card/request is called before setup is complete, the 400 body carries { message, nextStep } so agents can self-correct.
• A single check — response.nextStep?.action === 'issueCard' — replaces the old pattern of inspecting four profile fields to decide whether the agent can issue a card.

CLI Commands

All amount flags are in cents (the BE DTO takes integer cents).

Use Cases

• Autonomous purchasing — agents can buy digital services and subscriptions
• Expense management — track agent spending across cards
• Service payments — pay for external APIs, hosting, and infrastructure