{"uid":"cap__l1STrFeUtX-mFtR45ZBV","slug":"x402card-virtual-card-top-up-7edee178","name":"x402card Virtual Card Top-Up","description":"Issue and top up wallet-native virtual cards, or buy prepaid Freeland travel eSIMs with native USDC on Base through x402.","url":"https://api.x402card.org/api/card/topup","method":"POST","headers":{},"bodySchema":{"type":"object","properties":{"amountUsdCents":{"type":"integer","maximum":25000,"minimum":2500,"description":"Gross USDC payment in integer USD cents. Omit to use the current configured default."},"idempotencyKey":{"type":"string","maxLength":200,"minLength":1,"description":"Stable caller-generated key. Reuse it after an ambiguous response; never generate a replacement to retry payment."}}},"responseSchema":{"type":"json","example":{"ok":true,"owner":"<x402-payer-address>","status":"queued","product":"card_funding","economics":{"loadFeeBps":200,"loadFeeUsdCents":50,"walletPaymentUsdCents":2500,"expectedCardCreditUsdCents":2450},"fundingJob":{"id":"<job-id>","status":"queued"}}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"25","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$25/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"25","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"25","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_VQZvWpjb7DrijrtLXLPJK","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"25","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Top up a wallet-native virtual card with USDC on Base via the x402 payment protocol, crediting funds to the card after a load fee.","exampleAgentPrompt":"Top up my x402card virtual card with $25 USDC — use idempotency key 'topup-20240601-001' so it's safe to retry if something goes wrong.","exampleUseCases":[{"title":"Fund virtual card for online shopping","prompt":"Add $25 to my x402card virtual card using USDC so I can use it for online purchases — use idempotency key 'shop-fund-june-01'."},{"title":"Reload card before travel","prompt":"I'm about to travel — please top up my x402card with the maximum $250 USDC load so I have spending money. Use idempotency key 'travel-topup-2024'."},{"title":"Automate recurring card funding","prompt":"Every week, load $50 USDC onto my x402card virtual card. Start now with idempotency key 'weekly-topup-wk1'."}],"resultDescription":"Returns a JSON object confirming the funding job was queued, including the job ID, job status ('queued'), the owner wallet address, the gross payment in USD cents, the load fee in basis points and dollars, and the expected net card credit after fees.","failureModes":["Amount below minimum (2500 cents / $25) returns a validation error","Amount above maximum (25000 cents / $250) returns a validation error","Duplicate idempotency key with different amount may return conflict or replay the original result","Insufficient USDC balance in payer wallet causes payment failure","x402 payment protocol rejection if wallet or network conditions fail","Job may remain in 'queued' state if downstream card processor is delayed"],"whenToPreferThis":"Use this endpoint when an agent needs to programmatically fund a wallet-native virtual card with USDC on Base via the x402 payment protocol. Prefer this over traditional card top-up APIs when the user operates in a crypto-native environment and wants stablecoin-denominated card funding without fiat on-ramps. The idempotency key support makes it safe for automated or retry-prone workflows.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T06:33:16.808Z","isFirstParty":false}