---
name: agentcard
description: Requests card credentials for AI-agent purchases from a chosen payment source — AgentCard-issued single-use virtual cards by default, or the user's own connected network-tokenized cards (experimental, passkey-approved) — completes KYC verification when required, handles checkout 3DS challenges, manages the user's AgentCard agent email inbox, and uses the AgentCard USDC wallet for Base/x402 payments. Use when an agent needs to pay a merchant, complete required KYC, create a capped virtual card, complete a checkout, fetch paid x402 content, send or read agent email, inspect spend limits, or troubleshoot AgentCard CLI payments.
version: 2.0.0
author: "Alchemy (https://alchemy.com)"
license: MIT
homepage: https://agentcard.ai
prerequisites:
  commands:
    - npm
metadata:
  hermes:
    tags:
      - payments
      - commerce
      - identity
      - virtual-cards
      - agent-commerce
      - email
      - wallet
      - x402
      - 3ds
    category: payments
    homepage: https://agentcard.ai
    requires_toolsets:
      - terminal
---

# AgentCard

AgentCard gives agents payment and identity tools with user-controlled limits. The core model: **request a card credential for a purchase, choosing where the money comes from**:

- Source `agentcard` (default): a single-use virtual card issued by AgentCard, capped to the requested amount, live for 7 days, funded by a hold on the user's saved payment method. Instant, no approval step.
- Source `connected` (experimental): a one-time credential minted from one of the user's own enrolled Visa/Mastercard cards via network tokenization (Visa Intelligent Commerce first; Mastercard Agent Pay through the same commands later). Requires a browser passkey approval per purchase, is scoped to a specific merchant and amount, and supports multiple enrolled cards with per-purchase card choice.
- KYC verification for new or non-exempt direct accounts before spend.
- A dedicated `@agentcard.email` inbox for signups, verification codes, and user-approved communication.
- A self-custodial USDC wallet on Base for x402 HTTP payments and USDC transfers.

Prefer exact, command-driven workflows. The `agentcard create` and `agentcard agentic *` command families have been REMOVED — if instructions you hold reference them, refetch this skill. Purchases live under `agentcard request`; payment-source management lives under `agentcard sources`.

Experimental note: the connected-card source is very new and must not be the default checkout path. Prefer the default issued card (`agentcard request new --amount <dollars>`) unless the user explicitly chooses the connected-card path and understands that Visa Intelligent Commerce currently works only for a limited subset of Visa-issued cards.

## Install And Check

```bash
command -v agentcard >/dev/null || npm install -g agentcard
agentcard --version
agentcard --help
```

Use normal shell execution and parse stdout/stderr; many commands intentionally block while polling for user action. Every `request *` and `sources *` command accepts `--json` for machine-readable output (success: `{ "ok": true, ... }`; failure: `{ "ok": false, "error", "code"?, "fallback"? }`).

## Operating Rules

- Spend only for the amount and purpose the user requested. If the merchant, recipient, amount, or payment method is ambiguous, ask before paying.
- Never collect or type the user's real payment card details. During setup, show the printed Stripe setup URL to the user and let them complete it. Connected-card enrollment likewise happens in the user's browser via `agentcard sources connect`.
- New or non-exempt direct accounts must complete KYC verification before spend. Run `agentcard identity --no-open`; if it prints a verification URL, relay it to the user and wait for completion. Existing grandfathered accounts may be marked exempt and need no document check. Partner API accounts are manually provisioned by AgentCard and do not need the direct-user KYC flow.
- Normal direct accounts have a hard `$200` daily spend ceiling shared across both sources, in addition to the per-card cap and the per-source account limits. `agentcard limit --amount` cannot bypass the daily ceiling. Partner accounts with active API keys or webhooks use separately configured limits and are exempt from KYC verification and the default direct-user ceiling.
- Account-level spend limits are per source: the issued-card + wallet budget and the connected-card budget are separate. `agentcard limit` shows both.
- Treat PAN, CVV, expiry, billing address, billing ZIP, wallet addresses, emails, 3DS codes, and verification codes as sensitive. Do not save card details or codes in durable notes unless the user explicitly asks.
- For cards, use the printed cardholder name and billing address exactly. Mismatches can cause declines.
- New AgentCard issued cards use cardholder name `Alchemy Agentcard` and billing address `77 Geary St, San Francisco, CA, 94108, US`. Use those values at checkout unless the CLI prints newer card-specific billing fields.
- Use `agentcard support` immediately for failed purchases, CAPTCHAs, declines, confusing errors, or merchant checkout blocks.

## Quick Reference

| Task | Command |
|------|---------|
| Sign up or log in | `agentcard signup --email <email>` |
| Set up payment, email, wallet | `agentcard setup` |
| Complete KYC | `agentcard identity [--no-open]` |
| Reset setup | `agentcard setup --reset` |
| Show spend limits (both sources) | `agentcard limit` |
| Change issued-card limit | `agentcard limit --amount <dollars>` |
| Change connected-card limit | `agentcard limit --amount <dollars> --source connected` |
| List payment sources | `agentcard sources` |
| Connect user's own card (experimental) | `agentcard sources connect [--network visa\|mastercard\|auto]` |
| Set default connected card | `agentcard sources default <payment-method-id>` |
| Remove connected card | `agentcard sources remove <payment-method-id>` |
| Issue single-use card (default) | `agentcard request new --amount <dollars>` |
| Connected-card purchase (experimental) | `agentcard request new --source connected --merchant <name> --url <merchant-url> --item <item> --amount <dollars> [--card <payment-method-id>]` |
| List purchases (both sources) | `agentcard request get` |
| Purchase details / re-fetch live card | `agentcard request get <id>` |
| One-time connected credential | `agentcard request credentials <id>` |
| Cancel unused issued card | `agentcard request cancel <id>` |
| Get checkout 3DS code | `agentcard 3ds` |
| Show agent email | `agentcard mail info` |
| List email threads | `agentcard mail list [--include-sent]` |
| Read email thread | `agentcard mail get <thread-id>` |
| Send email | `agentcard mail send --to <email> --subject <subject> --body <body>` |
| Reply to thread | `agentcard mail reply <thread-id> --body <body>` |
| Show wallet | `agentcard wallet info` |
| Print USDC balance | `agentcard wallet balance` |
| Send USDC on Base | `agentcard wallet send --to <0x...> --amount <usdc>` |
| x402 fetch | `agentcard wallet fetch <url> [-H "Key: Value"] [-X METHOD] [-d BODY] [--max-cost <usdc>]` |
| Current account | `agentcard whoami` |
| Report issue | `agentcard support --message "details" [--card-id <id>] [--url <url>] [--error <error>]` |

## First-Time Setup

1. Authenticate:

   ```bash
   agentcard signup --email <user-email>
   ```

   The command sends a magic link and polls for up to five minutes. Tell the user to check their inbox and click the link. Let the process finish; do not kill and retry while it is polling.

2. Run setup every time after authentication and before payment work:

   ```bash
   agentcard setup
   ```

   Setup is idempotent: if the account is already configured, it prints the current setup status and exits cleanly. It does not collect name, phone number, or manual KYC fields. Setup ensures a saved payment method exists for card holds, provisions the agent email inbox for signups and verification codes, and provisions the Base wallet for USDC/x402 payments. If setup prints a Stripe setup URL, relay the URL to the user and wait for completion, especially in headless or remote environments where the local browser may not be visible to them.

3. Confirm identity status:

   ```bash
   agentcard identity --no-open
   ```

   If the direct account is new or otherwise non-exempt, the command prints a KYC verification URL. Relay that URL to the user, wait for them to complete the hosted KYC flow, then rerun `agentcard identity --no-open` or retry the spend. Existing grandfathered and partner accounts may report that verification is not required.

4. Verify setup:

   ```bash
   agentcard whoami
   agentcard limit
   agentcard mail info
   agentcard wallet info
   ```

Run setup again whenever a task may need cards, agent email, or wallet access. Run `agentcard identity --no-open` before spend work when the account's verification status is unknown. Use `agentcard setup --reset` only when the user explicitly wants to replace payment method or agent email setup.

## Choose Payment Path First

Before issuing a card credential or initiating a wallet payment, determine the payment path from the merchant, recipient, or API surface:

1. Get the final total first, including shipping, taxes, and fees. Do not create a card credential before the final amount is known.
2. Understand what the user is buying well enough that the payment purpose is recognizable.
3. Choose the matching path:

| What you find | Use |
|---------------|-----|
| Merchant accepts a card at checkout | Card Credential Workflow with the default `agentcard` source |
| User explicitly asks to pay with their own connected card and has an active one | Card Credential Workflow with `--source connected` |
| HTTP endpoint returns `402 Payment Required` with x402 requirements | Wallet and x402 workflow |
| User gives a Base USDC recipient address and amount | Direct USDC send, after confirming recipient and amount |
| Payment method, amount, merchant, or recipient is unclear | Ask the user before creating credentials or paying |

The default source is always `agentcard` (issued single-use card). Use the connected-card source only when the user explicitly chooses it after being told it is experimental, limited to supported Visa-issued cards today, and may fail during enrollment, approval, or credential retrieval.

## Card Credential Workflow

One workflow covers both sources; only step 4 differs.

1. Get the final checkout total. `--amount` accepts decimals for both sources. Issued cards use whole-dollar caps from `1` to `150` — the CLI rounds a decimal total up and prints the rounding (`$24.99` becomes a `$25` cap). Do not add extra padding beyond the total.
2. If the total is over `150` (issued source), do not issue a card. Ask the user for a lower-cost plan, a different payment path, or explicit approval for a merchant-supported split payment. Do not split a checkout across multiple cards unless the merchant supports separate charges and the user approves.
3. Preflight, shared by both sources:
   - For subscriptions or trials on the issued source, do not proceed until the user explicitly accepts that the card is live for 7 days and future recurring charges may fail.
   - Confirm identity status with `agentcard identity --no-open`. If verification is required, relay the KYC verification URL to the user, wait for completion, and retry.
   - Check available spend with `agentcard limit` — it shows both budgets. If the purchase exceeds the relevant remaining limit, request an increase with `agentcard limit --amount <dollars>` (issued) or `agentcard limit --amount <dollars> --source connected`. This emails the account owner an approval link; tell the user to check their email. Approval links expire after 24 hours, and a newer request for the same limit supersedes older links. Lowering a limit applies immediately as long as it is not below the amount already spent.
   - Normal direct accounts also have a hard `$200` daily spend ceiling shared across both sources. A limit increase cannot bypass it. On `daily_spend_limit_exceeded`, stop and ask the user to wait until the next UTC day or use an approved partner account.
4. Issue the credential:

   **Default source (issued single-use card)** — instant, no approval step:

   ```bash
   agentcard request new --amount <dollars>
   ```

   **Connected source (experimental, explicit user opt-in only)** — needs the real merchant URL, no placeholders. Check `agentcard sources` first; if no active connected card exists, ask the user to approve enrollment and run `agentcard sources connect`. Then:

   ```bash
   agentcard request new --source connected --merchant "<merchant-name>" --url "<merchant-url>" --item "<item-or-cart>" --amount <dollars>
   ```

   The command opens a browser approval page, blocks while the user approves with a passkey, then prints a one-time PAN, CVV, and expiry. Add `--card <payment-method-id>` to pick a specific connected card (see `agentcard sources`), `--network visa|mastercard` to filter by network, `--async` to create the approval and return immediately with its URL, or `--wait` to wait for approval without consuming the one-time credential.

5. Enter the printed card details exactly once at the merchant checkout. Do not store them. For issued cards, the cardholder name is `Alchemy Agentcard` and the billing address is `77 Geary St, San Francisco, CA, 94108, US`; the card expires 7 days after issue.
6. If checkout asks for a 3DS or card verification code, run:

   ```bash
   agentcard 3ds
   ```

   3DS is conditional, not a required step. Codes usually appear within a few seconds and are listed for five minutes. Choose the code whose amount matches the checkout charge amount, not the rounded card cap; if multiple codes match, use the newest. Enter it directly into checkout. If no amount matches, wait a few seconds and run `agentcard 3ds` again.

7. Follow-ups by id (`agentcard request get` lists every purchase across both sources):
   - `agentcard request get <id>` — status and details; re-prints a live issued card's PAN/CVV.
   - `agentcard request credentials <id>` — retrieve a connected purchase's one-time credential after approval (also re-serves issued card details for symmetry). Credentials are retrievable through authenticated CLI/API calls only; browser action tokens can approve an instruction but cannot retrieve PAN/CVV.
   - `agentcard request cancel <id>` — cancel an unused issued card and release its hold immediately. Only live, unused issued cards can be canceled; used or expired cards return an error, and connected purchases simply expire on their own.

8. **Fallback rule**: if any connected-source step fails — enrollment unsupported, approval timeout or decline, credential retrieval error — tell the user, then fall back to the default issued card: `agentcard request new --amount <rounded-up-total>`. The CLI prints this fallback command on connected-source failures.

For issued cards, AgentCard places a hold on the user's stored payment method for the requested amount before issuing the virtual card. If the hold fails or the funding card needs unresolved bank authentication, no card is issued. The user is charged only if the merchant uses the card; unused holds release within seven days, or immediately via `agentcard request cancel <id>`. Connected-card purchases charge the user's own enrolled card directly at the merchant; AgentCard never holds funds for them.

## Wallet And x402 Workflow

Use the wallet for USDC on Base and HTTP endpoints that return `402 Payment Required` with x402 requirements.

```bash
agentcard wallet info
agentcard wallet balance
agentcard wallet fetch <url> --max-cost <usdc>
```

`wallet fetch` wraps native fetch, pays x402 requirements in USDC when needed, retries the request, and prints the final response body to stdout. Always pass `--max-cost` unless the user explicitly approved any valid charge from that endpoint. The value is decimal USDC, not atomic token units; for dollar-pegged USDC amounts, 15 USD cents is `--max-cost 0.15`.

Pass HTTP details through the CLI when the endpoint needs them:

```bash
agentcard wallet fetch <url> -H "Authorization: Bearer <token>" -X POST -d '<json-body>' --max-cost <usdc>
```

Use one `-H` flag per header. The final response body is printed to stdout; stderr contains HTTP/payment errors.

For direct USDC transfers:

```bash
agentcard wallet send --to <0x-recipient> --amount <usdc>
```

Before sending USDC, confirm the recipient address and amount are exactly what the user intended. Gas is sponsored, but USDC and x402 spend count toward the same AgentCard spend controls as issued cards, including the normal direct-account daily ceiling when it applies. Fund the wallet by sending USDC on Base to the address from `agentcard wallet info`.

## Agent Email Workflow

Use the agent email for account signup, verification codes, receipts, and user-approved communication. Read verification codes only for the active user-approved workflow, enter them directly into the target service, and do not paste them into chat or store them unless the user explicitly requests it.

```bash
agentcard mail info
agentcard mail list --include-sent
agentcard mail get <thread-id>
agentcard mail send --to <email> --subject <subject> --body <body>
agentcard mail reply <thread-id> --body <body>
```

Prefer `agentcard mail get <thread-id>` before replying so the response matches the current thread context.

## Troubleshooting

| Symptom | Action |
|---------|--------|
| `agentcard: command not found` | Run `npm install -g agentcard`, then `agentcard --version`. |
| Old `agentcard agentic ...` or `agentcard create` commands error | Those commands were removed. Refetch this skill; use `agentcard request new [--source connected ...]` and `agentcard sources`. |
| Not logged in or session expired | Run `agentcard signup --email <email>` again. |
| Missing payment method, email, or wallet | Run `agentcard setup`. |
| KYC verification required | Run `agentcard identity --no-open`, relay the KYC verification URL to the user, and wait for completion before retrying spend. Do not ask the user to send ID documents directly to the agent. |
| Connected-card source disabled or unavailable | Use the default `agentcard request new --amount <dollars>` after confirming the final total. |
| No active connected card | Use the default issued card. Ask the user to approve `agentcard sources connect` only if they explicitly want the experimental path. |
| Card enrollment fails | Explain that the card may not be supported by Visa Intelligent Commerce yet and use `agentcard request new --amount <dollars>` instead. |
| Multiple active connected cards in headless mode | Run `agentcard sources`, then pass `--card <payment-method-id>` or set a default with `agentcard sources default <payment-method-id>`. |
| Connected purchase missing URL | Get the real merchant checkout or site URL before creating the purchase. Do not use placeholders. |
| Passkey approval timeout | Run `agentcard request get <id>`; if still awaiting approval, ask the user to approve in the browser or rerun the purchase command. Otherwise fall back to the issued card. |
| Amount rejected | Issued cards are capped at `$150` during beta; the CLI rounds decimal totals up to whole dollars. Stop and ask the user if the rounded-up total is over `150`. |
| Spend limit exceeded | Run `agentcard limit` (shows both budgets), then `agentcard limit --amount <dollars>` or `agentcard limit --amount <dollars> --source connected` for the budget that tripped. Tell the user to check their email address and approve the link before retrying. |
| Daily spend ceiling hit | Normal direct accounts cannot spend over `$200` per UTC day across both sources. Stop and ask the user to wait until the next UTC day or use an approved partner account with separate limits. |
| 3DS code missing | Run `agentcard 3ds` only after checkout requests a code. Wait a few seconds and retry; if no matching recent code appears, file support. |
| Card declined | Check the live 7-day window, exact billing fields (`Alchemy Agentcard`; `77 Geary St, San Francisco, CA, 94108, US`), 3DS challenge status, and spend limit. File support, then ask the user before issuing a replacement card. |
| Wallet not provisioned | Run `agentcard setup`. |
| Wallet balance too low | Show `agentcard wallet info` and ask the user to fund the Base USDC address. |
| x402 fetch fails | Retry with `--max-cost`, inspect stderr, and report persistent failures. |

## Report Issues

For any purchase failure, decline, CAPTCHA, anti-bot block, unexpected CLI error, confusing output, or merchant checkout problem, run:

```bash
agentcard support --message "what happened, what you tried, and what the user expected" --url "<checkout-or-api-url>" --error "<error-text>"
```

Add `--card-id <id>` when the issue involves a specific card request.

Redact secrets from support messages and errors: never include PAN, CVV, bearer tokens, 3DS codes, verification codes, or private keys.