@opencardcode/opencard-sdk

Client SDK for OpenCard — create virtual prepaid cards with USDC payments via the x402 protocol.

Solana first. Also supports Base.

Install

npm install @opencardcode/opencard-sdk @solana/web3.js

Quick Start (Solana)

import { OpenCardClient } from '@opencardcode/opencard-sdk';

const client = new OpenCardClient({
  solanaPrivateKey: 'your-base58-private-key',  // or solanaKeypair
  network: 'solana',  // default
});

// One line — SDK handles payment automatically
const result = await client.createCard({
  amount: 10,               // $10 card
  nameOnCard: 'AI AGENT',
  email: '[email protected]',
});

console.log(result.order);  // { cardId, status: 'processing', ... }
// Card details delivered via webhook (5-15 min)

Quick Start (Base)

import { OpenCardClient } from '@opencardcode/opencard-sdk';

const client = new OpenCardClient({
  privateKey: '0x...',  // Base wallet with USDC
  network: 'base',
});

const result = await client.createCard({
  amount: 50,
  nameOnCard: 'AI AGENT',
  email: '[email protected]',
});

Configuration

| Option | Type | Required | Description | |--------|------|----------|-------------| | network | "solana" \| "base" | No | Payment network (default: "solana") | | solanaPrivateKey | string | One of | Base58 Solana private key | | solanaKeypair | Keypair | One of | @solana/web3.js Keypair instance | | solanaRpcUrl | string | No | Solana RPC URL (default: mainnet-beta) | | privateKey | 0x${string} | One of | EVM hex private key (for Base) | | walletClient | WalletClient | One of | viem WalletClient (for Base) | | rpcUrl | string | No | Base RPC URL | | baseUrl | string | No | API URL (default: https://opencard.declawds.fun) | | timeout | number | No | Request timeout in ms (default: 60000) |

API

client.createCard(params): Promise<CardResult>

Create a virtual card. SDK handles x402 payment automatically.

const result = await client.createCard({
  amount: 10,               // 10 | 25 | 50 | 100 | 200 | 500
  nameOnCard: 'AI AGENT',
  email: '[email protected]',
});

Note: Card delivery is asynchronous (5-15 minutes). Include a webhookUrl in your request to receive card details when ready.

client.getTiers(): Promise<TiersResponse>

Get pricing tiers and fee breakdown (no payment required).

client.health(): Promise<{ status: string }>

Check if the OpenCard API is reachable.

client.address: string

The wallet address being used for payments.

client.paymentNetwork: "solana" | "base"

The configured payment network.

Error Handling

import {
  OpenCardClient,
  InsufficientBalanceError,
  PaymentError,
  ApiError,
  TimeoutError,
  ConfigError,
} from '@opencardcode/opencard-sdk';

try {
  const result = await client.createCard({ ... });
} catch (error) {
  if (error instanceof InsufficientBalanceError) {
    console.log(`Need ${error.required}, have ${error.available}`);
  } else if (error instanceof PaymentError) {
    console.log(`Payment failed: ${error.message}`);
  } else if (error instanceof ConfigError) {
    console.log(`Configuration error: ${error.message}`);
  } else if (error instanceof ApiError) {
    console.log(`Server error ${error.status}:`, error.body);
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  }
}

How It Works

Your Code          SDK                    OpenCard API          Chain (Solana/Base)
   |                |                         |                    |
   |-- createCard ->|                         |                    |
   |                |--- POST /create/tier -->|                    |
   |                |<-- 402 + challenge -----|                    |
   |                |                         |                    |
   |                |--- USDC.transfer() -----|-------- tx ------->|
   |                |<-- txHash --------------|-------- receipt ---|
   |                |                         |                    |
   |                |--- POST + X-Payment --->|                    |
   |                |<-- 202 + order status --|                    |
   |<- CardResult --|                         |                    |

Card details are delivered asynchronously via webhook (5-15 minutes).

Pricing

| Card | Cost (USDC) | |------|-------------| | $10 | ~$11.80 | | $25 | ~$28.00 | | $50 | ~$55.00 | | $100 | ~$109.00 | | $200 | ~$217.00 | | $500 | ~$541.00 |

Prices are estimates. Actual cost from Trocador may vary slightly.

License

MIT