Cryptocardium ileinşa edin.

Hoş Geldiniz

Cryptocardium, kripto ile fonlanan KYC gerektirmeyen bir kart programıdır. Panelde yapabileceğiniz her işlem — hesap açma, yükleme, kart çıkarma, yükleme, harcama, işlemleri izleme — aynı REST API ve MCP sunucusu aracılığıyla kullanılabilir.

Bu dokümantasyon her şeyi kapsar: kurallar (API nasıl iletişim kurar), kaynaklar (neler isteyebilirsiniz), olaylar (senkronize nasıl kalırsınız) ve entegrasyonlar (Claude, ChatGPT, Cursor, herhangi bir ajan).

Hızlı Başlangıç

Sıfırdan üç çağrıyla canlı bir sanal karta ulaşın. Aşağıdaki kabuk cURL kullanır; herhangi bir HTTP istemcisiyle değiştirin.

1. Kimlik doğrulama

API anahtarınızı Authorization başlığına ekleyin. Her endpoint bunu gerektirir.

export CCM_KEY="ccm_live_a1b2c3d4..."

2. Hazineyi yükle

USDT depozit adresi oluşturun. Fonları gönderin; onay sonrasında yükleyeceğiz.

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. Kart çıkar & harca

Bir BIN seçin (cüzdanlar için Visa Platinum, reklamlar için Visa Business), yükleyin ve kullanıma hazır olun.

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

Kimlik Doğrulama

Entegrasyon biçimine göre seçilen üç kimlik bilgisi türü:

Bearer başlığı

Her üçü de aynı başlıktan geçer:

Authorization: Bearer ccm_live_a1b2c3d4...

API anahtarı oluştur

Anahtarlar yalnızca panelde oluşturulur. Panel oturumuna bağlı kimliği doğrulanmış bir oturum olmadan API üzerinden anahtar oluşturma isteğini asla kabul etmeyiz.

1. Hesabınıza giriş yapın.
2. API Ayarları'nı açın.
3. Yeni anahtar'a tıklayın, tanınabilir bir ad verin, düz metni kaydedin (yalnızca bir kez gösterilir).
4. Bir gizli yöneticide saklayın. Ortamınıza CCM_KEY olarak ekleyin.

Test & Sandbox

Gerçek ödeme yapmadan entegrasyon yapabilmeniz için $200 altındaki yüklemeler canlı kabul edilir ancak sandbox kart işlemcisine yönlendirilir. Üretim hesapları anahtar başına sandbox modu geçişlerine sahiptir.

• $200 ve üzeri yükleme → üretim altyapısı, gerçek ödeme.
• $200 altı yükleme → sandbox altyapısı, simüle edilmiş onaylar.
• Sandbox yüklemelerinden çıkarılan kartlar "mode": "sandbox" taşır.

Temel URL & Sürümleme

Üretim temel URL'si:

https://api.cryptocardium.com/v1

v1 öneki yolun bir parçasıdır. v1 sonsuza kadar LTS'tir — bu altında asla kırıcı değişiklik yayınlanmayacaktır. Eklemeli değişiklikler (yeni isteğe bağlı alanlar, yeni endpointler) şeffaf biçimde yayınlanır.

Kırıcı değişiklikler en az altı aylık çakışmayla yeni bir önek (v2) altında yayınlanır. Kullanım dışı bırakmalar webhook (system.deprecation) ve değişiklik günlüğü aracılığıyla duyurulur.

İstekler

Tüm istekler yalnızca HTTPS (TLS 1.3) üzerinden yapılır. İstek gövdeleri JSON biçimindedir; iç içe nesneler birinci sınıf desteklenir. Form kodlu gövdeler desteklenmez.

• Content-Type: Yazma endpointleri için application/json.
• <strong>Karakter seti</strong>: Her zaman UTF-8.
• HTTP metotları: GET (okuma), POST (oluşturma / aksiyon), PATCH (kısmi güncelleme), DELETE (silme).
• Başlık limitleri: Toplam 8 KB, değer başına 4 KB.
• Gövde limiti: 25 MB (itiraz kanıtı yüklemeleri için 100 MB).
• Zaman aşımları: 30 s bağlantı, 60 s okuma. Uzun süren işlemler asenkrondur.

Yanıtlar

Her yanıt JSON biçimindedir. Başarılı yanıtlar kaynak gövdesiyle birlikte 200/201/204 döndürür. Hatalar yapılandırılmış bir hata nesnesi döndürür — bkz. Hatalar.

Standart zarf

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

Zaman damgaları

Tüm zaman damgaları UTC'de ISO 8601 biçimindedir ve YYYY-MM-DDTHH:MM:SSZ olarak formatlanır. API'de başka saat dilimi kullanılmaz.

Parasal değerler

Tüm tutarlar amount_usd alanlarında USD karşılığı ondalık biçimindedir. İki ondalık basamak hassasiyetinde. Dahili olarak USDT ile desteklenir.

Sayfalandırma

Liste endpointleri (/topups, /cards, /transactions, …) imleç tabanlı sayfalandırma kullanır. Offset veya SQL LIMIT yoktur.

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

• limit — sayfa boyutu, varsayılan 25, maksimum 100.
• cursor — önceki yanıttaki next_cursor'ı geri gönderin.
• Sayfalandırma her kaynağın doğal sıralamasını izler (genellikle <code>created_at</code> azalan).

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

Filtreleme & Sıralama

Her liste endpointi, birincil alanlarında sorgu parametreleri aracılığıyla filtrelemeyi destekler:

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

sort parametresi tek bir alan kabul eder; azalan sıra için - öneki ekleyin. Desteklenen filtre anahtarları için her kaynağın endpoint referansına bakın.

Idempotency

Her yazma isteği (POST, PATCH, DELETE) bir Idempotency-Key başlığını kabul eder. Mantıksal işlem başına benzersiz bir değer gönderin. Aynı anahtarla yapılan yeniden denemeler orijinal yanıtı döndürür.

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

• Anahtarlar 24 saat saklanır. Bu sürenin ardından aynı anahtar yeni bir işlem için yeniden kullanılabilir.
• Önerilen biçim: <operation>_<uuid-v4>.
• Aynı anahtar + farklı gövde → conflict_idempotency_key ile 409 Conflict.
• GET istekleri her zaman idempotent'tir ve başlığa gerek duymaz (veya kabul etmez).

İstek Limitleri

API anahtarı başına:

Her yanıt şunları içerir:

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

Limiti aştığınızda saniye cinsinden Retry-After başlığıyla birlikte 429 Too Many Requests alırsınız. Buna uyun; kötü davrananlar için üstel geri çekilme uyguluyoruz.

Hatalar

Her hata yanıtı aynı yapıyı kullanır:

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

HTTP durum kodu eşlemesi

Her zaman request_id'yi kaydedin. Destek talepleri doğrudan buna başvurur.

Hesaplar

Hesap, kök kaynağınızdır. Diğer her şey (yüklemeler, kartlar, işlemler) bir hesaba aittir.

Oluştur

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

Hemen bir oturum bearer'ı döndürür. API'yi kullanmaya başlamak için KYC gerekmez, belge yüklemesi veya e-posta doğrulama adımı yoktur.

Mevcut hesabı getir

GET /v1/accounts/me

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

Bakiye & Hazine

Hesap bakiyesi, harcanabilir USDT havuzudur. Yüklemeler bakiyeyi artırır, kart yüklemeleri ve para çekme işlemleri azaltır.

GET /v1/balance

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

pending_usd, uçuştaki yüklemeleri (henüz onaylanmamış) ve uçuştaki kart yüklemelerini kapsar.

Yüklemeler

Yükleme, zincir üzerinde kripto taahhüt ettiğiniz ve kesinleşme sonrasında USDT yüklediğimiz asimetrik adımdır.

Oluştur

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

Bir depozit adresi, QR veri URI'si ve bir son kullanma süresi (varsayılan 60 dk) döndürür. Tam tutarı adrese gönderin; onay sonrasında yükleriz.

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

Durum yaşam döngüsü

Sorgulama yerine topup.confirmed webhook'unu tercih edin — bir kez tetiklenir ve 30+ sorguyu önler.

Kartlar

Kartlar iki türdedir — sanal (saniyeler içinde aktif) ve fiziksel (5–9 günde kargolanan, Visa Gold BIN'e kilitli).

Kart çıkar

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

BIN kataloğu

Tam PAN + CVV'yi görüntüle

Tam kart numarası, CVV ve son kullanma tarihi yalnızca özel, denetimli bir çağrıyla döndürülür:

GET /v1/cards/:id/pan

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

Her görüntüleme denetim izine kaydedilir. Ajanlar satın alma başına bir kez görüntülemeli, asla saklamamalı ve kullanımdan sonra bellekten silmelidir.

İşlemler

• POST /v1/cards/:id/freeze — yetkilendirmeleri durdur.
• POST /v1/cards/:id/unfreeze — devam ettir.
• POST /v1/cards/:id/load — karta USDT ekle.
• POST /v1/cards/:id/unload — harcanmamış bakiyeyi hazineye geri taşı.
• POST /v1/cards/:id/cancel — kalıcı kapatma.
• PATCH /v1/cards/:id/limits — kart başına işlem / aylık tavan.
• PATCH /v1/cards/:id/mcc — MCC izin/engel listeleri.
• PATCH /v1/cards/:id/geo — ülke izin listeleri.

Kart Yüklemeleri & Bakiyeler

Kart bakiyesi USD karşılığı USDT cinsinden ifade edilir. Yükleme hazineden düşer, %2 altyapı ücreti uygulanır ve karta yüklenir.

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
}

Yüklemeler atomiktir — çağrı yalnızca fonlar transfer edildikten sonra döner.

İşlemler

Her yetkilendirme, tahsilat, iade ve ret bir işlem nesnesidir. Bunlar yalnızca eklenir ve değiştirilemez.

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 üzerinde filtreleyin.

Para Çekme

Hazine USDT'sini kontrolünüzdeki herhangi bir harici cüzdana gönderin.

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

Minimum $10, maksimum tam bakiyeniz. Desteklenen zincirler: tron (en ucuz), ethereum, bsc. Ağlar arası göndermeler geri alınamaz — adresi her zaman doğrulayın.

İtirazlar

Herhangi bir işlem için ters ibraz dosyalayın:

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

Neden kodları: duplicate, not_received, fraud, not_as_described, cancelled_subscription, other.

POST /v1/disputes/:id/evidence aracılığıyla kanıt (makbuzlar, ekran görüntüleri, yazışmalar) ekleyin. İhraçcıya sizin adınıza dosyalıyoruz — ekstra ücret yok.

Webhooks · abone olma

Webhooks, olayları gerçek zamanlı olarak HTTPS endpoint'inize iletir. Sorgulama yapmaktan kaçının; webhook kullanın.

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

Yanıt bir signing_secret içerir — bunu saklayın; payload'ları doğrulamak için gerekecek. Her olayı almak için "*"'a abone olun.

Webhooks · imza doğrulama

Her webhook, Cryptocardium-Signature başlığında HMAC-SHA256 imzası taşır:

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

signing_secret'ınızla "{t}.{rawBody}" üzerinden beklenen imzayı hesaplayın. Sabit zamanlı bir işlev kullanarak karşılaştırın.

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 · yeniden denemeler & tekrarlar

En az bir kez teslim garantisi. 2xx dışı herhangi bir yanıt veya zaman aşımında (10 s) yeniden deneriz.

Herhangi bir olayı panodan veya POST /v1/webhooks/:id/replay/:event_id aracılığıyla tekrar oynatın. Kendi tarafınızdaki yinelenenleri kaldırmak için Cryptocardium-Event-Id başlığını kullanın.

Olay Kataloğu

MCP Sunucu

https://mcp.cryptocardium.com/v1 adresinde bir Model Context Protocol sunucusu barındırıyoruz. REST endpointleriyle 1:1 eşlenen, ajan dostu adlara sahip 40+ araç sunar (create_topup, issue_card, reveal_pan vb.).

Aktarım: Streamable HTTP. Kimlik doğrulama: Dynamic Client Registration ile OAuth 2.1 — ajanlar ilk bağlantıda kendilerini kaydeder, ajanın yapılandırmasına API anahtarı yapıştırılması gerekmez.

MCP · İstemci Kurulumu

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

Tarayıcınızda yetkilendirdikten sonra ajan, katalogdaki her araca (veya kapsamı daralttıysanız yalnızca verdiğiniz araçlara) erişim sağlar.

MCP · Araç Kataloğu

Araçlar REST endpointlerini yansıtır. Küçük bir örnek (tam liste /api adresinde):

MCP · OAuth 2.1 + DCR

Ajanlar RFC 7591 aracılığıyla kendilerini dinamik olarak kaydeder. Akış:

1. Ajan POST /oauth/register — client_id & client_secret alır.
2. Kullanıcıdan tarayıcıda yetkilendirme istenir (bir kez).
3. Ajan access_token alır (kapsamlı, zamanlı).
4. Sonraki istekler JWT bearer taşır.

Araç başına kapsamlar

Bir ajanı salt okunur moduna, belirli bir karta veya araç alt kümesine kısıtlamak için kayıt sırasında scope= parametresini kullanın. Örnekler:

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

SDK'lar & örnekler

Resmi SDK'lar yakında sunulacak. O zamana kadar API düz bir REST arayüzüdür — her modern HTTP istemcisi bunu destekler.

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

Değişiklik günlüğü

Geriye dönük uyumlu değişiklikler şeffaf biçimde yayınlanır. Kırıcı değişiklikler yeni bir sürüm ön ekiyle sunulur.

• 2026-05-19 · v1.4 Eklendi

  POST /v1/cards/:id/load & /unload artık atomik. card.loaded webhook olayı eklendi.

• 2026-05-18 · v1.3 Eklendi

  MCP sunucusu mcp.cryptocardium.com adresinde yayında. OAuth 2.1 DCR. REST API'sinden eşlenen 40+ araç.

• 2026-05-17 · v1.2 Eklendi

  Fiziksel Altın kart programı (BIN 448585), Visa Business ve Visa Gold için 3-D Secure.

• 2026-05-15 · v1.1 Değiştirildi

  Sandbox yönlendirmesi için minimum yükleme tutarı 20 $'a, üretim rayları için 200 $'a düşürüldü.

• 2026-05-12 · v1.0 Yayınlandı

  v1 LTS. 50'den fazla uç nokta. Taşıyıcı doğrulama + idempotency anahtarları + HMAC webhook'ları.

Destek

Takıldınız mı? İki yol:

• yardım merkezi SSS'ye göz atın — aranabilir 30'dan fazla yanıtlı soru.
• Bir destek bileti açın — yalnızca aktif kart sahipleri, 24 saat içinde yanıt.

Başarısız yanıttaki request_id'yi ekleyin — çözümü 10 kat hızlandırır.