kya_getCard
Generate a single-use virtual Visa card for secure online purchases without exposing real payment details. The card is locked to a specific merchant and amount, then automatically deactivates after use.
Instructions
Get a single-use virtual Visa to make a purchase on behalf of the user. You MUST call kya_getAgentIdentity first — you cannot pay without being identified.
Declare the merchant, amount, and what you're buying. The user approves via MFA. kyaLabs issues a card locked to this purchase. The card self-destructs after use. Your user's real card never enters the chat.
Call kya_reportPurchase after the transaction.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| merchant | Yes | The merchant or store where the purchase will be made | |
| estimated_amount | Yes | Estimated purchase amount in USD (max $500) | |
| description | Yes | Brief description of what is being purchased |
Implementation Reference
- src/tools/getCard.ts:212-240 (handler)The main handler function for kya_getCard, responsible for checking authentication, routing to API or mock implementation, and returning the result.
export async function getCard(input: GetCardInput): Promise<CardResult> { process.stderr.write(`[kyaLabs:info] getCard called: merchant=${input.merchant} amount=$${input.estimated_amount}\n`); if (!getStoredConsentKey()) { process.stderr.write(`[kyaLabs:error] getCard: no consent key found\n`); return { product_name: "kyaLabs", status: "error", message: "Not authenticated. Run kya_getAgentIdentity first to activate your agent, or set KYA_API_KEY in your MCP config.", }; } if (api.isApiMode()) { try { const result = await getCardViaApi(input); process.stderr.write(`[kyaLabs:info] getCard result: status=${result.status}\n`); return result; } catch (err) { process.stderr.write(`[kyaLabs:error] getCard API error: ${err instanceof Error ? err.message : String(err)}\n`); return { product_name: "kyaLabs", status: "error", message: err instanceof Error ? err.message : String(err), }; } } return getCardViaMock(input); } - src/tools/getCard.ts:5-34 (schema)Type definitions for the input and output of the kya_getCard tool.
export interface GetCardInput { merchant: string; estimated_amount: number; description: string; } export interface CardResult { product_name: string; status: string; intent_id?: string; card?: { number: string; exp_month: string | number; exp_year: string | number; cvv: string; billing_name?: string; last_four?: string; }; merchant?: string; amount?: number; identity?: unknown; badge_warning?: string; remaining_balance?: number; instructions?: string; message?: string; reason?: string; merchant_url?: string; estimated_amount?: number; approve_endpoint?: string; } - src/index.ts:167-189 (registration)The tool registration for kya_getCard in the MCP server.
server.tool( "kya_getCard", `Get a single-use virtual Visa to make a purchase on behalf of the user. You MUST call kya_getAgentIdentity first — you cannot pay without being identified. Declare the merchant, amount, and what you're buying. The user approves via MFA. kyaLabs issues a card locked to this purchase. The card self-destructs after use. Your user's real card never enters the chat. Call kya_reportPurchase after the transaction.`, { merchant: z.string().max(500).describe("The merchant or store where the purchase will be made"), estimated_amount: z.number().positive().max(500).describe("Estimated purchase amount in USD (max $500)"), description: z.string().max(1000).describe("Brief description of what is being purchased"), }, async ({ merchant, estimated_amount, description }) => { const result = await getCard({ merchant, estimated_amount, description }); const formatted = formatCardResponse(result, merchant, estimated_amount); return { content: [ { type: "text", text: formatted }, { type: "text", text: `\n---\n${JSON.stringify(result, null, 2)}` }, ], }; } );