# AgentCard — Quick Reference for AI Agents

Virtual debit cards you can use to pay for things online.
Cards are funded with a fixed USD amount and work anywhere Mastercard is accepted.

## When to Use AgentCard

- You need to buy something online (API credits, domains, SaaS subscriptions, data, licenses)
- You need a virtual card with a hard spending limit for a specific task
- You need to make an x402 payment to access a paid HTTP resource
- A human has asked you to purchase something and you need payment credentials

## When NOT to Use AgentCard

- You need to make a physical in-store purchase (these are virtual cards, CNP only)
- You need recurring billing that auto-renews (cards are single-use)
- You need to send money to another person (use a payment service instead)
- The merchant requires 3DS/SMS verification (virtual cards may not support interactive auth)

## Install

npm install -g agent-cards

## Authenticate

agent-cards signup
# Enter your email, click the magic link in your inbox. Done.

## Set up a payment method

agent-cards payment-methods setup
# Opens a Stripe page to save your card. Required before creating virtual cards.

## Create a card

agent-cards cards create --amount 50
# Charges your saved payment method. Card details print in your terminal.

## List your cards

agent-cards cards list

## Get card details (PAN, CVV, expiry)

agent-cards cards details <card-id>

## Check balance

agent-cards balance <card-id>

## View transactions

agent-cards cards transactions <card-id>

---

## MCP Integration (Claude Code / Claude Desktop)

Run this to connect the MCP server:

agent-cards setup-mcp

This registers the following tools with your MCP client:

### Core Tools

setup_payment_method
  params: {}
  Sets up a payment method for future card creation.
  Returns a Stripe checkout URL for the user to save their card details.
  Must be done once before creating any cards.

create_card
  params: { amount_cents: number, sandbox?: boolean }
  Creates a virtual card funded from the saved payment method.
  Limits: max $50 per card, max 5 cards/month (free plan).
  May return user_info_required — if so, call submit_user_info first.
  Use sandbox: true for testing without real charges.

submit_user_info
  params: { phone_number: string, terms_accepted: boolean }
  Submit phone number and terms acceptance required before first card creation.
  Call this when create_card returns a user_info_required response.

list_cards
  params: {}
  Returns all cards with ID, last four, expiry, balance, status.
  If empty, call create_card to issue a new one.

get_card_details
  params: { card_id: string }
  Returns decrypted PAN, CVV, expiry, balance.
  May require human approval — if so, prompt the user and call approve_request.
  Use only when you need to fill in a payment form. Prefer check_balance for balance checks.

check_balance
  params: { card_id: string }
  Returns current balance. Faster than get_card_details and does not expose credentials.

close_card
  params: { card_id: string }
  Permanently closes a card. Irreversible. Safe to call on already-closed cards.

list_transactions
  params: { card_id: string, limit?: number, status?: string }
  Returns transactions with amount, merchant, status, timestamps.
  Filter by status: PENDING, SETTLED, DECLINED, REVERSED, EXPIRED, REFUNDED.

approve_request
  params: { approval_id: string, decision: "approved" | "denied", action: "card_details" | "transaction", resource_id: string }
  Resolve a pending approval request. Required when get_card_details or create_card returns a 202.
  On approval, automatically completes the follow-up action and returns the result.

### Chrome Extension Tools

pay_checkout
  params: { url?: string, amount_cents?: number, tab_id?: number }
  Auto-fill a checkout page with an AgentCard. Creates or reuses a card, fills the payment form.
  Requires Chrome with the AgentCard Pay extension installed.
  If not installed: npx agent-cards extension install

fill_card
  params: { card_id: string, tab_id?: number }
  Fill an existing card into the current checkout form.
  Requires Chrome with the AgentCard Pay extension.

detect_checkout
  params: { tab_id?: number }
  Check if the current browser tab is a checkout page.
  Returns detection confidence, detected amount, and scoring signals.

remove_payment_method
  params: { payment_method_id: string }
  Remove a saved payment method permanently.

### Support Tools

start_support_chat
  params: { message: string }
  Start a new support conversation.

send_support_message
  params: { conversation_id: string, message: string }
  Send a message in an existing support conversation.

read_support_chat
  params: { conversation_id: string }
  Read the message history of a support conversation.

---

## Typical flow

1. Human runs: agent-cards signup
2. Human runs: agent-cards setup-mcp
3. Human sets up payment method via setup_payment_method (one-time)
4. Agent submits user info via submit_user_info if first time (one-time)
5. Agent calls create_card with amount_cents (e.g. 5000 for $50)
6. Agent calls get_card_details to get the PAN, CVV, expiry
7. Agent uses the card to pay for something online
8. The card closes automatically after the first transaction (single-use)

## Links

Website: https://www.agentcard.sh
npm: https://www.npmjs.com/package/agent-cards