Transaction Decision API

Check a transaction before recording a payment

ChainZap checks a blockchain transaction before your application records a payment as received. One response combines transaction facts, risk signals and, if you ask for it, a comparison with the recipient, token and amount you expected.

What you can check

TRON, Ethereum mainnet and TON mainnet adapters are implemented. TRON checks are live for every new organization. TON is a preview whose checks of executed transactions currently return LIMITED_DATA; Ethereum checks are activated by support on request. Sign in with your ChainZap account to the developer dashboard, create an API key and start with the canonical transaction quickstart.

• POST /v1/transaction/check: the canonical detailed contract 0.3 response. The network is required; expected payment details enable verification.
• POST /v1/check: send a transaction hash. The network and the expected payment details are optional. The response is a short assessment with full evidence in details.
• POST /v1/wallet/check: send a wallet address. The network is read from its format. The response is a state, a coverage level and reason codes with per-module facts in details; see wallet check.
• GET /v1/usage: your organization's quota and recent usage.

Call the API from your server and send your API key in the X-API-Key header.

Interpret the whole response

A successful HTTP response does not mean a payment is confirmed or free of risk. For /v1/check, read state, risk_level and coverage together with the transaction state, the matching flags, the freshness data and the reasons in details. The canonical /v1/transaction/check returns those detailed fields at the top level. null means unknown or not requested, depending on the field. Never treat missing evidence as a clean result.

Continue with the quickstart, then read data completeness and idempotency.

Your first transaction check

Get access

Sign in with your ChainZap account to the developer dashboard. An organization is created for you automatically and you become its owner; an invitation code is needed only to join an existing organization. Create a key on the API keys page and store it in your server's secret store. TRON checks are live at once: a sandbox key lets you test for free, and a plan for live checks is bought on the Plan and billing page. Contact support to invite colleagues to your organization.

Send your first request

This example uses a fictional key and transaction hash. Replace them on your server. All amounts are decimal strings. Store your idempotency key together with the payment operation, so that it survives a process restart.

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

Read X-Request-ID in the response headers and request_id in the JSON body. Keep this identifier for support. This canonical endpoint requires network. See status axes before consuming a result; POST /v1/check is the optional short response.

Verify expected payment details

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

The example addresses are public sample addresses, not payment instructions. Match an exact token contract, not a symbol. Read all three match flags; they refer to the same selected transfer. See matching.

Consume contract 0.3

Use verification_final and integrity_status for payment verification, then evaluate risk_status and recommended_action separately. Pending is NOT_EVALUATED, never MATCH. Final MATCH with risk_status: INSUFFICIENT confirms the payment comparison but requires MANUAL_REVIEW, not automatic credit or payout approval. Read risk_retryable independently from retryable. The response examples show these branches.

Close a payout automatically

Without context about your side, a final MATCH with risk_status: NO_MATERIAL_SIGNAL and no reason to review gives CONFIRM_INTERNAL_STATE: the chain and the risk screen are in order, but ChainZap cannot see whether this payment is the one you owe or whether it was already settled. It is not a refusal: confirm in your own records that the payout is still owed and not already marked paid, then close it. The same action without a MATCH (no expected fields sent) has not compared the payment: do not close a payout on it.

To reach PROCEED, tell ChainZap what the payment is for: send direction: "OUTGOING", workflow_type: "PAYOUT" and the payout's external_reference together with the expected fields, or record the obligation first and send its external_reference with the check. A clean, final match against that recorded outgoing obligation is PROCEED; without an external_reference the best answer stays CONFIRM_INTERNAL_STATE, unless the check also sends customer_context.credit_status: "NOT_CREDITED", which alone is enough for PROCEED unless allocation_status is UNKNOWN (see statuses). direction and workflow_type are accepted without the obligation ledger, but on their own they never reach PROCEED; with direction: "OUTGOING", a payout that is not found also carries ATTEMPT_MAY_STILL_LAND: do not pay again. external_reference and the other obligation fields need the obligation ledger and answer 403 ledger_not_enabled where it is off.

Handle uncertainty

If the connection closes before you receive a response, retry with the same body and the same Idempotency-Key. Never create a new key to get around an uncertain result. Retry a received error only when error.retryable is true; honor Retry-After and cap the number of attempts. A stored error can be replayed unchanged: retryable does not force a new provider check.

See the Python and TypeScript examples for bounded retries and usage for quota inspection.

Check a wallet too

The same key screens a counterparty's address: POST /v1/wallet/check with {"address": "..."} returns a state, coverage and reason codes in the same shape, and is billed when a state is produced. See wallet check.

One transaction hash, one check

POST /v1/check needs only tx_hash. The API reports facts, risks and data gaps. Your application decides what to do with the payment. Sign in with your ChainZap account to the developer dashboard and create a server key on the API keys page.

A first result

Set CHAINZAP_API_KEY, TX_HASH and a persisted operation ID CHECK_ID on your server. These examples make one request only when you run them. For test data without provider calls, use a sandbox key. Never put a key in browser code. The request takes fewer than ten lines of application code; check the HTTP status before interpreting the result.

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

Network discovery

The accepted network names are tron, eth and ton; aliases are rejected. An explicit network restricts the search to that network. Hash shape, a 0x prefix, base64 and provider response order never determine the network, in the sandbox included.

Without network, ChainZap reads facts only in supported, activated networks enabled for your organization. details.checked_networks reports that scope; uniqueness says nothing about other chains. AML screening does not run across networks. All other checked networks must conclusively report no transaction. Provider failure, indexing gaps or timeouts do not count as absence. A single positive result plus an unknown result requires network.

Automatic detection uses the same provider-call budget as explicit selection, whether one network is in scope or several. Providers must still confirm that the transaction hash belongs to the network reported. A read whose price is not configured is recorded as unknown cost, never as zero.

NETWORK_AMBIGUOUS means several networks found the transaction. NETWORK_REQUIRED means the available context cannot prove a unique result: for example one network found it while another could not answer, or no networks are enabled. When every checked network confirms the transaction is absent, the answer is 404 transaction_not_found instead. Both use HTTP 422, state: insufficient_input, network: null, error.retryable: false, error.required_field: network, error.candidates and error.checked_networks. Specify the network and use a new idempotency key. Retrying the same body will replay the same error.

Short and detailed response

state is details.overall_state in lowercase. Detailed reason objects live in details.reasons; strings and objects are never mixed. Known high risks remain visible with partial coverage. A requested comparison with the value null is unfinished. All expected_* fields must match the same transfer; several full matches are ambiguous.

The canonical /v1/transaction/check keeps uppercase states, coverage: complete or partial and 2 to 5 reason objects. /v1/usage and X-API-Key are unchanged. /v1/check returns HTTP 404 transaction_not_found for a verified explicit-network absence; the canonical endpoint keeps HTTP 200 transaction_state: not_found. A pending check is HTTP 200 with review/limited_data, never clear, and is not charged. Both endpoints use the same limits, quota and costs. Idempotency keys are shared per organization: switching the endpoint or changing the body conflicts. Stored results, including the resolved network and the errors answered after the check was accepted, replay without another provider check; 429 and 5xx are never stored. Replay rechecks access.

Ethereum and TON coverage

Ethereum internal native transfers need execution traces and are outside this version's scope. ERC-20 logs do not establish a recipient's net balance change for fee-on-transfer or rebasing tokens. Mint, burn and zero-value transfers require review. Unknown decimals leave amount: null; symbols never establish authenticity. Other tokens can have transfer facts but incomplete authenticity/KYT coverage.

TON accepts transaction hashes only, in 64-digit hex (optional 0x) or canonical 32-byte base64/base64url. A message hash or BOC is not silently reinterpreted as a transaction hash. Friendly addresses require a valid checksum; bounceable and non-bounceable normalize to workchain/account. Test-only addresses are rejected. expected_token means jetton master, expected_recipient means wallet owner. An isolated transfer_notification is not proof. Bounces, failed compute/actions, missing descendants and emulation cannot produce clear. Current wallet get-method results are cross-checked with the second index; historical identity changes require further investigation. Finality is provider-attested, not a locally verified validator signature proof.

Ethereum and TON checks are activated per organization by support after live acceptance. AML screening covers the assets the AML source supports on each network; a specific account's entitlement, actual costs and coverage still require live verification. Missing AML or sanctions evidence never defaults to low/clear. See source coverage.

Deterministic response example

This is an illustrative fixture, not a live observation. Expand the complete JSON below.

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

Authentication

One ChainZap account

Use Continue with ChainZap to sign in with the account you use in the app. From Settings → Developer API → Dashboard, an existing browser login continues without another sign-in. Your organization, API keys and API allowance stay separate from personal app credits. A previous Google portal login is linked using the verified Google account identifier, never by matching email addresses.

Ordinary sign-in needs no invitation code. Invitations are only for joining an existing organization. If Telegram opens a separate browser that has no ChainZap session, sign in there once with the same account. Link Google and Telegram in the app's account settings before switching between them.

Server API keys

Send X-API-Key over HTTPS on every request to the business API. Never place a key in a URL, browser storage, analytics, a support message or source control. A key grants access to one organization; a request cannot select another organization.

Signing in to the developer dashboard is separate from API keys. Live keys start with cz_live_; sandbox keys start with cz_test_.

Dashboard roles:

• Owner, admin and developer members create, rotate and revoke API keys.
• Owner, admin and billing members view payment history, buy plans and extra checks packages and manage the subscription.
• Viewer members only inspect usage and key metadata.

An API key cannot buy anything.

Key lifecycle

Give each integration its own key with a descriptive label. The full key is shown only once, on creation or rotation; lists show a prefix. Rotation revokes the old key and creates its replacement in one operation. Update your server's secret store right after rotation. To avoid an outage during a planned migration, create a separate key, move your integration to it and verify it, then revoke the previous key.

Access errors

• 401 invalid_api_key: the key is invalid or revoked.
• 403 tenant_suspended: the organization is suspended.
• 403 network_not_enabled: the requested network is not enabled for the organization.

Correct access first. Retrying the same request without a change does not help.

POST /v1/transaction/check

Request

This strict JSON request requires network and a 32-byte tx_hash. Unknown fields are rejected. Expected addresses are validated and normalized for the selected network. expected_amount is a nonnegative decimal string; JSON numbers and exponent notation are rejected. For optional network context and the short response, use POST /v1/check.

Address formats and exact comparison rules are in matching. Request bodies are limited to 4 KiB; a larger body is refused with 413 payload_too_large. Organizations on the pilot contract must send all three expected_* fields.

Send Content-Type: application/json, your server-side X-API-Key and an Idempotency-Key for the logical check operation. X-Request-ID links the request to your own operation log. The generated API reference lists the exact required fields, enums and response schemas.

Response

Read transaction_state independently from overall_state. The response includes confirmations, normalized transfers, the selected transfer, risk level, sanctions status, token authenticity, matching flags, coverage, freshness and 2 to 5 prioritized reasons. Transfer and exposure amounts are decimal strings. Handle nullable fields explicitly.

transfers_truncated=true means the transfer list was cut short. AMBIGUOUS_TRANSFER means several transfers satisfy your conditions. Both need attention. Do not treat a truncated list as complete and do not combine matching flags from different transfers.

Consume contract 0.3

Use verification_final and integrity_status for payment verification, then evaluate risk_status and recommended_action separately. Pending is NOT_EVALUATED, never MATCH. Final MATCH with risk_status: INSUFFICIENT confirms the payment comparison but requires MANUAL_REVIEW, not automatic credit or payout approval. Read risk_retryable independently from retryable. The response examples show these branches.

Billing

A final answer with coverage: complete uses one check from your quota, including a complete high-risk result: the transaction is confirmed past its finality policy, or it failed for good. A pending transaction, a transaction not found and a response with coverage: partial are not charged. Replaying the same idempotent operation never charges twice.

expected_token is a contract address (not a ticker); the legacy name expected_token_contract remains accepted. Send only one. The response carries schema_version: "0.3" and policy_version, the decision policy that produced the answer (store it with the answer), the three separate risk/sanctions flags, workflow_coverage and source_coverage. Read coverage before interpreting a clear result. Idempotency keys used before contract 0.2 return 409 idempotency_conflict; use a new key after handling the old result.

Check a wallet before you accept it or pay it

POST /v1/wallet/check screens one address the same way POST /v1/check screens one transaction: same key, same quota, same idempotency rules, same shape of answer. Send an address, receive a state, a coverage level and reason codes, and decide in your own workflow whether the counterparty needs a closer look.

Request

The three formats cannot be confused with each other, so a wallet check never answers NETWORK_REQUIRED or NETWORK_AMBIGUOUS. A string that matches none of them is 422 invalid_address. Unknown fields are rejected and the body is limited to 4 KiB. Send Content-Type: application/json, your server-side X-API-Key and an Idempotency-Key for the logical operation; X-Request-ID links the request to your own log.

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

The address in the example is a public sample address, not a payment instruction. The response echoes address in its canonical spelling: Ethereum in lower case, TON as workchain:hash, TRON unchanged.

Response

Read the top level first, then details.

details explains where the state came from:

• overall_state and data_coverage: the upper-case state and the engine's own coverage word, FULL, PARTIAL or INSUFFICIENT.
• modules: seven rows in a fixed order, sanctions_aml, wallet_behaviour, token_authenticity, contract_controls, address_security, counterparties_services, flows_connections. Each row has a status (RISK_DETECTED, NO_MATCHES_FOUND, PARTIALLY_CHECKED, INSUFFICIENT_DATA, NOT_SUPPORTED, NOT_CHECKED) and a source_coverage (complete, partial, none, not_applicable). A module that was not screened says so; it is never reported as clean.
• sanctions: direct_match against the configured OFAC, EU, UK and UN indexes (null when no index was screened), the listing authorities, whether the listing is attributed, and indirect_exposure reported by the AML provider (null when it did not run).
• address_security: public denylist status and category, provider_flagged (whether the address-security provider flagged the address; null when it did not answer or its rights do not let ChainZap show it), and whether the stablecoin issuer has frozen the address. The provider's own labels are never returned; the deprecated provider_flags is ["PROVIDER_SECURITY_FLAG"] when provider_flagged is true and empty otherwise.
• behaviour: whether the address is a contract, the transaction count and whether it was capped, the wallet age, first and last activity, and the number of counterparties.
• counterparties and token_authenticity: how many counterparties were screened, unverified or flagged, and how many held tokens are official, fake, suspicious or unknown.
• freshness and source_coverage: when the check ran, whether the analysis came from the analysis cache (5 minutes on Ethereum, 30 minutes on TRON and TON; the AML provider's answer is reused for up to 24 hours), the oldest source age, and one observation per source with the same status vocabulary as the transaction check. Sources are named by role: 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.

Every wallet reason code is listed with its meaning in reason codes.

What a wallet check is not

There is no numeric score anywhere in the response, by design. A number invites a threshold, and no threshold is honest across three networks with different sources. The response tells you what was found, what was screened and what could not be screened. It is not a compliance certificate and it does not know the internal rules of any exchange or bank. Treat clear as "nothing critical in the screened sources", review as "look before you proceed", high_risk as "a critical finding needs resolving", and limited_data as "we could not tell".

Billing

A wallet check uses one check from your quota when it produces a state: clear, review or high_risk, with complete or partial coverage. limited_data is free, as are errors, timeouts and idempotent replays. This differs from the transaction check, which is charged only with complete coverage: a wallet screen often reaches a firm verdict while one counterparty in fifty stays unattributed, and the paid sources have already answered. Sandbox keys never use paid checks.

Time budget and retries

A cold wallet check reads several providers and has a server budget of 30 seconds; use a client deadline of about 35 seconds. If the server answers 504 request_timeout, retry with the same body and the same Idempotency-Key: the analysis keeps running to completion on the server and lands in the shared cache, so the retry is usually answered at once and carries freshness.served_from_analysis_cache: true. The general retry rules apply unchanged.

Idempotency across kinds

Idempotency keys are shared per organization and environment across all check endpoints. Reusing a transaction's key for a wallet body, or a wallet's key for another address, answers 409 idempotency_conflict. One logical operation, one key.

Server examples

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

Deterministic response example

This is an illustrative fixture, not a live observation. Expand the complete JSON below.

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

Match a transfer to a payment

Use the expected_* fields to verify the recipient, token contract and amount of a specific payment. Send all three fields or only the comparisons you need.

The following comparisons apply after chain finality. While transaction_status: PENDING, integrity and every requested comparison are NOT_EVALUATED, and all match flags are null, even when an observed transfer has the expected values. A final MATCH verifies payment details independently of KYT; insufficient risk still requires MANUAL_REVIEW.

One transfer, three comparisons

A transaction can contain several transfers. ChainZap first looks for a transfer that satisfies every supplied condition. If none does, it selects the transfer with the most matches. Ties are resolved consistently using the transfer index.

recipient_match, token_match and amount_match all describe that same transfer. If several transfers satisfy every condition, the response includes AMBIGUOUS_TRANSFER. A transfer that did not execute, such as one in a reverted transaction, is never a match: its three fields are null, and a failed transaction in which nothing executed is NOT_EVALUATED, never LIMITED_DATA for missing transfer rows.

Contract 0.3 states the comparison in full in integrity: status (see status axes), selected_event_ref, relevant_event_count (executed transfers to the expected recipient in the expected token) and comparisons with the expected and actual value and a result for recipient, sender, token, amount and network. The amount result is EXACT, WITHIN_TOLERANCE, UNDERPAID, OVERPAID, NOT_EVALUATED or INSUFFICIENT, with the signed delta and delta_raw.

How values are compared

If you provide an expected value but its transfer data is unavailable, the corresponding match field is null, coverage is partial, and the reasons include EXPECTED_DATA_UNAVAILABLE. Missing token decimals, for example, do not prove an amount mismatch. Do not treat null as a successful match.

Addresses are validated and normalized for the selected network:

For TON, expected_recipient is the wallet owner and expected_token is the jetton master, not the jetton wallet.

Tokens are compared by exact contract, never by name or symbol; the same symbol does not prove the same token. Amounts are converted from decimal strings to raw integer units using the known token decimals and compared exactly; no floating-point tolerance is applied. To accept a small difference, send amount_tolerance: an absolute amount in token units, symmetric, 0 by default. A difference within it is WITHIN_TOLERANCE and adds AMOUNT_WITHIN_TOLERANCE; a tolerance with more decimal places than the token answers 422 invalid_amount_tolerance. expected_sender compares the sending address the same way as the recipient. Digits beyond the token's decimals are accepted when they are zeros: "10.0000000" equals "10" for a 6-decimal token. A nonzero digit beyond them returns 422 invalid_expected_amount.

Mismatch example

If you expect "10.000001" but the selected transfer contains "10", the response includes amount_match=false and EXPECTED_AMOUNT_MISMATCH.

A different recipient produces EXPECTED_RECIPIENT_MISMATCH; a different token contract produces EXPECTED_TOKEN_MISMATCH. A matching amount does not prove that the recipient and token also match. Before accepting a payment, check every required comparison, the transaction state and the overall assessment.

Pilot contract

An organization on the design-partner pilot contract must send all three fields on every check: a check without expected_recipient, expected_token or expected_amount is refused with 422 expected_fields_required, and an expected_token other than official USDT on TRON with 422 token_not_enabled. Refusals happen before the check is accepted: nothing is charged or stored, and sandbox keys follow the same rules.

Network context

These comparisons work with both check endpoints. When you already know the payment network, supply it explicitly. The API then validates the expected addresses against that network and never switches to another chain. See network discovery for requests without network.

Obligations, attempts and allocations

A single check answers whether one transaction pays what you expect. The obligation ledger answers whether a business obligation, a payout or a deposit you are owed, was paid: once, in full, by which transactions, and whether the same payment is presented for something else. It keeps your instructions, your execution attempts, the payment events ChainZap verified and how they were allocated, and never rewrites any of them.

The ledger is switched on per deployment. While it is off, a check with any ledger field and every ledger endpoint answer 403 ledger_not_enabled.

The model

external_reference, attempt_reference and approval_reference are up to 128 printable ASCII characters. Do not put personal data in them.

Check against an obligation

Add the obligation's reference to an ordinary transaction check:

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

The first check of a new reference records the obligation and its instruction (version 1, or the instruction_version you send). Later checks may send only the reference: the recorded instruction is what the transaction is compared with. The answer adds an obligation block (status, expected_amount, allocated_amount, residual_amount, attempts, events, pending_events) and a reuse block.

When the transaction matches, or pays the right recipient and token a different amount, its event is allocated to the obligation. Only final, executed events are allocated; a pending one is counted in pending_events and never closes the obligation. When several movements fit equally (integrity_status: AMBIGUOUS), each is linked to the obligation as UNKNOWN with nothing allocated, until you declare which one paid. A check that omits direction takes the obligation's recorded one, or else infers it from workflow_type (PAYOUT and REFUND are outgoing, DEPOSIT and INVOICE incoming); a payment whose direction stays unknown is never PROCEED.

Instructions never change in place

An instruction version is immutable. Sending the same version with different terms is refused with 409 instruction_conflict; sending different terms without a version is refused with 409 instruction_version_required. A changed instruction is a new version, recorded with POST /v1/obligations and a higher instruction_version; earlier versions stay on record and a check can name the version it was paid under. A version you never recorded is not reconstructed: the check answers integrity_status: INSUFFICIENT with INSTRUCTION_UNAVAILABLE. A payment in a block before instruction_effective_at adds INSTRUCTION_NOT_EFFECTIVE.

Record obligations and attempts up front

An attempt is not an execution. execution_confirmed turns true only when a payment event of its transaction is allocated to the obligation; a TIMEOUT attempt followed by a successful retry leaves two attempts and one execution. When attempts carry an amount, a check made with that attempt_reference compares the transaction with the attempt's amount, so a payout split into legs matches leg by leg.

Shared payments and reuse

One payment can settle several obligations, and one obligation can be paid by several payments.

• Several obligations, one payment. ChainZap never splits a payment on its own. Declare the shares with POST /v1/allocations (network, tx_hash, event_ref, allocations: [{external_reference, amount}], and an optional owner that stamps any earlier allocation the declaration replaces). The event exists once a check naming an obligation recorded it with complete coverage (404 payment_event_not_found otherwise); it must have executed and be final (409 payment_event_not_settled), be in the obligation's token (409 allocation_token_mismatch), and the shares cannot exceed it (409 allocation_exceeds_event). A check of one share then compares that share, not the whole payment, with what the obligation is owed.
• One obligation, several payments. Each check under the same reference adds its event; residual_amount falls until the obligation is ALLOCATED.
• Reversal. POST /v1/allocations/{allocation_id}/reversal with a reason (CUSTOMER_CORRECTION, DISPUTED, DUPLICATE_RECORD, OTHER) stamps the allocation as reversed, and DISPUTED marks it DISPUTED. It stays on record, and a later check never restores it; only a declaration can.

reuse.status says what the ledger already knows about the payment event:

An idempotent replay (the same Idempotency-Key and body) returns the stored answer and is not a reuse.

Incoming payments

For a deposit, send direction: "INCOMING" and tell ChainZap what your system already did with it in customer_context: credit_status (NOT_CREDITED, CREDITED, PARTIALLY_CREDITED, UNKNOWN) and allocation_status (NOT_ALLOCATED, PARTIALLY_ALLOCATED, ALLOCATED, UNKNOWN), how far your books already applied it. ChainZap cannot see your books: without NOT_CREDITED a clean deposit is CONFIRM_INTERNAL_STATE, an UNKNOWN allocation is too, and a payment credited or applied even in part gives REVIEW with ALREADY_CREDITED. The same obligation, allocation and reuse rules apply to deposits and payouts.

Retention

Raw references, addresses and transaction hashes are kept for 90 days and then replaced by keyed digests; owners are removed. Amounts, tokens, statuses and versions remain, so the totals stay right. After that the ledger still recognises a reused payment and a repeated reference by digest, and the API returns redacted: true where a raw value is gone. A digest of an amount and a block time is pseudonymous, not anonymous.

Batches

A batch checks a file of payments, 50 to 200 rows, on the same engine as a single check: every row gets the same answer, reasons and ledger effects it would get alone. The file is validated and priced first; nothing runs and nothing is charged until you confirm. Batches use the obligation ledger, and answer 403 batch_not_enabled while it is off.

You can upload, run and export a batch in the developer dashboard on the Batches page, or through the API below. Both use the same service and limits.

The file

A CSV in UTF-8 (a byte order mark is fine), comma- or semicolon-separated, with a header row. Up to 200 rows and 256 KiB. One row is one payment of one obligation.

Common header names are recognised: order_id, payout_id, invoice_id, reference for the reference; txid, hash, transaction_hash for the hash; to, recipient, address, wallet for the recipient; token, contract, asset, currency for the token; amount, tolerance, from, sender, chain, attempt, provider, status. Unknown columns are ignored and listed in preflight.ignored_columns. Query parameters network, direction and workflow_type set defaults for rows that leave them empty. Download a template from the dashboard.

Upload and 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 returns the batch in PREFLIGHTED with:

• preflight: rows, checks, obligations_only, invalid and duplicates, with errors and warnings counted by code. A row with an error is skipped (SKIPPED_INVALID) and the error names the field, for example invalid_tron_address or unknown_token_symbol; an identical repeated row is skipped as a duplicate. When rows give one reference different terms, the first stands and the later ones are refused (conflicting_rows_for_obligation). Warnings do not skip a row: tx_shared_across_references (one transaction under several references without allocated_amount), declared_shared_payment, several_transactions_for_obligation, and tx_seen_for_other_obligation when the ledger already ties the transaction to another obligation.
• estimate: an upper bound, never a promise. distinct_transactions, billable_checks_at_most, provider_calls_at_most, provider_usd_at_most (priced as if nothing were cached), quota_available and quota_sufficient.

A file that is not UTF-8, is empty, has no header or data rows, or has a malformed row answers 422 invalid_csv; a header without an external_reference column or with a repeated column answers 422 invalid_csv_header; more than 200 rows answer 413 batch_too_large. An Idempotency-Key names one file: the same key with the same file returns the same batch, with another file 409 idempotency_conflict. An organization runs at most two batches at a time; starting a third answers 429 batch_limit_reached (uploading and preflighting cost nothing and are not limited this way).

Run

POST /v1/batches/{batch_id}/execute with {"confirm": true} queues the batch; without confirm it answers 422 confirmation_required. If the quota cannot cover every distinct transaction it answers 409 insufficient_quota; send "allow_partial": true to start anyway.

Rows are checked by a worker, never faster than half of your organization's rate limit, so your own traffic keeps working; batches of all organizations take turns, a slice at a time. Rows of one transaction run in file order. Each distinct transaction is charged once per batch: once a row of it produced a charged answer, later rows of the same transaction are checked against their own obligation for free (a row that was refused charges nothing, so the next one is charged). If the quota or the daily ceiling of unbilled checks runs out, the batch pauses (PAUSED, with pause_reason quota_exceeded or daily_unbilled_ceiling); execute it again to resume.

POST /v1/batches/{batch_id}/retry runs again only the RETRYABLE rows of a completed or paused batch, up to five attempts per row; 409 nothing_to_retry when there are none. POST /v1/batches/{batch_id}/cancel stops it.

A row whose only gap is risk (a KYT outage) is DONE, not RETRYABLE: read its risk_retryable and risk_retry_after_seconds, and check that transaction again with a new Idempotency-Key when you need the risk part (see retries).

Results

• GET /v1/batches lists your recent batches; GET /v1/batches/{batch_id} returns one with progress and, once it ran, summary.
• GET /v1/batches/{batch_id}/rows?after=0&limit=100 pages through the rows with their compact answers (the four statuses, recommended_action, the amount result and delta, the reuse and obligation status, reason codes, decision_id). Filter with state= or review=true.
• GET /v1/batches/{batch_id}/export.csv returns every row and its answer. Cells that a spreadsheet would read as a formula are prefixed with ', and every cell is quoted.

summary counts rows by state and by overall_state, gives the distribution of each status axis and of recommended_action, the number of rows with analyst_review_required, the errors, and the cost: usd_total, usd_per_transaction and usd_per_exception (any answer other than CLEAR), with cost_complete. obligations lists the open ones with what is allocated and what remains.

analyst_review_required marks a row a person must look at: a MANUAL_REVIEW or HOLD_AND_ESCALATE recommendation. A row whose answer is not final yet (RECHECK_LATER) asks for a retry, not for a person.

Sandbox

Sandbox keys run batches against sandbox fixtures and spend the sandbox allowance; the same file runs unchanged on a live key. Raw row values are kept for 90 days, like the ledger's, and then removed; counts, statuses and digests remain.

Legal pack and delivery scope

The Business Terms, Pilot Agreement, Pilot Data Annex and Privacy Policy are available from the portal legal links. Pre-incorporation templates still require the contracting and commercial fields before signature. The initial pilot profile is official USDT/TRON.

There is no dedicated integrity-only switch: checks invoke the risk layer and show insufficient/degraded coverage when required risk evidence is missing. The portal presents compact rows, review flags, known residuals and CSV; detailed decision evidence and reversal/correction operations use the API. A completed batch is a decision-time snapshot and does not automatically refresh after later ledger corrections. DONE means processed, not paid or a customer-confirmed outcome.

Escrow deals

An escrow deal holds USDT on TRON in its own contract. The money moves only when someone with the right acts: the buyer releases it, the seller refunds it, a party claims it after a deadline the other side let pass, both parties propose the same split in a dispute, or a resolver named before funding decides one. Your platform drafts the deal and shows it; the buyer and the seller sign the terms and move the funds with their own wallets. ChainZap creates the contract once both have signed and watches the deadlines, but it never holds the parties' keys, is never a resolver and cannot move the money.

Escrow deals are a closed pilot. Until your organization is enabled, every call answers 403 escrow_not_enabled. The sandbox runs on the TRON Nile test network with a test token that has no value.

Two modes

Every deal can be disputed. The only choice is whether a resolver may also decide a dispute.

Start without a resolver: it suits deliveries that pass or fail an objective check, and both parties can always end a dispute themselves.

What the contract allows

• Each deal is its own contract, created by an immutable factory: no owner, no upgrade, no pause and no admin key.
• Money moves only on a party's own act, or on the resolver's ruling within its window:
  • the buyer releases (release) and the seller refunds (refund) at any time after funding until the deal settles, a dispute included;
  • the buyer claims a refund (claimRefund) once the delivery deadline passed without delivery; the seller claims the payment (claimRelease) once inspection ended without acceptance or dispute;
  • in a dispute, the deal settles the moment both parties' proposals match (proposeSettlement), or when the resolver rules (resolve).
• No timer decides a dispute, and a deadline moves nothing by itself: it only opens a claim for one party.
• Anyone, ChainZap included, may only confirm the funding (confirmFunding), close an unfunded deal after its deadline (expire), pay out what is already credited to its fixed recipient (withdraw) and credit stray tokens to the buyer (sweepExcess). All of these work directly on the contract, without ChainZap.
• Payouts go only to the buyer, the seller, the fee recipient fixed in the factory and, after its ruling, the named resolver.

Lifecycle

status is the off-chain draft state (DRAFT, AGREED, CREATING, ON_CHAIN, CANCELLED, AGREEMENT_EXPIRED, CREATION_BLOCKED); once on chain, state is the contract's own (AWAITING_FUNDS, FUNDED, DELIVERED, DISPUTED, RELEASED, REFUNDED, SPLIT, EXPIRED). Deadlock is not a contract state: it is a dispute no resolver can decide any more, reported as settlement.deadlocked. The chain is the source of truth: the API reports what it read from solidified blocks and marks contract.out_of_sync when it cannot confirm the latest state.

Funding

Funding is an ordinary transfer of the deal's token to the escrow address, with no allowance and no transferFrom. Once the escrow holds at least the amount, anyone may call confirmFunding before the funding deadline; ChainZap does it as soon as it sees the balance. Until then funding reports what the escrow has received and what remaining amount is missing, as last read from the chain.

• Less than the amount. The deal stays AWAITING_FUNDS; send the rest before the funding deadline. confirmFunding refuses an escrow that holds less.
• More than the amount, or a second transfer. After funding, the excess is credited to the buyer (sweepExcess, event escrow_deal.excess_credited) and withdrawn like any payout. It is never locked in the deal and never goes to ChainZap.
• Too late. After the funding deadline the deal can only be closed (expire, state EXPIRED); anything sent to it is credited to the buyer and can be withdrawn.
• From another address. Only the escrow's balance counts, so a transfer from any address funds the deal, and every refund or excess goes to the buyer's address in the terms, not to the sender.

The deal page sends exactly the remaining amount to the escrow it read from the factory, and refuses any other recipient, token or value.

Deadlines and claims

Deadlines use block time. An action is accepted only before its deadline and a claim only from the deadline on, so the two never overlap. A claim is not automatic: until the party makes it, the other side can still act, for example the buyer can still release after the delivery deadline. timeline.if_nobody_acts in every response says what the current deadline opens: at, outcome (EXPIRED, REFUNDED, RELEASED or DEADLOCK) and claim_by (BUYER, SELLER, ANYONE, or null when nothing opens).

Live deals give the buyer at least 72 hours to inspect (422 inspection_period_below_policy otherwise). Because silence lets the seller claim the payment, ChainZap reminds the buyer by Telegram right after delivery, half way through inspection, 12 hours and 1 hour before it ends; the seller is reminded 24 and 2 hours before the delivery deadline, and each party is told when its claim opens.

Disputes, proposals and deadlock

The buyer may open a dispute (dispute, with an evidence hash) only during inspection. From then on the seller cannot claim the payment, and no timer decides the outcome.

• Proposals. Each party proposes buyer_amount, what the buyer gets back out of the amount: 0 sends everything to the seller (less the fee), the full amount refunds the buyer, anything between is a split. Either party may change its proposal at any time; the deal settles the moment both match (settlement_reason: MUTUAL_SETTLEMENT, event escrow_deal.settlement_proposed for each proposal). settlement.buyer_proposal and settlement.seller_proposal show the current ones.
• Resolver. In a deal that named one, the resolver may rule within resolve_period after the dispute (timeline.resolve_deadline): resolve(buyer_amount, ruling_hash), by the signed criteria only. Its fee comes off the top, and the ruling is what the buyer gets out of the rest (settlement_reason: RESOLVER).
• Deadlock. Without a resolver, or once its window has passed, a dispute without matching proposals is a deadlock (settlement.deadlocked: true). The funds stay locked until both parties propose the same split, the buyer releases or the seller refunds. Neither a timer nor ChainZap can end it.

Money

The service fee is a fixed amount set when the deal is drafted (fee_bps of the amount, by your pilot policy), paid only out of the seller's payout:

• release or the seller's claim: the seller receives the amount minus the fee;
• split: the fee is cut in proportion to the seller's part;
• refund, the buyer's claim or expiry: no fee.

The resolver fee is fixed in the terms and paid only if the resolver decides the dispute. Example: amount 100, resolver fee 5, ruling "buyer 40": the buyer gets 40, the resolver 5 and the seller 55 less the service fee on 55. A settlement by matching proposals, a release or a refund pays the resolver nothing.

balances separates what the contract credited (accrued), what is still to withdraw (claimable) and what has left the contract (withdrawn), each for buyer, seller, fee and resolver. Each party pays the network cost of its own transactions in TRX; ChainZap pays for confirming the funding, closing unfunded deals, crediting excess and pushing payouts.

Create a draft

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

This draft has no resolver. To name one, add "resolver_enabled": true, the resolver ("resolver_id", or your policy's default), its fee in token units and its window after a dispute:

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

A deal with a resolver without these settings answers 422 resolver_settings_required; a deal without one that sends any of them answers 422 resolver_settings_without_resolver. The resolver fee may not exceed the share of the amount your policy allows (422 invalid_resolver_fee).

The same external_reference with the same body returns the same draft (replayed: true); with a different body it answers 409 escrow_reference_conflict. Find a draft later with POST /v1/escrow-deals/lookup. Delivery criteria are two to five objective checks: a dispute is argued against these lines only. Categories are limited to digital deliveries with an objective acceptance test, as enabled by your pilot policy.

POST /v1/escrow-deals/{ref}/versions replaces the terms of a draft (send expected_version); signatures on the previous version stop counting. POST /v1/escrow-deals/{ref}/cancel closes a draft. Neither is possible once both parties signed.

Resolvers

A resolver is optional. A deal that names one names an external resolver your platform registered. A resolver is never ChainZap: its address and every key of its TRON account must not be a ChainZap address or key, nor a key of the deal's buyer or seller.

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 is PLATFORM (operated by your platform) or INDEPENDENT; the parties see it, and that your platform registered the resolver. On live the account is read on chain: it must sign rulings with one key (SINGLE_KEY) or two of three keys whose active permission may only call contracts (MULTISIG_2_OF_3); anything else is refused (resolver_scheme_unsupported, resolver_account_not_activated). On the sandbox the read is best effort; a resolver that cannot sign stays registered but eligible: false.

GET /v1/escrow-deals/resolvers lists your resolvers and the shared ones; each shows key_scheme, signatures_required, eligible and ineligible_reason. POST …/resolvers/{id}/verify reads the account again. POST …/resolvers/{id}/disable stops new deals naming it (deals that already name it keep it); …/enable allows them again after a fresh read on live. A registration cannot be edited: a resolver's identity is part of the terms both parties sign, so a different resolver is a new registration. The fee is not part of the registration: each deal sets its own. Up to 20 active resolvers per network (100 registrations in all); another organization's resolver answers 404 resolver_not_found. The developer portal's escrow tab does the same.

Consent

Send the parties the deal link from links. On the deal page each signs in with the wallet named in the deal, sees every term, and signs one text with TronLink (signMessageV2). The page recomputes the terms hash, the deal id and the text from the terms it shows and refuses to offer a signature if anything differs. Every transaction it offers later is checked against the same terms: the escrow address is read from the factory's own registry, a transfer goes only to that escrow and only for the remaining amount, and a withdrawal only to the signed-in party.

To collect signatures in your own interface, read GET /v1/escrow-deals/{ref}/consent: message is the exact text, params the contract parameters and terms the document (chainzap.escrow.terms/2) whose canonical JSON hash is terms_hash. Relay a signature with POST /v1/escrow-deals/{ref}/consents (version, role, signature). A party whose account is controlled by other keys (permission multisig) approves on chain instead (approveTerms in actions).

Both signatures are verified twice: by the API, and by the factory, which renders the same text itself before it creates the contract. The text names the resolver or Resolver: none, and says what silence and a dispute mean. These are its lines for a deal with a resolver, then for one without:

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

Party transactions

GET /v1/escrow-deals/{ref}/actions?role=BUYER lists what that party can sign now. Each action carries the contract, the function, the ABI-encoded parameters, a fee limit and an energy estimate:

Actions anyone can call are listed under each party's role while they are open. If your own interface builds these transactions, make the same checks before your users sign: the escrow is escrowOf(deal_id) on the factory named in the signed terms, and the token is the factory's. After you relay a transaction, report it with POST /v1/escrow-deals/{ref}/transactions; it counts only when the chain confirms it, and reporting never changes the deal by itself. A report is accepted only while the deal can have that transaction (409 action_not_available) and with at most five pending per party (429 too_many_pending_transactions); a confirmed transaction that is not that call from that party is dropped.

Telegram

links.telegram_invite is a t.me link to the ChainZap bot for this deal; share it with the parties next to the deal link. The bot names no deal details: it opens the deal page in the browser, where every signature and payment happens, and the deal's status in the Telegram Mini App. The status screen shows only deals a party linked from a private chat after signing in with their wallet; nothing can be signed or sent from Telegram. Web and Telegram show the same deal under the same id.

Evidence

POST /v1/escrow-deals/{ref}/evidence adds a text note and PUT /v1/escrow-deals/{ref}/evidence/files?purpose=DELIVERY&file_name=log.pdf a file (PDF, PNG, JPEG, WebP or plain text, up to 10 MiB). Items you add are labelled as submitted by the platform: they show who sent them, not that a delivery happened. Each item keeps its SHA-256, author and time; a replacement is a new item. When a party marks delivery or opens a dispute, the hash of their evidence set is recorded on chain. File contents are deleted after the retention period; the hashes stay.

GET /v1/escrow-deals/{ref}/dispute returns the criteria, both sides' evidence and the dispute deadlines.

Events and webhooks

Every change becomes an event: 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 and evidence_added. Deadline reminders go to the parties by Telegram, not to the webhook.

Set one endpoint per environment with PUT /v1/escrow-deals/webhook ({"url": "https://..."}); the response shows the signing secret once. The endpoint must be HTTPS on port 443 at a public address; redirects are not followed. Each delivery is a POST with:

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"])

Answer 2xx within 10 seconds. Failed deliveries are retried with growing pauses (30 seconds up to 12 hours, 12 attempts). Delivery is at least once and not in order: deduplicate by X-ChainZap-Event-Id and use sequence to order. GET /v1/escrow-deals/events?after=<sequence> is the full feed to catch up after downtime; POST /v1/escrow-deals/events/{event_id}/redeliver sends one again, POST /v1/escrow-deals/webhook/test sends a signed escrow.ping, POST /v1/escrow-deals/webhook/rotate-secret replaces the secret and DELETE /v1/escrow-deals/webhook stops deliveries.

What changed in protocol v2

New deals use contract and terms version 2. If you integrated with the first pilot version:

• Draft request. dispute_enabled is now resolver_enabled: every deal can be disputed, only the resolver is optional. With a resolver send resolver_id, resolver_fee and timeline.resolve_period_seconds. timeline.response_period_seconds and timeout_outcome are gone: there is no seller answer window and no outcome by timeout in a dispute.
• Deal response. New: protocol_version, resolver.fee, timeline.resolve_deadline, settlement (proposals and deadlocked, while disputed), funding (while awaiting funds) and resolver in each of balances.accrued, claimable and withdrawn. timeline.if_nobody_acts is now {at, outcome, claim_by}. Gone: dispute_enabled, timeline.response_period_seconds, timeline.seller_response_deadline and timeline.seller_responded. settlement_reason may be MUTUAL_SETTLEMENT; TIMEOUT_NO_RULING appears only on archived deals.
• Funding and deadlines. Funding is a direct transfer and confirmFunding instead of an allowance and fund. After a delivery or inspection deadline the buyer or the seller claims the money; nothing settles by timeout.
• Actions. New: TRANSFER_FUNDS, CONFIRM_FUNDING, CLAIM_REFUND, CLAIM_RELEASE, PROPOSE_SETTLEMENT, EXPIRE and SWEEP_EXCESS. Gone: APPROVE_TOKEN, FUND, RESPOND, PROCESS_TIMEOUT and CREDIT_EXCESS.
• Events. New: escrow_deal.settlement_proposed and escrow_deal.excess_credited. Gone: escrow_deal.seller_responded.
• Terms. chainzap.escrow.terms/2 adds rules: "chainzap.escrow.rules/2" and resolver.fee, and drops timeout_outcome and timeline.response_period.
• Errors. New: resolver_settings_required, resolver_settings_without_resolver, invalid_resolver_fee and invalid_buyer_amount. Gone: invalid_simple_deal, dispute_settings_required, dispute_settings_without_disputes, disputes_disabled and invalid_timeout_outcome.

Deals created before version 2 keep protocol_version: 1. They are archived: the API and the deal page show them read-only from ChainZap's record, and nothing acts on them.

Errors

All errors use the common format. Escrow requests are limited to 16 KiB of JSON; an evidence file to 10 MiB.

Sandbox

Sandbox keys work on the TRON Nile test network with the test token labelled "ChainZap TEST USD (NO VALUE)". The flow, the pages and the webhooks are the same as live, and the sandbox policy may allow a shorter inspection period to try the flow; no real funds can be involved. Live deals use USDT on TRON mainnet only for pilot organizations, with an allowlist of participants and caps per deal and in total.

GET /v1/usage

Request

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 is an integer from 1 to 90; the default is 30. This read does not need an idempotency key. Read the X-Request-ID response header. A usage request is rate-limited but does not use checks. Retry only errors marked retryable and respect Retry-After.

Quota for the current period

period.start and period.end delimit the current billing period: the paid period anchored to the confirmed payment, or the UTC calendar month for an organization without a paid plan.

A reservation is released when a request finishes without a charge. balances adds extra checks and the total available; subscription describes the paid period; status: "legacy" with plan: null means your organization's limits were set by agreement (for example a pilot contract) rather than by a self-serve plan, and the limits shown are the ones that apply. See plans and payment. environment is live or sandbox, depending on the key. All API keys of the organization and requests made in the developer dashboard share the same quota.

Statistics for the selected window

recent counts completed logical checks during the requested rolling window of days days. Idempotent HTTP replays are not new check records. It includes charged, error and LIMITED_DATA counts, average latency, networks and the overall-state distribution. It contains no transaction hashes or provider details.

The developer dashboard adds UTC daily buckets, 1/7/30-day counters and p50/p95 latency when at least 20 completed latency samples exist in the last 30 days. Successful-response counts include partial responses; limited coverage is a subset, not an additional total.

The usage chart compares completed requests with charged checks for 7, 30 or 90 days. Hover over the chart, tap it or use the day slider with the arrow keys to inspect exact values. Days without checks show zero; the first and last UTC days may be partial. Live and Sandbox are separate views. The daily table remains available below the charts. The allowance bar shows included checks for the current billing period; extra packages are listed in Plan and billing.

Developer dashboard and plans

After signing in to the developer dashboard, open /dashboard/usage/ for quota counters, daily tables, result distribution and latency statistics. /dashboard/plan/ shows the current plan, monthly quota, requests per minute and the concurrency limit. Networks entitled by the plan and networks currently enabled for checks are displayed separately; an enabled flag is not a live provider health check.

The Playground page accepts automatic network detection or an explicit TRON, Ethereum or TON selection within your available networks. Its checks use the same organization quota and idempotency rules as the server API.

Plans and extra checks packages are bought on the Plan and billing page; see plans and payment. Renewal is manual: there is no automatic charge, invoicing or API wallet. Consumer Mini App subscriptions do not grant B2B API quota. Public documentation does not require sign-in.

Plans, checks and payment (beta)

What you pay for

A check is one API check of a transaction. You pay for a complete, final check only: a response with coverage: complete and a state of CLEAR, REVIEW or HIGH_RISK for a transaction that is confirmed past its finality policy or failed for good. A risky result is a useful result and is charged. A pending transaction, a transaction that was not found, LIMITED_DATA, transport errors, timeouts, quota errors and idempotent replays are not charged on either endpoint; their reservation is released. A successful HTTP response is not the same as a charged check.

Beta plans (pricing policy BETA_PRICING_V0)

A plan gives your organization a number of included checks per billing period.

Prices are in US dollars. GET /v1/catalog publishes them in integer minor units (cents). These are preliminary beta terms and may change for future billing periods; an order or a billing period that is already paid keeps the terms it was sold under. Request-rate and concurrency limits are preliminary until general availability. Scale is agreed individually and is not sold online.

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

Billing periods and renewal

A paid billing period starts when the payment is confirmed on the server and lasts one calendar month (31 January runs to 28 or 29 February; the anchor day returns afterwards). Renewal is manual: nothing is charged automatically. Paying early schedules the next billing period to start when the current one ends; paying after a gap starts a new billing period immediately. A different plan applies from the next billing period; the current paid period is never reset. Included checks do not carry over.

Extra checks packages

An extra checks package adds checks on top of the included checks. A package contains 100 to 10 000 checks in steps of 50 and costs the extra-check price of your current plan. Extra checks are valid for 12 months from purchase, are used only after the included checks, and can be used only while a paid plan is active. While the plan is inactive they are frozen, not lost. The price is fixed at purchase and is not recalculated by later catalog changes.

Payment

Purchases are made in the developer dashboard by owner, admin and billing members, never with an API key. Payment is in cryptocurrency. Check the total and choose Pay with crypto: the payment page opens, where you pay the exact total in USDT or another coin offered there. The total is fixed in US dollars, and the page stays payable for the order's validity time, at least 15 minutes. If you leave it, the order on the Plan and billing page takes you back to it or cancels the order. Checks are granted only after the server confirms the payment with the payment provider itself: the wallet's own response, a screenshot or returning to the dashboard page does not grant anything. A payment page cannot be withdrawn, so money sent after you cancel an order or after it expires is still credited when it can apply and reviewed by support otherwise. A duplicate or partial payment is recorded and reviewed by support; it is never granted twice.

Balance in the 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 keeps its meaning: the included checks left in the current billing period. balances.extra shows extra checks, balances.total_available shows the total that a new check can draw on, and balances.included.reserved shows checks that are still running. subscription reports the billing period, the plan and the manual renewal. The X-Quota-Available header carries the total on check responses. A balance does not override a suspended organization, a network that is not enabled or an inactive plan: 429 quota_exceeded is returned when nothing is available.

Refunds and disputes

Support handles refunds case by case and records them as separate events: the unused remainder of a grant is reversed, checks already used are not clawed back, and the available balance never goes below zero.

Sandbox

Sandbox keys start with cz_test_. They are created in the developer dashboard or by your organization's operator. They call the same endpoints with the same request and response schemas, but never reach data providers, never cost anything and never touch your paid checks. Every sandbox success carries environment: "sandbox", and so does every error the check itself returns (for example provider_unavailable, network_not_enabled, quota and rate limits): branch on that field. A refusal before the check starts (401, 403 tenant_suspended, 503 api_disabled, the per-IP 429 applied before the key is read, 413, 415, a 422 request validation error, invalid_idempotency_key) carries no environment, and an unexpected 500 or 504 may carry none; there the key you sent tells the environment. POST /v1/check and the wallet check also carry details.evidence.source: "sandbox"; POST /v1/transaction/check has no details, and its evidence items name the same source roles as a live answer, so rely on environment. Treat such a result as a fixture, never as an observation. Each fixture explains itself with the same reason_codes the live engine emits, so the branches you write against the sandbox are the branches production takes.

Deterministic outcomes

The first character of the transaction hash selects the outcome, so you can exercise every state on purpose:

The sandbox fabricates only what a provider would return. The comparison with your expectations, the status axes, the evidence items and the reasons come from the live engine, so a sandbox answer has the shape and the rules of a live one, contract 0.3 fields included. With the obligation ledger on, sandbox checks, obligations and batches are recorded in a sandbox ledger kept apart from the live one.

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

Without network, the sandbox answers for TRON when TRON is enabled for your organization, otherwise for the first network you have. As in live discovery, the shape of the hash (0x, base64) never selects the network. Send network explicitly to see whether a network is enabled: it answers 403 network_not_enabled in the sandbox exactly as it does live. Base64 TON hashes use the top four bits of the first byte.

Allowance and isolation

The sandbox spends its allowance on exactly what a live check is charged for: a complete, final result. A pending one, a partial one, an absent transaction and the outage fixture cost nothing, as in production; the failed fixture (d) is final and is charged, as a live failed transaction is. If your organization is on the pilot contract, sandbox keys are refused the same way live keys are (expected_fields_required, token_not_enabled, check_kind_not_enabled). expected_recipient, expected_token and expected_amount are compared against the fixture and a mismatch is never CLEAR, so the branch you test is the branch production takes; a nonzero digit beyond the token's decimals answers 422 invalid_expected_amount, as live. Sandbox checks draw on a separate allowance of 50 test checks per UTC calendar month; GET /v1/usage with a sandbox key reports that allowance with environment: "sandbox". Idempotency keys, quota and usage statistics are separate per environment: the same Idempotency-Key in the sandbox and in the live environment are two different operations. A sandbox key cannot buy anything and does not prove that a live network is enabled for your organization.

Wallet fixtures

For POST /v1/wallet/check the sandbox picks the outcome from a hash of the normalised address, so it cannot be steered by the first character. Use one of the pinned addresses below; each row is stable across releases and checked by the test suite.

Every wallet fixture carries environment: "sandbox" and details.evidence.source: "sandbox", explains itself with the same reason codes as the live engine, and spends the sandbox allowance exactly as a live wallet check spends quota: when a state is produced.

Integration examples

These retry examples and response fixtures use the canonical contract 0.3 POST /v1/transaction/check endpoint with an explicit network. For the shorter /v1/check request and its short response, see one hash check. Both endpoints use the same retry and quota rules.

A successful HTTP response must be evaluated on separate axes: verification_final with integrity_status for payment comparison; risk_status, risk_final and recommended_action for risk and action. Pending never means MATCH; final MATCH with insufficient KYT requires MANUAL_REVIEW. Risk retries use risk_retryable and risk_retry_after_seconds, not verification retryable. See status axes.

Python: idempotent retry

This server-side example uses httpx. The key is fictional. In a real integration, load the API key from your server's secret store and persist operation_key and body in your own operation ledger before the first attempt. After a process restart, reuse both.

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)

The loop handles retryable 409/429/503/504 responses and network uncertainty without creating another logical operation. Handle the returned business states according to your payment workflow. Do not log body or the entire result.

JavaScript / TypeScript: server request

Use this code on your server, never in a browser with a live key. The operation key and body must be persisted before calling the function, just as in the Python example.

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

Response scenarios

The following synthetic fixtures illustrate valid response shapes, not live checks. Every sample has an X-Request-ID header equal to its request_id. Inspect null values and coverage as well as the overall state.

Confirmed transaction

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