sh.agentcard/agentcard

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 HEIC or HEIF photos 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.

Show who you are operating as: the authenticated AgentCard account's email, user id, name, plan, KYC + account status, member-since date, and how this session is connected (personal login vs a third-party OAuth app connection, with the app name). Call this when the user asks "who am I" / "which account is this", or before money-moving actions when you need to confirm the account. Read-only. KYC shown here is the stored snapshot — use get_kyc_status when you need the live, provider-checked state.

Withdraw cash from the user's balance, either to their saved bank account or to a crypto address on Base (USDC). Transfers are processed manually by the Agentcard team, usually within 1-3 business days; the user is emailed when it's sent. For a bank withdrawal, if the user has no saved bank account yet, call create_withdrawal_recipient first. For a crypto withdrawal, pass destination_address (a 0x Base address). ALWAYS confirm the amount and destination with the user before calling this.