![\"Dexter\"](\"https://raw.githubusercontent.com/Dexter-DAO/dexter-x402-sdk/main/assets/dexter-wordmark.svg\")
\n\n \n
\n Issue and manage virtual cards for AI agents.\n
\n\n\n ![\"npm\"](\"https://img.shields.io/npm/v/@dexterai/dextercard.svg\")
\n ![\"Node\"](\"https://img.shields.io/badge/node-%3E=18-brightgreen.svg\"){kind=icon}
\n ![\"Marketplace\"](\"https://img.shields.io/badge/Marketplace-dexter.cash-blueviolet\"){kind=icon}
\n Browse Dexter →\n
\n\n---\n\n## What is Dextercard?\n\nDextercard is the card-issuance layer for the Dexter ecosystem. It turns an authenticated user's stablecoin treasury into a real virtual Mastercard that spends anywhere Mastercard is accepted, with a per-wallet spend cap that you control. The SDK wraps the underlying regulated card carrier with a clean TypeScript surface — auth (OTP + hCaptcha), self-managed sessions with auto-refresh, encrypted credential storage, and typed methods for every step of the card lifecycle (KYC onboarding, issue, reveal, link wallet, freeze, transactions).\n\nThis package is consumed by [`@dexterai/x402-mcp-tools`](https://www.npmjs.com/package/@dexterai/x402-mcp-tools) (which exposes the four `card_*` MCP tools used by the [Dexter MCP server](https://www.npmjs.com/package/@dexterai/opendexter)) and by the Dexter web app's card-issuance pages.\n\n---\n\n## Install\n\n```bash\nnpm install @dexterai/dextercard\n```\n\n## Quickstart\n\n```ts\nimport {\n Dextercard,\n LoginFlow,\n EncryptedFileSessionStore,\n DextercardNoAccountError,\n} from \"@dexterai/dextercard\";\n\nconst store = new EncryptedFileSessionStore(\n `${process.env.HOME}/.config/dexter/dextercard.enc`,\n process.env.DEXTERCARD_KEY!,\n);\n\n// First run: trigger OTP, exchange code, persist session.\nconst flow = new LoginFlow();\nawait flow.requestCode({ email, captchaToken }); // user solved hCaptcha\nconst { session } = await flow.completeWithCode({ email, code, store });\n\n// Every subsequent run: resume.\n// const session = await new LoginFlow().resume(store);\n\nconst card = new Dextercard({ session });\nconst user = await card.userRetrieve(); // { id, email }\n\ntry {\n const status = await card.cardRetrieve();\n} catch (err) {\n if (err instanceof DextercardNoAccountError) {\n // user hasn't completed onboarding yet — kick them through KYC\n } else throw err;\n}\n```\n\n---\n\n## Auth Model\n\n### `LoginFlow`\n\nHigh-level orchestration. Send the OTP, exchange the code for a session, optionally persist into a `SessionStore`, and resume across processes.\n\n### `DextercardSession`\n\nLong-lived session manager. Reads from a `SessionStore`, proactively refreshes JWTs before expiry, persists rotated refresh tokens. Concurrent calls coalesce into a single refresh. The `Dextercard` 401-retry path uses this to recover transparently when a JWT has been rejected mid-flight.\n\n### `EncryptedFileSessionStore`\n\nAES-256-GCM + scrypt encrypted file store. Pass any caller-controlled key material (passphrase, machine-bound random, KMS-fetched secret). Wrong key returns null instead of corrupting state. For environments where you've already protected the storage path with filesystem permissions, the simpler `JsonFileSessionStore` writes a plaintext 0600-mode file.\n\n### hCaptcha\n\nThe carrier protects the OTP-trigger endpoint with hCaptcha (sitekey exported as `DEXTERCARD_HCAPTCHA_SITEKEY`). For browser callers, use `renderDextercardHCaptcha`:\n\n```ts\nimport { renderDextercardHCaptcha, LoginFlow } from \"@dexterai/dextercard\";\n\nconst widget = await renderDextercardHCaptcha({ container: divEl });\nconst captchaToken = await widget.token;\nwidget.destroy();\n\nawait new LoginFlow().requestCode({ email, captchaToken });\n```\n\nServer-side / automation: use a captcha-solving service that returns a real hCaptcha response token, OR open a partnership with the carrier to request a captcha bypass for service-account flows.\n\n---\n\n## Methods\n\nEvery method on `Dextercard` maps 1:1 to a carrier tool (`POST /api/tools/