> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt > Use this file to discover all available pages before exploring further. # create_card > The one card tool: get the user a virtual debit card for a purchase. Connect to `https://mcp.agentcard.sh/mcp` with the **user's connection token** (or a `buy_token` for org-owned accounts). ## What it does The one card tool: get the user a virtual debit card for a purchase. Cards are live and charged for real when used. For a FIRST-TIME user it starts by putting the user's OWN card in their Agentcard vault (any Visa, Mastercard, Amex, or Discover from any country, no identity verification (KYC), no balance funding): the call returns a secure link (vault\_started); send it to the user (they type the card once and lock it with Face ID; Agentcard never sees the number). A vaulted card pays through the buy tool, where the user approves each purchase with Face ID on their device; it never becomes a card number you type, so after vault\_started (or vault\_ready, when a card is already in the vault) use buy for purchases instead of calling create\_card again. If the user specifically needs a card NUMBER, that is an Agentcard funded from their cash balance, which requires KYC the first time: only after the user agrees, call create\_card with source "issued". Established users: the saved default decides (get\_settings default\_payment: their chosen added card, or the wallet balance); with no saved default, an active ADDED card wins, otherwise the cash balance. Per-call overrides: connected\_card\_id issues against a specific added card, source "issued" forces the cash balance, restart\_setup mints a fresh vault link. If the balance is short on the issued path, 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. ## Inputs | Field | Type | Description | | --------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `amount_cents` *(required)* | number | Card funding amount in CENTS, not dollars (minimum 100). 100 = \$1.00 and 2500 = \$25.00; a value like 25 would be \$0.25. Company-governed connections have no maximum; personal accounts are capped by their plan — call get\_plan for the limits in effect. | | `connected_card_id` | string | Multi-card: issue against a SPECIFIC added card (an id from the user's added cards, see list\_added\_cards) instead of the newest active one. Omit for the default. | | `source` | string: `issued` | Force the card to be funded from the user's cash balance (the issued path: KYC + wallet funding) even when they have an added or vaulted card or would otherwise be offered the vault. Use it only after the user explicitly picks the balance option. Omit for the default (an active added card wins; first-time users get the vault link). | | `restart_setup` | boolean | Set true ONLY when the user lost or never received a vault link, it expired (about 15 minutes), or they want to add ANOTHER card. Never needed on the first call or for normal retries. | | `funds_source` | string: `onramp_flow` · `company_flow` | Where the card funds come from. OMIT unless instructed: the server applies the right default (company-connected accounts use the company wallet automatically when the company enables it). company\_flow = the company's wallet funds the card; onramp\_flow = the user's own wallet. | | `type` | string: `single_use` · `multi_use` | Card behavior. 'single\_use' (default) closes after its first approved charge — right for one-off purchases. 'multi\_use' stays open across charges until its total limit is spent — right for subscriptions and recurring merchants. Multi-use cards can be paused (pause\_card), resumed (resume\_card), and resized (update\_card\_limit). | | `expires_at` | string | Optional hard expiry for a multi-use card (ISO-8601 with timezone, e.g. "2027-01-01T00:00:00Z"). Must be in the future, at most 365 days out. The card closes automatically when it passes. | | `preset` | string · object | Rules for this card: a built-in name (ai\_labs, weekday\_meals, cli\_only, daily), a comma-separated list of built-ins, a saved name or id from list\_presets, inline JSON privileges, or `{ name?, privileges }`. Rules only tighten. Inline, a currency rule is `{ "kind": "currency", "currencies": ["USD"] }`, with `"enforcement": "watch"` for `Watch`. Omit it and the card inherits the app default, then the account default, else it is unrestricted. See [Set rules on a card](/issuing/set-rules-on-a-card). | | `scope_preset` | string: `ai_labs` | Older spelling of `preset: "ai_labs"`: a multi-use card for AI vendors (OpenAI, Anthropic, Gemini). The card network declines charges anywhere else. Charges at software and AI vendors on this card earn the boosted tokenback rate; other charges on it earn the normal rate. Requires type 'multi\_use'; with single\_use the call is refused with `scope_preset_requires_multi_use`. Prefer `preset`. | ## Returns | Field | Type | Description | | ---------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `message` *(required)* | string | Human-readable result or guidance for the next step. | | `status` | string | Outcome discriminator: "created" (card issued), "vault\_started" (first-time setup: send vaultUrl to the user; once their card is in the vault, purchases go through buy, not create\_card), "vault\_ready" (the user's own card is already in their vault: use buy; only source "issued" produces a card number), "attach\_started" / "attach\_pending" (an older add-card enrollment still in flight: send attachUrl or wait, then call again with the same arguments), "issuing\_suggested" (legacy servers only: offer the balance-funded fallback, noting it requires KYC, and only then call again with source "issued"), "approval\_required" (human approval needed), "approval\_pending" (added-card passkey approval: send approvalUrl to the user, then retry with the same arguments in \~10s), "kyc\_required" (issued path only), "user\_info\_required" (check missingFields: phone/terms go through submit\_user\_info; consent must be recorded by the connecting platform), "beta\_capacity\_reached", "issuing\_balance\_insufficient" (issued path only), "payment\_method\_declined", "limit\_reached", "funding\_in\_progress" (company wallet funding underway: retry with the same arguments in \~10s), "funding\_not\_approved", "org\_wallet\_funding\_required", "org\_wallet\_unavailable" (the company wallet backing this account is not active: the company must finish setup; do not retry immediately), or "rate\_limited" (wait \~1 minute, then retry). | | `cardId` | string | The new card ID. Present only when status is "created". | | `last4` | string | Last four digits of the new card. Present only when status is "created". | | `expiry` | string | Card expiry (MM/YY). Present only when status is "created". | | `balanceCents` | number | Card balance in cents. Present only when status is "created". | | `balanceDollars` | string | Card balance formatted as USD dollars, e.g. "12.50". Present only when status is "created". | | `cardStatus` | string | Card status, e.g. "active". Present only when status is "created". | | `preset` | object | The rules on the new card: `id`, `name`, `version`, `summary`. Null when the card is unrestricted. Present only when status is "created". | | `approvalId` | string | The approval request ID to pass to approve\_request. Present only when status is "approval\_required". | | `approvalUrl` | string | The passkey approval link to send to the user. Present only when status is "approval\_pending". | | `vaultUrl` | string | The secure link the user opens to put their card in their vault. Present only when status is "vault\_started". | | `vaultCards` | number | How many cards the user already holds in their vault. Present only when status is "vault\_ready". | | `attachUrl` | string | The secure link the user opens to finish an older add-card enrollment. Present only when status is "attach\_started". | | `expiresAt` | string | When the link expires (ISO 8601). Present when status is "vault\_started" or "attach\_started". | | `source` | string | "connected" when the card was created against the user's added card. Absent for wallet-funded cards. | | `reason` | string | On "issuing\_suggested" (legacy servers only; current servers route every first-time user to the vault instead): why the card could not be added. On "kyc\_required": why the previous identity-verification attempt failed (e.g. "document\_unverified\_other"), present only when a prior attempt was rejected. | | `missingFields` | array | What is missing when status is "user\_info\_required" (e.g. "termsAccepted", "consent"). | ## Example call ```json theme={null} { "tool": "create_card", "arguments": { "amount_cents": "\u2026" } } ``` A card with a currency rule says who enforces it. `create_card` with `"preset": { "privileges": [{ "kind": "currency", "currencies": ["USD", "EUR"] }] }` on a sandbox connection, captured from a local run; `structuredContent.preset.agentcardOnly` lists `currency`: ```text theme={null} TEST card created (sandbox connection). Card ID: cmttouxtv000hjpk0bp7mbvzs Last 4: 8549 Expiry: 09/28 Balance: $20.00 Status: OPEN Preset: Currency: USD, EUR. (Agentcard enforces the currency rule at checkout and settlement; the card network does not) This is a TEST card: no real charge, not usable at real merchants. Tell the user it is a test card before they try to spend it. ``` ## Example error `scope_preset: "ai_labs"` with `type: "single_use"`, captured from a local sandbox. `isError` is set and `structuredContent.status` carries the code: ```json theme={null} { "content": [ { "type": "text", "text": "Scoped (AI) cards are always multi-use — omit type or pass multi_use." } ], "structuredContent": { "message": "Scoped (AI) cards are always multi-use — omit type or pass multi_use.", "status": "scope_preset_requires_multi_use" }, "isError": true } ``` A `preset` with a currency Agentcard cannot read answers the same way, with `policy_invalid`. `create_card` with `"preset": { "privileges": [{ "kind": "currency", "currencies": ["ZZZ"] }] }`, captured from a local run: ```json theme={null} { "content": [ { "type": "text", "text": "ZZZ is not a currency code. Use an ISO 4217 code (USD, EUR, GBP, JPY) or a common name (dollars, euros, pounds, yen)." } ], "structuredContent": { "message": "ZZZ is not a currency code. Use an ISO 4217 code (USD, EUR, GBP, JPY) or a common name (dollars, euros, pounds, yen).", "status": "policy_invalid" }, "isError": true } ```