--- name: trustin-dart-api description: Screen blockchain addresses and transactions for AML risk with TrustIn DART, and manage the rulesets and rules that drive the verdicts. Use when asked to check an address or transaction, read a screening result, or create, clone, edit or highlight compliance rules. --- # TrustIn DART API TrustIn DART is a blockchain AML screening API. Give it a wallet address (KYA) or a transaction hash (KYT) and it traces the funds up to five hops through labeled counterparties, matches every fund-flow path against a ruleset, and returns a 0–100 fund-attribution score with a verdict — accept, review, edd or block — and the exact rules behind it. Every screening is saved as an immutable snapshot. The same API lets a customer manage the rulesets and rules that drive the verdicts. ## Before you start - You need the user's API key (created in the console under Account › API Keys). Never invent one; ask for it. Send it as the `X-Api-Key` header. - Base URL: `https://api.trustin.bond` (production). If the user says "test environment", use `https://test-api.trustin.bond` — its ruleset ids differ. - Every response is `{"code": 0, "msg": "success", "data": …}`; on error `code` is -1 and `msg` names the problem. Status codes: 400 invalid field, 401 key, 403 builtin read-only, 404 not yours / missing, 409 duplicate rule_code, 429 back off. - Prefer `"mode": "async"` for screenings and poll `GET /api/v3/screen/result/{job_id}?type=kya` every 2–5 seconds until `status` is `COMPLETE`. - If an MCP client is available, connect to `https://api.trustin.bond/mcp` with `Authorization: Bearer ` and use the tools instead of raw HTTP. ## How to think about it Two rulesets shape a screening. The path-matching ruleset (ruleset_type kya for address screening, kyt_in / kyt_out for the two sides of a transaction) holds rules; each rule fires when a fund-flow path — or, for a rule with max_hops -1, the screened address's own labels — meets all of its conditions, and a hit carries the rule's risk_level and action into the result. The scoring ruleset (ruleset_type scoring) holds a scoring_config: for each hop band and direction a base, per-severity weights, and verdict bands; the score sums, over the distinct inbound edges that carried tainted funds, edge amount ÷ total inflow × base × severity weight; an address whose own labels hit a self-hit rule overrides the sum with the self-hit score (100 by default). Builtin rulesets — AML KYA Default v1.3, AML KYT-IN Default, AML KYT-OUT Default, the fund-attribution scoring default — are visible to everyone and read-only. Anything a customer creates or clones is theirs to edit. The normal way to customise: clone the builtin, edit the copy, pass the copy's id as ruleset_id (or scoring_ruleset_id) when screening. Screening with ruleset_id 0 uses the builtin default. Rule fields: - rule_code — your identifier, unique within the ruleset; names the hit in results and snapshots. - name, category, description, reference — free text. - risk_level — low | medium | high | critical (drives the score's severity weight). - action — alert | review | edd | block | allow (the disposition a hit recommends). - direction — inbound | outbound | both. - min_hops / max_hops — path length the rule applies to; max_hops -1 = the address's own labels, no path. - conditions — array of {parameter, operator, value}; all must hold. - is_highlighted — highlighted (★) rules are surfaced first in results; presentation only. - sort_order — display order. Condition parameters: - Counterparty labels: primary_category (e.g. Sanctions, Obfuscation, Cybercrime, Public Freezing Action), secondary_category, risk_level (low | medium | high | critical), risk_score (number). - Path: hops, amount (USD, the path's smallest transfer — its bottleneck), risk_rate (% of the counterparty's outflow that reached this address, e.g. 10 = 10%), inflow_total_amount, outflow_total_amount, direction, chain_name. Condition operators: ==, !=, IN, NOT_IN, CONTAINS, >, <, >=, <=. The spellings =, eq, in, not_in, contains, gt, gte, lt, lte are accepted and normalised. ## Recipes Common workflows: 1. Screen an address synchronously: POST /api/v3/screen/kya {"chain_name":"Tron","address":"T…"} → data.score.verdict, data.hits, data.exposures. 2. Screen asynchronously (recommended for deep hops or busy addresses): add "mode":"async" → data.job_id; then GET /api/v3/screen/result/{job_id}?type=kya until status is COMPLETE; poll no faster than every 2 seconds. The job computes immediately — polling only reads. 3. Customise the rules: POST /api/v3/rulesets/clone {"source_ruleset_id": , "name": "Ours"} → data.id; POST /api/v3/rulesets/rule/create {"ruleset_id": , "rule_code": "MY_MIXER_EXPOSURE_H2", "name": "…", "risk_level": "high", "action": "review", "direction": "inbound", "min_hops": 2, "max_hops": 2, "conditions": [{"parameter":"primary_category","operator":"==","value":"Obfuscation"},{"parameter":"risk_rate","operator":">=","value":10}]}; then screen with "ruleset_id": . 4. Read before you change: POST /api/v3/rulesets/list {"ruleset_type":"kya"} to find ids; POST /api/v3/rulesets/rule/list {"ruleset_id": } for the catalogue. 5. Highlight what matters: POST /api/v3/rulesets/rule/highlight {"ruleset_id": , "rule_ids": [...], "is_highlighted": true}. Pitfalls: builtin rulesets cannot be edited (403) — clone them; ids differ between the test and production environments; a sync screening can take minutes on deep hops — prefer async; a rule needs at least one condition; deleting a ruleset never rewrites past snapshots. ## Endpoints - `GET /api/v3/chains` — Supported Chains (v3) - `POST /api/v3/screen/kya` — KYA Screen (v3) - `POST /api/v3/screen/kyt` — KYT Screen (v3) - `GET /api/v3/screen/result/{jobId}` — Get Screen Result (async) - `POST /api/v3/rulesets/list` — List Rulesets - `POST /api/v3/rulesets/get` — Get Ruleset - `POST /api/v3/rulesets/create` — Create Ruleset - `POST /api/v3/rulesets/update` — Update Ruleset - `POST /api/v3/rulesets/delete` — Delete Ruleset - `POST /api/v3/rulesets/clone` — Clone Ruleset - `POST /api/v3/rulesets/rule/list` — List Rules - `POST /api/v3/rulesets/rule/get` — Get Rule - `POST /api/v3/rulesets/rule/create` — Create Rule - `POST /api/v3/rulesets/rule/update` — Update Rule - `POST /api/v3/rulesets/rule/delete` — Delete Rule - `POST /api/v3/rulesets/rule/highlight` — Highlight Rules Full reference with request and response examples: https://v2.trustin.bond/llms-full.txt · OpenAPI: https://v2.trustin.bond/openapi.json