ابنِ مع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.

الاختبار & Sandbox

حاليًا، تُقبل التعبئات دون 200 دولار كإنتاج حقيقي لكنها تُوجَّه إلى معالج بطاقات Sandbox، حتى تتمكن من التكامل دون استنزاف تسوية حقيقية. تحصل حسابات الإنتاج على مفاتيح بوضع Sandbox.

• تعبئة 200 دولار+ → سكك الإنتاج، تسوية حقيقية.
• تعبئة أقل من 200 دولار → سكك Sandbox، تفويضات محاكاة.
• البطاقات الصادرة من تعبئات Sandbox تحمل "mode": "sandbox".

عنوان URL الأساسي & الإصدارات

عنوان URL الأساسي للإنتاج:

https://api.cryptocardium.com/v1

البادئة v1 جزء من المسار. v1 مدعوم إلى الأبد — لن تُجرى تغييرات كسر الاتوافقية تحتها أبدًا. تُضاف التغييرات الإضافية (حقول اختيارية جديدة، نقاط نهاية جديدة) بشفافية.

تذهب التغييرات الكاسرة تحت بادئة جديدة (v2) مع تداخل لا يقل عن ستة أشهر. تُعلن الإهمالات عبر Webhook (system.deprecation) وسجل التغييرات.

الطلبات

جميع الطلبات عبر HTTPS فقط (TLS 1.3). أجسام الطلبات بصيغة JSON؛ الكائنات المتداخلة مدعومة. لا تُقبل الأجسام بصيغة form-encoded.

• Content-Type: application/json لنقاط النهاية للكتابة.
• <strong>ترميز المحارف</strong>: UTF-8 دائمًا.
• HTTP methods: 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",
  ...
}

الطوابع الزمنية

جميع الطوابع الزمنية بصيغة ISO 8601 بتوقيت UTC، بالصيغة YYYY-MM-DDTHH:MM:SSZ. لا توجد مناطق زمنية أخرى في API.

القيم النقدية

جميع المبالغ هي أرقام عشرية مكافئة للدولار الأمريكي في حقول amount_usd. دقة منزلتين عشريتين. مدعومة داخليًا بـ USDT.

ترقيم الصفحات

نقاط نهاية القوائم (/topups، /cards، /transactions، …) تستخدم ترقيمًا بالمؤشر. لا offset، لا LIMIT بـ SQL.

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

يُعيد عنوان إيداع وبيانات QR ووقت انتهاء (افتراضي 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"
}

دورة حياة الحالة

فضّل Webhook topup.confirmed على الاستطلاع — يُطلق مرة واحدة ويوفّر عليك 30+ استطلاعًا.

البطاقات

البطاقات نوعان — افتراضية (نشطة في ثوانٍ) ومادية (تُشحن خلال 5–9 أيام، مقيّدة بـ BIN Visa Gold).

إصدار

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 — قوائم السماح بالدول.

تحميل البطاقات & الأرصدة

رصيد البطاقة مقوّم بـ 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 · الاشتراك

تدفع Webhooks الأحداث إلى نقطة نهاية HTTPS الخاصة بك فور حدوثها. تجنّب الاستطلاع؛ استخدم Webhooks.

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 يحمل توقيع HMAC-SHA256 في رأس Cryptocardium-Signature:

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

احسب التوقيع المتوقع على "{t}.{rawBody}" باستخدام signing_secret الخاص بك. قارن باستخدام دالة ذات زمن ثابت.

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

نستضيف خادم Model Context Protocol على https://mcp.cryptocardium.com/v1. يعرض 40+ أداة مُعيَّنة 1:1 إلى نقاط نهاية REST، بأسماء صديقة للوكلاء (create_topup، issue_card، reveal_pan، إلخ).

النقل: Streamable HTTP. المصادقة: OAuth 2.1 مع 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

SDKs & أمثلة

ستُشحن SDKs الرسمية قريبًا. حتى ذلك الحين، 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 باتا الآن ذريّتَين. أُضيف حدث webhook باسم card.loaded.

• 2026-05-18 · v1.3 مُضاف

  خادم MCP متاح على mcp.cryptocardium.com. OAuth 2.1 DCR. أكثر من 40 أداة مُعيَّنة من REST.

• 2026-05-17 · v1.2 مُضاف

  برنامج بطاقة الذهب المادية (BIN 448585)، وتقنية 3-D Secure على Visa Business و Visa Gold.

• 2026-05-15 · v1.1 مُعدَّل

  خُفِّض الحد الأدنى للتعبئة إلى 20$ لتوجيه بيئة الاختبار، و200$ للسكك الإنتاجية.

• 2026-05-12 · v1.0 مُطلَق

  الإصدار v1 LTS. أكثر من 50 نقطة نهاية. مصادقة Bearer + مفاتيح الأمانة + webhooks بتوقيع HMAC.

الدعم

هل واجهت عقبة؟ ثمة مساران:

• تصفّح الأسئلة الشائعة في مركز المساعدة — أكثر من 30 سؤالًا وجوابًا، قابلة للبحث.
• افتح تذكرة دعم — لأصحاب البطاقات النشطين فحسب، الرد خلال 24 ساعة.

أرفق request_id من الاستجابة المُخفِقة — فهو يُسرّع الحل عشرة أضعاف.