基于Cryptocardium 构建。

欢迎

Cryptocardium 是一个以加密货币充值的免 KYC 卡片项目。您在控制面板中能执行的所有操作——开户、充值、签发卡片、卡片入账、消费、查看交易——均可通过同一套 REST API 和 MCP 服务器实现。

本文档涵盖所有内容：约定规范（API 的通信方式）、资源（可请求的内容）、事件（保持数据同步的机制）以及集成方案（Claude、ChatGPT、Cursor 及各类代理）。

快速入门

从零到一张可用的虚拟卡，只需三次调用。以下示例使用 cURL，可替换为任意 HTTP 客户端。

1. 身份验证

将您的 API 密钥放入 Authorization 请求头。所有端点均需此头。

export CCM_KEY="ccm_live_a1b2c3d4..."

2. 充值财库

创建 USDT 充值地址。发送资金，确认后即到账。

curl https://api.cryptocardium.com/v1/topups \
  -H "Authorization: Bearer $CCM_KEY" \
  -H "Idempotency-Key: top_$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount_usd": 500, "asset": "USDT", "chain": "tron" }'

3. 签发卡片并消费

选择一个 BIN（Visa Platinum 适合钱包，Visa Business 适合广告投放），入账后即可使用。

curl https://api.cryptocardium.com/v1/cards \
  -H "Authorization: Bearer $CCM_KEY" \
  -d '{
    "type": "virtual",
    "bin": "489517",
    "load_usd": 300,
    "wallet_provision": ["apple_pay", "google_pay"]
  }'

# → 201 Created · card is live, balance loaded, wallet-ready

身份验证

三种凭证类型，按集成场景选择：

Bearer 请求头

三种方式均通过同一请求头传递：

Authorization: Bearer ccm_live_a1b2c3d4...

生成 API 密钥

密钥只能在控制面板中生成。我们不接受未附带面板会话的 API 密钥创建请求。

1. 登录您的账户。
2. 打开 API 设置。
3. 点击新建密钥，为其命名，并保存明文（仅显示一次）。
4. 存入密钥管理器，并以 CCM_KEY 的形式添加到您的环境变量中。

测试与沙箱

目前，$200 以下的充值将作为真实交易接受，但路由至沙箱卡处理器，让您无需消耗真实结算资金即可完成集成。生产账户可按密钥设置沙箱模式开关。

• 充值 $200 及以上 → 生产支付网络，真实结算。
• 充值低于 $200 → 沙箱支付网络，模拟授权。
• 由沙箱充值签发的卡片带有 "mode": "sandbox" 标记。

基础 URL 与版本控制

生产环境基础 URL：

https://api.cryptocardium.com/v1

v1 前缀是路径的一部分。v1 为长期支持版本——其下永不引入破坏性变更。新增变更（新增可选字段、新增端点）将透明发布。

破坏性变更将在新前缀（v2）下发布，并提供至少六个月的并行支持期。废弃通知将通过 Webhook（system.deprecation）和更新日志发布。

请求

所有请求仅支持 HTTPS（TLS 1.3）。请求体为 JSON 格式，原生支持嵌套对象。不支持表单编码请求体。

• Content-Type：写入端点使用 application/json。
• <strong>字符集</strong>：始终使用 UTF-8。
• HTTP 方法：GET（读取）、POST（创建/操作）、PATCH（部分更新）、DELETE（删除）。
• 请求头限制：总计 8 KB，单个值最大 4 KB。
• 请求体限制：25 MB（争议证据上传为 100 MB）。
• 超时时间：连接 30 秒，读取 60 秒。长时间操作为异步执行。

响应

所有响应均为 JSON 格式。成功响应返回 200/201/204 及资源内容。错误响应返回结构化错误对象——详见错误章节。

标准信封格式

{
  "id": "card_8f3a91b7c4d2",
  "object": "card",
  "created_at": "2026-05-19T07:30:00Z",
  "updated_at": "2026-05-19T07:30:00Z",
  ...
}

时间戳

所有时间戳均为 UTC 时间的 ISO 8601 格式，格式为 YYYY-MM-DDTHH:MM:SSZ。API 中不使用其他时区。

货币金额

所有金额均为 amount_usd 字段中的美元等值小数，精确到两位小数，内部以 USDT 为底层计价单位。

分页

列表端点（/topups、/cards、/transactions 等）采用游标分页。不使用偏移量或 SQL LIMIT。

GET /v1/transactions?limit=50&cursor=tx_8f3a91b7c4d2

• limit——每页数量，默认 25，最大 100。
• cursor——传入上次响应中的 next_cursor 值。
• 分页遵循各资源的自然排序（通常为 <code>created_at</code> 降序）。

{
  "object": "list",
  "data": [ /* 50 items */ ],
  "has_more": true,
  "next_cursor": "tx_2bea88..."
}

过滤与排序

每个列表端点均支持通过查询参数对主要字段进行过滤：

GET /v1/transactions
  ?card_id=card_8f3a91b7c4d2
  &status=captured
  &created_after=2026-05-01T00:00:00Z
  &sort=-amount_usd

sort 参数接受单个字段，前缀 - 表示降序排列。各资源支持的过滤键，请参阅对应的端点参考文档。

幂等性

所有写请求（POST、PATCH、DELETE）均接受 Idempotency-Key 请求头。每次逻辑操作传入唯一值。使用相同密钥重试时，将返回原始响应。

POST /v1/cards
Idempotency-Key: card_create_b9f1a4...
Authorization: Bearer ccm_live_...

• 密钥保存 24 小时。此后，同一密钥可用于新的操作。
• 推荐格式：<operation>_<uuid-v4>。
• 相同密钥 + 不同请求体 → 返回 409 Conflict，错误码为 conflict_idempotency_key。
• GET 请求天然具有幂等性，无需（也不接受）该请求头。

速率限制

每个 API 密钥：

每次响应均携带：

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 943
X-RateLimit-Reset:     1718999999

超出限制时，将返回 429 Too Many Requests，并附带以秒为单位的 Retry-After 请求头。请遵守该头；我们会对频繁违规者实施指数退避处理。

错误

所有错误响应均采用统一结构：

{
  "object": "error",
  "type": "invalid_request_error",
  "code": "missing_required_field",
  "message": "Field 'bin' is required.",
  "param": "bin",
  "request_id": "req_a9f4b1..."
}

HTTP 状态码映射

请务必记录 request_id。提交支持工单时将直接引用该值。

账户

账户是您的根资源。其他所有内容（充值、卡片、交易）均归属于账户。

创建

POST /v1/accounts
{
  "email": "[email protected]",
  "password": "long-random-string"
}

立即返回会话 Bearer 令牌。无需 KYC，无需上传文件，无需邮箱验证即可开始使用 API。

获取当前账户

GET /v1/accounts/me

{
  "id": "acc_8f3a91b7c4d2",
  "email": "[email protected]",
  "balance_usd": 487.20,
  "twofa_enabled": true,
  "created_at": "2026-05-18T20:14:00Z"
}

余额与财库

账户余额是可用的 USDT 资金池。充值会增加余额，卡片入账和提现会扣减余额。

GET /v1/balance

{
  "object": "balance",
  "available_usd": 487.20,
  "pending_usd": 200.00,
  "updated_at": "2026-05-19T07:30:00Z"
}

pending_usd 包含进行中的充值（尚未确认）和进行中的卡片入账。

充值

充值是非对称步骤：您在链上提交加密货币，我们在最终确认后将 USDT 到账。

创建

POST /v1/topups
{
  "amount_usd": 500,
  "asset": "USDT",
  "chain": "tron"
}

返回充值地址、二维码数据 URI 及到期时间（默认 60 分钟）。向该地址发送精确金额，确认后即到账。

{
  "id": "top_4e21a99c7b",
  "status": "pending",
  "amount_usd": 500,
  "deposit_address": "T9zFR...kQp",
  "qr_data_uri": "data:image/png;base64,...",
  "expires_at": "2026-05-19T08:30:00Z"
}

状态生命周期

建议使用 topup.confirmed Webhook 替代轮询——它仅触发一次，可节省 30 次以上的轮询请求。

卡片

卡片分为两种类型——虚拟卡（数秒内生效）和实体卡（5 至 9 个工作日配送，锁定 Visa Gold BIN）。

签发

POST /v1/cards
{
  "type": "virtual",
  "bin": "489517",
  "load_usd": 300,
  "wallet_provision": ["apple_pay", "google_pay"]
}

BIN 目录

查看完整卡号与 CVV

完整卡号、CVV 和有效期仅通过专用的受审计接口返回：

GET /v1/cards/:id/pan

{
  "pan": "4895 1712 ●●●● 4218",
  "cvv": "347",
  "expires_at": "2029-08",
  "audit_id": "audit_8c2e3f..."
}

每次查看均记录至审计日志。代理应在每次购买时查看一次，切勿存储，并在使用后从内存中销毁。

操作

• POST /v1/cards/:id/freeze——停止授权。
• POST /v1/cards/:id/unfreeze——恢复授权。
• POST /v1/cards/:id/load——向卡片充入 USDT。
• POST /v1/cards/:id/unload——将未消费余额退回财库。
• POST /v1/cards/:id/cancel——永久注销卡片。
• PATCH /v1/cards/:id/limits——设置单卡交易与月度上限。
• PATCH /v1/cards/:id/mcc——MCC 允许/拒绝列表。
• PATCH /v1/cards/:id/geo——国家允许列表。

卡片入账与余额

卡片余额以美元等值 USDT 计价。入账操作从财库扣款，收取 2% 支付网络手续费，并将资金存入卡片。

POST /v1/cards/:id/load
{ "amount_usd": 200 }

{
  "card_id": "card_8f3a91b7c4d2",
  "loaded_usd": 200.00,
  "rail_fee_usd": 4.00,
  "new_card_balance_usd": 200.00,
  "new_treasury_balance_usd": 283.20
}

入账操作为原子性——仅在资金移转完成后才返回响应。

交易

每笔授权、扣款、退款和拒绝均为一条交易对象。交易记录只追加、不可变更。

GET /v1/cards/:id/transactions?status=captured&limit=50

{
  "object": "list",
  "data": [
    {
      "id": "tx_b1c2d3",
      "object": "transaction",
      "card_id": "card_8f3a91b7c4d2",
      "status": "captured",
      "amount_usd": 42.95,
      "merchant": { "name": "OpenAI", "mcc": "7372" },
      "auth_response_code": "00",
      "created_at": "2026-05-19T03:14:00Z"
    }
  ],
  "has_more": false
}

可按 status、card_id、mcc、merchant_name、created_after、created_before、amount_min、amount_max 过滤。

提现

将财库中的 USDT 发送至您控制的任意外部钱包。

POST /v1/withdrawals
{
  "amount_usd": 100,
  "chain": "tron",
  "address": "T9zFR...kQp"
}

最低 $10，最高全部余额。支持链：tron（手续费最低）、ethereum、bsc。跨网络转账不可恢复——请务必核对地址。

争议

对任意交易发起拒付申请：

POST /v1/disputes
{
  "transaction_id": "tx_b1c2d3",
  "reason": "duplicate",
  "description": "Merchant charged twice on 2026-05-19, same order #4921."
}

原因代码：duplicate（重复扣款）、not_received（未收到）、fraud（欺诈）、not_as_described（与描述不符）、cancelled_subscription（已取消订阅）、other（其他）。

通过 POST /v1/disputes/:id/evidence 上传证据（收据、截图、往来记录）。我们将代您向发卡机构提交——无需额外费用。

Webhooks · 订阅

Webhook 会在事件发生时即时推送至您的 HTTPS 端点。请避免轮询，改用 Webhook。

POST /v1/webhooks
{
  "url": "https://yourapp.example.com/webhooks/cryptocardium",
  "events": [
    "topup.confirmed",
    "card.issued",
    "transaction.captured",
    "transaction.declined"
  ],
  "description": "Production sync"
}

响应中包含 signing_secret——请妥善保存，用于验证请求体签名。订阅 "*" 可接收所有事件。

Webhooks · 签名验证

每个 Webhook 在 Cryptocardium-Signature 请求头中携带 HMAC-SHA256 签名：

Cryptocardium-Signature: t=1718999999,v1=4a8b2f0e6c9d...
Cryptocardium-Event-Id:  evt_a1b2c3d4
Cryptocardium-Delivery:  dlv_8f3a91...

使用您的 signing_secret 对 "{t}.{rawBody}" 计算期望签名。请使用常量时间函数进行比较。

Node.js

import crypto from 'crypto';

export function verify(rawBody, sigHeader, secret) {
  const [t, v1] = sigHeader.split(',')
    .map(s => s.split('=')[1]);
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(v1), Buffer.from(expected)
  );
}

Python

import hmac, hashlib

def verify(raw_body: bytes, sig_header: str, secret: str) -> bool:
    parts = dict(p.split('=') for p in sig_header.split(','))
    t, v1 = parts['t'], parts['v1']
    expected = hmac.new(
        secret.encode(),
        f"{t}.{raw_body.decode()}".encode(),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(v1, expected)

PHP

function verify($rawBody, $sigHeader, $secret): bool {
    $parts = [];
    foreach (explode(',', $sigHeader) as $p) {
        [$k, $v] = explode('=', $p, 2);
        $parts[$k] = $v;
    }
    $expected = hash_hmac('sha256',
        "{$parts['t']}.{$rawBody}", $secret);
    return hash_equals($expected, $parts['v1']);
}

Webhooks · 重试与回放

至少投递一次。任何非 2xx 响应或超时（10 秒）均会触发重试。

可从控制台或通过 POST /v1/webhooks/:id/replay/:event_id 回放任意事件。在您的服务端使用 Cryptocardium-Event-Id 请求头进行去重。

事件目录

MCP 服务器

我们在 https://mcp.cryptocardium.com/v1 托管了一个 Model Context Protocol 服务器，提供 40 余个与 REST 端点一一对应的工具，命名对代理友好（create_topup、issue_card、reveal_pan 等）。

传输协议：Streamable HTTP。认证方式：OAuth 2.1 配合动态客户端注册——代理在首次连接时自助注册，无需将 API 密钥粘贴到代理配置文件中。

MCP · 客户端配置

Claude Desktop / Claude Code

// ~/.config/claude/claude_desktop_config.json
{
  "mcpServers": {
    "cryptocardium": {
      "url": "https://mcp.cryptocardium.com/v1",
      "transport": "http"
    }
  }
}

Cursor / Continue / mcp-cli

# Adds the server, kicks off OAuth DCR on first connect
mcp-cli add cryptocardium \
  --url https://mcp.cryptocardium.com/v1 \
  --auth oauth

在浏览器中完成授权后，代理即可访问目录中的所有工具（若您限制了授权范围，则仅限您授予的工具）。

MCP · 工具目录

工具与 REST 端点一一对应。以下为部分示例（完整列表见 /api）：

MCP · OAuth 2.1 + DCR

代理通过 RFC 7591 动态自助注册。流程如下：

1. 代理 POST /oauth/register——接收 client_id 和 client_secret。
2. 用户在浏览器中完成授权（仅需一次）。
3. 代理接收 access_token（有范围限制，有时效）。
4. 后续请求携带 JWT Bearer 令牌。

按工具划分的权限范围

在注册时传入 scope=，可将代理限制为只读模式、特定卡片或工具子集。示例：

scope=read           # list & get only, no writes
scope=cards:write    # manage cards but not withdraw
scope=card:card_8f3a91b7c4d2  # single card

SDK 与示例

官方 SDK 即将推出。在此之前，API 是一个扁平化的 REST 接口——所有现代 HTTP 客户端均可直接调用。

Node.js（fetch）

const res = await fetch('https://api.cryptocardium.com/v1/cards', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.CCM_KEY}`,
    'Idempotency-Key': `card_${crypto.randomUUID()}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'virtual', bin: '489517', load_usd: 300
  })
});
const card = await res.json();

Python（requests）

import requests, os, uuid

r = requests.post(
    'https://api.cryptocardium.com/v1/cards',
    headers={
        'Authorization': f"Bearer {os.environ['CCM_KEY']}",
        'Idempotency-Key': f"card_{uuid.uuid4()}",
    },
    json={'type': 'virtual', 'bin': '489517', 'load_usd': 300}
)
card = r.json()

PHP（curl）

$ch = curl_init('https://api.cryptocardium.com/v1/cards');
curl_setopt_array($ch, [
    CURLOPT_POST => 1,
    CURLOPT_RETURNTRANSFER => 1,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $_ENV['CCM_KEY'],
        'Idempotency-Key: card_' . bin2hex(random_bytes(16)),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'type' => 'virtual',
        'bin' => '489517',
        'load_usd' => 300,
    ]),
]);
$card = json_decode(curl_exec($ch), true);

更新日志

新增变更将以透明方式发布。重大变更将在新版本前缀下推出。

• 2026-05-19 · v1.4 新增

  POST /v1/cards/:id/load 与 /unload 现已实现原子操作。新增 card.loaded Webhook 事件。

• 2026-05-18 · v1.3 新增

  MCP 服务器已上线，地址为 mcp.cryptocardium.com。OAuth 2.1 DCR，40余项工具从 REST 映射而来。

• 2026-05-17 · v1.2 新增

  实体黄金卡计划（BIN 448585）上线，Visa Business 与 Visa Gold 支持 3-D Secure。

• 2026-05-15 · v1.1 变更

  沙盒路由的最低充值额降至 $20，生产环境降至 $200。

• 2026-05-12 · v1.0 发布

  v1 长期支持版。50余个端点，Bearer 认证 + 幂等键 + HMAC Webhook。

支持

遇到问题了？有两条途径：

• 浏览帮助中心常见问题——30余条已解答的问题，支持搜索。
• 提交支持工单——仅限活跃持卡人，24小时内回复。

请在工单中附上失败响应中的 request_id——可将处理效率提升10倍。