一緒に構築する、Cryptocardium。

ようこそ

Cryptocardiumは暗号資産で資金調達するKYC不要のカードプログラムです。パネルで行えるすべての操作 — アカウント開設、チャージ、カード発行、入金、利用、トランザクション確認 — は同じREST APIとMCPサーバーから利用できます。

このドキュメントはすべてを網羅しています。規約（APIの通信方法）、リソース（取得できるもの）、イベント（同期の維持方法）、インテグレーション（Claude、ChatGPT、Cursor、任意のエージェント）。

クイックスタート

ゼロから3回のコールでライブのバーチャルカードを発行できます。以下のシェルはcURLを使用していますが、任意のHTTPクライアントに置き換えてください。

1. 認証

AuthorizationヘッダーにAPIキーを設定してください。すべてのエンドポイントで必須です。

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

認証

3種類の認証情報があり、インテグレーションの形態に応じて選択します。

Bearerヘッダー

3種類すべてが同じヘッダーを通じて渡されます。

Authorization: Bearer ccm_live_a1b2c3d4...

APIキーの生成

キーはパネル内でのみ生成されます。パネルセッション自体に紐付いた認証済みセッションなしには、APIを通じたキー作成リクエストは受け付けません。

1. アカウントにサインインしてください。
2. API Settingsを開いてください。
3. New keyをクリックし、識別しやすい名前を付けて、プレーンテキストを保存してください（一度だけ表示されます）。
4. シークレットマネージャーに保存し、環境変数CCM_KEYとして追加してください。

テストとサンドボックス

現在、$200未満のチャージはライブとして受け付けられますが、サンドボックスのカードプロセッサーにルーティングされます。そのため、実際の決済を使わずにインテグレーションが可能です。本番アカウントではキーごとにサンドボックスモードの切り替えができます。

• $200以上のチャージ → 本番レール、実際の決済。
• $200未満のチャージ → サンドボックスレール、模擬認証。
• サンドボックスチャージから発行されたカードには"mode": "sandbox"が付与されます。

ベースURLとバージョン管理

本番ベースURL：

https://api.cryptocardium.com/v1

v1プレフィックスはパスの一部です。v1はLTS永続対応 — 破壊的変更は一切行われません。追加的な変更（新しいオプションフィールド、新しいエンドポイント）は透過的に追加されます。

破壊的変更は新しいプレフィックス（v2）の下で、少なくとも6か月の並行期間を設けて導入されます。非推奨化はWebhook（system.deprecation）および変更履歴で告知されます。

リクエスト

すべてのリクエストはHTTPS専用（TLS 1.3）です。リクエストボディはJSON形式で、ネストされたオブジェクトもファーストクラスとして扱われます。フォームエンコードボディはサポートしていません。

• Content-Type：書き込みエンドポイントはapplication/json。
• <strong>文字コード</strong>：常にUTF-8。
• HTTPメソッド：GET（読み取り）、POST（作成／アクション）、PATCH（部分更新）、DELETE（削除）。
• ヘッダー制限：合計8 KB、1値あたり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フィールドにUSD相当の小数として格納されます。小数点以下2桁の精度で、内部的にはUSDTに裏付けられています。

ページネーション

リストエンドポイント（/topups、/cards、/transactionsなど）はカーソルページネーションを採用しています。オフセットやSQLLIMITは使用しません。

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>。
• 同じキーで異なるボディ → conflict_idempotency_keyとともに409 Conflict。
• 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"
}

即座にセッションベアラーが返されます。APIの利用開始にKYCは不要です。書類のアップロードもメール認証ステップもありません。

現在のアカウントを取得

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"
}

入金アドレス、QRデータ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回以上のポーリングを省略できます。

カード

カードには2種類あります — バーチャル（数秒で有効化）とフィジカル（5〜9日で配送、Visa Gold BINのみ）。

発行

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

BINカタログ

全PAN＋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 — 国の許可リストを設定します。

カードへの入金と残高

カード残高はUSD相当の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で証拠（領収書、スクリーンショット、連絡履歴）を添付してください。弊社が発行者に代わって申請します — 追加料金はかかりません。

Webhook · 購読

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が含まれます — ペイロードの検証に必要ですので保存してください。"*"を購読するとすべてのイベントを受信できます。

Webhook · 署名検証

すべての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']);
}

Webhook · 再試行とリプレイ

少なくとも1回の配信を保証します。2xx以外のレスポンスまたはタイムアウト（10秒）の場合に再試行します。

ダッシュボードから、またはPOST /v1/webhooks/:id/replay/:event_idを通じて任意のイベントをリプレイできます。自分側での重複排除にはCryptocardium-Event-Idヘッダーを使用してください。

イベントカタログ

MCPサーバー

https://mcp.cryptocardium.com/v1でModel Context Protocolサーバーをホストしています。RESTエンドポイントに1対1で対応する40以上のツールが公開されており、エージェントに親しみやすい名称（create_topup、issue_card、reveal_panなど）が付けられています。

トランスポート：Streamable HTTP。認証：OAuth 2.1 with Dynamic Client Registration — エージェントは初回接続時に自己登録します。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。REST から 40 以上のツールをマッピング。

• 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 LTS。50 以上のエンドポイント。Bearer 認証・冪等性キー・HMAC Webhook。

サポート

お困りですか？二つの方法があります：

• ヘルプセンター FAQ を参照してください — 30 以上の Q&A が検索可能な形で掲載されています。
• サポートチケット を開いてください — 有効なカード所持者のみ、24 時間以内に返信します。

失敗したレスポンスに含まれる request_id を記載してください — 解決速度が 10 倍速くなります。