sh.agentcard/agentcard

Generate a secure checkout link the user opens to add cash to their own balance (the money that funds new cards) via Apple Pay or Google Pay, in USD. Calling this tool moves NO money and initiates NO transfer: it only prepares a single-use hosted payment page — the exact equivalent of the user clicking 'Add funds' in the dashboard. The user personally reviews, authorizes, and completes (or abandons) the payment in their own browser with their own payment method; you never see or handle payment credentials. If a one-time phone verification is needed first, this tool automatically sends the user a code and tells you where it went: ask the user for the code, call verify_phone with it, then call add_funds again.

Resolve a pending approval request (approve or deny) once the USER has decided. Use this after get_card_details or create_card returns a 202 requiring approval, or for a row from list_pending_approvals. For card_details and transaction, approval automatically completes the follow-up action and returns the result. For cross_app actions (asks from another app: close/pause/resume a card, change a limit, view details), approval records the user's consent and the REQUESTING app completes the action from its side when it retries with the approval id.

Attach the user's OWN Visa card to Agentcard so purchases charge that card directly — no identity verification (KYC) and no balance funding needed. Two-phase and conversational: the first call returns a secure link the user opens (about a minute: a one-time code from their bank plus a passkey); call attach_card again to check whether they finished. Once attached, create_card automatically mints against the attached card. If the card is not eligible (for example a Chase-branded, business, or non-US card), fall back to create_card, which issues an Agentcard funded from the user's cash balance.

Shop and check out, in natural language, across the merchants the user has linked (DoorDash, etc.). Pass the whole ask as `request` — e.g. "order a caesar salad from Zuni on DoorDash" — and this tool runs the shopping flow for you. It is CONVERSATIONAL: this tool RETURNS a `conversation_id`; pass that SAME `conversation_id` back on every follow-up (your reply to a question, "add a coke", "yes, check out") so it continues the SAME order. Omit it (or set new_order=true) only to start a fresh order. It will ask for the delivery address and have you confirm the cart and total. CHECKOUT (which charges a one-time card) happens ONLY after the user explicitly confirms in a later message — relay the confirmation through `request` ("yes, place the order") on the SAME conversation_id. If it hands out a merchant login link (hosted connect), just reply on the SAME conversation_id once the user finishes (e.g. "done — I logged in") and it verifies the link itself. Logins started here have no pending_id, so the buy_connect / buy_connect_status pair does not apply to them. Call get_instructions FIRST for the current usage guide before your first buy.

Connect a merchant for shopping. For merchants that need a real login (e.g. DoorDash) this opens a secure hosted browser session and returns a URL the user opens to log in; after they finish, call buy_connect_status with the pending_id to confirm. Merchants that need no login (e.g. Agentcard Flights) come back ready immediately. Use this instead of buy_link_merchant for hosted-login merchants. This tool pairs only with buy_connect_status and only tracks logins it started itself; a login link handed out by the conversational `buy` tool has no pending_id and is verified inside that same buy conversation (the user replies there, e.g. "done — I logged in").

Check the status of a hosted merchant login started with buy_connect. Returns linking (still in progress — call again in a few seconds), linked (success — the merchant is ready to shop), expired, or error. Pass the merchant and the pending_id from buy_connect. ONLY for logins started by the buy_connect tool: a login link handed out by the conversational `buy` tool has no pending_id — for those, reply to the same `buy` conversation ("done — I logged in") instead of calling this.

List merchants available for agent commerce (Rappi, Good Eggs, DoorDash) and whether this user has linked each one. Link a merchant before shopping it.

Disconnect a merchant — drops the saved session + link. The user must re-link (e.g. hosted connect) before shopping it again.

Check the conversational verification state — use after the user uploads their ID via the browser upload link (or any time you need to re-orient). Returns the current step and the fields still missing.

Permanently close a virtual card. This is irreversible — the card cannot be reopened. Safe to call on an already-closed card (idempotent). The user's rewards card (the card their tokenback redeems onto) is close-protected: closing it returns its balance to the wallet but retires the card number the user may have on file at AI labs, so it requires confirm_rewards_card — set it ONLY after the user explicitly confirms they want the rewards card closed.

Create a new virtual debit card. Cards are live and charged for real when used. Money source: by default an active ATTACHED card wins when the user has one (attach_card), otherwise the card is funded from the user's cash balance; pass connected_card_id to mint against a specific attached card, or source "issued" to force the cash balance even when a card is attached. If the balance is short, top up with add_funds. Connections through a company OAuth client have NO card count or amount limits; only first-party personal accounts have per-plan caps. Call get_plan for the limits in effect.

Save a bank account as a withdrawal destination for the user's cash balance. Supports US bank accounts (ACH: routing + account number) and international bank accounts (SWIFT wire: IBAN + BIC). Ask the user for their bank details conversationally, then call this once. After saving, use withdraw to request a payout.

The user's cash balance: the money that funds new cards. Provisions the balance account on first use. Users add cash with Apple Pay or Google Pay in USD; funds are held as USDC. (Their wallet, meaning the cards themselves, is list_cards.)

The live balance of ONE virtual card (the user's overall cash balance is get_balance). Prefer this over get_card_details when you only need to verify available funds: it is faster and does not expose sensitive card credentials.

Get decrypted PAN, CVV, expiry, and current balance for a specific card. Use this only when you need to fill in a payment form — prefer get_card_balance if you only need the balance. May require human approval before returning credentials. If approval is required, prompt the user and then call approve_request. Card details are encrypted at rest with AES-256-GCM.

Call this BEFORE using `buy`; returns the latest usage guide for shopping and checking out with AgentCard.

Check the user's identity verification (KYC) status. Returns whether they are verified and, if not, the current state plus the conversational next step. Use this to poll after the user does the face scan, or any time create_card reports kyc_required.

Show the user's current subscription plan, card limits, and this month's usage. Call this before create_card when you need the per-card amount cap or remaining monthly quota, or whenever the user asks about their plan, limits, billing, or upgrading. To cancel a paid plan, the gated tool cancel_plan also exists; call it by name even though it isn't in the tools list.

Show the user's tokenback: balance, lifetime earned, and recent activity. Tokenback pays tokens (1 token = 1¢ of credit value) on settled card spend. AI cards (create_card scope_preset: 'ai_labs') earn a boosted rate on AI-lab purchases, and companies can route a share of their earnings to their users as tokenback. Redeem with redeem_rewards.

View the user's notification preferences (which email alerts they receive) and authorization settings (whether viewing card details or making transactions requires explicit approval). Authorization settings are read-only here; change notification preferences with the gated tool update_settings, calling it by name even though it isn't in the tools list.

Link or merge another Agentcard account that belongs to the same person. Use when the user says they already have an account under a DIFFERENT email or phone number — most often after identity verification (KYC) is rejected as a duplicate, which means that person already verified on another account. Two steps: (1) call with { type, identifier } to send a one-time code to that email/phone; (2) call again with the { ticket, code } to verify. If the identifier belongs to a different account, the two accounts are MERGED (the identity-verified account survives and gains the other's email/phone, so both sign in to one account); if no account has it, it is simply added to the current account.

List the user's ATTACHED cards (their own Visa cards enrolled via attach_card — the BYOC funding source), with ids, brand, last4, expiry, and status. The newest active one is the default mint target; create_card can pick a specific one via connected_card_id. Not the same as list_cards (the virtual cards Agentcard issues).

The user's wallet: every live card they hold, with IDs, last four digits, expiry, balance, and status. Start here to find available cards; if none are returned, call create_card to issue one. When the shared wallet is enabled, `wallet` lists every card across all connected apps and companies, each tagged with its source (kind personal/company, the minting app, and the company where applicable) — cards minted by another app or company are read-only from this session: get_card_details and close_card will not work on them.

List the third-party apps the user has connected to their Agentcard account via OAuth (e.g. Kilo), including when each was connected and whether it is still active. Read-only. To revoke an app, call revoke_connection with its clientId.

List the saved payment methods (used only to pay for flight bookings, not for cards or adding funds). Returns each method with its id, brand, last 4 digits, and expiry, and marks the default one. Use setup_payment_method to add a new one. The gated tools set_default_payment_method and remove_payment_method also exist; call them by name even though they aren't in the tools list.

List the user's PENDING approval requests: asks from connected apps (create a card, view full card details, close/pause/resume a card, change a limit) waiting on the user's decision. Surface each one to the user and let THEM decide; after the user answers, resolve with approve_request. NEVER approve or deny on your own — an approval is the user's consent, not yours. Personal sessions only; company-connected sessions have no personal inbox.

Transactions with amount, merchant, status, and timestamps. Pass card_id for one card's transactions; OMIT it for every card in the account (newest first, each row tagged with its card). Use limit and status to filter. The gated views list_all_transactions and list_transactions_by_payment_method also exist; call them by name even though they aren't in the tools list.

List the user's saved bank accounts for withdrawals, masked (bank name and last four only). Use a recipient's id as recipient_id with withdraw. If the list is empty, collect the user's bank details and call create_withdrawal_recipient first.

Manage a recurring meal/grocery SUBSCRIPTION (e.g. Locale) — NOT a one-time purchase, and no payment is taken (the subscription auto-bills the card on file at the merchant). action: 'menu_search' (browse the recurring menu; items flagged inPlan are covered by the plan), 'get_skip_dates' (list skipped/paused deliveries), 'skip'/'unskip' (one upcoming delivery date), 'set_skip_dates' (replace the full skip set; [] resumes all), 'update_setting' (change a setting). Locale settings: subscription_size (meals, e.g. 8), calorie_preference (low_calorie|both|moderate), diets (array), longevity_allergens (array), ingredient_allergies (array), default_window ('9am - 6pm'|'3pm - 7pm'|'9am - 12pm'), delivery_instructions (text). Link the merchant first.

Pause a multi-use card: temporarily blocks ALL new charges (reversible — use resume_card to unblock). Right for "stop this subscription for now" or a card the user suspects is compromised but is not sure. Only multi-use cards can be paused; single-use cards close after one charge and cannot be paused.

Read the message history of a support conversation

Redeem a promo code that adds money to the user's cash balance. Each code works once per user; the credit lands in the balance and becomes spendable within a minute or two. The gated tool list_codes shows the user's code history; call it by name even though it isn't in the tools list.

Redeem tokenback: the tokens' cash value (1 token = 1¢) lands on the user's rewards card as spending power. The rewards card is permanent and locked to AI-lab merchants (OpenAI, Anthropic, Gemini) — minted on first redemption, topped up after. Check get_rewards first for the balance and the minimum. Ask the user before redeeming.

Remove (unenroll) one of the user's attached cards. Irreversible for that enrollment: any virtual cards minted against it are closed first, then the card is unenrolled at the network. ALWAYS confirm with the user before calling. Get ids from list_attached_cards. The user can re-attach the same card later with attach_card.

Resume a paused multi-use card so it accepts charges again. The inverse of pause_card.

Revoke a third-party app's access to the user's Agentcard account. Disconnects the app and invalidates its OAuth tokens; it must reconnect via OAuth to regain access. Pass the clientId shown by list_connections.

Send a message in an existing support conversation

Save a payment method used ONLY to pay for flight bookings (the fare is charged to it via a hold at booking; no virtual card is minted for flights). It does NOT fund cards or the cash balance — cards are funded from the balance (see add_funds). Returns a secure checkout URL the user must open to save their card details.

Begin (or resume) identity verification. Verification is CONVERSATIONAL: it starts with a photo of the user's government ID — the backend reads the printed details automatically and the user confirms every value. Only fields the ID does not carry are asked (like the SSN for US documents, or the national ID number for non-US ones); occupation/income questions are never asked. The only browser step is a short face scan at the end. Relay each step to the user as ONE SHORT message (one or two sentences — the current ask only, never the whole flow, never an unrequested link). Returns the next step, ID-photo upload options, and (for legacy hosted-flow accounts) a hosted verification URL instead.

Send (or re-send) the user's one-time funding verification code (the provider verifies the phone on the user's Agentcard identity, valid 60 days). add_funds already sends this code automatically when verification is needed — call this tool only to RE-send when the code never arrived (any unexpired code still works; sends are rate-limited). Returns the masked destination (text or email) and whether a code was sent; if the phone is already verified it says so and you go straight to add_funds. After the user reads back the code, call verify_phone.

Start a new support conversation and send the first message

Submit the user's ID photo for identity verification. Ways in: (a) image data you hold programmatically (e.g. the user sent the photo in this chat and your platform exposes its bytes) — pass front_base64 (and back_base64 for a license back; its barcode reads most accurately); (b) local (stdio) mode — pass file_path/back_file_path and the file is read from disk; (c) neither — you get a secure upload link to hand the user. Do NOT ask the user what kind of document it is or where it was issued — the type and country are detected automatically from the photo; only relay a question if the result says the type could not be determined. Returns the fields read off the document — SHOW THEM TO THE USER for confirmation before continuing — plus whatever is still missing. If the result says NO identity details could be read, the image did not read as an ID at all: never insist to the user that it was their ID. Supported: JPEG/PNG/WebP up to 12MB (convert iPhone HEIC first).

Submit identity fields for verification: the ones the ID photo didn't carry (listed by missingFields — the tax/ID number always has to be asked since IDs don't print it; call it "SSN" only for US documents and "national ID number" otherwise), corrections to extracted values the user flagged, and the User Agreements acceptance (agreements_accepted, after presenting each agreement verbatim). That number is forwarded directly to the verification provider and never stored by Agentcard. NEVER ask about occupation, income, spending volume, or account purpose — those are filled automatically and must not be asked.

Submit the user's phone number and terms acceptance for a virtual card. Call this after create_card returns user_info_required. Do NOT ask the user for occupation, income, or account purpose — those are never asked. Identity fields (name, date of birth, SSN / national ID, address) belong to the KYC flow: create_card tells you whether it runs conversationally (start_kyc → ID photo → face scan) or via a hosted verification_url. After phone + terms are saved, retry create_card.

Buy the user something totally unexpected and very silly/stupid-fun under a small dollar cap (default $10, hard max $25). Great when the user cannot decide what to order (from DoorDash etc.) or just wants a fun surprise. It kicks off a shopping conversation that FIRST brainstorms deliberately stupid ideas, picks ONE genuinely unexpected item, builds the cart, and shows the item + exact total. It NEVER checks out by itself: the reply includes a conversation_id — relay the user's explicit confirmation ("yes, place it") through the `buy` tool on that SAME conversation_id, exactly like a normal order. Each surprise_me call starts a fresh surprise; use `buy` for all follow-ups (answers, tweaks, the confirmation).

Change a multi-use card's total spending limit. Raising it reserves the extra amount from the user's cash balance (top up with add_funds if short); lowering it frees the difference, but the new limit can never go below what the card has already spent. Single-use cards cannot be resized.

Start a paid-plan upgrade. Choose the target plan: 'basic' ($15/mo — 15 cards/month, up to $500 per card) or 'pro' ($100/mo — 50 cards/month, up to $1,000 per card). Defaults to 'basic' if omitted. Returns a Stripe Checkout URL the user must open in their browser to complete payment. After they finish checkout, the plan updates automatically; verify with get_plan. Use only when the user explicitly wants to upgrade. To cancel a paid plan instead, the gated tool cancel_plan also exists; call it by name even though it isn't in the tools list.

Check the one-time code the user received from start_phone_verification. On success the balance is unlocked for funding (the verification stays fresh for 60 days) — call add_funds next. A wrong or expired code returns a recoverable status so you can ask the user to re-check it, or call start_phone_verification to resend.