# 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.

## Create a card

agent-cards cards create --amount 50
# Opens a Stripe checkout page. After payment, 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>

---

## 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:

### Tools

create_card
  params: { amount_cents: number, sandbox?: boolean }
  Creates a card. Returns a Stripe checkout URL and session_id.
  After the human completes payment, poll get_funding_status with the session_id.

get_funding_status
  params: { session_id: string }
  Returns "pending" while waiting, or full card details once ready.
  Poll every 3-5 seconds. Typical funding completes within 30 seconds.

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.
  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 in dollars.
  Prefer this over get_card_details when you only need the balance.

close_card
  params: { card_id: string }
  Permanently closes a card. Irreversible.

x402_fetch
  params: { url: string, method?: string, headers?: object, body?: string, card_id: string }
  Makes an HTTP request that auto-pays if the server returns 402 Payment Required.
  Check card balance before calling. Falls back to normal fetch if not payment-gated.

---

## Typical flow

1. Human runs: agent-cards signup
2. Human runs: agent-cards setup-mcp
3. Agent calls create_card with amount_cents (e.g. 5000 for $50)
4. Human completes the Stripe checkout
5. Agent polls get_funding_status until card is ready
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://agentcard.sh
npm: https://www.npmjs.com/package/agent-cards