Transaction Decision API

Periksa transaksi sebelum mengonfirmasi pembayaran

ChainZap memeriksa transaksi blockchain sebelum aplikasi Anda mencatat pembayaran sebagai diterima. Satu respons menggabungkan fakta transaksi, sinyal risiko, dan, jika Anda meminta, perbandingan dengan penerima, token, dan jumlah yang Anda harapkan.

Apa yang dapat diperiksa

Adaptor TRON, Ethereum mainnet, dan TON mainnet telah diimplementasikan. Pemeriksaan TRON langsung tersedia untuk setiap organisasi baru. TON berstatus pratinjau dan pemeriksaannya atas transaksi yang sudah dieksekusi saat ini menghasilkan LIMITED_DATA; pemeriksaan Ethereum diaktifkan oleh dukungan atas permintaan. Masuk dengan akun ChainZap ke dasbor pengembang, buat kunci API, dan mulai dari quickstart transaksi kanonis.

• POST /v1/transaction/check: respons terperinci kanonis kontrak 0.3. Jaringan wajib; rincian pembayaran yang diharapkan memungkinkan verifikasi.
• POST /v1/check: kirim hash transaksi. Jaringan dan rincian pembayaran yang diharapkan bersifat opsional. Respons berisi penilaian ringkas dengan bukti lengkap pada details.
• POST /v1/wallet/check: kirim alamat dompet. Jaringan dikenali dari formatnya. Respons berisi status, tingkat cakupan, dan kode alasan dengan fakta per modul pada details; lihat pemeriksaan dompet.
• GET /v1/usage: kuota dan statistik penggunaan organisasi Anda.

Panggil API dari server Anda dan kirim kunci API pada header X-API-Key.

Baca seluruh respons

Respons HTTP yang berhasil tidak berarti pembayaran sudah terkonfirmasi atau bebas risiko. Untuk /v1/check, baca state, risk_level, dan coverage bersama status transaksi, hasil pencocokan, waktu data, dan alasan pada details. Endpoint kanonis /v1/transaction/check mengembalikan kolom terperinci tersebut di tingkat teratas respons. Nilai null berarti tidak diketahui atau tidak diminta, bergantung pada kolomnya. Jangan pernah menganggap data yang hilang sebagai hasil bersih.

Lanjutkan ke panduan awal, lalu baca kelengkapan data dan idempotensi.

Pemeriksaan transaksi pertama Anda

Dapatkan akses

Masuk dengan akun ChainZap ke dasbor pengembang. Organisasi dibuat otomatis untuk Anda dan Anda menjadi pemiliknya; kode undangan hanya diperlukan untuk bergabung ke organisasi yang sudah ada. Buat kunci di halaman Kunci API dan simpan di penyimpanan rahasia server. Pemeriksaan TRON langsung tersedia: kunci sandbox memungkinkan pengujian gratis, dan paket untuk pemeriksaan live dibeli di halaman Paket dan pembayaran. Hubungi dukungan untuk mengundang rekan ke organisasi Anda.

Kirim permintaan pertama

Contoh ini menggunakan kunci dan hash transaksi fiktif. Ganti keduanya di server Anda. Semua jumlah berupa string desimal. Simpan kunci idempotensi bersama operasi pembayaran agar tetap ada setelah proses dimulai ulang.

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

Baca X-Request-ID pada header respons dan request_id pada JSON. Simpan pengenal ini untuk dukungan. Endpoint kanonis ini memerlukan network. Baca sumbu status sebelum menggunakan hasil; POST /v1/check menyediakan respons ringkas opsional.

Cocokkan dengan rincian pembayaran

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

Alamat dalam contoh adalah alamat publik untuk ilustrasi, bukan tujuan pengiriman dana. Cocokkan kontrak token yang tepat, bukan simbolnya. Baca ketiga hasil pencocokan; semuanya mengacu pada transfer terpilih yang sama. Lihat pencocokan pembayaran.

Gunakan kontrak 0.3

Gunakan verification_final dan integrity_status untuk verifikasi pembayaran, lalu nilai risk_status dan recommended_action secara terpisah. Pending bernilai NOT_EVALUATED, tidak pernah MATCH. MATCH final dengan risk_status: INSUFFICIENT mengonfirmasi perbandingan pembayaran tetapi memerlukan MANUAL_REVIEW, bukan kredit otomatis atau persetujuan pembayaran. Baca risk_retryable terpisah dari retryable. Contoh respons menampilkan cabang ini.

Menutup pembayaran keluar secara otomatis

Tanpa konteks dari sisi Anda, MATCH final dengan risk_status: NO_MATERIAL_SIGNAL dan tanpa alasan untuk ditinjau menghasilkan CONFIRM_INTERNAL_STATE: blockchain dan penyaringan risiko beres, tetapi ChainZap tidak dapat melihat apakah pembayaran ini memang yang wajib Anda bayar atau apakah sudah diselesaikan. Ini bukan penolakan: pastikan di catatan Anda sendiri bahwa pembayaran itu masih terutang dan belum ditandai lunas, lalu tutup. Tindakan yang sama tanpa MATCH (kolom yang diharapkan tidak dikirim) belum membandingkan pembayaran: jangan tutup pembayaran keluar berdasarkan itu.

Untuk mencapai PROCEED, beri tahu ChainZap untuk apa pembayaran ini: kirim direction: "OUTGOING", workflow_type: "PAYOUT", dan external_reference pembayaran bersama kolom yang diharapkan, atau catat kewajiban terlebih dahulu lalu kirim external_reference-nya dalam pemeriksaan. Kecocokan final yang bersih terhadap kewajiban keluar yang tercatat itu adalah PROCEED; tanpa external_reference jawaban terbaik tetap CONFIRM_INTERNAL_STATE, kecuali pemeriksaan juga mengirim customer_context.credit_status: "NOT_CREDITED", yang saja sudah cukup untuk PROCEED kecuali allocation_status bernilai UNKNOWN (lihat sumbu status). direction dan workflow_type diterima tanpa buku besar kewajiban, tetapi sendiri saja tidak pernah mencapai PROCEED; dengan direction: "OUTGOING", pembayaran yang tidak ditemukan juga membawa ATTEMPT_MAY_STILL_LAND: jangan bayar lagi. external_reference dan kolom kewajiban lainnya memerlukan buku besar kewajiban dan dijawab 403 ledger_not_enabled jika buku besar itu tidak aktif.

Tangani ketidakpastian

Jika koneksi terputus sebelum respons diterima, kirim ulang isi permintaan dan Idempotency-Key yang sama. Jangan membuat kunci baru untuk menghindari hasil yang belum pasti. Ulangi galat yang diterima hanya bila error.retryable bernilai true; patuhi Retry-After dan batasi jumlah percobaan. Galat yang sudah disimpan dapat dikembalikan tanpa perubahan: retryable tidak memaksa pemeriksaan penyedia yang baru.

Lihat contoh Python dan TypeScript untuk pengulangan terbatas, serta penggunaan untuk memeriksa kuota.

Periksa dompet juga

Kunci yang sama dapat menyaring alamat pihak lawan: POST /v1/wallet/check dengan {"address": "..."} mengembalikan status, cakupan, dan kode alasan dalam bentuk yang sama, dan ditagih saat status dihasilkan. Lihat pemeriksaan dompet.

Satu hash, satu pemeriksaan

POST /v1/check hanya memerlukan tx_hash. API melaporkan fakta, risiko, dan kekurangan data; keputusan pembayaran tetap berada pada aplikasi Anda. Masuk dengan akun ChainZap ke dasbor pengembang dan buat kunci server di halaman Kunci API.

Hasil pertama

Atur CHAINZAP_API_KEY, TX_HASH, dan ID operasi tersimpan CHECK_ID di server Anda. Contoh ini mengirim satu permintaan hanya saat dijalankan. Untuk data uji tanpa panggilan penyedia, gunakan kunci sandbox. Jangan pernah menempatkan kunci dalam kode browser. Permintaan membutuhkan kurang dari sepuluh baris kode aplikasi; periksa status HTTP sebelum menafsirkan hasilnya.

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

Penentuan jaringan

Nama jaringan yang diterima adalah tron, eth, dan ton; alias ditolak. Jaringan eksplisit membatasi pencarian pada jaringan itu saja. Bentuk hash, awalan 0x, base64, dan urutan respons penyedia tidak pernah menentukan jaringan, termasuk di sandbox.

Tanpa network, fakta dibaca hanya pada jaringan yang didukung, diaktifkan, dan diizinkan untuk organisasi Anda. Lingkup pencarian dilaporkan di details.checked_networks; hasil unik dalam lingkup ini tidak membuktikan apa pun tentang jaringan lain. Pemeriksaan AML tidak dijalankan di semua jaringan. Semua jaringan lain yang diperiksa harus memastikan transaksi tidak ditemukan. Kegagalan penyedia, indeks yang belum lengkap, dan waktu habis tidak dihitung sebagai ketidakadaan. Satu hasil positif ditambah satu hasil tidak diketahui tetap memerlukan network.

Deteksi otomatis memakai batas panggilan penyedia yang sama dengan pemilihan jaringan secara eksplisit, baik untuk satu jaringan maupun beberapa. Penyedia tetap harus mengonfirmasi bahwa hash transaksi ditemukan di jaringan yang dilaporkan. Panggilan yang harganya belum dikonfigurasi dihitung sebagai biaya tidak diketahui, bukan nol.

NETWORK_AMBIGUOUS berarti transaksi ditemukan di beberapa jaringan. NETWORK_REQUIRED berarti konteks yang tersedia belum cukup untuk membuktikan satu hasil: misalnya satu jaringan menemukannya sementara jaringan lain tidak dapat menjawab, atau tidak ada jaringan aktif. Bila semua jaringan yang diperiksa memastikan transaksi tidak ada, jawabannya 404 transaction_not_found. Keduanya memakai HTTP 422, state: insufficient_input, network: null, error.retryable: false, error.required_field: network, error.candidates, dan error.checked_networks. Tentukan jaringan dan gunakan kunci idempotensi baru. Mengulang isi yang sama akan mengembalikan galat tersimpan yang sama.

Respons ringkas dan terperinci

state adalah details.overall_state dalam huruf kecil. Objek alasan terperinci berada di details.reasons; string dan objek tidak pernah dicampur. Risiko tinggi yang diketahui tetap terlihat saat cakupan parsial. null pada perbandingan yang diminta berarti belum selesai. Semua kolom expected_* harus cocok dengan transfer yang sama; beberapa kecocokan lengkap berarti ambigu.

Endpoint kanonis /v1/transaction/check mempertahankan status huruf besar, coverage: complete atau partial, dan 2 sampai 5 objek alasan. /v1/usage dan X-API-Key tidak berubah. /v1/check mengembalikan HTTP 404 transaction_not_found untuk ketidakadaan yang terverifikasi pada jaringan eksplisit; endpoint kanonis tetap mengembalikan HTTP 200 transaction_state: not_found. Pemeriksaan yang tertunda menghasilkan HTTP 200 dengan review/limited_data, tidak pernah clear, dan tidak ditagih. Kedua endpoint memakai batas, kuota, dan biaya yang sama. Kunci idempotensi dibagi per organisasi: berganti endpoint atau mengubah isi menimbulkan konflik. Hasil tersimpan, termasuk jaringan yang ditentukan dan galat yang dijawab setelah pemeriksaan diterima, di-replay tanpa pemeriksaan penyedia baru; 429 dan 5xx tidak pernah disimpan. Replay memeriksa ulang akses.

Cakupan Ethereum dan TON

Transfer ETH native internal memerlukan trace eksekusi dan berada di luar lingkup versi ini. Log ERC-20 tidak menetapkan perubahan saldo bersih penerima untuk token fee-on-transfer atau rebasing. Mint, burn, dan transfer bernilai nol memerlukan review. Decimals yang tidak diketahui membuat amount: null; simbol tidak pernah membuktikan keaslian. Token lain dapat memiliki fakta transfer dengan cakupan keaslian/KYT yang belum lengkap.

TON hanya menerima hash transaksi: 64 digit hex dengan 0x opsional atau base64/base64url kanonis sepanjang 32 byte. Hash pesan atau BOC tidak ditafsirkan ulang secara diam-diam sebagai hash transaksi. Checksum alamat friendly diperiksa; bounceable/non-bounceable dinormalisasi ke workchain/account, sedangkan alamat test-only ditolak. expected_token berarti jetton master, expected_recipient berarti pemilik wallet. Satu transfer_notification tidak cukup. Bounce, kegagalan compute/action, keturunan yang hilang, dan emulasi tidak dapat menghasilkan clear. Hasil get-method terkini diperiksa silang dengan indeks kedua; perubahan identitas historis memerlukan pemeriksaan lanjutan. Finalitas berasal dari pernyataan penyedia, bukan verifikasi lokal tanda tangan validator.

Pemeriksaan Ethereum dan TON diaktifkan per organisasi oleh dukungan setelah pengujian langsung. Penyaringan AML mencakup aset yang didukung sumber AML pada tiap jaringan; hak akun tertentu, biaya aktual, dan cakupan masih perlu diverifikasi langsung. Bukti AML atau sanksi yang tidak tersedia tidak pernah menjadi low/clear. Lihat kelengkapan data.

Contoh respons deterministik

Ini fixture ilustratif, bukan pengamatan langsung. Buka JSON lengkap di bawah.

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

Autentikasi

Satu akun ChainZap

Pilih Masuk dengan akun ChainZap dan gunakan akun yang sama dengan aplikasi. Dari Pengaturan → API pengembang → Dasbor, sesi aktif di browser yang sama dilanjutkan tanpa masuk lagi. Organisasi, kunci API, dan kuota API dikelola terpisah dari kredit pribadi di aplikasi. Akun portal Google yang sudah ada ditautkan melalui identitas Google yang terverifikasi, bukan kecocokan alamat email.

Anda tidak perlu kode undangan untuk masuk. Undangan hanya digunakan untuk bergabung dengan organisasi yang sudah ada. Jika Telegram membuka browser lain yang belum memiliki sesi ChainZap, masuk sekali dengan akun yang sama. Tautkan Google dan Telegram di pengaturan akun aplikasi sebelum menggunakannya secara bergantian.

Kunci API server

Kirim X-API-Key melalui HTTPS pada setiap permintaan ke API bisnis. Jangan pernah menempatkan kunci di URL, penyimpanan browser, analitik, pesan dukungan, atau kontrol sumber. Satu kunci memberikan akses ke satu organisasi; permintaan tidak dapat memilih organisasi lain.

Masuk ke dasbor pengembang terpisah dari kunci API. Kunci live diawali cz_live_; kunci sandbox diawali cz_test_.

Peran di portal:

• Anggota dengan peran owner, admin, dan developer membuat, mengganti, dan mencabut kunci API.
• Anggota dengan peran owner, admin, dan billing melihat riwayat pembayaran, membeli paket dan paket pemeriksaan tambahan, serta mengelola langganan.
• Anggota dengan peran viewer hanya melihat statistik dan metadata kunci.

Kunci API tidak dapat membeli apa pun.

Siklus hidup kunci

Beri setiap integrasi kuncinya sendiri dengan nama yang jelas. Kunci lengkap hanya ditampilkan satu kali, saat dibuat atau diganti; daftar kunci menampilkan awalannya saja. Penggantian mencabut kunci lama dan membuat penggantinya dalam satu operasi. Perbarui penyimpanan rahasia server segera setelah penggantian. Untuk perpindahan terencana tanpa gangguan, buat kunci terpisah terlebih dahulu, pindahkan integrasi ke kunci itu dan pastikan berfungsi, lalu cabut kunci sebelumnya.

Galat akses

• 401 invalid_api_key: kunci tidak valid atau sudah dicabut.
• 403 tenant_suspended: organisasi ditangguhkan.
• 403 network_not_enabled: jaringan yang diminta tidak diaktifkan untuk organisasi.

Perbaiki akses terlebih dahulu. Mengulang permintaan yang sama tanpa perubahan tidak membantu.

POST /v1/transaction/check

Permintaan

Permintaan JSON ketat ini memerlukan network dan tx_hash 32 byte. Kolom yang tidak dikenal ditolak. Alamat yang diharapkan divalidasi dan dinormalisasi sesuai jaringan terpilih. expected_amount berupa string desimal nonnegatif; angka JSON dan notasi eksponen ditolak. Untuk konteks jaringan opsional dan respons ringkas, gunakan POST /v1/check.

Format alamat dan aturan perbandingan tepat ada di pencocokan pembayaran. Isi permintaan dibatasi 4 KiB; isi yang lebih besar ditolak dengan 413 payload_too_large. Organisasi dengan kontrak pilot wajib mengirim ketiga kolom expected_*.

Kirim Content-Type: application/json, X-API-Key dari server, dan Idempotency-Key untuk operasi pemeriksaan logis. X-Request-ID menghubungkan permintaan dengan catatan operasi Anda sendiri. Referensi API memuat kolom wajib, enum, dan skema respons yang tepat.

Respons

Baca transaction_state terpisah dari overall_state. Respons mencakup jumlah konfirmasi, transfer yang dinormalisasi, transfer terpilih, tingkat risiko, status sanksi, keaslian token, hasil pencocokan, cakupan, waktu data, dan 2 sampai 5 alasan yang diprioritaskan. Jumlah transfer dan paparan berupa string desimal. Tangani kolom bernilai null secara eksplisit.

transfers_truncated=true berarti daftar transfer dipersingkat. AMBIGUOUS_TRANSFER berarti beberapa transfer memenuhi syarat Anda. Keduanya perlu diperhatikan. Jangan menganggap daftar yang dipersingkat sudah lengkap dan jangan menggabungkan hasil pencocokan dari transfer yang berbeda.

Gunakan kontrak 0.3

Gunakan verification_final dan integrity_status untuk verifikasi pembayaran, lalu nilai risk_status dan recommended_action secara terpisah. Pending bernilai NOT_EVALUATED, tidak pernah MATCH. MATCH final dengan risk_status: INSUFFICIENT mengonfirmasi perbandingan pembayaran tetapi memerlukan MANUAL_REVIEW, bukan kredit otomatis atau persetujuan pembayaran. Baca risk_retryable terpisah dari retryable. Contoh respons menampilkan cabang ini.

Penagihan

Respons final dengan coverage: complete memakai satu pemeriksaan dari kuota, termasuk hasil lengkap yang berisiko tinggi: transaksi sudah terkonfirmasi melewati kebijakan finalitasnya, atau gagal secara permanen. Transaksi yang tertunda, transaksi yang tidak ditemukan, dan respons dengan coverage: partial tidak ditagih. Mengulang operasi idempoten yang sama tidak pernah ditagih dua kali.

expected_token adalah alamat kontrak, bukan simbol; nama lama expected_token_contract tetap diterima. Kirim hanya satu nama. Respons memuat schema_version: "0.3", policy_version (kebijakan keputusan yang menghasilkan respons; simpan bersama respons), tiga penanda risiko/sanksi terpisah, workflow_coverage, dan source_coverage. Baca cakupan sebelum menafsirkan hasil. Kunci idempotensi yang dipakai sebelum kontrak 0.2 menghasilkan 409 idempotency_conflict; gunakan kunci baru setelah menangani hasil lama.

Periksa dompet sebelum Anda menerimanya atau membayarnya

POST /v1/wallet/check menyaring satu alamat dengan cara yang sama seperti POST /v1/check menyaring satu transaksi: kunci yang sama, kuota yang sama, aturan idempotensi yang sama, dan bentuk jawaban yang sama. Kirim alamat, terima status, tingkat cakupan, dan kode alasan, lalu putuskan dalam alur kerja Anda sendiri apakah pihak lawan perlu diperiksa lebih lanjut.

Permintaan

Ketiga format tidak mungkin tertukar satu sama lain, sehingga pemeriksaan dompet tidak pernah menjawab NETWORK_REQUIRED atau NETWORK_AMBIGUOUS. String yang tidak cocok dengan format mana pun menghasilkan 422 invalid_address. Kolom yang tidak dikenal ditolak dan isi permintaan dibatasi 4 KiB. Kirim Content-Type: application/json, X-API-Key sisi server, dan Idempotency-Key untuk operasi logis; X-Request-ID menghubungkan permintaan dengan log Anda sendiri.

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

Alamat dalam contoh adalah alamat publik untuk ilustrasi, bukan tujuan pembayaran. Respons mengembalikan address dalam ejaan kanonik: Ethereum dalam huruf kecil, TON sebagai workchain:hash, TRON tanpa perubahan.

Respons

Baca tingkat teratas lebih dulu, lalu details.

details menjelaskan dari mana status berasal:

• overall_state dan data_coverage: status dalam huruf kapital dan istilah cakupan dari mesin analisis sendiri, FULL, PARTIAL, atau INSUFFICIENT.
• modules: tujuh baris dalam urutan tetap, sanctions_aml, wallet_behaviour, token_authenticity, contract_controls, address_security, counterparties_services, flows_connections. Setiap baris memiliki status (RISK_DETECTED, NO_MATCHES_FOUND, PARTIALLY_CHECKED, INSUFFICIENT_DATA, NOT_SUPPORTED, NOT_CHECKED) dan source_coverage (complete, partial, none, not_applicable). Modul yang tidak disaring menyatakannya secara terbuka; modul itu tidak pernah dilaporkan bersih.
• sanctions: direct_match terhadap indeks OFAC, EU, UK, dan UN yang dikonfigurasi (null jika tidak ada indeks yang disaring), otoritas pencatatan pada authorities, apakah pencatatan itu attributed, dan indirect_exposure yang dilaporkan penyedia AML (null jika penyedia tidak dijalankan).
• address_security: status dan kategori pada daftar hitam publik, provider_flagged (apakah penyedia keamanan alamat menandai alamat ini; null bila penyedia tidak menjawab atau haknya tidak mengizinkan ChainZap menampilkannya), dan apakah penerbit stablecoin telah membekukan alamat. Label milik penyedia tidak pernah dikembalikan; provider_flags yang usang berisi ["PROVIDER_SECURITY_FLAG"] ketika provider_flagged bernilai true dan kosong selain itu.
• behaviour: apakah alamat adalah kontrak, jumlah transaksi dan apakah jumlahnya dibatasi, usia dompet, aktivitas pertama dan terakhir, serta jumlah pihak lawan.
• counterparties dan token_authenticity: berapa banyak pihak lawan yang disaring, belum terverifikasi, atau ditandai, dan berapa banyak token yang dipegang tergolong resmi, palsu, mencurigakan, atau tidak dikenal.
• freshness dan source_coverage: kapan pemeriksaan berjalan, apakah analisis berasal dari cache analisis (5 menit di Ethereum, 30 menit di TRON dan TON; jawaban penyedia AML dipakai ulang hingga 24 jam), usia sumber tertua, dan satu pengamatan per sumber dengan kosakata status yang sama seperti pemeriksaan transaksi. Sumber dinamai menurut perannya: 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.

Semua kode alasan dompet beserta artinya tercantum di kode alasan.

Apa yang bukan merupakan pemeriksaan dompet

Tidak ada skor numerik di mana pun dalam respons, dan itu disengaja. Angka mengundang ambang batas, dan tidak ada ambang batas yang jujur untuk tiga jaringan dengan sumber yang berbeda. Respons memberi tahu apa yang ditemukan, apa yang disaring, dan apa yang tidak dapat disaring. Ini bukan sertifikat kepatuhan dan tidak mengetahui aturan internal bursa atau bank mana pun. Pahami clear sebagai "tidak ada temuan kritis pada sumber yang disaring", review sebagai "periksa lebih lanjut sebelum melanjutkan", high_risk sebagai "ada temuan kritis yang harus diselesaikan", dan limited_data sebagai "kami tidak dapat memastikan".

Penagihan

Pemeriksaan dompet menggunakan satu pemeriksaan dari kuota Anda saat menghasilkan status: clear, review, atau high_risk, dengan cakupan lengkap maupun sebagian. limited_data gratis, begitu pula galat, batas waktu, dan replay idempoten. Ini berbeda dari pemeriksaan transaksi yang hanya ditagih pada cakupan lengkap: penyaringan dompet sering mencapai keputusan yang tegas meski satu dari lima puluh pihak lawan belum teratribusi, sementara sumber berbayar sudah menjawab. Kunci sandbox tidak pernah menggunakan pemeriksaan berbayar.

Anggaran waktu dan pengulangan

Pemeriksaan dompet yang belum di-cache membaca beberapa penyedia dan memiliki anggaran server 30 detik; gunakan batas waktu klien sekitar 35 detik. Jika server menjawab 504 request_timeout, ulangi dengan isi permintaan dan Idempotency-Key yang sama: analisis tetap berjalan sampai selesai di server dan masuk ke cache bersama, sehingga pengulangan biasanya dijawab seketika dan membawa freshness.served_from_analysis_cache: true. Aturan pengulangan umum berlaku tanpa perubahan.

Idempotensi antar jenis pemeriksaan

Kunci idempotensi dibagi per organisasi dan lingkungan di semua endpoint pemeriksaan. Memakai ulang kunci transaksi untuk isi permintaan dompet, atau kunci dompet untuk alamat lain, menghasilkan 409 idempotency_conflict. Satu operasi logis, satu kunci.

Contoh di sisi server

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

Contoh respons deterministik

Ini fixture ilustratif, bukan pengamatan langsung. Buka JSON lengkap di bawah.

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

Cocokkan transfer dengan rincian pembayaran

Gunakan kolom expected_* untuk memverifikasi penerima, kontrak token, dan jumlah dari pembayaran tertentu. Kirim ketiga kolom atau hanya perbandingan yang Anda perlukan.

Perbandingan berikut berlaku setelah finalitas jaringan. Ketika transaction_status: PENDING, integritas dan setiap perbandingan yang diminta bernilai NOT_EVALUATED, dan semua penanda pencocokan null, meskipun transfer yang diamati memuat nilai yang diharapkan. MATCH final memverifikasi rincian pembayaran terpisah dari KYT; risiko tidak memadai tetap memerlukan MANUAL_REVIEW.

Satu transfer, tiga perbandingan

Satu transaksi dapat berisi beberapa transfer. ChainZap terlebih dahulu mencari transfer yang memenuhi setiap syarat yang Anda kirim. Jika tidak ada, layanan memilih transfer dengan kecocokan terbanyak. Jika hasilnya seri, indeks transfer menentukan pilihan secara konsisten.

recipient_match, token_match, dan amount_match selalu mengacu pada transfer terpilih tersebut. Jika beberapa transfer memenuhi seluruh syarat, respons memuat AMBIGUOUS_TRANSFER. Transfer yang tidak dieksekusi, misalnya transfer dalam transaksi yang dibatalkan (revert), tidak pernah dianggap cocok: ketiga kolomnya bernilai null, dan transaksi gagal yang di dalamnya tidak ada yang dieksekusi bernilai NOT_EVALUATED, tidak pernah LIMITED_DATA karena baris transfer yang tidak ada.

Kontrak 0.3 menyatakan perbandingan secara lengkap di integrity: status (lihat sumbu status), selected_event_ref, relevant_event_count (transfer yang dieksekusi ke penerima yang diharapkan dengan token yang diharapkan), dan comparisons dengan nilai expected dan actual serta result untuk recipient, sender, token, amount, dan network. Hasil untuk jumlah adalah EXACT, WITHIN_TOLERANCE, UNDERPAID, OVERPAID, NOT_EVALUATED, atau INSUFFICIENT, beserta delta dan delta_raw yang bertanda.

Cara nilai dibandingkan

Jika Anda memberikan nilai yang diharapkan tetapi data transfernya tidak tersedia, kolom perbandingan terkait bernilai null, cakupan menjadi parsial (partial), dan alasan menyertakan EXPECTED_DATA_UNAVAILABLE. Misalnya, tanpa jumlah desimal token, API tidak dapat menyatakan bahwa jumlahnya berbeda. Jangan menganggap null sebagai kecocokan yang terkonfirmasi.

Alamat divalidasi dan dinormalisasi sesuai jaringan yang dipilih:

Untuk TON, expected_recipient adalah pemilik dompet dan expected_token adalah jetton master, bukan jetton wallet.

Token dibandingkan berdasarkan kontrak yang tepat, tidak pernah berdasarkan nama atau simbol; simbol yang sama tidak membuktikan token yang sama. Jumlah dikonversi dari string desimal, misalnya "10.000001", menjadi bilangan bulat dalam satuan terkecil token menggunakan decimals yang diketahui, lalu dibandingkan secara tepat tanpa toleransi floating-point. Untuk menerima selisih kecil, kirim amount_tolerance: jumlah absolut dalam satuan token, simetris, bernilai bawaan 0. Selisih dalam batas itu menghasilkan WITHIN_TOLERANCE dan menambahkan AMOUNT_WITHIN_TOLERANCE; toleransi dengan angka desimal lebih banyak daripada decimals token dijawab 422 invalid_amount_tolerance. expected_sender membandingkan alamat pengirim dengan cara yang sama seperti penerima. Digit di luar decimals token diterima jika berupa nol: "10.0000000" sama dengan "10" untuk token dengan 6 decimals. Digit bukan nol di luar batas itu menghasilkan 422 invalid_expected_amount.

Contoh ketidakcocokan

Anda mengharapkan "10.000001", tetapi transfer terpilih berjumlah "10". Respons berisi amount_match=false dan EXPECTED_AMOUNT_MISMATCH.

Penerima yang berbeda menghasilkan EXPECTED_RECIPIENT_MISMATCH. Kontrak token yang berbeda menghasilkan EXPECTED_TOKEN_MISMATCH. Jumlah yang cocok tidak membuktikan bahwa penerima dan token juga cocok. Sebelum mengonfirmasi pembayaran, periksa seluruh perbandingan yang diperlukan, status transaksi, dan penilaian keseluruhan.

Kontrak pilot

Organisasi dengan kontrak pilot mitra desain wajib mengirim ketiga kolom pada setiap pemeriksaan: pemeriksaan tanpa expected_recipient, expected_token, atau expected_amount ditolak dengan 422 expected_fields_required, dan expected_token selain USDT resmi di TRON ditolak dengan 422 token_not_enabled. Penolakan terjadi sebelum pemeriksaan diterima: tidak ada yang ditagih atau disimpan, dan kunci sandbox mengikuti aturan yang sama.

Konteks jaringan

Perbandingan ini berlaku untuk kedua endpoint pemeriksaan. Jika jaringan pembayaran sudah diketahui, kirim secara eksplisit. API lalu memvalidasi alamat yang diharapkan sesuai jaringan tersebut dan tidak pernah beralih ke jaringan lain. Lihat penentuan jaringan untuk permintaan tanpa network.

Kewajiban, percobaan, dan alokasi

Satu pemeriksaan menjawab apakah satu transaksi membayar sesuai yang Anda harapkan. Buku besar kewajiban menjawab apakah sebuah kewajiban bisnis, yaitu pembayaran keluar atau setoran yang menjadi hak Anda, telah dibayar: sekali, penuh, oleh transaksi yang mana, dan apakah pembayaran yang sama diajukan untuk hal lain. Buku besar menyimpan instruksi Anda, percobaan eksekusi Anda, peristiwa pembayaran yang diverifikasi ChainZap, dan cara peristiwa itu dialokasikan, tanpa pernah menulis ulang satu pun.

Buku besar diaktifkan per deployment. Selama nonaktif, pemeriksaan dengan kolom buku besar apa pun dan setiap endpoint buku besar menjawab 403 ledger_not_enabled.

Model

external_reference, attempt_reference, dan approval_reference berisi paling banyak 128 karakter ASCII yang dapat dicetak. Jangan memasukkan data pribadi ke dalamnya.

Periksa terhadap kewajiban

Tambahkan referensi kewajiban ke pemeriksaan transaksi biasa:

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

Pemeriksaan pertama atas referensi baru mencatat kewajiban dan instruksinya (versi 1, atau instruction_version yang Anda kirim). Pemeriksaan berikutnya boleh hanya mengirim referensi: transaksi dibandingkan dengan instruksi yang tercatat. Jawaban menambahkan blok obligation (status, expected_amount, allocated_amount, residual_amount, attempts, events, pending_events) dan blok reuse.

Ketika transaksi cocok, atau membayar penerima dan token yang benar dengan jumlah yang berbeda, peristiwanya dialokasikan ke kewajiban tersebut. Hanya peristiwa yang final dan telah dieksekusi yang dialokasikan; peristiwa yang tertunda dihitung dalam pending_events dan tidak pernah menutup kewajiban. Jika beberapa pergerakan sama-sama sesuai (integrity_status: AMBIGUOUS), masing-masing dikaitkan ke kewajiban sebagai UNKNOWN tanpa ada yang dialokasikan, sampai Anda menyatakan mana yang membayar. Pemeriksaan yang tidak menyertakan direction memakai arah yang tercatat pada kewajiban, atau jika tidak ada, menyimpulkannya dari workflow_type (PAYOUT dan REFUND adalah pembayaran keluar, DEPOSIT dan INVOICE pembayaran masuk); pembayaran yang arahnya tetap tidak diketahui tidak pernah bernilai PROCEED.

Instruksi tidak pernah diubah di tempat

Versi instruksi tidak dapat diubah. Mengirim versi yang sama dengan ketentuan berbeda ditolak dengan 409 instruction_conflict; mengirim ketentuan berbeda tanpa versi ditolak dengan 409 instruction_version_required. Instruksi yang berubah adalah versi baru, dicatat dengan POST /v1/obligations dan instruction_version yang lebih tinggi; versi sebelumnya tetap tercatat dan pemeriksaan dapat menyebutkan versi yang menjadi dasar pembayaran. Versi yang tidak pernah Anda catat tidak direkonstruksi: pemeriksaan menjawab integrity_status: INSUFFICIENT dengan INSTRUCTION_UNAVAILABLE. Pembayaran dalam blok sebelum instruction_effective_at menambahkan INSTRUCTION_NOT_EFFECTIVE.

Catat kewajiban dan percobaan sejak awal

Percobaan bukanlah eksekusi. execution_confirmed menjadi true hanya ketika peristiwa pembayaran dari transaksinya dialokasikan ke kewajiban; percobaan TIMEOUT yang diikuti pengulangan yang berhasil menghasilkan dua percobaan dan satu eksekusi. Jika percobaan membawa amount, pemeriksaan yang dibuat dengan attempt_reference tersebut membandingkan transaksi dengan jumlah pada percobaan itu, sehingga pembayaran keluar yang dipecah menjadi beberapa bagian dicocokkan bagian demi bagian.

Pembayaran bersama dan pemakaian ulang

Satu pembayaran dapat menyelesaikan beberapa kewajiban, dan satu kewajiban dapat dibayar oleh beberapa pembayaran.

• Beberapa kewajiban, satu pembayaran. ChainZap tidak pernah membagi pembayaran atas inisiatifnya sendiri. Nyatakan bagian-bagiannya dengan POST /v1/allocations (network, tx_hash, event_ref, allocations: [{external_reference, amount}], dan owner opsional yang dicap pada setiap alokasi sebelumnya yang digantikan oleh pernyataan ini). Peristiwa tersebut ada setelah pemeriksaan yang menyebut sebuah kewajiban mencatatnya dengan cakupan lengkap (jika tidak, 404 payment_event_not_found); peristiwa itu harus sudah dieksekusi dan final (409 payment_event_not_settled), dalam token kewajiban (409 allocation_token_mismatch), dan jumlah bagian tidak boleh melebihinya (409 allocation_exceeds_event). Pemeriksaan atas satu bagian kemudian membandingkan bagian itu, bukan seluruh pembayaran, dengan yang terutang pada kewajiban.
• Satu kewajiban, beberapa pembayaran. Setiap pemeriksaan dengan referensi yang sama menambahkan peristiwanya; residual_amount berkurang hingga kewajiban menjadi ALLOCATED.
• Pembalikan. POST /v1/allocations/{allocation_id}/reversal dengan reason (CUSTOMER_CORRECTION, DISPUTED, DUPLICATE_RECORD, OTHER) menandai alokasi sebagai dibalik, dan DISPUTED menandainya DISPUTED. Alokasi tetap tercatat, dan pemeriksaan berikutnya tidak pernah memulihkannya; hanya pernyataan yang dapat melakukannya.

reuse.status menyatakan apa yang sudah diketahui buku besar tentang peristiwa pembayaran tersebut:

Replay idempoten (Idempotency-Key dan isi permintaan yang sama) mengembalikan jawaban yang tersimpan dan bukan pemakaian ulang.

Pembayaran masuk

Untuk setoran, kirim direction: "INCOMING" dan beri tahu ChainZap apa yang sudah dilakukan sistem Anda terhadapnya melalui customer_context: credit_status (NOT_CREDITED, CREDITED, PARTIALLY_CREDITED, UNKNOWN) dan allocation_status (NOT_ALLOCATED, PARTIALLY_ALLOCATED, ALLOCATED, UNKNOWN), yaitu sejauh mana pembukuan Anda sudah menerapkannya. ChainZap tidak dapat melihat pembukuan Anda: tanpa NOT_CREDITED, setoran yang bersih bernilai CONFIRM_INTERNAL_STATE, begitu pula alokasi UNKNOWN, dan pembayaran yang sudah dikreditkan atau diterapkan, meskipun sebagian, menghasilkan REVIEW dengan ALREADY_CREDITED. Aturan kewajiban, alokasi, dan pemakaian ulang yang sama berlaku untuk setoran maupun pembayaran keluar.

Masa penyimpanan

Referensi, alamat, dan hash transaksi dalam bentuk mentah disimpan selama 90 hari, lalu diganti dengan digest berkunci; pemilik dihapus. Jumlah, token, status, dan versi tetap tersimpan, sehingga totalnya tetap benar. Setelah itu, buku besar tetap mengenali pembayaran yang dipakai ulang dan referensi yang berulang melalui digest, dan API mengembalikan redacted: true jika nilai mentahnya sudah tidak ada. Digest dari jumlah dan waktu blok bersifat pseudonim, bukan anonim.

Pemeriksaan batch

Batch memeriksa satu file berisi 50 sampai 200 baris pembayaran dengan mesin yang sama seperti pemeriksaan tunggal: setiap baris mendapat jawaban, alasan, dan efek buku besar yang sama seperti jika diperiksa sendiri. File divalidasi dan diperkirakan biayanya terlebih dahulu; tidak ada yang dijalankan dan tidak ada yang ditagih sampai Anda mengonfirmasi. Batch memakai buku besar kewajiban, dan menjawab 403 batch_not_enabled selama buku besar nonaktif.

Anda dapat mengunggah, menjalankan, dan mengekspor batch di halaman Batch pada dasbor pengembang, atau melalui API di bawah ini. Keduanya memakai layanan dan batas yang sama.

File

CSV dalam UTF-8 (byte order mark diperbolehkan), dipisahkan koma atau titik koma, dengan baris header. Paling banyak 200 baris dan 256 KiB. Satu baris adalah satu pembayaran untuk satu kewajiban.

Nama header yang umum dikenali: order_id, payout_id, invoice_id, reference untuk referensi; txid, hash, transaction_hash untuk hash; to, recipient, address, wallet untuk penerima; token, contract, asset, currency untuk token; amount, tolerance, from, sender, chain, attempt, provider, status. Kolom yang tidak dikenal diabaikan dan dicantumkan di preflight.ignored_columns. Parameter kueri network, direction, dan workflow_type menetapkan nilai bawaan untuk baris yang mengosongkannya. Unduh templat dari dasbor.

Unggah dan 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 mengembalikan batch dalam status PREFLIGHTED dengan:

• preflight: rows, checks, obligations_only, invalid, dan duplicates, beserta errors dan warnings yang dihitung per kode. Baris dengan galat dilewati (SKIPPED_INVALID) dan galatnya menyebutkan kolomnya, misalnya invalid_tron_address atau unknown_token_symbol; baris identik yang berulang dilewati sebagai duplikat. Jika beberapa baris memberi satu referensi ketentuan berbeda, baris pertama berlaku dan baris-baris berikutnya ditolak (conflicting_rows_for_obligation). Peringatan tidak membuat baris dilewati: tx_shared_across_references (satu transaksi di bawah beberapa referensi tanpa allocated_amount), declared_shared_payment, several_transactions_for_obligation, dan tx_seen_for_other_obligation jika buku besar sudah mengaitkan transaksi itu dengan kewajiban lain.
• estimate: batas atas, tidak pernah janji. distinct_transactions, billable_checks_at_most, provider_calls_at_most, provider_usd_at_most (dihitung seolah-olah tidak ada yang tersimpan di cache), quota_available, dan quota_sufficient.

File yang bukan UTF-8, kosong, tidak memiliki header atau baris data, atau memiliki baris yang rusak dijawab 422 invalid_csv; header tanpa kolom external_reference atau dengan kolom berulang dijawab 422 invalid_csv_header; lebih dari 200 baris dijawab 413 batch_too_large. Satu Idempotency-Key menunjuk satu file: kunci yang sama dengan file yang sama mengembalikan batch yang sama, dengan file lain 409 idempotency_conflict. Satu organisasi menjalankan paling banyak dua batch sekaligus; memulai batch ketiga dijawab 429 batch_limit_reached (mengunggah dan preflight tidak memakan biaya dan tidak dibatasi dengan cara ini).

Jalankan

POST /v1/batches/{batch_id}/execute dengan {"confirm": true} memasukkan batch ke antrean; tanpa confirm, API menjawab 422 confirmation_required. Jika kuota tidak dapat menutup setiap transaksi unik, API menjawab 409 insufficient_quota; kirim "allow_partial": true untuk tetap memulai.

Baris diperiksa oleh worker, tidak pernah lebih cepat dari separuh batas laju organisasi Anda, sehingga lalu lintas Anda sendiri tetap berjalan; batch dari semua organisasi bergiliran, sepotong demi sepotong. Baris dari satu transaksi dijalankan sesuai urutan dalam file. Setiap transaksi unik ditagih sekali per batch: setelah satu barisnya menghasilkan jawaban yang ditagih, baris berikutnya dari transaksi yang sama diperiksa terhadap kewajibannya sendiri secara gratis (baris yang ditolak tidak menagih apa pun, sehingga baris berikutnya yang ditagih). Jika kuota atau batas harian pemeriksaan yang tidak ditagih habis, batch dijeda (PAUSED, dengan pause_reason quota_exceeded atau daily_unbilled_ceiling); jalankan execute lagi untuk melanjutkan.

POST /v1/batches/{batch_id}/retry menjalankan ulang hanya baris RETRYABLE dari batch yang selesai atau dijeda, hingga lima percobaan per baris; 409 nothing_to_retry jika tidak ada. POST /v1/batches/{batch_id}/cancel menghentikannya.

Baris yang kekurangannya hanya pada risiko (KYT tidak tersedia) berstatus DONE, bukan RETRYABLE: baca risk_retryable dan risk_retry_after_seconds-nya, lalu periksa transaksi itu lagi dengan Idempotency-Key baru bila perlu (lihat percobaan ulang).

Hasil

• GET /v1/batches mencantumkan batch terbaru Anda; GET /v1/batches/{batch_id} mengembalikan satu batch beserta progress dan, setelah dijalankan, summary.
• GET /v1/batches/{batch_id}/rows?after=0&limit=100 menampilkan baris per halaman beserta jawaban ringkasnya (keempat status, recommended_action, hasil dan selisih jumlah, status pemakaian ulang dan status kewajiban, kode alasan, decision_id). Saring dengan state= atau review=true.
• GET /v1/batches/{batch_id}/export.csv mengembalikan setiap baris beserta jawabannya. Sel yang akan dibaca spreadsheet sebagai rumus diberi awalan ', dan setiap sel diberi tanda kutip.

summary menghitung baris menurut state dan menurut overall_state, memberikan sebaran setiap sumbu status dan recommended_action, jumlah baris dengan analyst_review_required, galat, dan biaya: usd_total, usd_per_transaction, dan usd_per_exception (setiap jawaban selain CLEAR), beserta cost_complete. obligations mencantumkan kewajiban yang masih terbuka beserta jumlah yang sudah dialokasikan dan sisanya.

analyst_review_required menandai baris yang harus dilihat oleh seseorang: rekomendasi MANUAL_REVIEW atau HOLD_AND_ESCALATE. Baris yang jawabannya belum final (RECHECK_LATER) perlu diulang, bukan ditinjau seseorang.

Sandbox

Kunci sandbox menjalankan batch terhadap fixture sandbox dan memakai jatah sandbox; file yang sama dapat dijalankan tanpa perubahan dengan kunci live. Nilai baris mentah disimpan selama 90 hari, sama seperti pada buku besar, lalu dihapus; jumlah, status, dan digest tetap tersimpan.

Dokumen hukum dan cakupan hasil

Ketentuan Bisnis, Perjanjian Pilot, Lampiran Data dan Privasi tersedia melalui tautan portal. Templat sebelum pendirian badan hukum masih memerlukan rincian kontrak dan komersial sebelum ditandatangani. Profil pilot awal adalah USDT resmi di TRON.

Tidak ada sakelar integrity-only khusus: pemeriksaan memanggil lapisan risiko dan menampilkan cakupan tidak cukup/terdegradasi saat bukti risiko yang diperlukan tidak tersedia. Portal menampilkan baris ringkas, tanda review, sisa yang diketahui, dan CSV; bukti keputusan lengkap serta reversal/correction menggunakan API. Batch selesai merupakan snapshot saat keputusan dan tidak otomatis diperbarui setelah koreksi ledger. DONE berarti diproses, bukan dibayar atau hasil yang dikonfirmasi pelanggan.

Transaksi escrow

Transaksi escrow menahan USDT di TRON dalam kontraknya sendiri. Dana hanya bergerak jika pihak yang berhak bertindak: pembeli merilisnya, penjual mengembalikannya, salah satu pihak mengklaimnya setelah pihak lain melewatkan tenggat, kedua pihak mengusulkan pembagian yang sama dalam sengketa, atau resolver yang ditunjuk sebelum pendanaan memutuskan sengketa. Platform Anda membuat draf dan menampilkan transaksinya; pembeli dan penjual menandatangani ketentuan dan memindahkan dana dengan dompet mereka sendiri. ChainZap membuat kontrak setelah keduanya menandatangani dan memantau batas waktu, tetapi tidak pernah memegang kunci para pihak, tidak pernah menjadi resolver, dan tidak dapat memindahkan uangnya.

Transaksi escrow adalah pilot tertutup. Sampai organisasi Anda diaktifkan, setiap panggilan menjawab 403 escrow_not_enabled. Sandbox berjalan di jaringan uji TRON Nile dengan token uji yang tidak bernilai.

Dua mode

Setiap transaksi dapat disengketakan. Satu-satunya pilihan adalah apakah resolver juga boleh memutuskan sengketa.

Mulailah tanpa resolver: mode ini cocok untuk pengiriman dengan pemeriksaan objektif, dan kedua pihak selalu dapat mengakhiri sengketa sendiri.

Yang diizinkan kontrak

• Setiap transaksi adalah kontrak tersendiri yang dibuat oleh factory yang tidak dapat diubah: tanpa pemilik, tanpa upgrade, tanpa jeda, dan tanpa kunci admin.
• Dana hanya bergerak karena tindakan pihak itu sendiri, atau karena putusan resolver dalam jendela waktunya:
  • pembeli merilis (release) dan penjual mengembalikan dana (refund) kapan saja setelah pendanaan sampai transaksi selesai, termasuk selama sengketa;
  • pembeli mengklaim pengembalian dana (claimRefund) setelah batas pengiriman lewat tanpa pengiriman; penjual mengklaim pembayaran (claimRelease) setelah pemeriksaan berakhir tanpa penerimaan maupun sengketa;
  • dalam sengketa, transaksi selesai begitu usulan kedua pihak sama (proposeSettlement), atau saat resolver memutuskan (resolve).
• Tidak ada tenggat yang memutuskan sengketa, dan tenggat sendiri tidak memindahkan apa pun: tenggat hanya membuka hak klaim bagi satu pihak.
• Siapa pun, termasuk ChainZap, hanya dapat mengonfirmasi pendanaan (confirmFunding), menutup transaksi yang tidak didanai setelah tenggatnya (expire), membayarkan dana yang sudah dikreditkan ke penerimanya yang tetap (withdraw), dan mengkreditkan token yang nyasar ke pembeli (sweepExcess). Semua ini bekerja langsung pada kontrak, tanpa ChainZap.
• Pembayaran hanya ke pembeli, penjual, penerima biaya yang ditetapkan di factory, dan, setelah putusannya, resolver yang ditunjuk.

Siklus

status adalah status draf di luar jaringan (DRAFT, AGREED, CREATING, ON_CHAIN, CANCELLED, AGREEMENT_EXPIRED, CREATION_BLOCKED); setelah kontrak dibuat, state adalah status kontrak itu sendiri (AWAITING_FUNDS, FUNDED, DELIVERED, DISPUTED, RELEASED, REFUNDED, SPLIT, EXPIRED). Jalan buntu bukan status kontrak: itu adalah sengketa yang tidak dapat lagi diputuskan resolver mana pun, dilaporkan sebagai settlement.deadlocked. Sumber kebenaran adalah jaringan: API melaporkan apa yang dibacanya dari blok yang sudah solid dan menandai contract.out_of_sync saat tidak dapat memastikan status terbaru.

Pendanaan

Pendanaan adalah transfer biasa token transaksi ke alamat escrow, tanpa izin (allowance) dan tanpa transferFrom. Setelah escrow memegang setidaknya jumlah transaksi, siapa pun dapat memanggil confirmFunding sebelum batas pendanaan; ChainZap melakukannya begitu melihat saldonya. Sampai saat itu funding melaporkan berapa yang sudah received oleh escrow dan berapa yang masih remaining, menurut pembacaan terakhir dari jaringan.

• Kurang dari jumlah. Transaksi tetap AWAITING_FUNDS; kirim sisanya sebelum batas pendanaan. confirmFunding menolak escrow yang memegang kurang dari jumlah.
• Lebih dari jumlah, atau transfer kedua. Setelah pendanaan, kelebihannya dikreditkan ke pembeli (sweepExcess, peristiwa escrow_deal.excess_credited) dan ditarik seperti pembayaran lain. Kelebihan tidak pernah dikunci dalam transaksi dan tidak pernah ke ChainZap.
• Terlambat. Setelah batas pendanaan transaksi hanya dapat ditutup (expire, status EXPIRED); apa pun yang dikirim ke sana dikreditkan ke pembeli dan dapat ditarik.
• Dari alamat lain. Hanya saldo escrow yang dihitung, jadi transfer dari alamat mana pun mendanai transaksi, dan setiap pengembalian atau kelebihan dikirim ke alamat pembeli dalam ketentuan, bukan ke pengirimnya.

Halaman transaksi mengirim persis sisa jumlah ke escrow yang dibacanya dari factory, dan menolak penerima, token, atau nilai lain.

Batas waktu dan klaim

Batas waktu memakai waktu blok. Sebuah tindakan diterima hanya sebelum batas waktunya dan sebuah klaim hanya sejak batas itu, sehingga keduanya tidak pernah tumpang tindih. Klaim tidak otomatis: sampai pihak itu mengklaim, pihak lain masih dapat bertindak, misalnya pembeli masih dapat merilis setelah batas pengiriman. timeline.if_nobody_acts di setiap respons menyebutkan apa yang dibuka batas waktu saat ini: at, outcome (EXPIRED, REFUNDED, RELEASED atau DEADLOCK) dan claim_by (BUYER, SELLER, ANYONE, atau null jika tidak ada yang terbuka).

Transaksi live memberi pembeli paling sedikit 72 jam untuk memeriksa (jika tidak, 422 inspection_period_below_policy). Karena diamnya pembeli membuat penjual dapat mengklaim pembayaran, ChainZap mengingatkan pembeli lewat Telegram segera setelah pengiriman, di tengah periode pemeriksaan, 12 jam dan 1 jam sebelum berakhir; penjual diingatkan 24 dan 2 jam sebelum batas pengiriman, dan setiap pihak diberi tahu saat hak klaimnya terbuka.

Sengketa, usulan, dan jalan buntu

Pembeli dapat membuka sengketa (dispute, dengan hash bukti) hanya selama pemeriksaan. Sejak itu penjual tidak dapat mengklaim pembayaran, dan tidak ada tenggat yang memutuskan hasilnya.

• Usulan. Setiap pihak mengusulkan buyer_amount, yaitu jumlah yang kembali ke pembeli: 0 memberikan semuanya ke penjual (dikurangi biaya), jumlah penuh mengembalikan semuanya ke pembeli, nilai di antaranya adalah pembagian. Setiap pihak dapat mengubah usulannya kapan saja; transaksi selesai begitu keduanya sama (settlement_reason: MUTUAL_SETTLEMENT, peristiwa escrow_deal.settlement_proposed untuk setiap usulan). settlement.buyer_proposal dan settlement.seller_proposal menampilkan usulan saat ini.
• Resolver. Pada transaksi yang menunjuknya, resolver dapat memutuskan dalam resolve_period setelah sengketa dibuka (timeline.resolve_deadline): resolve(buyer_amount, ruling_hash), hanya berdasarkan kriteria yang ditandatangani. Imbalannya diambil lebih dulu, dan putusannya adalah jumlah yang didapat pembeli dari sisanya (settlement_reason: RESOLVER).
• Jalan buntu. Tanpa resolver, atau setelah jendela waktunya lewat, sengketa tanpa usulan yang sama adalah jalan buntu (settlement.deadlocked: true). Dana tetap terkunci sampai kedua pihak mengusulkan pembagian yang sama, pembeli merilis, atau penjual mengembalikan dana. Tenggat maupun ChainZap tidak dapat mengakhirinya.

Dana

Biaya layanan adalah jumlah tetap yang ditetapkan saat draf dibuat (fee_bps dari jumlah, menurut kebijakan pilot Anda) dan hanya diambil dari pembayaran penjual:

• rilis atau klaim penjual: penjual menerima jumlah dikurangi biaya;
• pembagian: biaya dipotong sebanding dengan bagian penjual;
• pengembalian, klaim pembeli, atau kedaluwarsa: tanpa biaya.

Imbalan resolver ditetapkan dalam ketentuan dan dibayar hanya jika resolver memutuskan sengketa. Contoh: jumlah 100, imbalan resolver 5, putusan "pembeli 40": pembeli mendapat 40, resolver 5, dan penjual 55 dikurangi biaya layanan atas 55 itu. Penyelesaian dengan usulan yang sama, rilis, atau pengembalian tidak membayar resolver apa pun.

balances memisahkan yang dikreditkan kontrak (accrued), yang belum ditarik (claimable), dan yang sudah keluar dari kontrak (withdrawn), masing-masing untuk buyer, seller, fee, dan resolver. Setiap pihak membayar biaya jaringan untuk transaksinya sendiri dalam TRX; ChainZap membayar konfirmasi pendanaan, penutupan transaksi yang tidak didanai, pengkreditan kelebihan, dan pengiriman pembayaran.

Membuat draf

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

Draf ini tanpa resolver. Untuk menunjuk resolver, tambahkan "resolver_enabled": true, resolvernya ("resolver_id", atau bawaan kebijakan Anda), imbalannya dalam satuan token, dan jendela waktunya setelah sengketa:

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

Transaksi dengan resolver tanpa pengaturan ini menjawab 422 resolver_settings_required; transaksi tanpa resolver yang mengirim salah satunya menjawab 422 resolver_settings_without_resolver. Imbalan resolver tidak boleh melebihi bagian dari jumlah yang diizinkan kebijakan Anda (422 invalid_resolver_fee).

external_reference yang sama dengan isi yang sama mengembalikan draf yang sama (replayed: true); dengan isi berbeda menjawab 409 escrow_reference_conflict. Temukan draf nanti dengan POST /v1/escrow-deals/lookup. Kriteria pengiriman adalah dua sampai lima pemeriksaan objektif: sengketa hanya dinilai berdasarkan baris ini. Kategori dibatasi pada pengiriman digital dengan uji penerimaan objektif, sesuai kebijakan pilot Anda.

POST /v1/escrow-deals/{ref}/versions mengganti ketentuan draf (kirim expected_version); tanda tangan pada versi sebelumnya tidak lagi dihitung. POST /v1/escrow-deals/{ref}/cancel menutup draf. Keduanya tidak mungkin lagi setelah kedua pihak menandatangani.

Resolver

Resolver bersifat opsional. Transaksi yang memilikinya menyebut resolver eksternal yang didaftarkan platform Anda. Resolver tidak pernah ChainZap: alamatnya dan setiap kunci akun TRON-nya tidak boleh berupa alamat atau kunci ChainZap, maupun kunci pembeli atau penjual transaksi.

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 adalah PLATFORM (dioperasikan platform Anda) atau INDEPENDENT; para pihak melihatnya, dan bahwa platform Anda yang mendaftarkan resolver. Di live, akun dibaca on-chain: akun harus menandatangani putusan dengan satu kunci (SINGLE_KEY) atau dua dari tiga kunci yang permission aktifnya hanya boleh memanggil kontrak (MULTISIG_2_OF_3); selain itu ditolak (resolver_scheme_unsupported, resolver_account_not_activated). Di sandbox pembacaan dilakukan sebisanya; resolver yang tidak dapat menandatangani tetap terdaftar tetapi eligible: false.

GET /v1/escrow-deals/resolvers menampilkan resolver Anda dan resolver bersama; masing-masing dengan key_scheme, signatures_required, eligible, dan ineligible_reason. POST …/resolvers/{id}/verify membaca akun lagi. POST …/resolvers/{id}/disable menghentikan transaksi baru yang menyebutnya (transaksi yang sudah menyebutnya tetap memakainya); …/enable mengizinkannya lagi setelah pembacaan baru di live. Pendaftaran tidak dapat diubah: identitas resolver termasuk dalam ketentuan yang ditandatangani kedua pihak, jadi resolver lain berarti pendaftaran baru. Imbalan tidak termasuk dalam pendaftaran: setiap transaksi menetapkannya sendiri. Paling banyak 20 resolver aktif per jaringan (dan 100 pendaftaran seluruhnya); resolver organisasi lain menjawab 404 resolver_not_found. Tab escrow di portal pengembang melakukan hal yang sama.

Persetujuan

Kirim tautan transaksi dari links ke para pihak. Di halaman transaksi setiap pihak masuk dengan dompet yang disebut dalam transaksi, melihat setiap ketentuan, dan menandatangani satu teks dengan TronLink (signMessageV2). Halaman menghitung ulang hash ketentuan, ID transaksi, dan teks dari ketentuan yang ditampilkan dan tidak menawarkan tanda tangan jika ada yang berbeda. Setiap transaksi yang ditawarkan sesudahnya juga dicocokkan dengan ketentuan yang sama: alamat escrow dibaca dari registri factory, transfer hanya ke escrow itu dan hanya sebesar sisa jumlah, dan penarikan hanya ke alamat pihak yang masuk.

Untuk mengumpulkan tanda tangan di antarmuka Anda sendiri, baca GET /v1/escrow-deals/{ref}/consent: message adalah teks persisnya, params parameter kontrak, dan terms dokumen (chainzap.escrow.terms/2) yang hash JSON kanoniknya adalah terms_hash. Teruskan tanda tangan dengan POST /v1/escrow-deals/{ref}/consents (version, role, signature). Pihak yang akunnya dikendalikan kunci lain (multisig melalui permission) menyetujui on-chain (approveTerms di actions).

Kedua tanda tangan diverifikasi dua kali: oleh API, dan oleh factory, yang menyusun teks yang sama sendiri sebelum membuat kontrak. Teks menyebut resolver atau Resolver: none, dan menjelaskan arti diam dan sengketa. Berikut barisnya untuk transaksi dengan resolver, lalu tanpa resolver:

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

Transaksi para pihak

GET /v1/escrow-deals/{ref}/actions?role=BUYER mencantumkan apa yang dapat ditandatangani pihak itu sekarang. Setiap tindakan berisi kontrak, fungsi, parameter berkode ABI, batas biaya, dan perkiraan energi:

Tindakan yang dapat dipanggil siapa pun dicantumkan di setiap peran pihak selama masih terbuka. Jika antarmuka Anda sendiri yang menyusun transaksi ini, lakukan pemeriksaan yang sama sebelum pengguna menandatangani: escrow adalah escrowOf(deal_id) pada factory yang disebut dalam ketentuan yang ditandatangani, dan tokennya adalah token factory itu. Setelah Anda meneruskan transaksi, laporkan dengan POST /v1/escrow-deals/{ref}/transactions; transaksi dihitung hanya setelah jaringan mengonfirmasinya, dan laporan itu sendiri tidak mengubah transaksi escrow. Laporan diterima hanya selama transaksi escrow dapat memiliki transaksi tersebut (409 action_not_available) dan paling banyak lima yang menunggu per pihak (429 too_many_pending_transactions); transaksi terkonfirmasi yang bukan panggilan itu dari pihak itu diabaikan.

Telegram

links.telegram_invite adalah tautan t.me ke bot ChainZap untuk transaksi ini; bagikan kepada para pihak bersama tautan transaksi. Bot tidak menyebut detail transaksi: bot membuka halaman transaksi di peramban, tempat semua tanda tangan dan pembayaran dilakukan, dan status transaksi di Mini App Telegram. Layar status hanya menampilkan transaksi yang ditautkan pihak dari chat pribadi setelah masuk dengan dompetnya; dari Telegram tidak ada yang dapat ditandatangani atau dikirim. Web dan Telegram menampilkan transaksi yang sama dengan id yang sama.

Bukti

POST /v1/escrow-deals/{ref}/evidence menambahkan catatan teks dan PUT /v1/escrow-deals/{ref}/evidence/files?purpose=DELIVERY&file_name=log.pdf sebuah berkas (PDF, PNG, JPEG, WebP, atau teks biasa, hingga 10 MiB). Item yang Anda tambahkan diberi label sebagai kiriman platform: item itu menunjukkan pengirimnya, bukan bahwa pengiriman terjadi. Setiap item menyimpan SHA-256, penulis, dan waktunya; pengganti adalah item baru. Saat suatu pihak menandai pengiriman atau membuka sengketa, hash kumpulan buktinya dicatat on-chain. Isi berkas dihapus setelah masa simpan; hash-nya tetap.

GET /v1/escrow-deals/{ref}/dispute mengembalikan kriteria, bukti kedua pihak, dan batas waktu sengketa.

Peristiwa dan webhook

Setiap perubahan menjadi peristiwa: 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, dan evidence_added. Pengingat batas waktu dikirim ke para pihak lewat Telegram, bukan ke webhook.

Atur satu endpoint per lingkungan dengan PUT /v1/escrow-deals/webhook ({"url": "https://..."}); respons menampilkan rahasia penandatanganan satu kali. Endpoint harus HTTPS di port 443 pada alamat publik; pengalihan tidak diikuti. Setiap pengiriman adalah POST dengan:

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

Jawab 2xx dalam 10 detik. Pengiriman yang gagal diulang dengan jeda yang makin panjang (30 detik hingga 12 jam, 12 percobaan). Pengiriman terjadi setidaknya sekali dan tidak berurutan: hapus duplikat berdasarkan X-ChainZap-Event-Id dan urutkan dengan sequence. GET /v1/escrow-deals/events?after=<sequence> adalah feed lengkap untuk menyusul setelah gangguan; POST /v1/escrow-deals/events/{event_id}/redeliver mengirim satu peristiwa lagi, POST /v1/escrow-deals/webhook/test mengirim escrow.ping bertanda tangan, POST /v1/escrow-deals/webhook/rotate-secret mengganti rahasia, dan DELETE /v1/escrow-deals/webhook menghentikan pengiriman.

Yang berubah di protokol v2

Transaksi baru memakai kontrak dan ketentuan versi 2. Jika Anda sudah berintegrasi dengan versi pilot pertama:

• Permintaan draf. dispute_enabled kini menjadi resolver_enabled: setiap transaksi dapat disengketakan, hanya resolver yang opsional. Dengan resolver, kirim resolver_id, resolver_fee, dan timeline.resolve_period_seconds. timeline.response_period_seconds dan timeout_outcome dihapus: tidak ada lagi jendela tanggapan penjual maupun hasil sengketa karena tenggat.
• Respons transaksi. Baru: protocol_version, resolver.fee, timeline.resolve_deadline, settlement (usulan dan deadlocked, selama sengketa), funding (selama menunggu dana), dan resolver di balances.accrued, claimable, dan withdrawn. timeline.if_nobody_acts kini {at, outcome, claim_by}. Dihapus: dispute_enabled, timeline.response_period_seconds, timeline.seller_response_deadline, dan timeline.seller_responded. settlement_reason dapat bernilai MUTUAL_SETTLEMENT; TIMEOUT_NO_RULING hanya muncul pada transaksi arsip.
• Pendanaan dan batas waktu. Pendanaan adalah transfer langsung dan confirmFunding, bukan izin dan fund. Setelah batas pengiriman atau pemeriksaan, pembeli atau penjual mengklaim dananya; tidak ada yang selesai karena tenggat.
• Tindakan. Baru: TRANSFER_FUNDS, CONFIRM_FUNDING, CLAIM_REFUND, CLAIM_RELEASE, PROPOSE_SETTLEMENT, EXPIRE, dan SWEEP_EXCESS. Dihapus: APPROVE_TOKEN, FUND, RESPOND, PROCESS_TIMEOUT, dan CREDIT_EXCESS.
• Peristiwa. Baru: escrow_deal.settlement_proposed dan escrow_deal.excess_credited. Dihapus: escrow_deal.seller_responded.
• Ketentuan. chainzap.escrow.terms/2 menambahkan rules: "chainzap.escrow.rules/2" dan resolver.fee, serta menghapus timeout_outcome dan timeline.response_period.
• Kesalahan. Baru: resolver_settings_required, resolver_settings_without_resolver, invalid_resolver_fee, dan invalid_buyer_amount. Dihapus: invalid_simple_deal, dispute_settings_required, dispute_settings_without_disputes, disputes_disabled, dan invalid_timeout_outcome.

Transaksi yang dibuat sebelum versi 2 tetap protocol_version: 1. Transaksi itu diarsipkan: API dan halaman transaksi menampilkannya hanya baca dari catatan ChainZap, dan tidak ada tindakan apa pun atasnya.

Kesalahan

Semua kesalahan memakai format umum. Permintaan escrow dibatasi 16 KiB JSON; berkas bukti 10 MiB.

Sandbox

Kunci sandbox bekerja di jaringan uji TRON Nile dengan token uji berlabel "ChainZap TEST USD (NO VALUE)". Alur, halaman, dan webhook sama seperti live, dan kebijakan sandbox dapat mengizinkan periode pemeriksaan yang lebih pendek untuk mencoba alurnya; dana nyata tidak mungkin terlibat. Transaksi live memakai USDT di mainnet TRON hanya untuk organisasi pilot, dengan daftar peserta yang diizinkan serta batas per transaksi dan total.

GET /v1/usage

Permintaan

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 adalah bilangan bulat 1 sampai 90; nilai bawaannya 30. Pembacaan ini tidak memerlukan kunci idempotensi. Baca header respons X-Request-ID. Permintaan penggunaan terkena batas laju, tetapi tidak memakai pemeriksaan. Ulangi hanya galat bertanda retryable dan patuhi Retry-After.

Kuota periode berjalan

period.start dan period.end menandai periode penagihan saat ini: periode berbayar yang berjangkar pada pembayaran yang dikonfirmasi, atau bulan kalender UTC untuk organisasi tanpa paket berbayar.

Reservasi dilepaskan ketika permintaan selesai tanpa tagihan. balances menambahkan pemeriksaan tambahan dan total yang tersedia; subscription menjelaskan periode berbayar; status: "legacy" dengan plan: null berarti batas organisasi Anda ditetapkan melalui kesepakatan (misalnya kontrak pilot), bukan melalui paket swalayan, dan batas yang ditampilkan adalah yang berlaku. Lihat paket dan pembayaran. environment bernilai live atau sandbox, bergantung pada kuncinya. Semua kunci API organisasi dan permintaan dari dasbor pengembang memakai kuota yang sama.

Statistik jendela pilihan

recent menghitung pemeriksaan logis yang selesai dalam jendela bergulir sepanjang days hari. Replay HTTP idempoten bukan catatan pemeriksaan baru. Statistik ini mencakup jumlah pemeriksaan yang ditagih, galat, dan LIMITED_DATA, latensi rata-rata, jaringan, serta distribusi penilaian keseluruhan. Tidak ada hash transaksi atau rincian penyedia di dalamnya.

Dasbor pengembang menambahkan data harian UTC, penghitung 1/7/30 hari, dan latensi p50/p95 jika terdapat setidaknya 20 sampel latensi selesai dalam 30 hari terakhir. Jumlah respons berhasil mencakup respons dengan cakupan parsial; cakupan terbatas adalah bagian dari total, bukan tambahan terpisah.

Grafik penggunaan membandingkan permintaan selesai dengan pemeriksaan yang ditagih selama 7, 30, atau 90 hari. Arahkan penunjuk, sentuh grafik, atau pilih hari dengan penggeser dan tombol panah untuk melihat angka pastinya. Hari tanpa pemeriksaan ditampilkan sebagai nol; hari UTC pertama dan terakhir mungkin belum penuh. Live dan Sandbox ditampilkan terpisah. Tabel harian dapat dibuka di bawah grafik. Bilah kuota menampilkan pemeriksaan yang termasuk dalam periode penagihan saat ini; paket tambahan tercantum di Paket dan pembayaran.

Dasbor pengembang dan paket

Setelah masuk ke dasbor pengembang, buka /dashboard/usage/ untuk penghitung kuota, tabel harian, distribusi hasil, dan statistik latensi. /dashboard/plan/ menampilkan paket saat ini, kuota bulanan, permintaan per menit, dan batas permintaan bersamaan. Jaringan yang tercakup paket ditampilkan terpisah dari jaringan yang saat ini diaktifkan untuk pemeriksaan; status aktif bukan pemeriksaan kesehatan penyedia secara langsung.

Bagian Uji API menerima deteksi jaringan otomatis atau pilihan eksplisit TRON, Ethereum, atau TON dari jaringan yang tersedia bagi Anda. Pemeriksaannya memakai kuota organisasi dan aturan idempotensi yang sama dengan API server.

Paket dan paket pemeriksaan tambahan dibeli di halaman Paket dan pembayaran; lihat paket dan pembayaran. Perpanjangan dilakukan manual: tidak ada penagihan otomatis, faktur, atau dompet API. Langganan konsumen Mini App tidak memberikan kuota B2B API. Dokumentasi publik tersedia tanpa perlu masuk.

Paket, pemeriksaan, dan pembayaran (beta)

Apa yang ditagih

Pemeriksaan adalah satu pemeriksaan transaksi melalui API. Anda hanya membayar pemeriksaan yang lengkap dan final: respons dengan coverage: complete dan status CLEAR, REVIEW, atau HIGH_RISK untuk transaksi yang sudah terkonfirmasi melewati kebijakan finalitasnya atau gagal secara permanen. Hasil berisiko tetap hasil yang berguna dan ditagih. Transaksi yang tertunda, transaksi yang tidak ditemukan, LIMITED_DATA, galat transport, waktu habis, galat kuota, dan replay idempoten tidak ditagih di kedua endpoint; reservasinya dilepaskan. Respons HTTP yang berhasil tidak sama dengan pemeriksaan yang ditagih.

Paket beta (kebijakan harga BETA_PRICING_V0)

Paket memberi organisasi Anda sejumlah pemeriksaan termasuk per periode penagihan.

Harga dalam dolar AS. GET /v1/catalog memublikasikannya dalam satuan terkecil bulat (sen). Ini ketentuan beta sementara dan dapat berubah untuk periode penagihan mendatang; pesanan atau periode penagihan yang sudah dibayar mempertahankan ketentuan saat dijual. Batas laju permintaan dan konkurensi bersifat sementara sampai peluncuran umum. Scale disepakati secara individual dan tidak dijual online.

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

Periode penagihan dan perpanjangan

Periode penagihan berbayar dimulai saat pembayaran dikonfirmasi di server dan berlangsung satu bulan kalender (31 Januari berakhir 28 atau 29 Februari; tanggal jangkar kembali setelahnya). Perpanjangan dilakukan manual: tidak ada penagihan otomatis. Membayar lebih awal menjadwalkan periode penagihan berikutnya mulai saat periode berjalan berakhir; membayar setelah jeda memulai periode penagihan baru segera. Paket yang berbeda berlaku mulai periode penagihan berikutnya; periode berbayar yang berjalan tidak pernah direset. Pemeriksaan termasuk tidak dibawa ke periode berikutnya.

Paket pemeriksaan tambahan

Paket pemeriksaan tambahan menambah pemeriksaan di atas pemeriksaan termasuk. Satu paket berisi 100 sampai 10.000 pemeriksaan dengan kelipatan 50 dan dihargai sesuai harga pemeriksaan tambahan paket Anda saat ini. Pemeriksaan tambahan berlaku 12 bulan sejak pembelian, dipakai hanya setelah pemeriksaan termasuk, dan hanya dapat dipakai selama paket berbayar aktif. Saat paket tidak aktif, pemeriksaan tambahan dibekukan, bukan hilang. Harga tetap saat pembelian dan tidak dihitung ulang oleh perubahan katalog di kemudian hari.

Pembayaran

Pembelian dilakukan di dasbor pengembang oleh anggota dengan peran owner, admin, dan billing, tidak pernah dengan kunci API. Pembayaran menggunakan kripto. Periksa total lalu pilih Bayar dengan kripto: halaman pembayaran terbuka, tempat Anda membayar total persis dalam USDT atau koin lain yang tersedia di sana. Total tetap dalam dolar AS, dan halaman tersebut bisa dibayar selama masa berlaku pesanan, minimal 15 menit. Jika Anda meninggalkannya, pesanan di halaman Paket dan pembayaran membawa Anda kembali ke pembayaran atau membatalkan pesanan. Pemeriksaan diberikan hanya setelah server mengonfirmasi pembayaran langsung ke penyedia pembayaran: respons dompet, tangkapan layar, atau kembali ke portal tidak memberikan apa pun. Halaman pembayaran tidak dapat ditarik, jadi dana yang dikirim setelah pesanan dibatalkan atau kedaluwarsa tetap dikreditkan bila masih dapat diterapkan, dan ditinjau dukungan bila tidak. Pembayaran ganda atau parsial dicatat dan ditinjau dukungan; tidak pernah diberikan dua kali.

Saldo di 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 tetap berarti sisa pemeriksaan termasuk pada periode penagihan saat ini. balances.extra menunjukkan pemeriksaan tambahan, balances.total_available menunjukkan total yang dapat dipakai pemeriksaan baru, dan balances.included.reserved menunjukkan pemeriksaan yang masih berjalan. subscription melaporkan periode penagihan, paket, dan perpanjangan manual. Header X-Quota-Available membawa total tersebut pada respons pemeriksaan. Saldo tidak membatalkan organisasi yang ditangguhkan, jaringan yang tidak diaktifkan, atau paket yang tidak aktif: 429 quota_exceeded dikembalikan ketika tidak ada yang tersedia.

Pengembalian dana dan sengketa

Dukungan menangani pengembalian dana kasus per kasus dan mencatatnya sebagai peristiwa terpisah: sisa alokasi yang belum dipakai dibalik, pemeriksaan yang sudah dipakai tidak ditarik kembali, dan saldo tersedia tidak pernah negatif.

Sandbox

Kunci sandbox diawali cz_test_. Kunci ini dibuat di dasbor pengembang atau oleh operator organisasi Anda. Kunci sandbox memanggil endpoint yang sama dengan skema permintaan dan respons yang sama, tetapi tidak pernah menjangkau penyedia data, tidak berbiaya, dan tidak menyentuh pemeriksaan berbayar Anda. Setiap respons sandbox yang berhasil membawa environment: "sandbox", begitu pula setiap galat yang dikembalikan oleh pemeriksaan itu sendiri (misalnya provider_unavailable, network_not_enabled, kuota, dan batas laju): jadikan kolom itu dasar percabangan. Penolakan sebelum pemeriksaan dimulai (401, 403 tenant_suspended, 503 api_disabled, batas 429 per IP yang berlaku sebelum kunci dibaca, 413, 415, galat validasi permintaan 422, invalid_idempotency_key) tidak membawa environment, dan 500 atau 504 yang tidak terduga mungkin tidak membawanya; di sana kunci yang Anda kirim menentukan lingkungannya. POST /v1/check dan pemeriksaan dompet juga membawa details.evidence.source: "sandbox"; POST /v1/transaction/check tidak memiliki details, dan item buktinya menyebut peran sumber yang sama seperti jawaban live, sehingga andalkan environment. Perlakukan hasil tersebut sebagai fixture, bukan pengamatan. Setiap fixture menjelaskan dirinya dengan reason_codes yang sama seperti mesin live, sehingga cabang yang Anda tulis untuk sandbox adalah cabang yang dijalankan produksi.

Hasil deterministik

Karakter pertama hash transaksi menentukan hasil, sehingga setiap status dapat diuji dengan sengaja:

Sandbox hanya membuat tiruan dari apa yang akan dikembalikan penyedia. Perbandingan dengan nilai yang Anda harapkan, sumbu status, item bukti, dan alasan berasal dari mesin live, sehingga jawaban sandbox memiliki bentuk dan aturan yang sama dengan jawaban live, termasuk kolom kontrak 0.3. Jika buku besar kewajiban aktif, pemeriksaan, kewajiban, dan batch sandbox dicatat dalam buku besar sandbox yang terpisah dari buku besar live.

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

Tanpa network, sandbox menjawab untuk TRON bila TRON diaktifkan untuk organisasi Anda, dan bila tidak, untuk jaringan pertama yang Anda miliki. Sama seperti penentuan jaringan live, bentuk hash (0x, base64) tidak pernah memilih jaringan. Kirim network secara eksplisit untuk mengetahui apakah jaringan aktif: sandbox menjawab 403 network_not_enabled persis seperti lingkungan live. Hash TON base64 memakai empat bit teratas dari byte pertama.

Jatah dan isolasi

Sandbox memakai jatahnya persis untuk apa yang ditagih pada pemeriksaan live: hasil yang lengkap dan final. Hasil tertunda, hasil parsial, transaksi yang tidak ditemukan, dan fixture gangguan tidak berbiaya, sama seperti di produksi; fixture transaksi gagal (d) bersifat final dan ditagih, seperti transaksi gagal live. Jika organisasi Anda memakai kontrak pilot, kunci sandbox ditolak dengan cara yang sama seperti kunci live (expected_fields_required, token_not_enabled, check_kind_not_enabled). expected_recipient, expected_token, dan expected_amount dibandingkan dengan fixture dan ketidakcocokan tidak pernah menghasilkan CLEAR, sehingga cabang yang Anda uji adalah cabang yang dijalankan produksi; digit bukan nol di luar decimals token menghasilkan 422 invalid_expected_amount, sama seperti pada pemeriksaan live. Pemeriksaan sandbox memakai jatah terpisah 50 pemeriksaan uji per bulan kalender UTC; GET /v1/usage dengan kunci sandbox melaporkan jatah itu dengan environment: "sandbox". Kunci idempotensi, kuota, dan statistik terpisah per lingkungan: Idempotency-Key yang sama di sandbox dan di lingkungan live adalah dua operasi berbeda. Kunci sandbox tidak dapat membeli apa pun dan tidak membuktikan bahwa jaringan live diaktifkan untuk organisasi Anda.

Fixture dompet

Untuk POST /v1/wallet/check, sandbox memilih hasil dari hash alamat yang dinormalisasi, sehingga tidak dapat diarahkan lewat karakter pertama. Gunakan salah satu alamat tetap di bawah ini; setiap baris stabil antar rilis dan diperiksa oleh rangkaian pengujian.

Setiap fixture dompet membawa environment: "sandbox" dan details.evidence.source: "sandbox", menjelaskan dirinya dengan kode alasan yang sama seperti mesin live, dan menghabiskan jatah sandbox persis seperti pemeriksaan dompet live menghabiskan kuota: saat sebuah status dihasilkan.

Contoh integrasi

Contoh pengulangan dan fixture respons di bawah menggunakan endpoint kanonis kontrak 0.3 POST /v1/transaction/check dengan jaringan eksplisit. Untuk permintaan singkat /v1/check dan respons ringkasnya, lihat pemeriksaan satu hash. Kedua endpoint memakai aturan pengulangan dan kuota yang sama.

Respons HTTP berhasil harus dinilai pada sumbu terpisah: verification_final dengan integrity_status untuk perbandingan pembayaran; risk_status, risk_final, dan recommended_action untuk risiko serta tindakan. Pending tidak pernah berarti MATCH; MATCH final dengan KYT tidak memadai memerlukan MANUAL_REVIEW. Pengulangan risiko memakai risk_retryable dan risk_retry_after_seconds, bukan retryable verifikasi. Lihat sumbu status.

Python: pengulangan idempoten

Contoh sisi server ini menggunakan httpx. Kuncinya fiktif. Dalam integrasi sebenarnya, muat kunci API dari penyimpanan rahasia server dan simpan operation_key serta body dalam catatan operasi Anda sendiri sebelum percobaan pertama. Setelah proses dimulai ulang, gunakan kembali keduanya.

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)

Loop ini menangani respons 409/429/503/504 yang dapat diulang dan ketidakpastian jaringan tanpa membuat operasi logis lain. Tangani status bisnis yang dikembalikan sesuai alur kerja pembayaran Anda. Jangan mencatat body atau seluruh hasil dalam log.

JavaScript / TypeScript: permintaan dari server

Gunakan kode ini di server Anda, tidak pernah di browser dengan kunci live. Kunci operasi dan isi permintaan harus disimpan sebelum memanggil fungsi, seperti pada contoh Python.

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

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

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

Skenario respons

Fixture sintetis berikut menggambarkan bentuk respons yang valid, bukan pemeriksaan langsung. Setiap contoh memiliki header X-Request-ID yang sama dengan request_id. Periksa nilai null dan cakupan, selain penilaian keseluruhan.

Transaksi terkonfirmasi

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