API Reference
Browse and test Width AML API endpoints
Base URLhttps://api.trustin.bond
https://api.trustin.bond/api/v3/screen/kyaKYA Screen (v3)
Chainalysis-aligned address screening. Runs the same ruleset detection engine as the Screening page and returns a Chainalysis-compatible response (with our extensions). Sync (default) returns the full result; async returns a job_id to poll — mode=async responds with data:{job_id, type:'kya', status:'PENDING'}. Defaults to the builtin KYA ruleset when ruleset_id=0. Auth (required — anonymous calls are rejected): API key via ?apikey=, the X-Api-Key header, or Authorization: Bearer <JWT> (same as v2). Rate limit: up to 300 concurrent in-flight requests per endpoint; beyond that a request waits up to 60s for a slot, then returns HTTP 429 {"code":429,"msg":"out of max connections"} — back off and retry, or use mode=async for high concurrency (result polling is not rate-limited).
Request Parameters
chain_namestringrequiredBlockchain network
addressstringrequiredWallet address to screen
tokenstringToken type
inflow_hopsnumberInflow tracing depth (0–5)
outflow_hopsnumberOutflow tracing depth (0–5)
min_timestampnumberStart time filter (Unix ms). Omit for the full history. Narrowing the window makes the upstream investigation noticeably slower, so set it only when you need it
max_timestampnumberEnd time filter (Unix ms). Default: current time
min_amountnumberMinimum transfer amount to consider
max_nodes_per_hopnumberMax nodes expanded per hop
force_time_sequencebooleanRequire every hop on a path to be no later than the one before it, so funds can only have moved forward in time. Paths are then read from the time-sequence layer, which is a strict subset of the raw one — expect fewer paths and a slower first run while the layer is built
ruleset_idnumber0 = default builtin KYA ruleset
scoring_ruleset_idnumberScoring ruleset driving the fund-attribution score (ruleset_type=scoring). 0 = the user's own scoring ruleset, else the builtin default
cex_immunebooleanTreat a plain CEX (exchange) deposit address as clean: returns no hits and score 0 instead of screening its history. A CEX that also carries other high-risk labels (e.g. Sanctioned CEX, Sanctions, Mixers) is still screened normally
force_runbooleanRe-run the investigation instead of reusing the one an identical earlier submit produced. gloomis dedups at the investigation level, so screening the same subject with the same parameters returns the earlier graph and misses anything that moved since. Costs a full investigation, so leave it off unless you need the chain re-read
modestringsync returns the full result immediately; async returns a job_id to poll via Get Screen Result
curl -X POST 'https://api.trustin.bond/api/v3/screen/kya?apikey=YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"chain_name": "",
"address": "",
"token": "",
"inflow_hops": 0,
"outflow_hops": 0,
"min_timestamp": 0,
"max_timestamp": 0,
"min_amount": 0,
"max_nodes_per_hop": 0,
"force_time_sequence": false,
"ruleset_id": 0,
"scoring_ruleset_id": 0,
"cex_immune": false,
"force_run": false,
"mode": ""
}'Run the request to see the response here.
addressstringThe queried wallet address
chainstringBlockchain network (Ethereum / Tron)
riskstringOur risk vocabulary: critical / high / medium / low
riskScorenumberNumeric risk score (0–100), mapped one-to-one from riskLevel (higher = riskier): critical = 90, high = 80, medium = 60, low = 10. It is 0 only when no rule is triggered (riskLevel then defaults to "low") — so riskLevel "low" with riskScore 0 means clean / no hits, whereas riskScore 10 means a low-severity rule fired.
riskReasonstringHuman-readable summary of the highest-severity finding
clusterobjectCluster attribution for the address (Chainalysis-style). Empty name/category when unresolved
addressTypestringAddress entity type (e.g. exchange, mixer). Empty string if unresolved
addressIdentificationsobject[]▲ hideWhat the address IS — identity-level findings derived from self-hits (e.g. the address itself is sanctioned)
[].categorystringIdentification category (e.g. "Sanctions")
[].namestringShort identification name
[].descriptionstringHuman-readable description
exposuresobject[]▲ hideAggregated exposure amounts by category and direction, derived from path hits
[].categorystringExposure category (e.g. "Sanctions", "Cybercrime")
[].directionstringFund flow direction: inflow or outflow
[].valuenumberExposure amount in token units
hitsobject[]▲ hidePer-hit rule match detail with path evidence (our extension — not part of the Chainalysis spec)
[].ruleCodestringUnique rule code (e.g. "KYA_SANCTION_EXPOSURE")
[].ruleNamestringRule name
[].categorystringRule category (e.g. "Sanctions", "Cybercrime")
[].riskLevelstringRule risk level: low / medium / high / critical
[].actionstringRecommended action: block / review / alert / monitor
[].directionstringReserved direction field (empty for KYA self/path hits)
[].pathFlowstringPath flow direction: inflow or outflow
[].hopsnumberNumber of hops from the risk entity to the target address
[].opponentAddressstringThe risk entity address at the other end of the path
[].maxAmountnumberMaximum transfer amount on this path
[].pathNodesstring[]Ordered address list from opponent → target
rulesTriggeredstring[]Rule codes triggered across all hits
rulesetIdnumberThe ruleset ID used for detection
totalPathsnumberTotal number of fund paths analyzed
hitPathsnumberNumber of paths that matched at least one rule
inflowRiskAmountnumberContaminated inflow amount across unique hit inbound paths (token units)
inflowRiskRatenumberinflowRiskAmount / total inflow path amount, range 0–1
outflowRiskAmountnumberRisk outflow amount across unique hit outbound paths (token units)
outflowRiskRatenumberoutflowRiskAmount / total outflow path amount, range 0–1
scoreobject▲ hideFund-attribution risk score (资金占比评分). score = Σ (base × severity weight × fund ratio), where fund ratio is the deduped risky amount ÷ the address's total on-chain flow. Null when the graph had no flow totals.
.scorenumber0–100 (null when denominators unavailable)
.verdictstringaccept / review / edd / block (banded: 0-20 accept, 20-50 review, 50-80 edd, 80-100 block)
.selfHitbooleanTrue when the subject itself is flagged (score = self-hit score × severity weight)
.components[]object[]Per-cell breakdown: each = base × weight × ratio = points
.r1 / .r2 / .rOutnumberDirect-in / indirect-in / out flow ratios (0–1)
.totalIn / .totalOutnumberThe on-chain token volume used as the denominator
.hitPaths / .riskyEdgesnumberHit path count / deduped risky edge count
scoreOverviewobject▲ hideThe address's on-chain activity behind the score: full token volume (the denominator) + tx counts + balance + activity window. Absent when the chain-volume fetch failed.
.addressstringThe screened address
.tokenstringToken (usdt / usdc)
.inTotal / .outTotalnumberTotal token inflow / outflow
.inCount / .outCountnumberTransfer counts in / out
.balancenumberCurrent token balance (null when unavailable)
.firstTs / .lastTsnumberEarliest / latest transfer timestamp (ms)
.truncatedbooleanTrue when the volume hit the provider page cap — the ratio is then conservative