OpenCard API Documentation

npm install @opencardsdk/sdk viem

import { OpenCardClient } from '@opencardsdk/sdk';

const client = new OpenCardClient({
  privateKey: '0x...',       // or pass a viem WalletClient
  baseUrl: 'https://api.opencard.dev',
});

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

console.log(card.cardDetails); // { cardNumber, cvv, expiry, ... }

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

const result = await client.fundCard({
  amount: 25,
  cardId: 'card-uuid',
});

import {
  OpenCardClient,
  InsufficientBalanceError,
  PaymentError,
  ApiError,
  TimeoutError,
} from '@opencardsdk/sdk';

try {
  const card = 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}, tx: ${error.txHash}`);
  } else if (error instanceof ApiError) {
    console.log(`Server error ${error.status}:`, error.body);
  } else if (error instanceof TimeoutError) {
    console.log('Request timed out');
  }
}

import {
  parseChallenge,
  checkBalance,
  executePayment,
  buildPaymentProof,
  handleX402Payment,
} from '@opencardsdk/sdk';

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

curl -X POST https://api.opencard.dev/cards/create/tier/10 \
  -H "Content-Type: application/json" \
  -d '{"nameOnCard": "AGENT ALPHA", "email": "[email protected]"}'

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxAmountRequired": "17200000",
      "payTo": "0x3Be892b244B7CE6731A297A7eBca16F16f27c288",
      "maxTimeoutSeconds": 300,
      "resource": "/cards/create/tier/10",
      "description": "Create card with $10 load"
    }
  ]
}

{
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "authorization": {
      "from": "0xYourAgentWallet",
      "to": "0xTreasuryAddress",
      "value": "17200000"
    },
    "txHash": "0xYourTransactionHash..."
  }
}

// Domain
{ "name": "OpenCard", "version": "1", "chainId": 8453 }

// Types
{ "Auth": [
    { "name": "action", "type": "string" },
    { "name": "timestamp", "type": "uint256" }
] }

// Message
{ "action": "opencard-auth", "timestamp": 1707600000 }

import { createWalletClient, http } from 'viem';
import { base } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY');
const timestamp = Math.floor(Date.now() / 1000);

const signature = await account.signTypedData({
  domain: { name: 'OpenCard', version: '1', chainId: 8453 },
  types: {
    Auth: [
      { name: 'action', type: 'string' },
      { name: 'timestamp', type: 'uint256' },
    ],
  },
  primaryType: 'Auth',
  message: { action: 'opencard-auth', timestamp: BigInt(timestamp) },
});

const response = await fetch('https://api.opencard.dev/cards', {
  headers: {
    'X-WALLET-ADDRESS': account.address,
    'X-WALLET-SIGNATURE': signature,
    'X-WALLET-TIMESTAMP': String(timestamp),
  },
});

{
  "status": "ok",
  "timestamp": "2026-02-11T14:00:00.000Z",
  "version": "1.0.0"
}

{
  "creation": {
    "tiers": [{
      "loadAmount": 10,
      "totalCost": 17.2,
      "issuanceFee": 3.0,
      "topUpFee": 2.2,
      "ourFee": 2.0,
      "endpoint": "/cards/create/tier/10"
    }]
  },
  "funding": {
    "tiers": [{
      "fundAmount": 10,
      "totalCost": 14.2,
      "topUpFee": 2.2,
      "ourFee": 2.0,
      "endpoint": "/cards/fund/tier/10"
    }]
  }
}

{
  "creation": [{
    "loadAmount": 10,
    "totalCost": 17.2,
    "endpoint": "/cards/create/tier/10",
    "breakdown": {
      "cardLoad": 10, "issuanceFee": 3, "topUpFee": 2.2, "ourFee": 2, "buffer": 0
    }
  }],
  "funding": [{
    "fundAmount": 10,
    "totalCost": 14.2,
    "endpoint": "/cards/fund/tier/10",
    "breakdown": { "fundAmount": 10, "topUpFee": 2.2, "ourFee": 2 }
  }]
}

// Response 201 Created (after successful payment)
{
  "success": true,
  "card": {
    "cardId": "550e8400-e29b-41d4-a716-446655440000",
    "nameOnCard": "AGENT ALPHA",
    "balance": 10,
    "status": "active",
    "createdAt": "2026-02-11T14:00:00.000Z"
  },
  "payment": {
    "amountCharged": 17.2,
    "txHash": "0x...",
    "network": "base"
  },
  "details": {
    "cardNumber": "4111111111111111",
    "expiryMonth": 12,
    "expiryYear": 2028,
    "cvv": "123",
    "billingAddress": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    }
  }
}

// Response 200 OK
{
  "success": true,
  "cardId": "550e8400-e29b-41d4-a716-446655440000",
  "fundedAmount": 25,
  "newBalance": 35.0,
  "payment": {
    "amountCharged": 29.4,
    "txHash": "0x...",
    "network": "base"
  }
}

{
  "cards": [{
    "cardId": "550e8400-e29b-41d4-a716-446655440000",
    "nameOnCard": "AGENT ALPHA",
    "lastFour": "1111",
    "balance": 10.0,
    "status": "active",
    "createdAt": "2026-02-11T14:00:00.000Z"
  }]
}

{
  "card": {
    "cardId": "550e8400-e29b-41d4-a716-446655440000",
    "nameOnCard": "AGENT ALPHA",
    "email": "[email protected]",
    "balance": 8.5,
    "initialAmountUsd": 10,
    "status": "active",
    "createdAt": "2026-02-11T14:00:00.000Z",
    "updatedAt": "2026-02-11T15:30:00.000Z"
  }
}

{
  "details": {
    "cardNumber": "4111111111111111",
    "expiryMonth": 12,
    "expiryYear": 2028,
    "cvv": "123",
    "billingAddress": {
      "street": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    }
  }
}

{ "success": true, "cardId": "550e8400-...", "status": "frozen" }

{ "success": true, "cardId": "550e8400-...", "status": "active" }

{ "error": "Human-readable error message" }

AI Agent (Base wallet + USDC)
        │
        ▼
   HTTP Request (no auth)
        │
        ▼
┌──────────────────────────────┐
│        OpenCard API          │
│     (Express + x402)         │
│                              │
│  x402 paid (tier-based):     │
│   POST /cards/create/tier/N  │
│   POST /cards/fund/tier/N    │
│                              │
│  Wallet-signed (free):       │
│   GET  /cards                │
│   GET  /cards/:id            │
│   GET  /cards/:id/details    │
│   POST /cards/:id/freeze     │
│   POST /cards/:id/unfreeze   │
│                              │
│  Public:                     │
│   GET  /health               │
│   GET  /pricing              │
│   GET  /cards/tiers          │
└──────────┬───────────────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
 Coinbase     Card
 x402          Issuing
 Facilitator   Provider