npm package: @opencardcode/opencard-sdk
Description: Client SDK for OpenCard — create virtual cards with USDC payments via x402
Latest version: 2.0.1

# @opencardcode/opencard-sdk

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

**Solana first.** Also supports Base.

## Install

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

## Quick Start (Solana)

```typescript
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: 'agent@example.com',
});

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

## Quick Start (Base)

```typescript
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: 'agent@example.com',
});
```

## 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.

```typescript
const result = await client.createCard({
  amount: 10,               // 10 | 25 | 50 | 100 | 200 | 500
  nameOnCard: 'AI AGENT',
  email: 'agent@example.com',
});
```

**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

```typescript
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