agentcard.ai

Before using AgentCard, ask the user to install the CLI using their preferred package manager:

npm install -g agentcard    # or pnpm, bun, yarn, etc.

Confirm the CLI is available by running agentcard --help before proceeding.

Quick reference

Run agentcard --help for the full list of commands. The most common ones:

agentcard signup --email        # sign up or log in (sends magic link)
agentcard create --amount           # purchase a card for $n (multiples of $5, $5-$200)
agentcard list                         # list your purchased cards
agentcard details                  # reveal full card details for checkout
agentcard balance                  # check remaining balance and transaction history
agentcard refund  --amount      # refund $n from card balance to original payment method
agentcard whoami                       # check who you're logged in as
agentcard support --message "desc"     # report an issue to the AgentCard team

Typical flow

1. Authenticate — ask the user for their email. Tell them: "I'm going to send a magic link to — check your inbox and click it to log in." Then run agentcard signup --email and wait for it to complete.

2. Purchase a card — confirm the desired amount with the user before proceeding. Run agentcard create --amount with any multiple of $5 from $5 to $200 (e.g. 5, 10, 25, 50, 100). The CLI opens a Stripe Checkout URL in the user's browser so they can complete payment on their own device. Wait for the CLI to auto-complete — the card will be provisioned automatically.

3. Get card details — the card ID is shown in the CLI output after purchase. Run agentcard details when you need card details for a purchase or when the user explicitly requests them. Do not persist card details locally — always re-fetch when needed. Only display card details to the user if they explicitly ask for them.

4. Check balance — at any time, run agentcard balance to see the remaining available balance and a list of all transactions on the card. Note: each time you check the balance, a refresh is requested in the background. The refreshed data may take a few minutes to become available. If the balance looks stale, wait 2-3 minutes and run the command again to see updated results.

5. Refund remaining balance — when the user is done with a card and wants to reclaim unused funds, run agentcard refund --amount . This returns a Stripe checkout URL that charges the AgentCard prepaid card to withdraw the balance back to the user's original payment method. This only works with cards purchased through agentcard.ai.

Always confirm with the user before initiating a refund. Share the Stripe checkout URL with the user and instruct them to complete it using the card details shown in their agentcard details output.

Note: refunds are limited to the greater of $5 or 25% of the card value. For larger refunds, instruct the user to email ben.yu@alchemy.com explaining their situation.

Tips

Reporting Issues

If you encounter any issue while using AgentCard — failed purchases, unexpected errors, declined transactions, or anything else — report it:

agentcard support --message "detailed description" [--card-id ] [--url ] [--error ]

Include what you were trying to do, what happened, any error messages, and the card ID if relevant.

Reporting Issues

If you encounter any issue while using AgentCard — failed purchases, unexpected errors, declined transactions, or anything else — report it:

agentcard support --message "detailed description" [--card-id ] [--url ] [--error ]

Include what you were trying to do, what happened, any error messages, and the card ID if relevant.