Transaction Decision API

Проверка транзакции перед зачислением

ChainZap проверяет транзакцию в блокчейне до того, как ваше приложение засчитает платёж полученным. Один ответ объединяет факты о транзакции, сигналы риска и, если вы попросите, сравнение с ожидаемыми получателем, токеном и суммой.

Что можно проверить

Адаптеры TRON, Ethereum mainnet и TON mainnet реализованы. Проверки TRON доступны каждой новой организации сразу. TON работает в режиме предварительного доступа, и его проверки исполненных транзакций сейчас возвращают LIMITED_DATA; проверки Ethereum подключает поддержка по запросу. Войдите с аккаунтом ChainZap в кабинет разработчика, создайте API-ключ и начните с канонического transaction quickstart.

• POST /v1/transaction/check: канонический подробный ответ контракта 0.3. Сеть обязательна; ожидаемые данные платежа включают verification.
• POST /v1/check: передайте хеш транзакции. Сеть и ожидаемые данные платежа необязательны. Ответ содержит краткую оценку и полные данные в details.
• POST /v1/wallet/check: передайте адрес кошелька. Сеть определяется по его формату. Ответ содержит состояние, уровень покрытия и коды причин, а в details факты по каждому модулю; см. проверку кошелька.
• GET /v1/usage: квота и статистика запросов вашей организации.

Вызывайте API со своего сервера и передавайте API-ключ в заголовке X-API-Key.

Читайте ответ целиком

Успешный HTTP-ответ не означает, что платёж подтверждён или свободен от риска. Для /v1/check читайте state, risk_level и coverage вместе со статусом транзакции, результатами сравнения, временем данных и причинами внутри details. Канонический /v1/transaction/check возвращает эти подробные поля на верхнем уровне ответа. Значение null означает «неизвестно» или «не запрашивалось», в зависимости от поля. Отсутствие данных нельзя считать чистым результатом.

Продолжите с первого запроса, затем изучите полноту данных и идемпотентность.

Отправьте первый запрос

Получите доступ

Войдите с аккаунтом ChainZap в кабинет разработчика. Организация создаётся автоматически, и вы становитесь её владельцем; код приглашения нужен только для входа в существующую организацию. Создайте ключ на странице «API-ключи» и сохраните его в защищённом хранилище сервера. Проверки TRON доступны сразу: sandbox-ключ позволяет тестировать бесплатно, а тариф для рабочих проверок покупается на странице «Тариф и оплата». Коллег можно пригласить на странице «Организация».

Отправьте первый запрос

В примере используются вымышленный ключ и хеш. Замените их своими значениями на сервере. Все суммы передаются десятичными строками. Сохраните ключ идемпотентности вместе с платёжной операцией, чтобы он пережил перезапуск процесса.

curl --include --max-time 15 'https://api.chainzap.io/v1/transaction/check' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: cz_live_000000000000.fictional_example_only' \
  -H 'Idempotency-Key: merchant-order-1001-check-1' \
  -H 'X-Request-ID: merchant-order-1001-attempt-1' \
  --data '{"network":"tron","expected_recipient":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8","expected_token":"TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t","expected_amount":"1250.000001","tx_hash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}'

Прочитайте X-Request-ID в заголовках ответа и request_id в JSON. Сохраните этот идентификатор для поддержки. Канонический endpoint требует network. Перед обработкой ответа прочитайте оси статусов; POST /v1/check — отдельный сокращённый ответ.

Сравните с данными платежа

{
  "network": "tron",
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "expected_recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "expected_token": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "expected_amount": "1250.000001"
}

Адреса в примере публичные и приведены только для иллюстрации, отправлять на них средства не нужно. Сравнивайте точный контракт токена, а не символ. Читайте все три флага сравнения: они относятся к одному выбранному переводу. См. сравнение платежа.

Обработайте контракт 0.3

Для verification платежа читайте verification_final и integrity_status, затем отдельно оценивайте risk_status и recommended_action. Pending — NOT_EVALUATED, никогда не MATCH. Окончательный MATCH с risk_status: INSUFFICIENT подтверждает сравнение платежа, но требует MANUAL_REVIEW, а не автоматического зачисления или одобрения выплаты. Читайте risk_retryable отдельно от retryable. Эти ветки показаны в примерах ответов.

Автоматическое закрытие выплаты

Без контекста о вашей стороне окончательный MATCH с risk_status: NO_MATERIAL_SIGNAL и без причин для ручной проверки даёт CONFIRM_INTERNAL_STATE: блокчейн и проверка риска в порядке, но ChainZap не видит, тот ли это платёж, который вы должны, и не закрыт ли он уже. Это не отказ: убедитесь по своим записям, что выплата ещё причитается и не отмечена как оплаченная, и закройте её. То же действие без MATCH (ожидаемые поля не переданы) платёж не сравнивало: не закрывайте по нему выплату.

Чтобы получить PROCEED, сообщите ChainZap, за что этот платёж: передайте direction: "OUTGOING", workflow_type: "PAYOUT" и external_reference выплаты вместе с ожидаемыми полями либо сначала запишите обязательство и передайте его external_reference в проверке. Чистое окончательное совпадение с записанным исходящим обязательством — это PROCEED; без external_reference лучший ответ остаётся CONFIRM_INTERNAL_STATE, если только проверка не передаёт customer_context.credit_status: "NOT_CREDITED": этого одного достаточно для PROCEED, если allocation_status не равен UNKNOWN (см. оси статусов). direction и workflow_type принимаются и без реестра обязательств, но сами по себе до PROCEED не доводят; при direction: "OUTGOING" ненайденная выплата дополнительно получает ATTEMPT_MAY_STILL_LAND: не платите повторно. external_reference и остальные поля обязательства требуют реестра обязательств и там, где он выключен, получают ответ 403 ledger_not_enabled.

Если ответ не пришёл

Если соединение оборвалось до получения ответа, повторите запрос с тем же телом и тем же Idempotency-Key. Не создавайте новый ключ, чтобы обойти неизвестный результат. Полученную ошибку повторяйте только при error.retryable=true, учитывайте Retry-After и ограничивайте число попыток. Сохранённая ошибка может вернуться без изменений: retryable не заставляет сервер заново обращаться к источникам.

Готовые алгоритмы с ограниченными повторами есть в примерах Python и TypeScript; остаток квоты можно посмотреть через статистику запросов.

Проверьте и кошелёк

Тем же ключом можно проверить адрес контрагента: POST /v1/wallet/check с телом {"address": "..."} возвращает состояние, покрытие и коды причин в том же формате и списывается, когда получено состояние. См. проверку кошелька.

Один хеш — одна проверка

Для POST /v1/check достаточно tx_hash. API сообщает факты, риски и пробелы в данных; решение о платеже остаётся за вашим приложением. Войдите с аккаунтом ChainZap в кабинет разработчика и создайте серверный ключ на странице «API-ключи».

Первый результат

Задайте на сервере CHAINZAP_API_KEY, TX_HASH и сохранённый идентификатор операции CHECK_ID. Примеры отправляют один запрос только при запуске. Для тестовых данных без вызовов провайдеров используйте sandbox-ключ. Не размещайте ключ в браузере. Для запроса нужно меньше десяти строк прикладного кода; прежде чем читать результат, проверьте HTTP-статус.

curl --include --max-time 15 https://api.chainzap.io/v1/check \
  -H "X-API-Key: $CHAINZAP_API_KEY" -H "Idempotency-Key: $CHECK_ID" \
  -H 'Content-Type: application/json' --data "{\"tx_hash\":\"$TX_HASH\"}"

const response = await fetch("https://api.chainzap.io/v1/check", {
  method: "POST", signal: AbortSignal.timeout(15000),
  headers: {"Content-Type": "application/json", "X-API-Key": process.env.CHAINZAP_API_KEY,
    "Idempotency-Key": process.env.CHECK_ID},
  body: JSON.stringify({tx_hash: process.env.TX_HASH})
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.code);

import os, requests
response = requests.post("https://api.chainzap.io/v1/check", timeout=15,
    headers={"X-API-Key": os.environ["CHAINZAP_API_KEY"],
             "Idempotency-Key": os.environ["CHECK_ID"]},
    json={"tx_hash": os.environ["TX_HASH"]})
result = response.json()
response.raise_for_status()

<?php
$ch = curl_init('https://api.chainzap.io/v1/check');
curl_setopt_array($ch, [CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 15,
  CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'X-API-Key: '.getenv('CHAINZAP_API_KEY'), 'Idempotency-Key: '.getenv('CHECK_ID')],
  CURLOPT_POSTFIELDS => json_encode(['tx_hash' => getenv('TX_HASH')])]);
$result = json_decode(curl_exec($ch), true);
if (curl_errno($ch) || curl_getinfo($ch, CURLINFO_HTTP_CODE) >= 400) throw new RuntimeException($result['error']['code'] ?? 'transport_error');
curl_close($ch);

Определение сети

Допустимые названия сетей — tron, eth и ton; алиасы отклоняются. Явно указанная сеть ограничивает поиск этой сетью. Форма хеша, префикс 0x, base64 и порядок ответов провайдеров никогда не определяют сеть, в том числе в sandbox.

Без network факты читаются только в поддерживаемых, включённых сетях, разрешённых вашей организации. Область поиска возвращается в details.checked_networks; уникальность внутри неё ничего не говорит о других сетях. AML-проверка не запускается по всем сетям. Все остальные проверенные сети должны достоверно сообщить об отсутствии транзакции. Ошибка провайдера, неполная индексация или тайм-аут не считаются отсутствием. Один найденный результат плюс один неизвестный требуют явной сети.

Автоопределение использует тот же бюджет обращений к источникам, что и явный выбор сети, — и когда в области поиска одна сеть, и когда несколько. Источники всё равно должны подтвердить, что хеш транзакции найден в названной сети. Обращение с ненастроенной ценой учитывается как неизвестная стоимость, а не как нулевая.

NETWORK_AMBIGUOUS означает, что транзакция найдена в нескольких сетях. NETWORK_REQUIRED — что контекста недостаточно для единственного результата: например, одна сеть нашла транзакцию, а другая не смогла ответить, или включённых сетей нет. Если все проверенные сети подтвердили отсутствие транзакции, ответом будет 404 transaction_not_found. Оба ответа используют HTTP 422, state: insufficient_input, network: null, error.retryable: false, error.required_field: network, error.candidates и error.checked_networks. Укажите сеть и используйте новый ключ идемпотентности. Повтор прежнего тела вернёт ту же сохранённую ошибку.

Краткий и подробный ответ

state — это details.overall_state в нижнем регистре. Подробные объекты причин находятся в details.reasons; строки и объекты никогда не смешиваются. Известный высокий риск остаётся виден при частичном покрытии. null в запрошенном сравнении означает, что оно не завершено. Все поля expected_* должны совпасть в одном переводе; несколько полных совпадений — неоднозначность.

Канонический /v1/transaction/check сохраняет состояния в верхнем регистре, coverage: complete или partial и от 2 до 5 объектов причин. /v1/usage и X-API-Key не меняются. /v1/check возвращает HTTP 404 transaction_not_found, если отсутствие в явной сети подтверждено; канонический метод сохраняет HTTP 200 transaction_state: not_found. Незавершённая транзакция даёт HTTP 200 с review или limited_data, но никогда clear, и не списывается. У обоих методов общие лимиты, квота и стоимость. Ключи идемпотентности общие в пределах организации: смена метода или тела запроса даёт конфликт. Сохранённые результаты, включая определённую сеть и ошибки, выданные после принятия проверки, возвращаются без нового обращения к провайдерам; 429 и 5xx никогда не сохраняются. При повторе заново проверяется доступ.

Покрытие Ethereum и TON

Внутренние переводы ETH требуют трассировки выполнения и не входят в покрытие этой версии. Логи ERC-20 не подтверждают итоговое изменение баланса получателя для токенов с комиссией при переводе или с автоматическим изменением балансов. Выпуск, сжигание и переводы с нулевой суммой требуют внимания (review). Если количество десятичных знаков неизвестно, сумма остаётся null; символ токена никогда не доказывает подлинность. Для других токенов возможны факты перевода при неполном покрытии подлинности/KYT.

TON принимает только хеш транзакции: hex из 64 знаков с необязательным 0x либо канонический base64/base64url из 32 байтов. Хеш сообщения или BOC не подменяется хешем транзакции без предупреждения. Пользовательские адреса проверяются по контрольной сумме. Варианты bounceable и non-bounceable приводятся к одному workchain/account; адреса с признаком тестовой сети отклоняются. expected_token — jetton master, expected_recipient — владелец кошелька. Одного сообщения transfer_notification недостаточно. Возврат сообщения, ошибка вычисления или действия, неполная цепочка сообщений и эмуляция не могут дать clear. Текущие результаты get-методов сверяются со вторым индексатором; изменение исторической идентичности требует дополнительной проверки. Финальность подтверждается данными провайдеров, без локальной проверки подписей валидаторов.

Проверки Ethereum и TON подключает поддержка для конкретной организации после приёмки на реальных источниках. AML-скрининг охватывает те активы, которые AML-источник поддерживает в каждой сети; доступ конкретного аккаунта, фактическую стоимость и покрытие ещё нужно подтвердить на реальных данных. Отсутствующие данные AML или санкций никогда не превращаются в low/clear. См. полноту данных.

Детерминированный пример ответа

Это иллюстративная фикстура, а не наблюдение реальной транзакции. Полный JSON раскрывается ниже.

{
  "coverage": "complete",
  "details": {
    "aml_risk_level": "low",
    "amount": "1250.000001",
    "amount_match": true,
    "checked_networks": [
      "tron"
    ],
    "confirmations": 27,
    "coverage": "complete",
    "coverage_limitations": {
      "product": [
        "AML_TRANSACTION_LEVEL_ONLY",
        "RISK_STATE_AS_OF_CHECK",
        "SANCTIONS_CONFIGURED_LISTS_ONLY"
      ],
      "runtime": []
    },
    "coverage_status": "OK",
    "decimals": 6,
    "decision_id": "0199a1b2-7c3d-7e4f-8a9b-0c1d2e3f4a5b",
    "direct_sanctions_match": false,
    "direction": "OUTGOING",
    "environment": "live",
    "evidence": {},
    "evidence_items": [
      {
        "coverage": "checked",
        "dependency": "required",
        "disagreement": null,
        "effective_at": "2026-09-03T11:59:00Z",
        "evidence_id": "ev_3b9e1c7a5d2f8e61",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": 2,
          "stale": false,
          "stale_after_seconds": null
        },
        "kind": "transaction_facts",
        "observed_at": "2026-09-03T11:59:58Z",
        "source": "chain_explorer",
        "source_reference": "block:60000000",
        "subject": {
          "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "type": "transaction"
        },
        "temporal_scope": "TRANSACTION_TIME"
      },
      {
        "coverage": "checked",
        "dependency": "required",
        "disagreement": null,
        "effective_at": "2026-09-03T11:59:00Z",
        "evidence_id": "ev_5f0c3a1d9b2e7f40",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": 2,
          "stale": false,
          "stale_after_seconds": null
        },
        "kind": "transaction_facts",
        "observed_at": "2026-09-03T11:59:58Z",
        "source": "chain_node",
        "source_reference": "block:60000000",
        "subject": {
          "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "type": "transaction"
        },
        "temporal_scope": "TRANSACTION_TIME"
      },
      {
        "coverage": "checked_freshness_unknown",
        "dependency": "required",
        "disagreement": null,
        "effective_at": null,
        "evidence_id": "ev_8a4d2e6f1c9b3a75",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": 0,
          "stale": true,
          "stale_after_seconds": null
        },
        "kind": "aml_risk",
        "observed_at": "2026-09-03T12:00:00Z",
        "source": "aml_provider",
        "source_reference": "transaction_risk_score",
        "subject": {
          "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "type": "transaction"
        },
        "temporal_scope": "CHECK_TIME"
      },
      {
        "coverage": "checked",
        "dependency": "required",
        "disagreement": null,
        "effective_at": null,
        "evidence_id": "ev_c27f5b0e9d4a1863",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": 0,
          "stale": false,
          "stale_after_seconds": 172800
        },
        "kind": "sanctions_list",
        "observed_at": "2026-09-03T12:00:00Z",
        "source": "ofac",
        "source_reference": "configured_address_index",
        "subject": {
          "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "type": "transaction_addresses"
        },
        "temporal_scope": "LIST_PUBLICATION"
      },
      {
        "coverage": "checked",
        "dependency": "required",
        "disagreement": null,
        "effective_at": "2026-08-28T00:00:00Z",
        "evidence_id": "ev_4e18a9d3b6c07f52",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": 0,
          "stale": false,
          "stale_after_seconds": 3024000
        },
        "kind": "sanctions_list",
        "observed_at": "2026-09-03T12:00:00Z",
        "source": "eu",
        "source_reference": "configured_address_index",
        "subject": {
          "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "type": "transaction_addresses"
        },
        "temporal_scope": "LIST_PUBLICATION"
      },
      {
        "coverage": "checked",
        "dependency": "required",
        "disagreement": null,
        "effective_at": "2026-08-28T00:00:00Z",
        "evidence_id": "ev_91d6f2a8c3e5b047",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": 0,
          "stale": false,
          "stale_after_seconds": 3024000
        },
        "kind": "sanctions_list",
        "observed_at": "2026-09-03T12:00:00Z",
        "source": "uk",
        "source_reference": "configured_address_index",
        "subject": {
          "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "type": "transaction_addresses"
        },
        "temporal_scope": "LIST_PUBLICATION"
      },
      {
        "coverage": "not_applicable",
        "dependency": "not_applicable",
        "disagreement": null,
        "effective_at": null,
        "evidence_id": "ev_6b03e7c1f5a92d48",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": null,
          "stale": false,
          "stale_after_seconds": null
        },
        "kind": "sanctions_list",
        "observed_at": null,
        "source": "un",
        "source_reference": "configured_address_index",
        "subject": {
          "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "type": "transaction_addresses"
        },
        "temporal_scope": "LIST_PUBLICATION"
      },
      {
        "coverage": "checked",
        "dependency": "required",
        "disagreement": null,
        "effective_at": null,
        "evidence_id": "ev_f0a5c8e2d7b41936",
        "evidence_version": "ev-1",
        "freshness": {
          "age_seconds": 0,
          "stale": false,
          "stale_after_seconds": null
        },
        "kind": "token_authenticity",
        "observed_at": "2026-09-03T12:00:00Z",
        "source": "token_registry",
        "source_reference": "official",
        "subject": {
          "ref": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
          "type": "token"
        },
        "temporal_scope": "CHECK_TIME"
      }
    ],
    "finality_policy": "tron_solidified_19_confirmations",
    "finalized": true,
    "freshness": {
      "checked_at": "2026-09-03T12:00:00Z",
      "max_source_age_seconds": 2,
      "risk_data_at": "2026-09-03T12:00:00Z",
      "token_data_at": "2026-09-03T12:00:00Z",
      "transaction_at": "2026-09-03T11:59:00Z"
    },
    "indirect_sanctions_exposure": false,
    "integrity": {
      "comparisons": {
        "amount": {
          "actual": "1250.000001",
          "delta": "0",
          "delta_raw": "0",
          "expected": "1250.000001",
          "result": "EXACT",
          "tolerance": null
        },
        "network": {
          "actual": "tron",
          "expected": null,
          "result": "NOT_EVALUATED"
        },
        "recipient": {
          "actual": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
          "expected": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
          "result": "MATCH"
        },
        "sender": {
          "actual": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
          "expected": null,
          "result": "NOT_EVALUATED"
        },
        "token": {
          "actual": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
          "expected": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
          "result": "MATCH"
        }
      },
      "relevant_event_count": 1,
      "selected_event_ref": "log:0",
      "status": "MATCH"
    },
    "integrity_status": "MATCH",
    "key_exposure": [],
    "limitations": [],
    "network": "tron",
    "obligation": null,
    "overall_state": "CLEAR",
    "policy_version": "b2b-tx-2026-10.4",
    "reasons": [
      {
        "category": "transaction",
        "code": "TX_FACTS_VERIFIED",
        "severity": "info"
      },
      {
        "category": "transaction",
        "code": "TX_FINALIZED",
        "severity": "info"
      },
      {
        "category": "risk",
        "code": "AML_LOW",
        "severity": "info"
      },
      {
        "category": "sanctions",
        "code": "NO_DIRECT_SANCTIONS_MATCH",
        "severity": "info"
      },
      {
        "category": "token",
        "code": "TOKEN_OFFICIAL",
        "severity": "info"
      }
    ],
    "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
    "recipient_match": true,
    "recommended_action": "CONFIRM_INTERNAL_STATE",
    "request_id": "req-3f34a12f",
    "required_confirmations": 19,
    "result_final": true,
    "retry_after_seconds": null,
    "retryable": false,
    "reuse": {
      "first_seen_at": null,
      "other_obligations": 0,
      "prior_decisions": 0,
      "status": "FIRST_SEEN"
    },
    "risk": {
      "driver": null,
      "driver_evidence_ids": [],
      "status": "NO_MATERIAL_SIGNAL"
    },
    "risk_exposure": false,
    "risk_final": true,
    "risk_retry_after_seconds": null,
    "risk_retryable": false,
    "risk_status": "NO_MATERIAL_SIGNAL",
    "sanctions_hit": false,
    "schema_version": "0.3",
    "selected_transfer_index": 0,
    "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
    "source_coverage": {
      "risk_sources": {
        "aml_provider": {
          "checked_at": "2026-09-03T12:00:00Z",
          "data_updated_at": null,
          "error_code": null,
          "retrieved_at": "2026-09-03T12:00:00Z",
          "scope": "transaction_risk_score",
          "stale_after_seconds": null,
          "status": "checked_freshness_unknown"
        }
      },
      "sanctions_sources": {
        "eu": {
          "checked_at": "2026-09-03T12:00:00Z",
          "data_updated_at": "2026-08-28T00:00:00Z",
          "error_code": null,
          "retrieved_at": "2026-09-01T09:00:00Z",
          "scope": "configured_address_index",
          "stale_after_seconds": 3024000,
          "status": "checked"
        },
        "ofac": {
          "checked_at": "2026-09-03T12:00:00Z",
          "data_updated_at": null,
          "error_code": null,
          "retrieved_at": "2026-09-03T06:00:00Z",
          "scope": "configured_address_index",
          "stale_after_seconds": 172800,
          "status": "checked"
        },
        "uk": {
          "checked_at": "2026-09-03T12:00:00Z",
          "data_updated_at": "2026-08-28T00:00:00Z",
          "error_code": null,
          "retrieved_at": "2026-09-01T09:00:00Z",
          "scope": "configured_address_index",
          "stale_after_seconds": 3024000,
          "status": "checked"
        },
        "un": {
          "checked_at": null,
          "data_updated_at": null,
          "error_code": null,
          "retrieved_at": null,
          "scope": "configured_address_index",
          "stale_after_seconds": null,
          "status": "not_applicable"
        }
      },
      "transaction_sources": {
        "chain_explorer": {
          "checked_at": "2026-09-03T12:00:00Z",
          "data_updated_at": null,
          "error_code": null,
          "retrieved_at": "2026-09-03T11:59:58Z",
          "scope": "transaction_facts",
          "stale_after_seconds": null,
          "status": "checked"
        },
        "chain_node": {
          "checked_at": "2026-09-03T12:00:00Z",
          "data_updated_at": null,
          "error_code": null,
          "retrieved_at": "2026-09-03T11:59:58Z",
          "scope": "transaction_facts",
          "stale_after_seconds": null,
          "status": "checked"
        }
      },
      "universal_clearance": false
    },
    "status_drivers": {
      "action": "CUSTOMER_STATE_UNKNOWN",
      "coverage": null,
      "integrity": null,
      "risk": null,
      "transaction": "TX_FINALIZED"
    },
    "token_authenticity": "official",
    "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "token_match": true,
    "token_symbol": "USDT",
    "trace_complete": null,
    "transaction_category": "trc20_transfer",
    "transaction_state": "confirmed",
    "transaction_status": "CONFIRMED",
    "transaction_type": "TriggerSmartContract",
    "transfers": [
      {
        "amount": "1250.000001",
        "asset_type": "trc20",
        "decimals": 6,
        "event_ref": "log:0",
        "execution_status": "success",
        "index": 0,
        "raw_amount": "1250000001",
        "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
        "sender": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
        "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "token_id": null,
        "token_symbol": "USDT"
      }
    ],
    "transfers_truncated": false,
    "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "verification_final": true,
    "versions": {
      "contract": "0.3",
      "decision": "b2b-tx-2026-10.4",
      "evidence_schema": "ev-1",
      "reason_codes": "rc-1",
      "rules": {
        "allocation": "alloc-v1",
        "billing": "final_answers_only",
        "exposure": "b2b-exp-v2",
        "integrity": "int-v3",
        "reuse": "reuse-v1",
        "sanctions_freshness": "sf-v1"
      }
    },
    "workflow_coverage": "complete",
    "workflow_type": "PAYOUT"
  },
  "network": "tron",
  "reason_codes": [
    "TX_FACTS_VERIFIED",
    "TX_FINALIZED",
    "AML_LOW",
    "NO_DIRECT_SANCTIONS_MATCH",
    "TOKEN_OFFICIAL"
  ],
  "request_id": "req-3f34a12f",
  "risk_level": "low",
  "state": "clear"
}

Доступ и API-ключи

Один аккаунт ChainZap

Нажмите «Войти с аккаунтом ChainZap» и используйте аккаунт из приложения. Переход «Настройки → API для разработчиков → Кабинет» использует действующий вход в том же браузере. Организация, API-ключи и лимит API учитываются отдельно от личных проверок в приложении. Если раньше вы входили в кабинет через Google, прежняя организация сохраняется: связь проверяется по идентификатору Google, а не по совпадению адреса почты.

Для обычного входа код приглашения не нужен. Приглашения служат только для присоединения к существующей организации. Если Telegram открывает отдельный браузер, в котором вы ещё не входили в ChainZap, войдите там один раз с тем же аккаунтом. Чтобы пользоваться Google и Telegram как одним аккаунтом, сначала свяжите их в настройках приложения.

Серверные API-ключи

Передавайте X-API-Key по HTTPS в каждом запросе к рабочему API. Никогда не помещайте ключ в URL, хранилище браузера, аналитику, сообщение в поддержку или систему контроля версий. Ключ даёт доступ к одной организации; выбрать другую организацию в запросе нельзя.

Вход в кабинет разработчика и API-ключи работают независимо друг от друга. Live-ключи начинаются с cz_live_, sandbox-ключи — с cz_test_.

Роли в кабинете:

• Участники с ролями owner, admin и developer создают, заменяют и отзывают API-ключи.
• Участники с ролями owner, admin и billing видят историю платежей, покупают планы и пакеты дополнительных проверок и управляют подпиской.
• Участники с ролью viewer только просматривают статистику и метаданные ключей.

По API-ключу купить ничего нельзя.

Жизненный цикл ключа

Создавайте отдельный ключ с понятным названием для каждой интеграции. Полное значение показывается один раз — при создании или замене; в списке видно только начало ключа. При замене старый ключ отзывается, а новый создаётся в той же операции. Сразу после замены обновите хранилище секретов на сервере. Чтобы плановый переход прошёл без перерыва, сначала создайте отдельный ключ, переведите на него интеграцию и проверьте её, а затем отзовите прежний ключ.

Ошибки доступа

• 401 invalid_api_key: ключ неверен или отозван.
• 403 tenant_suspended: доступ организации приостановлен.
• 403 network_not_enabled: запрошенная сеть не включена для организации.

Сначала исправьте доступ. Повторение того же запроса без изменений не поможет.

POST /v1/transaction/check

Запрос

Строгий JSON-запрос требует network и tx_hash длиной 32 байта. Неизвестные поля отклоняются. Ожидаемые адреса проверяются и нормализуются по правилам выбранной сети. expected_amount — неотрицательная десятичная строка; JSON-числа и экспоненциальная запись отклоняются. Необязательная сеть и краткий ответ доступны в POST /v1/check.

Форматы адресов и правила точного сравнения описаны в разделе сравнения платежа. Размер тела запроса ограничен 4 КиБ; тело большего размера отклоняется с 413 payload_too_large. Организации, работающие по пилотному контракту, должны передавать все три поля expected_*.

Передайте Content-Type: application/json, серверный X-API-Key и Idempotency-Key для логической операции проверки. X-Request-ID связывает запрос с вашим журналом операций. Точный перечень обязательных полей, перечислений и схем ответа есть в справочнике API.

Ответ

Читайте transaction_state отдельно от overall_state. Ответ содержит число подтверждений, нормализованные переводы, выбранный перевод, уровень риска, результат санкционной проверки, подлинность токена, флаги сравнения, покрытие, актуальность данных и от 2 до 5 наиболее важных причин. Суммы переводов и доли риска представлены десятичными строками. Обрабатывайте поля со значением null явно.

transfers_truncated=true означает, что список переводов сокращён. AMBIGUOUS_TRANSFER означает, что вашим условиям соответствуют несколько переводов. Оба случая требуют внимания. Не считайте сокращённый список полным и не объединяйте флаги сравнения разных переводов.

Обработайте контракт 0.3

Для verification платежа читайте verification_final и integrity_status, затем отдельно оценивайте risk_status и recommended_action. Pending — NOT_EVALUATED, никогда не MATCH. Окончательный MATCH с risk_status: INSUFFICIENT подтверждает сравнение платежа, но требует MANUAL_REVIEW, а не автоматического зачисления или одобрения выплаты. Читайте risk_retryable отдельно от retryable. Эти ветки показаны в примерах ответов.

Списание

Окончательный ответ с coverage: complete списывает одну проверку из квоты, в том числе полный результат с высоким риском: транзакция подтверждена по правилам окончательного подтверждения или окончательно завершилась ошибкой. Транзакция, ожидающая подтверждения, ненайденная транзакция и ответ с coverage: partial не списываются. Повтор той же идемпотентной операции никогда не списывает проверку дважды.

expected_token — это адрес контракта, а не тикер; старое имя expected_token_contract также принимается. Передавайте только одно имя. Ответ содержит schema_version: "0.3", policy_version (политика принятия решений, по которой сформирован ответ; храните её вместе с ответом), три отдельных risk/sanctions-флага, workflow_coverage и source_coverage. Перед трактовкой результата прочитайте правила покрытия. Ключи идемпотентности, использованные до контракта 0.2, возвращают 409 idempotency_conflict; после обработки прежнего результата используйте новый ключ.

Проверьте кошелёк до того, как принять его или заплатить ему

POST /v1/wallet/check проверяет один адрес так же, как POST /v1/check проверяет одну транзакцию: тот же ключ, та же квота, те же правила идемпотентности и тот же формат ответа. Вы отправляете адрес, получаете состояние, уровень покрытия и коды причин, а решение, нужна ли контрагенту дополнительная проверка, принимает ваш процесс.

Запрос

Три формата невозможно спутать между собой, поэтому проверка кошелька никогда не отвечает NETWORK_REQUIRED или NETWORK_AMBIGUOUS. Строка, не подходящая ни под один формат, даёт 422 invalid_address. Неизвестные поля отклоняются, тело ограничено 4 КиБ. Передавайте Content-Type: application/json, серверный X-API-Key и Idempotency-Key логической операции; X-Request-ID связывает запрос с вашим журналом.

curl --include --max-time 35 'https://api.chainzap.io/v1/wallet/check' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: cz_live_000000000000.fictional_example_only' \
  -H 'Idempotency-Key: onboarding-4711-wallet-1' \
  -H 'X-Request-ID: onboarding-4711-attempt-1' \
  --data '{"address":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8"}'

Адрес в примере публичный и приведён только для иллюстрации, переводить на него ничего не нужно. В ответе address возвращается в каноническом написании: Ethereum в нижнем регистре, TON в виде workchain:hash, TRON без изменений.

Ответ

Сначала читайте верхний уровень, затем details.

details объясняет, из чего сложилось состояние:

• overall_state и data_coverage: состояние в верхнем регистре и слово о покрытии от самого движка, FULL, PARTIAL или INSUFFICIENT.
• modules: семь строк в фиксированном порядке, sanctions_aml, wallet_behaviour, token_authenticity, contract_controls, address_security, counterparties_services, flows_connections. У каждой есть status (RISK_DETECTED, NO_MATCHES_FOUND, PARTIALLY_CHECKED, INSUFFICIENT_DATA, NOT_SUPPORTED, NOT_CHECKED) и source_coverage (complete, partial, none, not_applicable). Непроверенный модуль так и сообщает об этом и никогда не выглядит чистым.
• sanctions: direct_match по настроенным индексам OFAC, EU, UK и UN (null, если ни один индекс не проверялся), органы authorities, признак attributed и indirect_exposure от AML-провайдера (null, если он не вызывался).
• address_security: статус и категория в публичных списках недобросовестных адресов, provider_flagged (отметил ли адрес провайдер безопасности адресов; null, если он не ответил или его права не позволяют ChainZap это показывать) и признак заморозки адреса эмитентом стейблкоина. Собственные метки провайдера никогда не возвращаются; устаревшее поле provider_flags равно ["PROVIDER_SECURITY_FLAG"], когда provider_flagged истинно, и пусто в остальных случаях.
• behaviour: является ли адрес контрактом, число транзакций и признак ограничения выборки, возраст кошелька, первая и последняя активность, число контрагентов.
• counterparties и token_authenticity: сколько контрагентов проверено, не подтверждено и помечено; сколько удерживаемых токенов официальные, поддельные, подозрительные или неизвестные.
• freshness и source_coverage: когда выполнялась проверка, взят ли анализ из кеша анализа (5 минут в Ethereum, 30 минут в TRON и TON; ответ AML-провайдера используется повторно до 24 часов), возраст самого старого источника и по одному наблюдению на каждый источник с тем же словарём статусов, что и у проверки транзакции. Источники названы по роли: ofac, eu_sanctions, uk_sanctions, un_sanctions, denylist, issuer_restrictions, aml_provider, address_security_provider, onchain, chain_explorer, chain_node, graph_risk.
• limitations: analysis_from_cache, transaction_sample_capped, aml_provider_unavailable, aml_provider_skipped_dominant_local_hit, counterparty_attribution_partial, network_assumed_eth, address_security_provider_withheld, sandbox_partial_fixture.

Все коды причин для кошельков с их значением перечислены в разделе коды причин.

Чем проверка кошелька не является

В ответе нет числового балла, и это сделано намеренно. Число провоцирует порог, а честного порога сразу для трёх сетей с разными источниками не существует. Ответ говорит, что найдено, что проверено и что проверить не удалось. Это не сертификат соответствия, и сервис не знает внутренних правил конкретной биржи или банка. Понимайте clear как «в проверенных источниках ничего критичного», review как «посмотрите внимательнее, прежде чем продолжать», high_risk как «есть критичная находка, которую нужно разобрать», а limited_data как «определить не удалось».

Списание

Проверка кошелька расходует одну проверку из квоты, когда получено состояние: clear, review или high_risk, с полным или частичным покрытием. limited_data бесплатно, как и ошибки, тайм-ауты и повторы по идемпотентности. Это отличается от проверки транзакции, которая списывается только при полном покрытии: проверка кошелька часто даёт уверенный результат, даже если один контрагент из пятидесяти остался неатрибутированным, а платные источники уже ответили. Sandbox-ключи платные проверки не расходуют.

Бюджет времени и повторы

Холодная проверка кошелька опрашивает несколько провайдеров, и серверный бюджет на неё составляет 30 секунд; на клиенте задайте предел ожидания около 35 секунд. Если сервер ответил 504 request_timeout, повторите запрос с тем же телом и тем же Idempotency-Key: анализ на сервере продолжается до конца и попадает в общий кеш, поэтому повтор обычно отвечает сразу и содержит freshness.served_from_analysis_cache: true. Общие правила повторов действуют без изменений.

Идемпотентность между видами проверок

Ключи идемпотентности общие для организации и среды на всех методах проверки. Повторное использование ключа транзакции для тела с кошельком или ключа кошелька для другого адреса даёт 409 idempotency_conflict. Одна логическая операция, один ключ.

Примеры для сервера

import os, requests
response = requests.post("https://api.chainzap.io/v1/wallet/check", timeout=35,
    headers={"X-API-Key": os.environ["CHAINZAP_API_KEY"],
             "Idempotency-Key": os.environ["CHECK_ID"]},
    json={"address": os.environ["WALLET_ADDRESS"]})
result = response.json()
response.raise_for_status()
if result["state"] != "clear":
    print(result["state"], result["reason_codes"])

const response = await fetch("https://api.chainzap.io/v1/wallet/check", {
  method: "POST", signal: AbortSignal.timeout(35000),
  headers: {"Content-Type": "application/json", "X-API-Key": process.env.CHAINZAP_API_KEY!,
    "Idempotency-Key": process.env.CHECK_ID!},
  body: JSON.stringify({address: process.env.WALLET_ADDRESS})
});
const result = await response.json();
if (!response.ok) throw new Error(result.error.code);
if (result.state !== "clear") console.info(result.state, result.reason_codes);

Пример детерминированного ответа

Это иллюстративная фикстура, а не реальное наблюдение. Полный JSON раскрывается ниже.

{
  "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "coverage": "complete",
  "details": {
    "address_security": {
      "denylist_category": null,
      "denylisted": false,
      "issuer_blocked": false,
      "issuer_blocked_symbols": [],
      "provider_flagged": false,
      "provider_flags": []
    },
    "behaviour": {
      "contract_verified": null,
      "counterparties_count": 37,
      "first_activity_at": "2024-09-20T10:15:00Z",
      "is_contract": false,
      "last_activity_at": "2026-09-19T08:02:11Z",
      "transaction_count": 412,
      "transaction_count_limited": false,
      "wallet_age_days": 731
    },
    "counterparties": {
      "flagged": 0,
      "screened": 37,
      "unverified": 0
    },
    "coverage_scope": "supported_deep_sources",
    "data_coverage": "FULL",
    "evidence": {
      "live": true,
      "source": "live"
    },
    "freshness": {
      "analyzed_at": "2026-09-21T08:59:58Z",
      "checked_at": "2026-09-21T09:00:00Z",
      "oldest_source_age_seconds": 2,
      "served_from_analysis_cache": false
    },
    "limitations": [],
    "modules": [
      {
        "key": "sanctions_aml",
        "source_coverage": "complete",
        "status": "NO_MATCHES_FOUND"
      },
      {
        "key": "wallet_behaviour",
        "source_coverage": "complete",
        "status": "NO_MATCHES_FOUND"
      },
      {
        "key": "token_authenticity",
        "source_coverage": "complete",
        "status": "NO_MATCHES_FOUND"
      },
      {
        "key": "contract_controls",
        "source_coverage": "complete",
        "status": "NO_MATCHES_FOUND"
      },
      {
        "key": "address_security",
        "source_coverage": "complete",
        "status": "NO_MATCHES_FOUND"
      },
      {
        "key": "counterparties_services",
        "source_coverage": "complete",
        "status": "NO_MATCHES_FOUND"
      },
      {
        "key": "flows_connections",
        "source_coverage": "complete",
        "status": "NO_MATCHES_FOUND"
      }
    ],
    "overall_state": "CLEAR",
    "reasons": [
      {
        "category": "sanctions",
        "code": "NO_DIRECT_SANCTIONS_MATCH",
        "severity": "info"
      },
      {
        "category": "risk",
        "code": "AML_LOW",
        "severity": "info"
      },
      {
        "category": "address",
        "code": "NO_ADDRESS_SECURITY_FLAGS",
        "severity": "info"
      },
      {
        "category": "behaviour",
        "code": "NO_BEHAVIOUR_FLAGS",
        "severity": "info"
      }
    ],
    "sanctions": {
      "attributed": false,
      "authorities": [],
      "direct_match": false,
      "exposure_source": "aml_provider",
      "indirect_exposure": false
    },
    "schema_version": "0.1",
    "source_coverage": {
      "ofac": {
        "checked_at": "2026-09-21T09:00:00Z",
        "data_updated_at": "2026-09-20T18:00:00Z",
        "error_code": null,
        "retrieved_at": "2026-09-21T09:00:00Z",
        "scope": "sanctions_aml",
        "stale_after_seconds": 172800,
        "status": "checked"
      }
    },
    "token_authenticity": {
      "fake": 0,
      "official": 3,
      "suspicious": 0,
      "total": 3,
      "unknown": 0
    },
    "universal_clearance": false
  },
  "environment": "live",
  "network": "tron",
  "reason_codes": [
    "NO_DIRECT_SANCTIONS_MATCH",
    "AML_LOW",
    "NO_ADDRESS_SECURITY_FLAGS",
    "NO_BEHAVIOUR_FLAGS"
  ],
  "request_id": "8a7f1c2e9d3b4f5a8c6d7e9f0a1b2c3d",
  "state": "clear"
}

Сравните перевод с данными платежа

Чтобы проверить конкретный платёж, передайте получателя, контракт токена и сумму в полях expected_*. Можно передать все три поля или только нужные сравнения.

Следующие сравнения применяются после окончательного подтверждения в блокчейне. При transaction_status: PENDING integrity и каждое запрошенное сравнение имеют NOT_EVALUATED, а флаги сравнения равны null, даже если наблюдаемый перевод содержит ожидаемые значения. Окончательный MATCH подтверждает данные платежа независимо от KYT; недостаточный риск всё равно требует MANUAL_REVIEW.

Один перевод, три сравнения

Одна транзакция может содержать несколько переводов. ChainZap сначала ищет перевод, который полностью соответствует вашим условиям. Если такого нет, выбирает перевод с наибольшим числом совпадений. При равном результате выбор определяется индексом перевода.

Поля recipient_match, token_match и amount_match относятся именно к этому выбранному переводу. Если полных совпадений несколько, в ответе появляется AMBIGUOUS_TRANSFER. Невыполненный перевод, например перевод в транзакции, завершившейся ошибкой, никогда не считается совпадением: все три его поля равны null, а транзакция с ошибкой, в которой ничего не выполнилось, получает NOT_EVALUATED и никогда не LIMITED_DATA из-за отсутствующих строк переводов.

Контракт 0.3 полностью описывает сравнение в integrity: status (см. оси статусов), selected_event_ref, relevant_event_count (выполненные переводы ожидаемому получателю в ожидаемом токене) и comparisons с expected и actual значениями и result для recipient, sender, token, amount и network. Результат по сумме — EXACT, WITHIN_TOLERANCE, UNDERPAID, OVERPAID, NOT_EVALUATED или INSUFFICIENT со знаковыми delta и delta_raw.

Как сравниваются значения

Если вы передали ожидаемое значение, но данных о переводе для сравнения нет, соответствующее поле содержит null, покрытие становится частичным (partial), а среди причин появляется EXPECTED_DATA_UNAVAILABLE. Например, без количества десятичных знаков токена нельзя утверждать, что сумма не совпала. Не считайте null подтверждением совпадения.

Адреса проверяются по правилам выбранной сети и приводятся к единому виду:

В TON поле expected_recipient означает владельца кошелька, а expected_token — контракт jetton master, а не отдельный jetton wallet.

Токен сравнивается по точному адресу контракта, а не по названию или символу: одинаковый символ не доказывает, что это один и тот же токен. Сумма передаётся десятичной строкой, например "10.000001". Сервис переводит её в целые минимальные единицы токена по известным decimals и сравнивает точно, без допуска на плавающую точку. Чтобы принять небольшое расхождение, передайте amount_tolerance: абсолютную сумму в единицах токена, симметричную, по умолчанию 0. Расхождение в этих пределах даёт WITHIN_TOLERANCE и добавляет AMOUNT_WITHIN_TOLERANCE; допуск с большим числом знаков после запятой, чем у токена, даёт 422 invalid_amount_tolerance. expected_sender сравнивает адрес отправителя так же, как адрес получателя. Знаки за пределами decimals токена принимаются, если это нули: "10.0000000" равно "10" для токена с 6 decimals. Ненулевой знак за этими пределами даёт 422 invalid_expected_amount.

Пример несовпадения

Вы ожидаете "10.000001", а в выбранном переводе указано "10". Результат: amount_match=false и причина EXPECTED_AMOUNT_MISMATCH.

Для несовпадения получателя используется EXPECTED_RECIPIENT_MISMATCH, для другого контракта токена: EXPECTED_TOKEN_MISMATCH. Совпадение суммы само по себе не подтверждает совпадение получателя и токена. Перед зачислением платежа проверьте все нужные сравнения, статус транзакции и общую оценку.

Пилотный контракт

Организация, работающая по пилотному контракту для дизайн-партнёров, должна передавать все три поля в каждой проверке: проверка без expected_recipient, expected_token или expected_amount отклоняется с 422 expected_fields_required, а expected_token, отличный от официального USDT в TRON, — с 422 token_not_enabled. Отказ происходит до принятия проверки: ничего не списывается и не сохраняется, а sandbox-ключи подчиняются тем же правилам.

Контекст сети

Сравнения работают в обоих методах проверки. Если сеть платежа известна, передайте её явно: тогда API проверит ожидаемые адреса по правилам этой сети и никогда не переключится на другую. Запросы без network описаны в разделе определения сети.

Обязательства, попытки и распределения

Отдельная проверка отвечает на вопрос, платит ли одна транзакция то, что вы ожидаете. Реестр обязательств отвечает на вопрос, было ли оплачено бизнес-обязательство — выплата или причитающийся вам депозит: один раз, полностью, какими транзакциями и не предъявляется ли тот же платёж за что-то другое. Он хранит ваши инструкции, ваши попытки исполнения, платёжные события, проверенные ChainZap, и то, как они распределены, и никогда ничего из этого не переписывает.

Реестр включается на уровне развёртывания сервиса. Пока он выключен, проверка с любым полем реестра и любой метод реестра отвечают 403 ledger_not_enabled.

Модель

external_reference, attempt_reference и approval_reference — до 128 печатных символов ASCII. Не помещайте в них персональные данные.

Проверка по обязательству

Добавьте референс обязательства в обычную проверку транзакции:

{
  "tx_hash": "…",
  "network": "tron",
  "external_reference": "payout-2026-10-0001",
  "attempt_reference": "attempt-1",
  "direction": "OUTGOING",
  "workflow_type": "PAYOUT",
  "expected_recipient": "T…",
  "expected_token": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "expected_amount": "100.00"
}

Первая проверка нового референса записывает обязательство и его инструкцию (версия 1 или instruction_version, которую вы передали). В последующих проверках можно передавать только референс: транзакция сравнивается с записанной инструкцией. Ответ дополняется блоком obligation (status, expected_amount, allocated_amount, residual_amount, attempts, events, pending_events) и блоком reuse.

Если транзакция совпадает или платит правильному получателю правильный токен, но в другой сумме, её событие распределяется на обязательство. Распределяются только окончательные выполненные события; событие, ожидающее подтверждения, учитывается в pending_events и никогда не закрывает обязательство. Если несколько движений подходят одинаково (integrity_status: AMBIGUOUS), каждое связывается с обязательством как UNKNOWN, и ничего не распределяется, пока вы не укажете, какое из них было оплатой. Проверка без direction берёт записанное направление обязательства, а если его нет — выводит направление из workflow_type (PAYOUT и REFUND — исходящие, DEPOSIT и INVOICE — входящие); платёж, направление которого осталось неизвестным, никогда не получает PROCEED.

Инструкции не меняются на месте

Версия инструкции неизменяема. Передача той же версии с другими условиями отклоняется с 409 instruction_conflict; передача других условий без версии — с 409 instruction_version_required. Изменённая инструкция — это новая версия, которая записывается через POST /v1/obligations с большим instruction_version; прежние версии остаются в записях, и в проверке можно указать версию, по которой был совершён платёж. Версия, которую вы никогда не записывали, не восстанавливается: проверка отвечает integrity_status: INSUFFICIENT с INSTRUCTION_UNAVAILABLE. Платёж в блоке раньше instruction_effective_at добавляет INSTRUCTION_NOT_EFFECTIVE.

Записывайте обязательства и попытки заранее

Попытка — это ещё не исполнение. execution_confirmed становится true, только когда платёжное событие её транзакции распределено на обязательство; попытка с TIMEOUT, за которой последовал успешный повтор, оставляет две попытки и одно исполнение. Если у попыток есть amount, проверка с этим attempt_reference сравнивает транзакцию с суммой попытки, поэтому выплата, разбитая на части, сверяется по частям.

Общие платежи и повторное использование

Один платёж может погашать несколько обязательств, а одно обязательство может быть оплачено несколькими платежами.

• Несколько обязательств, один платёж. ChainZap никогда не делит платёж сам. Укажите доли через POST /v1/allocations (network, tx_hash, event_ref, allocations: [{external_reference, amount}] и необязательный owner, которым помечается любое прежнее распределение, заменяемое этим указанием). Событие появляется, только когда его с полным покрытием записала проверка, в которой указано обязательство (иначе 404 payment_event_not_found); оно должно быть выполнено и окончательно (409 payment_event_not_settled), быть в токене обязательства (409 allocation_token_mismatch), а доли не могут его превышать (409 allocation_exceeds_event). После этого проверка одной доли сравнивает эту долю, а не весь платёж, с тем, что причитается по обязательству.
• Одно обязательство, несколько платежей. Каждая проверка под тем же референсом добавляет своё событие; residual_amount уменьшается, пока обязательство не станет ALLOCATED.
• Сторнирование. POST /v1/allocations/{allocation_id}/reversal с reason (CUSTOMER_CORRECTION, DISPUTED, DUPLICATE_RECORD, OTHER) помечает распределение как сторнированное, а DISPUTED помечает его как DISPUTED. Оно остаётся в записях, и последующая проверка никогда его не восстанавливает; это может сделать только указание долей.

reuse.status сообщает, что реестру уже известно о платёжном событии:

Идемпотентный повтор (тот же Idempotency-Key и то же тело) возвращает сохранённый ответ и повторным использованием не считается.

Входящие платежи

Для депозита передайте direction: "INCOMING" и сообщите ChainZap в customer_context, что ваша система уже сделала с ним: credit_status (NOT_CREDITED, CREDITED, PARTIALLY_CREDITED, UNKNOWN) и allocation_status (NOT_ALLOCATED, PARTIALLY_ALLOCATED, ALLOCATED, UNKNOWN) — насколько ваш учёт его уже применил. ChainZap не видит ваш учёт: без NOT_CREDITED чистый депозит получает CONFIRM_INTERNAL_STATE, как и при распределении UNKNOWN, а платёж, зачисленный или применённый хотя бы частично, даёт REVIEW с ALREADY_CREDITED. К депозитам и выплатам применяются одни и те же правила обязательств, распределений и повторного использования.

Хранение

Исходные референсы, адреса и хеши транзакций хранятся 90 дней, а затем заменяются ключевыми дайджестами; владельцы удаляются. Суммы, токены, статусы и версии сохраняются, поэтому итоги остаются верными. После этого реестр по-прежнему распознаёт повторно использованный платёж и повторный референс по дайджесту, а API возвращает redacted: true там, где исходного значения уже нет. Дайджест суммы и времени блока псевдонимен, а не анонимен.

Пакетная проверка

Пакет проверяет файл платежей из 50–200 строк тем же движком, что и отдельная проверка: каждая строка получает тот же ответ, те же причины и те же последствия в реестре, что получила бы сама по себе. Сначала файл проверяется и оценивается; пока вы не подтвердите запуск, ничего не выполняется и не списывается. Пакеты используют реестр обязательств и, пока он выключен, отвечают 403 batch_not_enabled.

Загрузить, запустить и выгрузить пакет можно в кабинете разработчика на странице «Пакеты» или через API ниже. Оба способа используют один и тот же сервис и одни и те же лимиты.

Файл

CSV в UTF-8 (метка порядка байтов допускается), разделитель — запятая или точка с запятой, первая строка — заголовок. До 200 строк и 256 КиБ. Одна строка — один платёж по одному обязательству.

Распространённые названия заголовков распознаются: order_id, payout_id, invoice_id, reference для референса; txid, hash, transaction_hash для хеша; to, recipient, address, wallet для получателя; token, contract, asset, currency для токена; а также amount, tolerance, from, sender, chain, attempt, provider, status. Неизвестные колонки игнорируются и перечисляются в preflight.ignored_columns. Параметры запроса network, direction и workflow_type задают значения по умолчанию для строк, где они пусты. Шаблон можно скачать в кабинете разработчика.

Загрузка и preflight

curl --max-time 30 'https://api.chainzap.io/v1/batches?network=tron' \
  -H 'X-API-Key: YOUR_SERVER_API_KEY' -H 'Content-Type: text/csv' \
  -H 'Idempotency-Key: payouts-2026-10-05' --data-binary @payouts.csv

201 возвращает пакет в статусе PREFLIGHTED с полями:

• preflight: rows, checks, obligations_only, invalid и duplicates, а также errors и warnings с подсчётом по кодам. Строка с ошибкой пропускается (SKIPPED_INVALID), а ошибка называет поле, например invalid_tron_address или unknown_token_symbol; точный дубль строки пропускается как дубликат. Если строки задают одному референсу разные условия, первая остаётся в силе, а последующие отклоняются (conflicting_rows_for_obligation). Предупреждения строку не пропускают: tx_shared_across_references (одна транзакция под несколькими референсами без allocated_amount), declared_shared_payment, several_transactions_for_obligation и tx_seen_for_other_obligation, когда реестр уже связывает транзакцию с другим обязательством.
• estimate: верхняя граница, а не обещание. distinct_transactions, billable_checks_at_most, provider_calls_at_most, provider_usd_at_most (оценка без учёта кеша), quota_available и quota_sufficient.

Файл не в UTF-8, пустой, без заголовка или строк данных либо с некорректной строкой даёт 422 invalid_csv; заголовок без колонки external_reference или с повторяющейся колонкой — 422 invalid_csv_header; больше 200 строк — 413 batch_too_large. Idempotency-Key обозначает один файл: тот же ключ с тем же файлом возвращает тот же пакет, а с другим файлом — 409 idempotency_conflict. Организация выполняет не больше двух пакетов одновременно; запуск третьего даёт 429 batch_limit_reached (загрузка и preflight ничего не стоят и этим ограничением не затрагиваются).

Запуск

POST /v1/batches/{batch_id}/execute с {"confirm": true} ставит пакет в очередь; без confirm ответ — 422 confirmation_required. Если квоты не хватает на каждую уникальную транзакцию, ответ — 409 insufficient_quota; передайте "allow_partial": true, чтобы всё равно начать.

Строки проверяет фоновый обработчик, не быстрее половины лимита частоты вашей организации, поэтому ваш собственный трафик продолжает работать; пакеты всех организаций обрабатываются по очереди, частями. Строки одной транзакции выполняются в порядке файла. Каждая уникальная транзакция списывается один раз на пакет: после того как одна её строка дала платный ответ, последующие строки той же транзакции проверяются по своему обязательству бесплатно (отклонённая строка ничего не списывает, поэтому списывается следующая). Если заканчивается квота или дневной предел проверок без списания, пакет встаёт на паузу (PAUSED с pause_reason quota_exceeded или daily_unbilled_ceiling); запустите его снова, чтобы продолжить.

POST /v1/batches/{batch_id}/retry повторно запускает только строки RETRYABLE завершённого или приостановленного пакета, не больше пяти попыток на строку; если таких строк нет — 409 nothing_to_retry. POST /v1/batches/{batch_id}/cancel останавливает пакет.

Строка, у которой пробел только в оценке риска (недоступен KYT), получает DONE, а не RETRYABLE: смотрите её risk_retryable и risk_retry_after_seconds и при необходимости проверьте транзакцию снова с новым Idempotency-Key (см. повторы).

Результаты

• GET /v1/batches возвращает список ваших последних пакетов; GET /v1/batches/{batch_id} — один пакет с progress и, после выполнения, summary.
• GET /v1/batches/{batch_id}/rows?after=0&limit=100 постранично возвращает строки с краткими ответами (четыре статуса, recommended_action, результат сравнения суммы и разница, статус повторного использования и обязательства, коды причин, decision_id). Фильтруйте через state= или review=true.
• GET /v1/batches/{batch_id}/export.csv возвращает каждую строку с её ответом. Ячейки, которые электронная таблица прочитала бы как формулу, начинаются с ', и каждая ячейка заключена в кавычки.

summary считает строки по состоянию и по overall_state, показывает распределение по каждой оси статусов и по recommended_action, число строк с analyst_review_required, ошибки и стоимость: usd_total, usd_per_transaction и usd_per_exception (любой ответ, кроме CLEAR), а также cost_complete. obligations перечисляет открытые обязательства с тем, что распределено и что осталось.

analyst_review_required отмечает строку, которую должен посмотреть человек: рекомендация MANUAL_REVIEW или HOLD_AND_ESCALATE. Строке, ответ по которой ещё не окончательный (RECHECK_LATER), нужен повтор, а не человек.

Sandbox

Sandbox-ключи выполняют пакеты на фикстурах песочницы и расходуют её лимит; тот же файл без изменений выполняется и с боевым ключом. Исходные значения строк хранятся 90 дней, как и в реестре, а затем удаляются; счётчики, статусы и дайджесты остаются.

Юридические документы и объём услуг

Условия для бизнеса, Соглашение о пилоте, Приложение о данных и Privacy доступны по ссылкам portal. В шаблонах до учреждения юридического лица ещё нужно заполнить договорные и коммерческие поля до подписания. Начальный профиль пилота — официальный USDT/TRON.

Отдельного переключателя integrity-only нет: проверка вызывает risk layer и явно показывает недостаточное/деградированное покрытие при отсутствии необходимых risk-данных. Portal показывает краткие строки, review-флаги, известные остатки и CSV; подробные decision evidence и операции reversal/correction доступны через API. Завершённый batch является snapshot на момент решения и не пересчитывается автоматически после последующих исправлений ledger. DONE означает обработано, а не оплачено или подтверждённый клиентом исход.

Эскроу-сделки

Эскроу-сделка держит USDT в сети TRON в отдельном контракте. Деньги двигаются только по действию того, у кого есть на это право: покупатель выплачивает их продавцу, продавец возвращает их, сторона забирает их после срока, который пропустила другая, стороны в споре предлагают одинаковый раздел или спор решает арбитр, названный до внесения средств. Ваша площадка создаёт черновик и показывает сделку; покупатель и продавец подписывают условия и перемещают средства своими кошельками. ChainZap создаёт контракт после обеих подписей и следит за сроками, но не хранит ключи сторон, никогда не бывает арбитром и не может переместить деньги.

Эскроу-сделки работают в закрытом пилоте. Пока ваша организация не подключена, каждый вызов отвечает 403 escrow_not_enabled. Песочница работает в тестовой сети TRON Nile с тестовым токеном без ценности.

Два режима

Спор возможен в любой сделке. Выбирается только одно: может ли его решить ещё и арбитр.

Начинайте без арбитра: этот режим подходит для поставок с объективной проверкой, а завершить спор стороны всегда могут сами.

Что позволяет контракт

• Каждая сделка — отдельный контракт, который создаёт неизменяемая фабрика: без владельца, обновлений, паузы и административного ключа.
• Деньги двигаются только по действию самой стороны или по решению арбитра в его окно:
  • покупатель выплачивает (release), а продавец возвращает средства (refund) в любой момент после оплаты до завершения сделки, в том числе во время спора;
  • покупатель забирает средства обратно (claimRefund), если срок поставки прошёл, а поставка не отмечена; продавец забирает оплату (claimRelease), если срок проверки прошёл без приёмки и без спора;
  • в споре сделка завершается, как только предложения сторон совпадут (proposeSettlement), или решением арбитра (resolve).
• Никакой срок не решает спор, и сам по себе срок ничего не перемещает: он лишь открывает одной из сторон право потребовать деньги.
• Любой, в том числе ChainZap, может только подтвердить оплату (confirmFunding), закрыть неоплаченную сделку после срока (expire), перевести уже начисленное его постоянному получателю (withdraw) и зачислить покупателю лишние токены (sweepExcess). Всё это работает напрямую в контракте, без ChainZap.
• Выплаты уходят только покупателю, продавцу, получателю комиссии, зафиксированному в фабрике, и после решения — названному арбитру.

Жизненный цикл

status — состояние черновика вне сети (DRAFT, AGREED, CREATING, ON_CHAIN, CANCELLED, AGREEMENT_EXPIRED, CREATION_BLOCKED); после создания контракта state — его собственное состояние (AWAITING_FUNDS, FUNDED, DELIVERED, DISPUTED, RELEASED, REFUNDED, SPLIT, EXPIRED). Тупик — не состояние контракта: это спор, который уже не может решить ни один арбитр; API сообщает его как settlement.deadlocked. Источник истины — сеть: API сообщает то, что прочитал из подтверждённых (solidified) блоков, и ставит contract.out_of_sync, если не может подтвердить последнее состояние.

Оплата

Оплата — обычный перевод токена сделки на адрес эскроу, без разрешения (allowance) и без transferFrom. Когда на эскроу есть хотя бы сумма сделки, кто угодно может вызвать confirmFunding до срока оплаты; ChainZap делает это, как только увидит баланс. До этого funding показывает, сколько эскроу уже получил (received) и сколько не хватает (remaining), по последнему чтению из сети.

• Меньше суммы. Сделка остаётся в AWAITING_FUNDS; отправьте недостающее до срока оплаты. confirmFunding не принимает эскроу, на котором меньше суммы.
• Больше суммы или второй перевод. После оплаты излишек зачисляется покупателю (sweepExcess, событие escrow_deal.excess_credited) и выводится как любая выплата. Он не блокируется в сделке и никогда не уходит ChainZap.
• Слишком поздно. После срока оплаты сделку можно только закрыть (expire, состояние EXPIRED); всё, что на неё пришло, зачисляется покупателю и выводится.
• С другого адреса. Учитывается только баланс эскроу, поэтому перевод с любого адреса оплачивает сделку, а возврат и излишек уходят на адрес покупателя из условий, а не отправителю.

Страница сделки отправляет ровно недостающую сумму на эскроу, прочитанный из фабрики, и отказывается от любого другого получателя, токена или суммы.

Сроки и права требования

Сроки считаются по времени блоков. Действие принимается только до своего срока, требование — только начиная с него, поэтому они не пересекаются. Требование не срабатывает само: пока сторона его не предъявила, другая сторона ещё может действовать; например, покупатель может выплатить и после срока поставки. timeline.if_nobody_acts в каждом ответе говорит, что открывает текущий срок: at, outcome (EXPIRED, REFUNDED, RELEASED или DEADLOCK) и claim_by (BUYER, SELLER, ANYONE или null, если ничего не открывается).

В боевой среде у покупателя на проверку не меньше 72 часов (иначе 422 inspection_period_below_policy). Молчание покупателя позволяет продавцу забрать оплату, поэтому ChainZap напоминает покупателю в Telegram сразу после поставки, на середине срока проверки, за 12 часов и за 1 час до его конца; продавцу — за 24 и за 2 часа до срока поставки, и каждой стороне — когда у неё открывается право требования.

Спор, предложения и тупик

Покупатель может открыть спор (dispute с хешем материалов) только в срок проверки. С этого момента продавец не может забрать оплату, и никакой срок исход не решает.

• Предложения. Каждая сторона предлагает buyer_amount — сколько из суммы получает обратно покупатель: 0 отдаёт всё продавцу (за вычетом комиссии), полная сумма возвращает всё покупателю, промежуточное значение — раздел. Любая сторона может изменить своё предложение в любой момент; сделка завершается, как только они совпадут (settlement_reason: MUTUAL_SETTLEMENT, событие escrow_deal.settlement_proposed на каждое предложение). Текущие предложения — в settlement.buyer_proposal и settlement.seller_proposal.
• Арбитр. В сделке, где он назван, арбитр может вынести решение в течение resolve_period после открытия спора (timeline.resolve_deadline): resolve(buyer_amount, ruling_hash), только по подписанным критериям. Его вознаграждение берётся сверху, а решение — это сумма, которую покупатель получает из остатка (settlement_reason: RESOLVER).
• Тупик. Без арбитра или после окончания его окна спор без совпавших предложений — тупик (settlement.deadlocked: true). Средства остаются в контракте, пока обе стороны не предложат одинаковый раздел, покупатель не выплатит или продавец не вернёт деньги. Ни срок, ни ChainZap завершить его не могут.

Деньги

Комиссия сервиса — фиксированная сумма, которая определяется при создании черновика (fee_bps от суммы по политике вашего пилота) и берётся только из выплаты продавцу:

• выплата или требование продавца: продавец получает сумму за вычетом комиссии;
• раздел: комиссия уменьшается пропорционально части продавца;
• возврат, требование покупателя или истечение срока оплаты: комиссии нет.

Вознаграждение арбитра фиксируется в условиях и выплачивается, только если арбитр решит спор. Пример: сумма 100, вознаграждение 5, решение «покупателю 40»: покупатель получает 40, арбитр — 5, продавец — 55 за вычетом комиссии сервиса с этих 55. Совпавшие предложения, выплата и возврат арбитру ничего не платят.

balances разделяет начисленное контрактом (accrued), ещё не выведенное (claimable) и уже ушедшее из контракта (withdrawn) — для buyer, seller, fee и resolver. Каждая сторона оплачивает комиссию сети за свои транзакции в TRX; ChainZap оплачивает подтверждение оплаты, закрытие неоплаченных сделок, зачисление излишка и отправку выплат.

Создание черновика

curl --max-time 15 https://api.chainzap.io/v1/escrow-deals \
  -H 'X-API-Key: YOUR_SERVER_API_KEY' -H 'Content-Type: application/json' \
  -d '{
    "external_reference": "order-2026-10-0042",
    "buyer": "TAHXBmAAswvxo1fx7NzQeJe234766SHwG5",
    "seller": "TTogA7AhPuChVpzUEePBhPyFi8VsStSAmn",
    "amount": "1250.50",
    "category": "DIGITAL_GOODS",
    "title": "Annual licence key",
    "delivery": {
      "criteria": ["The key activates on the vendor site", "The licence covers 12 months"],
      "method": "Key sent through the order chat",
      "evidence_required": ["Screenshot of the activation page"]
    },
    "timeline": {
      "delivery_period_seconds": 259200,
      "inspection_period_seconds": 259200
    }
  }'

Этот черновик — без арбитра. Чтобы назвать арбитра, добавьте "resolver_enabled": true, самого арбитра ("resolver_id" или арбитр по умолчанию из политики), его вознаграждение в единицах токена и окно после открытия спора:

{
  "resolver_enabled": true,
  "resolver_id": "0192f0c4-6f1e-7a3b-9c2d-4e5f60718293",
  "resolver_fee": "12.50",
  "timeline": {
    "delivery_period_seconds": 259200,
    "inspection_period_seconds": 259200,
    "resolve_period_seconds": 259200
  }
}

Сделка с арбитром без этих настроек отвечает 422 resolver_settings_required; сделка без арбитра с любой из них — 422 resolver_settings_without_resolver. Вознаграждение арбитра не может превышать долю от суммы, которую допускает ваша политика (422 invalid_resolver_fee).

Тот же external_reference с тем же телом возвращает тот же черновик (replayed: true); с другим телом — 409 escrow_reference_conflict. Найти черновик позже можно через POST /v1/escrow-deals/lookup. Критерии поставки — от двух до пяти объективных проверок: спор ведётся только по этим строкам. Категории ограничены цифровыми поставками с объективной проверкой приёмки и включаются политикой пилота.

POST /v1/escrow-deals/{ref}/versions заменяет условия черновика (передайте expected_version); подписи под прежней версией перестают учитываться. POST /v1/escrow-deals/{ref}/cancel закрывает черновик. После подписи обеих сторон ни то ни другое невозможно.

Арбитры

Арбитр необязателен. Сделка, где он есть, называет внешнего арбитра, которого зарегистрировала ваша площадка. Арбитр никогда не ChainZap: его адрес и все ключи его аккаунта TRON не могут быть адресом или ключом ChainZap, а также ключом покупателя или продавца сделки.

curl --max-time 15 https://api.chainzap.io/v1/escrow-deals/resolvers \
  -H 'X-API-Key: YOUR_SERVER_API_KEY' -H 'Content-Type: application/json' \
  -d '{
    "address": "TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC",
    "name": "Example dispute service",
    "affiliation": "INDEPENDENT",
    "rules_version": "dispute-rules/2026-10",
    "rules_sha256": "5f0c…64 hex characters"
  }'

affiliation — PLATFORM (работает от вашей площадки) или INDEPENDENT; стороны видят это и то, что арбитра зарегистрировала ваша площадка. В боевой среде аккаунт читается в сети: он должен подписывать решения одним ключом (SINGLE_KEY) или двумя из трёх ключей, чья active permission может только вызывать контракты (MULTISIG_2_OF_3); всё прочее отклоняется (resolver_scheme_unsupported, resolver_account_not_activated). В песочнице чтение — по возможности; арбитр, который не может подписать, остаётся зарегистрированным, но с eligible: false.

GET /v1/escrow-deals/resolvers показывает ваших арбитров и общих; у каждого — key_scheme, signatures_required, eligible и ineligible_reason. POST …/resolvers/{id}/verify читает аккаунт заново. POST …/resolvers/{id}/disable запрещает новые сделки с ним (сделки, где он уже назван, сохраняют его); …/enable разрешает снова, в боевой среде — после нового чтения. Регистрацию нельзя изменить: данные арбитра входят в условия, которые подписывают обе стороны, поэтому другой арбитр — новая регистрация. Вознаграждение в регистрацию не входит: его задаёт каждая сделка. Не больше 20 активных арбитров на сеть (и 100 регистраций всего); арбитр другой организации отвечает 404 resolver_not_found. То же самое делает вкладка эскроу в кабинете разработчика.

Согласие

Отправьте сторонам ссылку на сделку из links. На странице сделки каждая сторона входит кошельком, указанным в сделке, видит все условия и подписывает один текст в TronLink (signMessageV2). Страница заново вычисляет хеш условий, идентификатор сделки и текст по показанным условиям и не предлагает подпись, если что-то не совпадает. Каждую транзакцию, которую она предлагает дальше, страница сверяет с теми же условиями: адрес эскроу читается из реестра фабрики, перевод уходит только на этот эскроу и только на недостающую сумму, вывод — только на адрес вошедшей стороны.

Чтобы собирать подписи в своём интерфейсе, прочитайте GET /v1/escrow-deals/{ref}/consent: message — точный текст, params — параметры контракта, terms — документ (chainzap.escrow.terms/2), хеш канонического JSON которого равен terms_hash. Передайте подпись через POST /v1/escrow-deals/{ref}/consents (version, role, signature). Сторона, чьим аккаунтом управляют другие ключи (мультиподпись через permissions), подтверждает условия транзакцией (approveTerms в actions).

Обе подписи проверяются дважды: API и фабрикой, которая перед созданием контракта сама формирует тот же текст. Текст называет арбитра или Resolver: none и говорит, что означают молчание и спор. Вот его строки для сделки с арбитром, а затем без него:

Resolver: TJRyWwFs9wTFGZg3JbrVriFbNfCug5tDeC
Resolver fee: 12.500000 USDT, paid from the escrow only if the resolver decides a dispute
Resolver period after dispute: 3d 00h 00m
If delivery is not marked in time: the buyer can claim a refund
If the buyer neither accepts nor disputes during inspection: the seller can claim payment
In a dispute: no automatic outcome; it settles when buyer and seller propose the same split, or by the resolver within its period; otherwise the funds stay locked

Resolver: none
If delivery is not marked in time: the buyer can claim a refund
If the buyer neither accepts nor disputes during inspection: the seller can claim payment
In a dispute: no automatic outcome; it settles when buyer and seller propose the same split; otherwise the funds stay locked

Транзакции сторон

GET /v1/escrow-deals/{ref}/actions?role=BUYER показывает, что эта сторона может подписать сейчас. У каждого действия есть контракт, функция, параметры в кодировке ABI, лимит комиссии и оценка энергии:

Действия, доступные кому угодно, показываются у каждой роли, пока они открыты. Если транзакции собирает ваш интерфейс, сделайте те же проверки до подписи: эскроу — это escrowOf(deal_id) фабрики, указанной в подписанных условиях, а токен — токен этой фабрики. После отправки транзакции сообщите о ней через POST /v1/escrow-deals/{ref}/transactions; она учитывается только после подтверждения сетью, а само сообщение сделку не меняет. Сообщение принимается, только пока у сделки может быть такая транзакция (409 action_not_available), и не больше пяти ожидающих на сторону (429 too_many_pending_transactions); подтверждённая транзакция, которая не является этим вызовом от этой стороны, отбрасывается.

Telegram

links.telegram_invite — ссылка t.me на бота ChainZap для этой сделки; отправьте её сторонам рядом со ссылкой на сделку. Бот не называет деталей сделки: он открывает страницу сделки в браузере, где делаются все подписи и платежи, и статус сделки в Mini App Telegram. Экран статуса показывает только сделки, которые сторона привязала из личного чата после входа кошельком; из Telegram ничего подписать или отправить нельзя. Веб и Telegram показывают одну и ту же сделку с одним id.

Материалы

POST /v1/escrow-deals/{ref}/evidence добавляет текстовую заметку, PUT /v1/escrow-deals/{ref}/evidence/files?purpose=DELIVERY&file_name=log.pdf — файл (PDF, PNG, JPEG, WebP или текст, до 10 МиБ). Ваши материалы помечаются как переданные площадкой: они показывают отправителя, а не факт поставки. У каждого материала сохраняются SHA-256, автор и время; замена — это новый материал. Когда сторона отмечает поставку или открывает спор, хеш её набора материалов записывается в сеть. Содержимое файлов удаляется после срока хранения; хеши остаются.

GET /v1/escrow-deals/{ref}/dispute возвращает критерии, материалы обеих сторон и сроки спора.

События и вебхуки

Каждое изменение становится событием: escrow_deal.created, terms_updated, consent_received, agreed, cancelled, agreement_expired, creation_blocked, contract_created, funded, delivered, disputed, settlement_proposed, settled, excess_credited, payout_withdrawn и evidence_added. Напоминания о сроках уходят сторонам в Telegram, а не на вебхук.

Задайте один адрес на среду через PUT /v1/escrow-deals/webhook ({"url": "https://..."}); ответ один раз показывает секрет подписи. Адрес должен быть HTTPS на порту 443 с публичным IP; перенаправления не выполняются. Каждая доставка — POST с заголовками:

import hashlib, hmac, time

def verify(secret: str, headers: dict, body: bytes) -> bool:
    timestamp = int(headers["X-ChainZap-Timestamp"])
    if abs(time.time() - timestamp) > 300:
        return False
    message = f"{timestamp}.{headers['X-ChainZap-Delivery-Id']}.".encode() + body
    expected = "v1=" + hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, headers["X-ChainZap-Signature"])

Ответьте 2xx в течение 10 секунд. Неудачные доставки повторяются с растущими паузами (от 30 секунд до 12 часов, 12 попыток). Доставка — не реже одного раза и не по порядку: удаляйте повторы по X-ChainZap-Event-Id и упорядочивайте по sequence. GET /v1/escrow-deals/events?after=<sequence> — полная лента, чтобы догнать события после простоя; POST /v1/escrow-deals/events/{event_id}/redeliver отправляет событие ещё раз, POST /v1/escrow-deals/webhook/test — подписанный escrow.ping, POST /v1/escrow-deals/webhook/rotate-secret меняет секрет, DELETE /v1/escrow-deals/webhook останавливает доставки.

Что изменилось в протоколе v2

Новые сделки используют вторую версию контракта и условий. Если вы интегрировались с первой версией пилота:

• Запрос черновика. dispute_enabled заменён на resolver_enabled: спор возможен в любой сделке, необязателен только арбитр. С арбитром передавайте resolver_id, resolver_fee и timeline.resolve_period_seconds. timeline.response_period_seconds и timeout_outcome удалены: окна ответа продавца и исхода спора по сроку больше нет.
• Ответ со сделкой. Новое: protocol_version, resolver.fee, timeline.resolve_deadline, settlement (предложения и deadlocked, пока идёт спор), funding (пока сделка ждёт оплаты) и resolver в balances.accrued, claimable и withdrawn. timeline.if_nobody_acts теперь {at, outcome, claim_by}. Удалены: dispute_enabled, timeline.response_period_seconds, timeline.seller_response_deadline и timeline.seller_responded. settlement_reason может быть MUTUAL_SETTLEMENT; TIMEOUT_NO_RULING встречается только у архивных сделок.
• Оплата и сроки. Оплата — прямой перевод и confirmFunding вместо разрешения и fund. После срока поставки или проверки деньги забирает покупатель или продавец; ничего не завершается по таймауту.
• Действия. Новые: TRANSFER_FUNDS, CONFIRM_FUNDING, CLAIM_REFUND, CLAIM_RELEASE, PROPOSE_SETTLEMENT, EXPIRE и SWEEP_EXCESS. Удалены: APPROVE_TOKEN, FUND, RESPOND, PROCESS_TIMEOUT и CREDIT_EXCESS.
• События. Новые: escrow_deal.settlement_proposed и escrow_deal.excess_credited. Удалено: escrow_deal.seller_responded.
• Условия. chainzap.escrow.terms/2 добавляет rules: "chainzap.escrow.rules/2" и resolver.fee и убирает timeout_outcome и timeline.response_period.
• Ошибки. Новые: resolver_settings_required, resolver_settings_without_resolver, invalid_resolver_fee и invalid_buyer_amount. Удалены: invalid_simple_deal, dispute_settings_required, dispute_settings_without_disputes, disputes_disabled и invalid_timeout_outcome.

Сделки, созданные до второй версии, сохраняют protocol_version: 1. Они в архиве: API и страница сделки показывают их только для чтения по записи ChainZap, и с ними ничего не делается.

Ошибки

Все ошибки в общем формате. Запросы к эскроу ограничены 16 КиБ JSON, файл материалов — 10 МиБ.

Песочница

Sandbox-ключи работают в тестовой сети TRON Nile с тестовым токеном «ChainZap TEST USD (NO VALUE)». Сценарий, страницы и вебхуки такие же, как в боевой среде, а политика песочницы может разрешать более короткий срок проверки, чтобы быстрее пройти сценарий; реальные средства задействовать невозможно. Боевые сделки используют USDT в основной сети TRON только для организаций пилота, со списком допущенных участников и лимитами на сделку и в сумме.

GET /v1/usage

Запрос

curl --include --max-time 15 'https://api.chainzap.io/v1/usage?days=30' \
  -H 'X-API-Key: cz_live_000000000000.fictional_example_only' \
  -H 'X-Request-ID: merchant-usage-1001'

days — целое число от 1 до 90, по умолчанию 30. Ключ идемпотентности для этого чтения не нужен. Читайте заголовок ответа X-Request-ID. Запрос статистики учитывается в лимите частоты запросов, но не расходует проверки. Повторяйте только ошибки с пометкой retryable и учитывайте Retry-After.

Квота текущего периода

period.start и period.end обозначают границы текущего расчётного периода: оплаченного периода, привязанного к подтверждённой оплате, либо календарного месяца по UTC для организации без оплаченного плана.

Резерв освобождается, когда запрос завершается без списания. balances добавляет дополнительные проверки и общий доступный остаток, subscription описывает оплаченный период (status: "legacy" при plan: null означает, что лимиты организации установлены по договорённости, например по пилотному контракту, а не самостоятельно выбранным планом, и действуют именно показанные лимиты); см. планы и оплату. environment равен live или sandbox в зависимости от ключа. Все API-ключи организации и запросы из кабинета разработчика используют одну квоту.

Статистика за выбранное окно

recent считает завершённые логические проверки за скользящее окно в days дней. Повторная выдача сохранённого ответа не создаёт новую запись о проверке. Статистика включает число списанных проверок, ошибок и результатов LIMITED_DATA, среднее время ответа, сети и распределение по общей оценке. Хеши транзакций и данные провайдеров в неё не входят.

Кабинет разработчика дополнительно показывает данные по дням UTC, счётчики за 1/7/30 дней и p50/p95, если за последние 30 дней накопилось не менее 20 завершённых измерений. В число успешных ответов входят и ответы с частичным покрытием: это часть общего числа, а не отдельная прибавка к нему.

График сравнивает завершённые запросы и списанные проверки за 7, 30 или 90 дней. Наведите указатель, коснитесь графика или выберите день ползунком — он также работает со стрелками на клавиатуре. Дни без проверок показаны нулями; первый и последний дни по UTC могут быть неполными. Live и Sandbox отображаются отдельно. Под графиками можно раскрыть таблицу по дням. Полоса лимита показывает включённые проверки текущего расчётного периода; дополнительные пакеты находятся в разделе «Тариф и оплата».

Кабинет разработчика и планы

После входа в кабинет разработчика откройте /dashboard/usage/: здесь находятся счётчики квоты, таблицы по дням, распределение результатов и время ответа. В /dashboard/plan/ показаны текущий план, месячная квота, запросы в минуту и лимит одновременных запросов. Сети, разрешённые планом, показаны отдельно от сетей, включённых для проверок сейчас; включённый флаг не означает проверку работоспособности провайдеров в реальном времени.

На странице «Тестовый запрос» можно выбрать автоматическое определение сети либо явно указать TRON, Ethereum или TON из доступных сетей. Такие проверки используют ту же квоту организации и те же правила идемпотентности, что и серверный API.

Планы и пакеты дополнительных проверок покупаются на странице «Тариф и оплата»; см. планы и оплату. Продление ручное: автоматических списаний, счетов и кошелька API нет. Пользовательские подписки Mini App не дают квоту B2B API. Публичная документация доступна без входа.

Планы, проверки и оплата (бета)

За что списывается

Проверка — это одна проверка транзакции через API. Оплачивается только полная и окончательная проверка: ответ с coverage: complete и состоянием CLEAR, REVIEW или HIGH_RISK по транзакции, которая подтверждена по правилам окончательного подтверждения или окончательно завершилась ошибкой. Рискованный результат — тоже полезный результат, и он списывается. Транзакция, ожидающая подтверждения, ненайденная транзакция, LIMITED_DATA, ошибки передачи, таймауты, ошибки квоты и повторная выдача сохранённого ответа не списываются ни на одном из эндпоинтов; их резерв освобождается. Успешный HTTP-ответ не равен списанной проверке.

Бета-планы (ценовая политика BETA_PRICING_V0)

План даёт организации определённое число включённых проверок на расчётный период.

Цены указаны в долларах США. GET /v1/catalog публикует их в целых минимальных единицах (центах). Это предварительные условия беты, они могут измениться для будущих расчётных периодов; уже оплаченный заказ или период сохраняет условия, на которых был продан. Лимиты частоты запросов и параллельности предварительные до общего запуска. Scale согласуется индивидуально и онлайн не продаётся.

curl --max-time 15 https://api.chainzap.io/v1/catalog \
  -H 'X-API-Key: cz_live_000000000000.fictional_example_only'

Расчётные периоды и продление

Оплаченный расчётный период начинается с подтверждения оплаты на сервере и длится один календарный месяц (31 января → 28 или 29 февраля; затем дата возвращается к исходному числу). Продление ручное: автоматических списаний нет. Досрочная оплата планирует следующий период с момента окончания текущего; оплата после перерыва начинает новый период сразу. Другой план применяется со следующего расчётного периода; текущий оплаченный период не обнуляется. Включённые проверки не переносятся.

Пакеты дополнительных проверок

Пакет дополнительных проверок добавляет проверки сверх включённых. Пакет содержит от 100 до 10 000 проверок с шагом 50 и стоит по цене дополнительной проверки вашего текущего плана. Дополнительные проверки действуют 12 месяцев с покупки, расходуются только после включённых и доступны только при активном оплаченном плане. При неактивном плане они заморожены, а не сгорают. Цена фиксируется при покупке и не пересчитывается при изменении каталога.

Оплата

Покупки оформляются в кабинете разработчика участниками с ролями owner, admin и billing, но никогда по API-ключу. Оплата — в криптовалюте. Проверьте итоговую сумму и нажмите «Оплатить криптовалютой»: откроется страница оплаты, где нужно оплатить точную сумму в USDT или другой предложенной там монете. Сумма зафиксирована в долларах США, а страница принимает оплату в течение срока действия заказа, не меньше 15 минут. Если вы ушли со страницы, заказ на странице «Тариф и оплата» вернёт к оплате или позволит его отменить. Проверки начисляются только после того, как сервер сам подтвердит оплату у платёжного провайдера: ответ кошелька, скриншот или возврат на страницу кабинета ничего не начисляют. Страницу оплаты нельзя отозвать, поэтому деньги, отправленные после отмены или истечения заказа, всё равно зачисляются, если их можно применить, а иначе разбираются поддержкой. Повторный или неполный платёж фиксируется и разбирается поддержкой; дважды он не начисляется.

Остаток в API

curl --max-time 15 'https://api.chainzap.io/v1/usage?days=7' \
  -H 'X-API-Key: cz_live_000000000000.fictional_example_only' | jq '.balances, .subscription'

period.remaining сохраняет смысл: это оставшиеся включённые проверки текущего расчётного периода. balances.extra показывает дополнительные проверки, balances.total_available — всё, что доступно новой проверке, balances.included.reserved — ещё выполняющиеся проверки. subscription сообщает расчётный период, план и ручное продление. Заголовок X-Quota-Available передаёт общий остаток в ответах проверки. Остаток не отменяет приостановку организации, невключённую сеть или неактивный план: когда доступных проверок нет, возвращается 429 quota_exceeded.

Возвраты и споры

Возвраты рассматриваются поддержкой индивидуально и фиксируются отдельными событиями: неизрасходованный остаток начисления сторнируется, уже использованные проверки не отзываются, доступный остаток никогда не становится отрицательным.

Sandbox

Sandbox-ключи начинаются с cz_test_. Они создаются в кабинете разработчика или оператором вашей организации. Такие ключи обращаются к тем же методам с теми же схемами запроса и ответа, но никогда не вызывают провайдеров данных, ничего не стоят и не затрагивают платные проверки. Каждый успешный ответ sandbox содержит environment: "sandbox", как и каждая ошибка, которую возвращает сама проверка (например provider_unavailable, network_not_enabled, квота и лимиты частоты): ориентируйтесь на это поле. У отказа до начала проверки (401, 403 tenant_suspended, 503 api_disabled, лимит 429 по IP, действующий до чтения ключа, 413, 415, ошибка валидации запроса 422, invalid_idempotency_key) поля environment нет, а у неожиданных 500 и 504 его может не быть; там среду определяет ключ, который вы отправили. POST /v1/check и проверка кошелька дополнительно содержат details.evidence.source: "sandbox"; у POST /v1/transaction/check блока details нет, а его элементы доказательств называют те же роли источников, что и боевой ответ, поэтому ориентируйтесь на environment. Считайте такой результат фикстурой, а не наблюдением. Каждая фикстура объясняет себя теми же reason_codes, что и боевой движок, поэтому ветки, написанные под sandbox, — это те же ветки, что сработают в продакшене.

Детерминированные исходы

Первый символ хеша транзакции задаёт исход, чтобы можно было намеренно проверить каждое состояние:

Песочница подменяет только то, что вернул бы провайдер. Сравнение с вашими ожидаемыми значениями, оси статусов, элементы доказательств и причины формирует боевой движок, поэтому ответ sandbox имеет ту же форму и подчиняется тем же правилам, что и боевой, включая поля контракта 0.3. Когда реестр обязательств включён, проверки, обязательства и пакеты в sandbox записываются в отдельный реестр песочницы, изолированный от боевого.

curl --max-time 15 https://api.chainzap.io/v1/check \
  -H 'X-API-Key: cz_test_000000000000.fictional_example_only' \
  -H 'Idempotency-Key: sandbox-demo-1' -H 'Content-Type: application/json' \
  --data '{"tx_hash":"8111111111111111111111111111111111111111111111111111111111111111"}'

Без network песочница отвечает для TRON, если TRON включён для вашей организации, а иначе — для первой доступной вам сети. Как и при боевом определении сети, форма хеша (0x, base64) никогда не выбирает сеть. Чтобы узнать, включена ли сеть, укажите network явно: песочница ответит 403 network_not_enabled так же, как боевая среда. Для base64-хешей TON используются старшие четыре бита первого байта.

Лимит и изоляция

Песочница расходует лимит ровно на то, за что списывается боевая проверка, — на полный окончательный результат. Результат по транзакции, ожидающей подтверждения, частичный результат, ненайденная транзакция и фикстура сбоя не стоят ничего, как и в продакшене; фикстура неуспешной транзакции (d) окончательна и списывается, как и боевая неуспешная транзакция. Если ваша организация работает по пилотному контракту, sandbox-ключи получают те же отказы, что и боевые (expected_fields_required, token_not_enabled, check_kind_not_enabled). Поля expected_recipient, expected_token и expected_amount сравниваются с фикстурой, и несовпадение никогда не даёт CLEAR, поэтому ветка, которую вы протестировали, — это ветка, которая сработает в бою; ненулевой знак за пределами decimals токена даёт 422 invalid_expected_amount, как и в боевой среде. Проверки sandbox расходуют отдельный лимит в 50 тестовых проверок за календарный месяц UTC; GET /v1/usage с sandbox-ключом показывает этот лимит с environment: "sandbox". Ключи идемпотентности, квота и статистика раздельны по средам: один и тот же Idempotency-Key в sandbox и в среде live — две разные операции. Sandbox-ключ не может ничего купить и не подтверждает, что live-сеть включена для вашей организации.

Фикстуры для кошельков

Для POST /v1/wallet/check песочница выбирает исход по хешу нормализованного адреса, поэтому первым символом им управлять нельзя. Используйте один из закреплённых адресов ниже; каждая строка стабильна между выпусками и проверяется тестами.

Каждая фикстура кошелька содержит environment: "sandbox" и details.evidence.source: "sandbox", объясняет себя теми же кодами причин, что и боевой движок, и расходует лимит песочницы ровно так же, как боевая проверка кошелька расходует квоту: когда получено состояние.

Примеры интеграции

Примеры повторов и ответов ниже относятся к каноническому методу контракта 0.3 POST /v1/transaction/check с явно указанной сетью. Короткий запрос /v1/check и его краткий ответ описаны в разделе проверки по одному хешу. Правила повторов и квоты общие для обоих методов.

Успешный HTTP-ответ требует отдельных проверок: verification_final с integrity_status — для сравнения платежа; risk_status, risk_final и recommended_action — для риска и действия. Pending никогда не означает MATCH; окончательный MATCH с недостаточным KYT требует MANUAL_REVIEW. Повтор риска использует risk_retryable и risk_retry_after_seconds, а не verification retryable. См. оси статусов.

Python: идемпотентный повтор

Этот серверный пример использует httpx. Ключ вымышленный. В рабочей интеграции загружайте API-ключ из хранилища секретов сервера, а operation_key и body сохраняйте в своём журнале операций до первой попытки. После перезапуска процесса используйте оба значения повторно.

import random
import time
import httpx

api_key = "cz_live_000000000000.fictional_example_only"
operation_key = "merchant-order-1001-check-1"
body = {
    "network": "tron", "tx_hash": "a" * 64,
    "expected_recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
    "expected_token": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "expected_amount": "1250.000001",
}


def check():
    with httpx.Client(timeout=15, follow_redirects=False) as client:
        for attempt in range(4):
            try:
                response = client.post(
                    "https://api.chainzap.io/v1/transaction/check",
                    headers={
                        "X-API-Key": api_key,
                        "Idempotency-Key": operation_key,
                        "X-Request-ID": f"order-1001-attempt-{attempt + 1}",
                    },
                    json=body,
                )
            except httpx.TransportError:
                if attempt == 3:
                    raise RuntimeError("unresolved_transport_outcome") from None
                time.sleep(2 ** attempt + random.uniform(0, 1))
                continue
            print("X-Request-ID:", response.headers.get("X-Request-ID"))
            try:
                result = response.json()
            except ValueError:
                raise RuntimeError("unresolved_gateway_response") from None
            if response.is_success:
                return result
            error = result.get("error", {})
            if error.get("retryable") is not True:
                raise RuntimeError(error.get("code", "unresolved_response"))
            if response.headers.get("Idempotent-Replayed") == "true":
                raise RuntimeError("stored_error_requires_reconciliation")
            try:
                instructed = int(response.headers.get("Retry-After", "0"))
            except ValueError:
                raise RuntimeError("invalid_retry_after") from None
            delay = max(instructed, 2 ** attempt) + random.uniform(0, 1)
            if attempt == 3 or delay > 30:
                raise RuntimeError("schedule_retry_with_same_operation_key")
            time.sleep(delay)

Цикл обрабатывает ответы 409/429/503/504 с разрешённым повтором и неизвестный исход сетевой ошибки, не создавая новую логическую операцию. Обрабатывайте возвращённые бизнес-состояния по правилам своего платёжного процесса. Не записывайте в лог body или полный ответ.

JavaScript / TypeScript: запрос с сервера

Используйте этот код на сервере и никогда — в браузере с live-ключом. Сохраните ключ операции и тело до вызова функции, как в примере Python.

type PublicResult = {
  request_id?: string;
  error?: { code: string; message: string; retryable: boolean };
  [field: string]: unknown;
};

const apiKey = "cz_live_000000000000.fictional_example_only";
const operationKey = "merchant-order-1001-check-1";
const body = {
  network: "tron", tx_hash: "a".repeat(64),
  expected_recipient: "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  expected_token: "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  expected_amount: "1250.000001",
};
const wait = (ms: number) => new Promise(resolve => setTimeout(resolve, ms));

async function check(): Promise<PublicResult> {
  for (let attempt = 0; attempt < 4; attempt++) {
    let response: Response;
    try {
      response = await fetch("https://api.chainzap.io/v1/transaction/check", {
        method: "POST", redirect: "error", signal: AbortSignal.timeout(15000),
        headers: {
          "Content-Type": "application/json", "X-API-Key": apiKey,
          "Idempotency-Key": operationKey,
          "X-Request-ID": `order-1001-attempt-${attempt + 1}`,
        },
        body: JSON.stringify(body),
      });
    } catch {
      if (attempt === 3) throw new Error("unresolved_transport_outcome");
      await wait((2 ** attempt + Math.random()) * 1000);
      continue;
    }
    console.info("X-Request-ID:", response.headers.get("X-Request-ID"));
    const result = await response.json() as PublicResult;
    if (response.ok) return result;
    if (result.error?.retryable !== true) {
      throw new Error(result.error?.code ?? "unresolved_response");
    }
    if (response.headers.get("Idempotent-Replayed") === "true") {
      throw new Error("stored_error_requires_reconciliation");
    }
    const instructed = Number(response.headers.get("Retry-After") ?? "0");
    if (!Number.isFinite(instructed) || instructed < 0) {
      throw new Error("invalid_retry_after");
    }
    const delay = Math.max(instructed, 2 ** attempt) + Math.random();
    if (attempt === 3 || delay > 30) {
      throw new Error("schedule_retry_with_same_operation_key");
    }
    await wait(delay * 1000);
  }
  throw new Error("retry_budget_exhausted");
}

Сценарии ответов

Ниже приведены синтетические фикстуры, которые показывают допустимую структуру ответа, а не реальные проверки. У каждого примера заголовок X-Request-ID равен полю request_id. Проверяйте не только общую оценку, но и значения null и покрытие.

Транзакция подтверждена

{
  "request_id": "example-confirmed",
  "tx_hash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "network": "tron",
  "transaction_type": "TriggerSmartContract",
  "transaction_category": "trc20_transfer",
  "transaction_state": "confirmed",
  "confirmations": 27,
  "required_confirmations": 19,
  "sender": "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3",
  "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "token_symbol": "USDT",
  "decimals": 6,
  "amount": "1250.000001",
  "transfers": [
    {
      "index": 0,
      "asset_type": "trc20",
      "sender": "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3",
      "recipient": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
      "token_contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "token_id": null,
      "token_symbol": "USDT",
      "decimals": 6,
      "amount": "1250.000001",
      "event_ref": "log:0",
      "execution_status": "success"
    }
  ],
  "transfers_truncated": false,
  "aml_risk_level": "low",
  "schema_version": "0.3",
  "policy_version": "b2b-tx-2026-10.4",
  "sanctions_hit": false,
  "direct_sanctions_match": false,
  "indirect_sanctions_exposure": false,
  "risk_exposure": false,
  "key_exposure": [],
  "token_authenticity": "official",
  "recipient_match": true,
  "token_match": true,
  "amount_match": true,
  "coverage": "complete",
  "workflow_coverage": "complete",
  "source_coverage": {
    "sanctions_sources": {
      "ofac": {
        "status": "checked",
        "checked_at": "2026-10-10T09:00:00Z",
        "retrieved_at": "2026-10-10T09:00:00Z",
        "data_updated_at": null,
        "stale_after_seconds": 172800,
        "scope": "configured_address_index",
        "error_code": null
      },
      "eu": {
        "status": "checked",
        "checked_at": "2026-10-10T09:00:00Z",
        "retrieved_at": "2026-10-02T23:49:24Z",
        "data_updated_at": "2026-09-22T18:01:34Z",
        "stale_after_seconds": 3024000,
        "scope": "configured_address_index",
        "error_code": null
      },
      "uk": {
        "status": "checked",
        "checked_at": "2026-10-10T09:00:00Z",
        "retrieved_at": "2026-10-02T23:47:32Z",
        "data_updated_at": "2026-10-02T00:00:00Z",
        "stale_after_seconds": 3024000,
        "scope": "configured_address_index",
        "error_code": null
      },
      "un": {
        "status": "not_applicable",
        "checked_at": null,
        "retrieved_at": null,
        "data_updated_at": null,
        "stale_after_seconds": null,
        "scope": "configured_address_index",
        "error_code": null
      }
    },
    "transaction_sources": {
      "chain_explorer": {
        "status": "checked",
        "checked_at": "2026-10-10T09:00:00Z",
        "retrieved_at": "2026-10-10T09:00:00Z",
        "data_updated_at": null,
        "stale_after_seconds": null,
        "scope": "transaction_facts",
        "error_code": null
      },
      "chain_node": {
        "status": "checked",
        "checked_at": "2026-10-10T09:00:00Z",
        "retrieved_at": "2026-10-10T09:00:00Z",
        "data_updated_at": null,
        "stale_after_seconds": null,
        "scope": "transaction_facts",
        "error_code": null
      }
    },
    "risk_sources": {
      "aml_provider": {
        "status": "checked_freshness_unknown",
        "checked_at": "2026-10-10T09:00:00Z",
        "retrieved_at": "2026-10-10T09:00:00Z",
        "data_updated_at": null,
        "stale_after_seconds": null,
        "scope": "transaction_risk_score",
        "error_code": null
      }
    },
    "universal_clearance": false
  },
  "freshness": {
    "checked_at": "2026-10-10T09:00:00Z",
    "transaction_at": "2026-10-10T09:00:00Z",
    "risk_data_at": "2026-10-10T09:00:00Z",
    "token_data_at": "2026-10-10T09:00:00Z",
    "max_source_age_seconds": 0
  },
  "overall_state": "CLEAR",
  "environment": "live",
  "reasons": [
    {
      "code": "TX_FACTS_VERIFIED",
      "category": "transaction",
      "severity": "info"
    },
    {
      "code": "TX_FINALIZED",
      "category": "transaction",
      "severity": "info"
    },
    {
      "code": "AML_LOW",
      "category": "risk",
      "severity": "info"
    },
    {
      "code": "NO_DIRECT_SANCTIONS_MATCH",
      "category": "sanctions",
      "severity": "info"
    },
    {
      "code": "TOKEN_OFFICIAL",
      "category": "token",
      "severity": "info"
    }
  ],
  "decision_id": null,
  "direction": null,
  "workflow_type": null,
  "versions": {
    "decision": "b2b-tx-2026-10.4",
    "rules": {
      "exposure": "b2b-exp-v2",
      "sanctions_freshness": "sf-v1",
      "billing": "final_answers_only",
      "integrity": "int-v3",
      "reuse": "reuse-v1",
      "allocation": "alloc-v1"
    },
    "reason_codes": "rc-1",
    "evidence_schema": "ev-1",
    "contract": "0.3"
  },
  "transaction_status": "CONFIRMED",
  "integrity_status": "MATCH",
  "risk_status": "NO_MATERIAL_SIGNAL",
  "coverage_status": "OK",
  "status_drivers": {
    "transaction": "TX_FINALIZED",
    "integrity": null,
    "risk": null,
    "coverage": null,
    "action": "CUSTOMER_STATE_UNKNOWN"
  },
  "result_final": true,
  "verification_final": true,
  "risk_final": true,
  "risk_retryable": false,
  "risk_retry_after_seconds": null,
  "retryable": false,
  "retry_after_seconds": null,
  "recommended_action": "CONFIRM_INTERNAL_STATE",
  "integrity": {
    "status": "MATCH",
    "selected_event_ref": "log:0",
    "relevant_event_count": 1,
    "comparisons": {
      "recipient": {
        "expected": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
        "actual": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
        "result": "MATCH"
      },
      "sender": {
        "expected": null,
        "actual": "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3",
        "result": "NOT_EVALUATED"
      },
      "token": {
        "expected": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "actual": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
        "result": "MATCH"
      },
      "amount": {
        "expected": "1250.000001",
        "actual": "1250.000001",
        "result": "EXACT",
        "tolerance": null,
        "delta": "0",
        "delta_raw": "0"
      },
      "network": {
        "expected": null,
        "actual": "tron",
        "result": "NOT_EVALUATED"
      }
    }
  },
  "risk": {
    "status": "NO_MATERIAL_SIGNAL",
    "driver": null,
    "driver_evidence_ids": []
  },
  "evidence_items": [
    {
      "evidence_id": "ev_431b2fd74ad43ef5",
      "kind": "transaction_facts",
      "source": "chain_explorer",
      "subject": {
        "type": "transaction",
        "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "source_reference": "block:80000000",
      "observed_at": "2026-10-10T09:00:00Z",
      "effective_at": "2026-10-10T09:00:00Z",
      "temporal_scope": "TRANSACTION_TIME",
      "coverage": "checked",
      "freshness": {
        "age_seconds": 0,
        "stale": false,
        "stale_after_seconds": null
      },
      "dependency": "required",
      "disagreement": null,
      "evidence_version": "ev-1"
    },
    {
      "evidence_id": "ev_63c8c4e421f6ff66",
      "kind": "transaction_facts",
      "source": "chain_node",
      "subject": {
        "type": "transaction",
        "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "source_reference": "block:80000000",
      "observed_at": "2026-10-10T09:00:00Z",
      "effective_at": "2026-10-10T09:00:00Z",
      "temporal_scope": "TRANSACTION_TIME",
      "coverage": "checked",
      "freshness": {
        "age_seconds": 0,
        "stale": false,
        "stale_after_seconds": null
      },
      "dependency": "required",
      "disagreement": null,
      "evidence_version": "ev-1"
    },
    {
      "evidence_id": "ev_896f4ce46de5246c",
      "kind": "aml_risk",
      "source": "aml_provider",
      "subject": {
        "type": "transaction",
        "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "source_reference": "transaction_risk_score",
      "observed_at": "2026-10-10T09:00:00Z",
      "effective_at": null,
      "temporal_scope": "CHECK_TIME",
      "coverage": "checked_freshness_unknown",
      "freshness": {
        "age_seconds": 0,
        "stale": true,
        "stale_after_seconds": null
      },
      "dependency": "required",
      "disagreement": null,
      "evidence_version": "ev-1"
    },
    {
      "evidence_id": "ev_7d0537ae6c2054d5",
      "kind": "sanctions_list",
      "source": "ofac",
      "subject": {
        "type": "transaction_addresses",
        "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "source_reference": "configured_address_index",
      "observed_at": "2026-10-10T09:00:00Z",
      "effective_at": null,
      "temporal_scope": "LIST_PUBLICATION",
      "coverage": "checked",
      "freshness": {
        "age_seconds": 0,
        "stale": false,
        "stale_after_seconds": 172800
      },
      "dependency": "required",
      "disagreement": null,
      "evidence_version": "ev-1"
    },
    {
      "evidence_id": "ev_2be872923c0687c9",
      "kind": "sanctions_list",
      "source": "eu",
      "subject": {
        "type": "transaction_addresses",
        "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "source_reference": "configured_address_index",
      "observed_at": "2026-10-10T09:00:00Z",
      "effective_at": "2026-09-22T18:01:34Z",
      "temporal_scope": "LIST_PUBLICATION",
      "coverage": "checked",
      "freshness": {
        "age_seconds": 0,
        "stale": false,
        "stale_after_seconds": 3024000
      },
      "dependency": "required",
      "disagreement": null,
      "evidence_version": "ev-1"
    },
    {
      "evidence_id": "ev_df2204c780968cb5",
      "kind": "sanctions_list",
      "source": "uk",
      "subject": {
        "type": "transaction_addresses",
        "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "source_reference": "configured_address_index",
      "observed_at": "2026-10-10T09:00:00Z",
      "effective_at": "2026-10-02T00:00:00Z",
      "temporal_scope": "LIST_PUBLICATION",
      "coverage": "checked",
      "freshness": {
        "age_seconds": 0,
        "stale": false,
        "stale_after_seconds": 3024000
      },
      "dependency": "required",
      "disagreement": null,
      "evidence_version": "ev-1"
    },
    {
      "evidence_id": "ev_76c33d7fb3a48fb7",
      "kind": "sanctions_list",
      "source": "un",
      "subject": {
        "type": "transaction_addresses",
        "ref": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
      },
      "source_reference": "configured_address_index",
      "observed_at": null,
      "effective_at": null,
      "temporal_scope": "LIST_PUBLICATION",
      "coverage": "not_applicable",
      "freshness": {
        "age_seconds": null,
        "stale": false,
        "stale_after_seconds": null
      },
      "dependency": "not_applicable",
      "disagreement": null,
      "evidence_version": "ev-1"
    },
    {
      "evidence_id": "ev_81b44db3a9445d39",
      "kind": "token_authenticity",
      "source": "token_registry",
      "subject": {
        "type": "token",
        "ref": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"
      },
      "source_reference": "official",
      "observed_at": "2026-10-10T09:00:00Z",
      "effective_at": null,
      "temporal_scope": "CHECK_TIME",
      "coverage": "checked",
      "freshness": {
        "age_seconds": 0,
        "stale": false,
        "stale_after_seconds": null
      },
      "dependency": "required",
      "disagreement": null,
      "evidence_version": "ev-1"
    }
  ],
  "coverage_limitations": {
    "runtime": [],
    "product": [
      "AML_TRANSACTION_LEVEL_ONLY",
      "RISK_STATE_AS_OF_CHECK",
      "SANCTIONS_CONFIGURED_LISTS_ONLY"
    ]
  },
  "obligation": null,
  "reuse": null
}