Entwickle mitCryptocardium.

Willkommen

Cryptocardium ist ein KYC-freies Kartenprogramm, finanziert mit Krypto. Jede Aktion, die im Panel möglich ist — Konto eröffnen, aufladen, eine Karte ausgeben, beladen, ausgeben, Transaktionen verfolgen — steht über dieselbe REST API und denselben MCP-Server zur Verfügung.

Diese Dokumentation deckt alles ab: Konventionen (wie die API kommuniziert), Ressourcen (was Sie abfragen können), Ereignisse (wie Sie synchron bleiben) und Integrationen (Claude, ChatGPT, Cursor, beliebige Agenten).

Schnellstart

Von null zur aktiven virtuellen Karte in drei Aufrufen. Das folgende Shell-Beispiel verwendet cURL; ersetzen Sie es durch einen beliebigen HTTP-Client.

1. Authentifizieren

Platzieren Sie Ihren API-Schlüssel im Authorization-Header. Jeder Endpoint erfordert ihn.

export CCM_KEY="ccm_live_a1b2c3d4..."

2. Treasury aufladen

Erstellen Sie eine USDT-Einzahlungsadresse. Senden Sie Mittel; wir schreiben sie nach Bestätigung gut.

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. Karte ausgeben & verwenden

Wählen Sie einen BIN (Visa Platinum für Wallets, Visa Business für Werbeanzeigen), laden Sie ihn auf — und Sie sind startklar.

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

Authentifizierung

Drei Anmeldeinformationstypen, gewählt nach Integrationsart:

Bearer-Header

Alle drei werden über denselben Header übermittelt:

Authorization: Bearer ccm_live_a1b2c3d4...

API-Schlüssel generieren

Schlüssel werden ausschließlich im Panel generiert. Wir akzeptieren keine Schlüsselerstellungsanfragen über die API ohne eine authentifizierte Session, die an die Panel-Session gebunden ist.

1. Melden Sie sich in Ihrem Konto an.
2. Öffnen Sie die API-Einstellungen.
3. Klicken Sie auf Neuer Schlüssel, vergeben Sie einen aussagekräftigen Namen und speichern Sie den Klartext (wird einmalig angezeigt).
4. In einem Secret-Manager ablegen. Ihrer Umgebung als CCM_KEY hinzufügen.

Testing & Sandbox

Derzeit werden Aufladungen unter $200 zwar als Live akzeptiert, jedoch an einen Sandbox-Kartenprozessor weitergeleitet, sodass Sie integrieren können, ohne echte Abrechnungen auszulösen. Produktionskonten erhalten Sandbox-Umschalter pro Schlüssel.

• Aufladung $200+ → Produktions-Rails, echte Abrechnung.
• Aufladung <$200 → Sandbox-Rails, simulierte Autorisierungen.
• Karten, die aus Sandbox-Aufladungen ausgegeben werden, tragen "mode": "sandbox".

Basis-URL & Versionierung

Produktions-Basis-URL:

https://api.cryptocardium.com/v1

Das Präfix v1 ist Bestandteil des Pfads. v1 ist dauerhaft LTS — unter diesem Präfix werden keine Breaking Changes eingeführt. Additive Änderungen (neue optionale Felder, neue Endpoints) werden transparent eingespielt.

Breaking Changes erscheinen unter einem neuen Präfix (v2) mit mindestens sechs Monaten Überschneidung. Veraltete Funktionen werden per Webhook (system.deprecation) und über das Changelog angekündigt.

Anfragen

Alle Anfragen sind ausschließlich HTTPS (TLS 1.3). Request-Bodies sind JSON; verschachtelte Objekte werden nativ unterstützt. Form-kodierte Bodies werden nicht akzeptiert.

• Content-Type: application/json für schreibende Endpoints.
• <strong>Zeichensatz</strong>: immer UTF-8.
• HTTP-Methoden: GET (lesen), POST (erstellen / ausführen), PATCH (partiell aktualisieren), DELETE (entfernen).
• Header-Limits: 8 KB gesamt, 4 KB pro Wert.
• Body-Limit: 25 MB (100 MB für Streitfall-Beweisdokumente).
• Timeouts: 30 s Verbindungsaufbau, 60 s Lesen. Lang laufende Operationen sind asynchron.

Antworten

Jede Antwort ist JSON. Erfolgreiche Antworten geben 200/201/204 mit dem Ressource-Body zurück. Fehler geben ein strukturiertes Fehlerobjekt zurück — siehe Fehler.

Standard-Envelope

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

Zeitstempel

Alle Zeitstempel sind ISO 8601 in UTC, formatiert als YYYY-MM-DDTHH:MM:SSZ. Die API verwendet keine anderen Zeitzonen.

Geldbeträge

Alle Beträge sind USD-äquivalente Dezimalwerte in amount_usd-Feldern. Zweistellige Dezimalpräzision. Intern durch USDT gedeckt.

Paginierung

Listen-Endpoints (/topups, /cards, /transactions, …) verwenden Cursor-Paginierung. Kein Offset, kein SQL-LIMIT.

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

• limit — Seitengröße, Standard 25, Maximum 100.
• cursor — übergeben Sie den next_cursor aus der vorherigen Antwort zurück.
• Die Paginierung folgt der natürlichen Sortierung jeder Ressource (typischerweise <code>created_at</code> absteigend).

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

Filterung & Sortierung

Jeder Listen-Endpoint unterstützt die Filterung nach seinen primären Feldern über Query-Parameter:

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

Der Parameter sort akzeptiert ein einzelnes Feld; stellen Sie - für absteigende Sortierung voran. Die unterstützten Filterschlüssel entnehmen Sie der Endpoint-Referenz der jeweiligen Ressource.

Idempotenz

Jede schreibende Anfrage (POST, PATCH, DELETE) akzeptiert einen Idempotency-Key-Header. Übergeben Sie einen eindeutigen Wert pro logischer Operation. Wiederholungen mit demselben Schlüssel geben die ursprüngliche Antwort zurück.

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

• Schlüssel werden 24 Stunden gespeichert. Danach kann derselbe Schlüssel für eine neue Operation wiederverwendet werden.
• Empfohlenes Format: <operation>_<uuid-v4>.
• Gleicher Schlüssel + abweichender Body → 409 Conflict mit conflict_idempotency_key.
• GET-Anfragen sind stets idempotent und benötigen (bzw. akzeptieren) den Header nicht.

Rate-Limits

Pro API-Schlüssel:

Jede Antwort enthält:

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

Bei Überschreitung des Limits erhalten Sie 429 Too Many Requests mit einem Retry-After-Header in Sekunden. Halten Sie sich daran; Clients mit Verstößen werden mit exponentiellem Backoff belegt.

Fehler

Jede Fehlerantwort hat dieselbe Struktur:

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

HTTP-Status-Zuordnung

Protokollieren Sie stets die request_id. Support-Tickets referenzieren sie direkt.

Konten

Das Konto ist Ihre Wurzelressource. Alles andere (Aufladungen, Karten, Transaktionen) gehört zu einem Konto.

Erstellen

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

Gibt sofort einen Session-Bearer zurück. Kein KYC, kein Dokument-Upload, keine E-Mail-Verifizierung erforderlich, um die API zu nutzen.

Aktuelles Konto abrufen

GET /v1/accounts/me

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

Guthaben & Treasury

Das Kontoguthaben ist der verfügbare USDT-Pool. Aufladungen erhöhen es, Kartenladungen und Auszahlungen verringern es.

GET /v1/balance

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

pending_usd umfasst ausstehende Aufladungen (noch nicht bestätigt) und ausstehende Kartenladungen.

Aufladungen

Eine Aufladung ist der asymmetrische Schritt, bei dem Sie Krypto on-chain einzahlen und wir nach Finalität USDT gutschreiben.

Erstellen

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

Gibt eine Einzahlungsadresse, einen QR-Daten-URI und eine Ablaufzeit (Standard 60 min) zurück. Senden Sie den genauen Betrag an die Adresse; wir schreiben ihn nach Bestätigung gut.

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

Status-Lebenszyklus

Bevorzugen Sie den Webhook topup.confirmed gegenüber Polling — er wird einmalig ausgelöst und erspart Ihnen 30+ Abfragen.

Karten

Karten gibt es in zwei Ausführungen — virtuell (innerhalb von Sekunden aktiv) und physisch (Versand in 5–9 Tagen, gebunden an den Visa Gold BIN).

Ausgeben

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

BIN-Katalog

Vollständige PAN + CVV abrufen

Die vollständige Kartennummer, CVV und das Ablaufdatum werden ausschließlich über einen dedizierten, geprüften Aufruf zurückgegeben:

GET /v1/cards/:id/pan

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

Jeder Abruf wird im Audit-Trail protokolliert. Agenten sollten einmalig pro Kauf abrufen, niemals speichern und den Wert nach der Verwendung aus dem Arbeitsspeicher löschen.

Operationen

• POST /v1/cards/:id/freeze — Autorisierungen stoppen.
• POST /v1/cards/:id/unfreeze — Autorisierungen fortsetzen.
• POST /v1/cards/:id/load — USDT auf die Karte laden.
• POST /v1/cards/:id/unload — ungenutztes Guthaben zurück zur Treasury übertragen.
• POST /v1/cards/:id/cancel — dauerhafte Stilllegung.
• PATCH /v1/cards/:id/limits — kartenbezogene Transaktions-/Monatsobergrenzen.
• PATCH /v1/cards/:id/mcc — MCC-Erlaubnis-/Sperrlisten.
• PATCH /v1/cards/:id/geo — Länder-Zulassungslisten.

Kartenladungen & -guthaben

Das Kartenguthaben wird in USD-äquivalentem USDT ausgewiesen. Eine Ladung belastet die Treasury, wendet die 2%-Rail-Gebühr an und schreibt der Karte gut.

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
}

Ladungen sind atomar — der Aufruf kehrt erst zurück, nachdem die Mittel transferiert wurden.

Transaktionen

Jede Autorisierung, Erfassung, Rückerstattung und Ablehnung ist ein Transaktionsobjekt. Sie sind append-only und unveränderlich.

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
}

Filtern Sie nach status, card_id, mcc, merchant_name, created_after, created_before, amount_min, amount_max.

Auszahlungen

Senden Sie Treasury-USDT an eine beliebige externe Wallet, die Sie kontrollieren.

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

Minimum $10, Maximum Ihr gesamtes Guthaben. Unterstützte Chains: tron (günstigste), ethereum, bsc. Netzwerkübergreifende Übertragungen sind unwiderruflich — überprüfen Sie die Adresse stets sorgfältig.

Streitfälle

Rückbuchung für eine beliebige Transaktion einleiten:

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

Grundcodes: duplicate, not_received, fraud, not_as_described, cancelled_subscription, other.

Belege (Quittungen, Screenshots, Korrespondenz) über POST /v1/disputes/:id/evidence beifügen. Wir leiten den Fall in Ihrem Namen an den Aussteller weiter — ohne zusätzliche Gebühr.

Webhooks · Abonnieren

Webhooks senden Ereignisse an Ihren HTTPS-Endpoint, sobald sie eintreten. Vermeiden Sie Polling; verwenden Sie Webhooks.

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

Die Antwort enthält ein signing_secret — speichern Sie es; Sie benötigen es zur Verifikation der Payloads. Abonnieren Sie "*", um alle Ereignisse zu empfangen.

Webhooks · Signaturverifizierung

Jeder Webhook enthält eine HMAC-SHA256-Signatur im Cryptocardium-Signature-Header:

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

Berechnen Sie die erwartete Signatur über "{t}.{rawBody}" mit Ihrem signing_secret. Vergleichen Sie mit einer zeitkonstanten Funktion.

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 · Wiederholungen & Replays

At-least-once-Zustellung. Wir wiederholen bei jeder Nicht-2xx-Antwort oder einem Timeout (10 s).

Jedes Ereignis kann über das Dashboard oder per POST /v1/webhooks/:id/replay/:event_id erneut abgespielt werden. Verwenden Sie den Cryptocardium-Event-Id-Header zur Deduplizierung auf Ihrer Seite.

Ereigniskatalog

MCP-Server

Wir betreiben einen Model Context Protocol-Server unter https://mcp.cryptocardium.com/v1. Er stellt 40+ Tools bereit, die 1:1 auf REST-Endpoints abgebildet sind, mit agentenfreundlichen Namen (create_topup, issue_card, reveal_pan usw.).

Transport: Streamable HTTP. Auth: OAuth 2.1 mit Dynamic Client Registration — Agenten registrieren sich beim ersten Verbindungsaufbau selbst; kein API-Schlüssel muss in die Konfiguration des Agenten eingefügt werden.

MCP · Client-Einrichtung

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

Nach der Autorisierung im Browser hat der Agent Zugriff auf alle Tools im Katalog (oder nur auf die genehmigten, falls der Scope eingeschränkt wurde).

MCP · Tools-Katalog

Tools spiegeln REST-Endpoints wider. Eine kleine Auswahl (die vollständige Liste finden Sie unter /api):

MCP · OAuth 2.1 + DCR

Agenten registrieren sich dynamisch über RFC 7591. Ablauf:

1. Agent POST /oauth/register — erhält client_id & client_secret.
2. Der Benutzer wird im Browser zur Autorisierung aufgefordert (einmalig).
3. Agent erhält access_token (eingeschränkt, zeitlich begrenzt).
4. Nachfolgende Anfragen tragen den JWT-Bearer.

Berechtigungen pro Tool

Schränken Sie einen Agenten auf Lesezugriff, auf eine bestimmte Karte oder auf eine Teilmenge von Tools ein, indem Sie bei der Registrierung scope= übergeben. Beispiele:

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

SDKs & Beispiele

Offizielle SDKs folgen demnächst. Bis dahin ist die API eine flache REST-Oberfläche — jeder moderne HTTP-Client kommt damit zurecht.

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);

Changelog

Additive Änderungen werden transparent ausgeliefert. Breaking Changes erhalten ein neues Versions-Präfix.

• 2026-05-19 · v1.4 Hinzugefügt

  POST /v1/cards/:id/load & /unload sind jetzt atomar. Webhook-Event card.loaded hinzugefügt.

• 2026-05-18 · v1.3 Hinzugefügt

  MCP-Server live unter mcp.cryptocardium.com. OAuth 2.1 DCR. 40+ Tools aus REST abgebildet.

• 2026-05-17 · v1.2 Hinzugefügt

  Physical Gold Card Programm (BIN 448585), 3-D Secure für Visa Business und Visa Gold.

• 2026-05-15 · v1.1 Geändert

  Mindest-Aufladebetrag auf $20 für Sandbox-Routing und $200 für Produktions-Rails gesenkt.

• 2026-05-12 · v1.0 Veröffentlicht

  v1 LTS. 50+ Endpunkte. Bearer-Auth + Idempotency Keys + HMAC-Webhooks.

Support

Nicht weitergekommen? Zwei Wege:

• Durchsuchen Sie das Hilfe-Center-FAQ — 30+ beantwortete Fragen, durchsuchbar.
• Öffnen Sie ein Support-Ticket — nur für aktive Karteninhaber, Antwort innerhalb von 24 h.

Geben Sie die request_id aus der fehlgeschlagenen Antwort an — das beschleunigt die Lösung um das 10-Fache.