함께 구축하세요,Cryptocardium으로.

소개

Cryptocardium은 암호화폐로 충전하는 KYC 없는 카드 프로그램입니다. 패널에서 할 수 있는 모든 작업 — 계정 개설, 충전, 카드 발급, 카드 로드, 결제, 거래 조회 — 이 모두 동일한 REST API와 MCP 서버를 통해 이용 가능합니다.

이 문서는 모든 내용을 다룹니다: 규칙 (API 통신 방식), 리소스 (요청 가능한 항목), 이벤트 (동기화 유지 방법), 통합 (Claude, ChatGPT, Cursor, 모든 에이전트).

빠른 시작

세 번의 호출로 처음부터 활성화된 가상 카드까지. 아래 예시는 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

인증

통합 방식에 따라 세 가지 자격 증명 유형을 선택할 수 있습니다:

Bearer 헤더

세 가지 모두 동일한 헤더를 통해 전달됩니다:

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입니다 — 하위 호환성을 깨는 변경 사항은 절대 배포되지 않습니다. 추가 변경 사항(새 선택적 필드, 새 엔드포인트)은 투명하게 반영됩니다.

하위 호환성을 깨는 변경 사항은 최소 6개월의 병행 운영과 함께 새 접두사(v2)로 제공됩니다. 더 이상 사용하지 않는 기능은 웹훅(system.deprecation)과 변경 이력을 통해 공지됩니다.

요청

모든 요청은 HTTPS 전용(TLS 1.3)입니다. 요청 본문은 JSON이며, 중첩 객체를 기본 지원합니다. Form-encoded 본문은 지원되지 않습니다.

• 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 필드에 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>.
• 동일한 키 + 다른 본문 → 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"
}

세션 Bearer를 즉시 반환합니다. 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 웹훅을 사용하세요 — 한 번만 발생하며 30건 이상의 폴링을 줄여줍니다.

카드

카드는 두 가지 유형이 있습니다 — 가상 (몇 초 내 활성화) 및 실물 (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를 통해 증거(영수증, 스크린샷, 서신)를 첨부하세요. 추가 비용 없이 발급사에 대신 제출해 드립니다.

웹훅 · 구독

웹훅은 이벤트 발생 즉시 귀하의 HTTPS 엔드포인트로 이벤트를 전송합니다. 폴링 대신 웹훅을 사용하세요.

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

응답에 signing_secret이 포함됩니다 — 저장해 두세요. 페이로드 검증에 필요합니다. "*"를 구독하면 모든 이벤트를 수신할 수 있습니다.

웹훅 · 서명 검증

모든 웹훅은 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']);
}

웹훅 · 재시도 & 재전송

최소 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. 인증: Dynamic Client Registration이 포함된 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. 사용자에게 브라우저에서 인증 요청이 표시됩니다 (최초 1회).
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 웹훅 이벤트가 추가되었습니다.

• 2026-05-18 · v1.3 추가됨

  MCP 서버가 mcp.cryptocardium.com에서 운영됩니다. OAuth 2.1 DCR. REST에서 매핑된 40개 이상의 도구.

• 2026-05-17 · v1.2 추가됨

  피지컬 골드 카드 프로그램 (BIN 448585), Visa 비즈니스 및 Visa 골드에서의 3-D Secure.

• 2026-05-15 · v1.1 변경됨

  샌드박스 라우팅의 최소 충전 금액이 $20으로, 프로덕션 레일은 $200으로 인하되었습니다.

• 2026-05-12 · v1.0 출시됨

  v1 LTS. 50개 이상의 엔드포인트. Bearer 인증 + 멱등성 키 + HMAC 웹훅.

지원

막히셨나요? 두 가지 방법이 있습니다:

• 도움말 센터 FAQ를 검색하세요 — 30개 이상의 답변된 Q&A, 검색 가능.
• 지원 티켓을 열어보세요 — 활성 카드 소지자 전용, 24시간 이내 답변.

실패한 응답에서 request_id를 포함해 주세요 — 문제 해결 속도가 10배 빨라집니다.