OpenCard API 文档

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

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

const client = new OpenCardClient({
  bnbPrivateKey: 'base58-private-key',
  network: 'bnb',  // default
});

const result = await client.createCard({
  amount: 10,               // $10 tier
  nameOnCard: 'AI AGENT',
  email: 'agent@example.com',
});

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

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,    // 10 | 25 | 50 | 100 | 200 | 500
  nameOnCard: 'AI AGENT',
  email: 'agent@example.com',
  webhookUrl: 'https://your-agent.com/card-callback',  // optional
});

import {
  OpenCardClient,
  InsufficientBalanceError,
  PaymentError,
  ConfigError,
  ApiError,
} 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);
  }
}

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

{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "bnb:mainnet",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "maxAmountRequired": "11800000",
      "payTo": "6NsXb5ChS8fxH9N3qvtMzGNZ6k2RABxuq3fgwB9hnnB",
      "maxTimeoutSeconds": 300,
      "extra": { "chainName": "BNB" }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "maxAmountRequired": "11800000",
      "payTo": "0x6A119204301bF22E7358f30A6DA0BFbF7A6B9E68",
      "maxTimeoutSeconds": 300,
      "extra": { "chainName": "Base" }
    }
  ]
}

{
  "scheme": "exact",
  "network": "bnb:mainnet",
  "payload": {
    "authorization": {
      "from": "YourAgentWalletPublicKey",
      "to": "TreasuryPublicKey",
      "value": "11800000"
    },
    "txHash": "YourTransactionSignature..."
  }
}

opencard-auth:<unix_timestamp>

{
  "status": "ok",
  "timestamp": "2026-02-27T00:00:00.000Z",
  "version": "2.0.0",
  "service": "OpenCard"
}

{
  "cardCreation": {
    "providerFeePercent": 6,
    "ourMarkupPercent": 2,
    "safetyBuffer": 0.5,
    "example": {
      "loadAmount": 50,
      "totalCostUsd": 55
    }
  },
  "network": "base",
  "asset": "USDC",
  "tiers": {
    "creation": [
      { "loadAmount": 10, "totalCost": 11.8, "endpoint": "/cards/create/tier/10" }
    ]
  }
}

// Response 202 Accepted
{
  "success": true,
  "order": {
    "cardId": "550e8400-e29b-41d4-a716-446655440000",
    "tradeId": "abc123",
    "status": "processing",
    "loadAmount": 10,
    "createdAt": "2026-02-27T00:00:00.000Z"
  },
  "delivery": {
    "method": "webhook",
    "webhookUrl": "https://your-agent.com/callback",
    "estimatedWait": "5-15 minutes",
    "statusEndpoint": "/cards/550e8400.../status"
  },
  "payment": {
    "amountCharged": 11.8,
    "txHash": "...",
    "network": "bnb"
  }
}

{
  "cards": [{
    "cardId": "550e8400-...",
    "nameOnCard": "AGENT ALPHA",
    "loadAmount": 10,
    "status": "completed",
    "createdAt": "2026-02-27T00:00:00.000Z"
  }]
}

{
  "cardId": "550e8400-...",
  "status": "completed",
  "details": {
    "cardNumber": "4111111111111111",
    "cvv": "123",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "billingAddress": { ... }
  }
}

{
  "orderId": "550e8400-...",
  "status": "completed",
  "cardDetails": {
    "cardNumber": "4111111111111111",
    "cvv": "123",
    "expiryMonth": "12",
    "expiryYear": "2028",
    "billingAddress": { ... }
  },
  "timestamp": "2026-02-27T00:15:00.000Z"
}

{
  "orderId": "550e8400-...",
  "status": "failed",
  "error": "Card provider rejected the order",
  "timestamp": "2026-02-27T00:15:00.000Z"
}

AI Agent (BNB/Base wallet + USDC)
        │
        ▼
   HTTP Request (no auth)
        │
        ▼
┌──────────────────────────────┐
│        OpenCard API          │
│     (Express + x402)         │
│                              │
│  x402 paid:                  │
│   POST /cards/create/tier/N  │
│                              │
│  Wallet-signed (free):       │
│   GET  /cards                │
│   GET  /cards/:id            │
│   GET  /cards/:id/status     │
│                              │
│  Public:                     │
│   GET  /health               │
│   GET  /pricing              │
│   GET  /cards/tiers          │
└──────────┬───────────────────┘
           │
     ┌─────┴─────┐
     ▼           ▼
 Treasury     Card
 (USDC)       Provider
     │             │
     └──────┬──────┘
            ▼
      Card Delivered
      via Webhook