From zero to a real Visa card in five minutes.

Cards402 ships as a single npm package with an included CLI. One install gets you the TypeScript SDK, the CLI, and the MCP server.

npm install cards402@latest
# or: pnpm add cards402@latest / bun add cards402@latest

The package exports purchaseCardOWS, createOrder, waitForCard, and a Cards402 client class for lower-level usage.

If you're running the CLI through npx (the recommended path for ephemeral agent invocations), always pin @latest:

npx -y cards402@latest --help

Without @latest, npx caches the first version it resolves and serves that indefinitely. SDK fixes affecting on-chain payment paths ship as patch releases — pinning @latest re-resolves against the registry on every invocation so your agent picks them up automatically. The CLI also prints a one-line stderr warning when a newer version is available, cached to one check per 24h.

Sign in to the dashboardwith any email (you'll get a 6-digit login code by return) and open the Agents tab. Click Create Agent, copy the claim code, and give it to the agent to run:

npx -y cards402@latest onboard --claim c402_abc123...

Claim codes are single-use. The agent exchanges one for a real API key on first run and invalidates the claim in the same round trip. Credentials never appear in the LLM transcript.

Your agent pays the receiver contract directly, so it needs a Stellar wallet with at least 2 XLM: 1 XLM minimum account balance (2 × 0.5 XLM base reserve), 0.5 XLM for the USDC trustline subentry, and ~0.5 XLM headroom for fees. The SDK creates the wallet for you, stored encrypted in an OWS vault:

import { createOWSWallet, getOWSBalance } from 'cards402';

// Creates or loads a vault entry for 'my-agent'. Idempotent.
const { walletId, publicKey } = createOWSWallet('my-agent');
console.log('Send at least 2 XLM to', publicKey);

// Check the balance whenever you need to.
const { xlm, usdc } = await getOWSBalance('my-agent');

Open a USDC trustline before the operator sends USDC. USDC on Stellar is an issued asset (issuer: GA5Z…KZVN, Circle's mainnet account), and every holder account must authorise the issuer via a changeTrust operation before it can receive or hold any balance. Without a trustline, a USDC payment to your wallet bounces back to the sender— the operator's funding attempt appears to disappear and everyone wastes a round trip.

Run this once, after XLM has landed:

npx -y cards402@latest wallet trustline

Or from TypeScript:

import { addUsdcTrustlineOWS } from 'cards402';

const txHash = await addUsdcTrustlineOWS({
  walletName: 'my-agent',
});
console.log('trustline opened:', txHash);

The operation costs ~0.00001 XLM in fees and bumps the account's minimum reserve by 0.5 XLM. After it lands, wallet balance reports usdc: 0.0000000 (line open, zero balance) rather than usdc: 0 (no line). XLM-only agents can skip this entirely — XLM is native and needs no trustline.

Cards402 never sees or touches the secret key — it lives in an encrypted OWS vault on the machine running the SDK, protected by an optional passphrase. The same vault is what the MCP server uses, so Claude Desktop and your TypeScript code share one wallet identity.

One SDK call creates the order, signs the Soroban payment, streams the fulfilment phases, and resolves with the card:

import { purchaseCardOWS } from 'cards402';

const card = await purchaseCardOWS({
  apiKey: process.env.CARDS402_API_KEY!,
  walletName: 'my-agent',
  amountUsdc: '25.00',
  paymentAsset: 'xlm',  // or 'usdc' (default)
});

console.log(card);
// {
//   number: '4111 2345 6789 0123',
//   cvv: '847',
//   expiry: '12/27',
//   brand: 'Visa',
//   order_id: 'a3f7c2d1-...'
// }

That's it. A real Visa card, sixty seconds from a stablecoin payment, no hosted checkout, no human in the loop.

Cards402 ships an MCP server so Claude Desktop and any other MCP-aware runtime can call it as a tool. Add it to your MCP config:

{
  "mcpServers": {
    "cards402": {
      "command": "npx",
      "args": ["cards402", "mcp"],
      "env": {
        "CARDS402_API_KEY": "cards402_..."
      }
    }
  }
}

Restart Claude Desktop and the purchase_vcc tool is now available alongside setup_wallet, check_order, and check_budget. The LLM can trigger an order, sign the Stellar payment, and get the card number in a single turn.