Стройте с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.

Тестирование & песочница

На данный момент пополнения до $200 принимаются как реальные, но направляются к процессору карт в режиме песочницы — можно интегрироваться, не расходуя реальные средства. Рабочие аккаунты получают переключатели режима песочницы для каждого ключа.

• Пополнение от $200 → реальные рельсы, реальный расчёт.
• Пополнение <$200 → рельсы песочницы, смоделированные авторизации.
• Карты, выпущенные из пополнений в режиме песочницы, содержат "mode": "sandbox".

Базовый URL & версионирование

Рабочий базовый URL:

https://api.cryptocardium.com/v1

Префикс v1 является частью пути. v1 — это долгосрочная поддержка навсегда — в нём никогда не будет критических изменений. Аддитивные изменения (новые необязательные поля, новые эндпоинты) добавляются прозрачно.

Критические изменения выходят под новым префиксом (v2) с периодом перекрытия не менее шести месяцев. Устаревание анонсируется через вебхук (system.deprecation) и историю изменений.

Запросы

Все запросы — только HTTPS (TLS 1.3). Тела запросов в формате JSON; вложенные объекты поддерживаются нативно. Тела в form-encoded формате не поддерживаются.

• Content-Type: application/json для записывающих эндпоинтов.
• <strong>Кодировка</strong>: всегда UTF-8.
• HTTP-методы: GET (чтение), POST (создание / действие), PATCH (частичное обновление), DELETE (удаление).
• Лимиты заголовков: 8 КБ суммарно, 4 КБ на одно значение.
• Лимит тела: 25 МБ (100 МБ для загрузки доказательств по спорам).
• Таймауты: 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 не используются.

Денежные значения

Все суммы — десятичные эквиваленты в USD в полях amount_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>.
• Тот же ключ + другое тело → 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"
}

Возвращает адрес для депозита, URI с 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"
}

Жизненный цикл статусов

Предпочтите вебхук 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 — списки разрешённых стран.

Загрузка карт & балансы

Баланс карты выражен в 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 — сохраните его; он потребуется для проверки данных. Подпишитесь на "*", чтобы получать все события.

Вебхуки · проверка подписи

Каждый вебхук содержит подпись 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']);
}

Вебхуки · повторы & воспроизведение

Доставка «хотя бы один раз». Мы повторяем запрос при любом ответе не-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. Последующие запросы несут Bearer JWT.

Разрешения на уровне инструментов

Ограничьте агента режимом только для чтения, конкретной картой или подмножеством инструментов, передав 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. Более 40 инструментов, отображённых из REST.

• 2026-05-17 · v1.2 Добавлено

  Программа физических карт Gold (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-аутентификация + ключи идемпотентности + HMAC-вебхуки.

Поддержка

Возникли трудности? Два варианта:

• Откройте FAQ центра помощи — более 30 вопросов и ответов с поиском.
• Создайте тикет поддержки — только для активных держателей карт, ответ в течение 24 ч.

Укажите request_id из ответа с ошибкой — это ускоряет решение в 10 раз.