agent-card

AgentCard

通过 AgentCard MCP 工具，帮助用户管理虚拟 Visa 卡，并代表用户购物。

词汇说明：用户的 WALLET 指的是他们的卡；BALANCE 指的是他们的现金。卡片通过 balance 充值。用户使用 Apple Pay 或 Google Pay 充值（资金以 USDC 持有，但用户始终以 USD 充值和消费）。首次充值需要进行一次性的身份验证步骤——下方的工作流会引导用户完成该步骤。

设置

工具前缀为 mcp__agent-cards__*。如果没有可用的 AgentCard 工具，请阅读 references/setup.md，并指导用户连接 MCP 服务。

重要：如果你刚在本次会话中添加了 MCP 服务，这些工具要等会话重启后才会可用。请告知用户重启其 Agent 会话，然后再回来重试。不要退而使用针对 API 的原始 curl 调用——API 路由是内部接口，可能会发生变化。请使用 MCP 工具或 CLI（参见 CLI 参考）。

可用工具

工具	用途
list_cards	列出所有卡片及其 ID、末四位数字、到期时间、余额和状态
create_card	创建一张新的虚拟 Visa 卡，使用钱包余额充值（默认单次使用；订阅请传入 type: "multi_use" — 参见卡片类型）
get_card_balance	查询实时余额，不暴露凭据
get_card_details	获取解密后的 PAN、CVV 和到期时间（可能需要审批）
close_card	永久关闭一张卡（不可撤销）
pause_card	阻止多次使用卡产生新的扣款（可撤销）
resume_card	解除多次使用卡的暂停状态
update_card_limit	调整多次使用卡的总额度（提高额度会从钱包余额中扣款）
get_balance	显示充值钱包、余额和状态
add_funds	通过 Apple Pay / Google Pay 以 USD 充值 — 返回一个一次性付款链接，可提供给用户
start_phone_verification	发送（或重新发送）充值前所需的一次性验证码；报告已遮蔽的接收地址（短信或电子邮件）
verify_phone	验证用户读回的一次性验证码（验证有效期为 60 天）
withdraw	将钱包资金提现到已保存的银行账户，或以 Base 上的 USDC 提现（由 AgentCard 团队执行，通常需要 1-3 个工作日）
create_withdrawal_recipient	保存银行账户（ACH 或国际电汇）作为提现目的地
redeem_code	使用促销码并将金额存入钱包（每位用户每个代码仅可使用一次）
list_codes	列出用户的促销码历史记录 — 用户已兑换或尝试使用的代码及其状态（used / processing / available 可重试 / expired）。无法发现用户从未提供过的代码
start_kyc	开始对话式身份验证（政府签发的证件照片 → 确认字段 → 在浏览器中进行简短的人脸扫描）
get_kyc_status	轮询身份验证状态，直到验证通过
get_rewards	显示 AI 卡消费获得的 TOKENBACK 奖励余额
redeem_rewards	兑换累计的 TOKENBACK
list_transactions	列出单张卡的交易，包括金额、商家、状态和时间戳
list_all_transactions	以一个平铺列表列出所有卡片的交易，每笔交易均标注对应卡片（id + last4）
list_transactions_by_payment_method	按付款方式分组列出交易（钱包 USDC 消费、已保存卡片消费、Apple/Google Pay 钱包充值），并包含商家信息和每笔购买对应的买单
whoami	显示已认证账户的信息：电子邮件、姓名、套餐、KYC + 账户状态，以及当前会话是个人登录还是第三方 OAuth 连接
attach_card	关联用户自己的卡片（BYOC），让购买直接从该卡扣款
link_account	将此登录关联到现有 AgentCard 账户
complete_kyc_transfer	使用当前充值渠道重新注册现有验证
submit_funding_profile	提交一次性充值资料问卷（职业、收入范围、预期交易量）；部分充值渠道要求填写
submit_kyc_document / submit_kyc_fields / check_kyc_document	对话式 start_kyc 流程的步骤（证件照片、缺失字段、证件状态）
buy_connect / buy_connect_status	关联用于购物的商家账户并查看关联状态
get_settings / update_settings	查看和更改通知/账户设置
manage_subscription	管理付费套餐订阅
surprise_me	趣味功能：让 Agent 挑选一份小礼物购买
setup_payment_method	通过 Stripe 保存付款方式
remove_payment_method	从 Stripe 移除已保存的付款方式
list_payment_methods	列出已保存的付款方式（id、品牌、last4、到期时间；标记默认方式）
set_default_payment_method	选择默认的已保存付款方式
buy	根据自然语言请求，在受支持的商家（DoorDash、Good Eggs、Rappi）购物并结账。这是完整的购物功能 — 它会构建购物车、询问配送地址、确认总额并下单，同时自动创建一张用于付款的卡
get_instructions	获取最新的购物/结账使用指南。在使用 buy 之前必须调用此工具
buy_list_merchants	列出受支持的商家，以及用户是否已关联各商家
buy_unlink_merchant	断开已关联的商家（删除已保存的会话；用户必须重新关联才能再次在该商家购物）
submit_user_info	提交首次创建卡片前所需的电话号码并接受条款
get_plan	显示当前套餐、卡片限额、每月用量和升级选项
upgrade_plan	启动 Stripe Checkout 以升级到 Basic 套餐
cancel_plan	取消当前付费订阅（恢复为 Free）
list_connections	列出通过 OAuth 连接到该账户的第三方应用（只读）
approve_request	批准或拒绝待处理的审批请求
start_support_chat	开启新的客服对话
send_support_message	在客服对话中发送消息
read_support_chat	查看客服对话的消息历史记录

工作流

使用指南

当用户的意图不明确时，先调用 list_cards 查看已有内容。后续调用使用响应中的卡片 ID。对于金额相关的问题，get_balance 会显示用于创建卡片的钱包余额。

为钱包充值

1. 调用 get_balance 查看当前余额和钱包状态。
2. 使用金额（单位为美分）和用户的 payment_method 调用 add_funds — "apple_pay"（默认）或 "google_pay"；如果不知道用户使用哪种方式，请询问。该工具会返回一次性付款链接 — 必须将链接原样转发给用户（绝不要缩短、展开或改写 URL），并告知用户打开链接并付款。资金会在几分钟内到账。
3. 如果 add_funds 报告需要验证：它会自动向用户发送一次性验证码，并报告验证码的发送渠道（短信或电子邮件，信息已屏蔽）。向用户索取验证码，使用该验证码调用 verify_phone，然后再次调用 add_funds。验证结果在 60 天内有效。
4. 如果始终收不到验证码：调用 start_phone_verification 重新发送（每 10 分钟发送次数有限 — 不要频繁发送）。
5. 如果完全无法发送验证码（账户尚无已验证的身份信息 — 新账户通常如此）：用户必须先完成身份验证。执行“创建卡片”流程（依次调用 submit_user_info 和 start_kyc）— 已验证的身份信息会提供电话号码，之后即可充值。
6. 付款链接只能使用一次 — 如果链接已被使用或过期，只需再次调用 add_funds 获取新链接。
7. 如果用户有促销码，redeem_code 会应用该促销码并直接为钱包充值；list_codes 会显示促销码历史记录（包括可重试的失败尝试）— 它无法查找用户从未提供过的促销码。

创建卡片

1. 向用户询问卡片金额。将美元转换为美分（例如 $25 = 2500）。限额取决于套餐 — 不确定时调用 get_plan。
2. 使用 amount_cents 调用 create_card。卡片资金从钱包余额中扣除。
3. 处理任何限制状态，然后重试 create_card：
   • user_info_required：收集用户的电话号码，并确认用户接受持卡人条款。使用 terms_accepted: true 调用 submit_user_info。
   • kyc_required：执行 start_kyc — 身份验证通过对话流程完成：用户发送政府颁发的身份证件照片（系统会自动读取，用户确认提取的字段），填写任何缺失字段，然后完成简短的浏览器人脸扫描。轮询 get_kyc_status 直至验证通过。
   • wallet_funding_required：钱包余额不足。执行“为钱包充值”工作流，至少补足差额，然后重试。
   • deposit_confirming：资金已在到账途中 — 等待建议的重试间隔，然后再次调用 create_card。不要要求用户再次付款。
4. 如果返回 202（需要审批）：系统会向账户所有者发送电子邮件。告知用户检查电子邮件并批准。批准后，使用审批 ID 调用 approve_request。
5. 成功后：提供卡片摘要（末 4 位、余额、有效期）。

所有卡片均可用于实际交易 — 消费者 MCP 不提供测试或沙盒模式。卡片会使用用户真实的钱包余额，因此创建前请先确认。

卡片类型：一次性与多次使用

• 卡片默认是一次性的：首次扣款获批后会自动关闭。适用于单次购买。
• 对于订阅或任何会重复扣款的商家，请创建多次使用卡片：使用 type: "multi_use" 调用 create_card（可选的 expires_at 会使卡片自动关闭）。多次使用卡片会保持开启状态，直到达到总限额。
• 管理多次使用卡片：pause_card 会阻止新的扣款（可撤销），resume_card 会解除限制，update_card_limit 会调整总限额（提高限额会使用钱包余额）。使用公司余额充值的卡片需由公司在服务端调整限额（POST /api/v1/cards/{id}/topups），而非通过 update_card_limit。

AI Card 和 TOKENBACK

使用 create_card 并设置 scope_preset: "ai_labs" 会创建一张 AI Card：该卡仅限在 AI 实验室商户使用（OpenAI、Anthropic、Gemini；其他任何商户都会在授权时被拒绝），符合条件的消费还可获得 TOKENBACK 奖励。get_rewards 会显示累计余额；使用 redeem_rewards 可兑换奖励。

从钱包提现

1. 先与用户确认金额和收款目的地——提现会转移真实资金。
2. 提现到银行账户：用户需要已保存的收款人——create_withdrawal_recipient 可保存 ACH 或国际电汇目的地。然后使用该收款人调用 withdraw。
3. 以 USDC 提现到 Base：使用用户控制的 0x… 地址调用 withdraw。
4. 提现由 AgentCard 团队处理，通常需要 1-3 个工作日，且每个步骤都会通过电子邮件通知用户。

购买与结账（购物）

buy 工具涵盖所有受支持商户的完整购物流程（DoorDash 已上线；Good Eggs 和 Rappi 视地区而定）。不要查找单独的搜索、购物车或结账工具——buy 会通过对话完成整个流程，并在后台创建一张卡用于付款。

1. 先获取最新指南。 使用 buy 前先调用 get_instructions——它会返回当前的购物/结账使用指南（流程会随时间变化）。
2. 开始订单，使用自然语言请求，例如 buy("order a caesar salad from Zuni on DoorDash")。它会返回一个 conversation_id。
3. 继续同一订单，再次调用 buy 并传入该 conversation_id，以回答相关问题（配送地址、确认购物车和总金额）或下单。持续传入相同的 conversation_id，以保留购物车和上下文。
4. 只有在用户明确确认后才能结账。 这是实际购买——下单前请与用户确认购物车内容和总金额。
5. 使用 buy_list_merchants 查看哪些商户可用，以及用户是否已关联各商户。要断开关联，请使用 buy_unlink_merchant——先与用户确认，因为这会删除已保存的会话，用户必须重新关联该商户才能再次购物。

查询余额

使用 card_id 调用 get_card_balance。将美分格式化为 $XX.XX（除以 100）。要查询钱包余额，请调用 get_balance。

查看卡片详情（PAN/CVV）

只有在用户明确需要完整卡号、CVV 或有效期时（例如填写付款表单），才使用 get_card_details。这可能会触发审批流程。

切勿主动显示 PAN 或 CVV。 常规余额查询请优先使用 get_card_balance。

查看交易

查询单张卡的交易记录时，使用 card_id 调用 list_transactions。还可按 status（PENDING、SETTLED、DECLINED、REVERSED、EXPIRED、REFUNDED）和 limit 筛选。

要一次查看所有卡片的交易活动，请调用 list_all_transactions（不传入 card_id）——它会返回所有交易的平面列表，并为每笔交易标注所属卡片。支持 limit、offset 和 status。

要查询“我花了多少钱，以及用了什么方式付款”，请调用 list_transactions_by_payment_method——它会按付款方式对账户活动进行分组（钱包 USDC 消费、旧版已保存卡消费，以及 Apple Pay / Google Pay 钱包充值），提供各方式的累计总额、每笔记录的商户名称和 MCC，以及通过 buy 完成的购买所对应的订单（商户、订单 ID、总额）。服务器端不会保存商品明细——需要时，请通过 buy 获取商户的订单历史记录。

关闭卡片

调用 close_card 前，务必先与用户确认。明确说明：“此操作将永久关闭该卡。确定吗？”此操作不可撤销。

支付方式设置

已保存的支付方式由 Stripe 管理，并会在 list_transactions_by_payment_method 中显示为独立的支出分组；创建卡片本身使用钱包余额支付。

1. 调用 setup_payment_method 获取 Stripe 结账 URL，并告知用户打开该链接并保存卡片信息。
2. 如需移除：调用 remove_payment_method，并传入 payment_method_id。
3. 如需查看已保存的支付方式及默认方式：调用 list_payment_methods。
4. 如需更改默认方式：调用 set_default_payment_method，并传入 payment_method_id。

套餐、限额与升级

1. 调用 get_plan 查看当前套餐（Free 或 Basic）、每张卡的金额上限、本月已使用／剩余的卡片数量，以及续订或取消状态。
2. 创建大额卡片前，或出现限额错误时，先检查 get_plan。
3. 如需升级：调用 upgrade_plan，将返回的 Stripe Checkout URL 提供给用户，并告知他们在浏览器中完成付款。之后套餐会自动更新——使用 get_plan 确认。
4. 如需取消付费订阅：调用 cancel_plan（将恢复为 Free）。请先与用户确认。

已连接的应用

调用 list_connections，查看用户通过 OAuth 连接到其 AgentCard 账户的第三方应用、各应用的连接时间，以及连接是否仍处于活动状态。此操作仅可读取——如需撤销应用，用户需在 CLI 中运行 agent-cards connections revoke <clientId>。

支持聊天

1. 调用 start_support_chat 并发送初始消息。保存返回的 conversation_id。
2. 使用 send_support_message，并传入 conversation_id 和消息。
3. 使用 read_support_chat 检查是否有回复。

安全规则

• 绝不主动显示 PAN 或 CVV。 仅在用户明确要求时显示。
• 关闭卡片前务必确认。 关闭操作永久且不可撤销。
• 创建卡片前务必确认。 每张卡都已生效，并会使用用户钱包中的真实余额。
• 使用 buy 下单前务必确认。 结账会花费真实资金——请先与用户确认购物车内容和总金额。
• 提现前务必确认。 提现会将真实资金转出钱包——请确认金额和目标地址。
• 准确转发支付链接。 充值结账链接只能使用一次——请原样转发给用户，绝不缩短或改述。
• 解除商家关联前务必确认。 buy_unlink_merchant 会删除已保存的会话，用户之后若要再次在该商家购物，必须重新关联。
• 金额以美元格式显示。 显示 $50.00，而不是 5000 cents。将美分数除以 100。
• 在整个对话中跟踪 ID。 记住卡片 ID、对话 ID 和审批 ID，避免用户重复提供。

错误处理

• phone_verification_required（充值）：需要一次性验证码。add_funds 会自动发送验证码并报告经过掩码处理的目标地址——收集验证码，调用 verify_phone，然后再次调用 add_funds。如果系统报告验证码未发送，请调用 start_phone_verification；如果因账户中没有身份信息而失败，请先完成 submit_user_info / start_kyc。
• user_info_required：首次使用的用户需要先通过 submit_user_info 提交电话号码并接受条款，然后才能创建卡片。
• kyc_required：运行 start_kyc（证件照片 → 字段 → 人脸扫描），轮询 get_kyc_status，然后重试。
• wallet_funding_required：钱包余额不足以支付卡片费用——运行钱包充值工作流，然后重试。
• deposit_confirming：存款正在结算——等待建议的时间间隔后重试。切勿要求用户再次付款。
• amount_out_of_range（充值）：金额超出服务提供方设定的范围——错误信息会列出准确的允许范围；调整金额后重试。
• approval_required (202)：该操作需要人工批准。系统已发送电子邮件。引导用户完成批准，然后调用 approve_request。
• amount_exceeds_limit / card_limit_reached (400)：已达到套餐限额。调用 get_plan 显示当前限额和用量；可提供 upgrade_plan 以提高限额。
• 创建卡片失败：检查 get_plan——用户可能已用完其套餐的月度卡片额度。建议升级套餐或等到下个月。

CLI 参考

如果 MCP 工具尚未加载（例如刚添加服务且会话尚未重启），请使用 agent-cards CLI 作为备用方案。不要使用原始 curl/API 调用——API 路由仅供内部使用。

agent-cards cards list                  # list all cards
agent-cards cards create --amount 5     # create a $5 card (interactive; walks through identity + funding on first run)
agent-cards balance                     # show the cash balance (provisions the account on first run)
agent-cards fund --amount 50            # add cash via Apple/Google Pay (may prompt for a one-time verification code)
agent-cards kyc                         # verify identity (ID photo + face scan) when a flow asks for it
agent-cards balance <card-id>           # check a single card
agent-cards transactions <card-id>      # list one card's transactions
agent-cards transactions                # list transactions across all cards
agent-cards payment-method              # manage payment methods
agent-cards setup-mcp                   # configure MCP server in Claude Code
agent-cards support                     # start support chat

警告：多个 CLI 命令（cards create、wallet fund、signup、support）会使用交互式提示，在非交互式 shell 中会崩溃或退出（账户尚未验证时，wallet fund 会提示输入一次性验证码）。不要从 shell 运行这些命令——请告诉用户在自己的终端中运行。可在任何 shell 中安全运行的命令：whoami、cards list、balance、transactions、payment-method、wallet（仅显示）。有可用的 MCP 工具时，优先使用这些工具。