When to screen

• Before accepting a deposit - screen the sender's address (direction: "inbound"). Block or hold if the result is CRITICAL or sanctions_hit is true.
• Before sending a withdrawal - screen the destination address (direction: "outbound") so you never pay out to a sanctioned or high-risk wallet.
• At wallet onboarding - screen a wallet when a user first registers it, and keep the result on file.
• Periodic re-screening - re-screen high-value wallets on your own schedule; risk exposure changes over time.

Suggested disposition matrix

This is guidance, not a rule engine - you decide the action; the compliance responsibility is yours.

Start from risk_drivers: it names the adverse counterparties behind the result and sums the amount moved through each, so you do not have to read the exposure lists to find out what drove a band. It can be empty on a CRITICAL result, which is a real outcome rather than an error - see Wallet Screening (KYT) for how to read that case and for the two denominators the shares use.

UNKNOWN is the lowest band, not a missing result. severity is the band of risk_score: UNKNOWN (0-9), LOW (10-39), MEDIUM (40-69), HIGH (70-89), CRITICAL (90-100). A score of 0 means nothing adverse was reported, and 1-9 is a real but sub-LOW signal, so read risk_score alongside the band. A screening that could not be completed comes back with status: ERROR or PENDING, never as severity: UNKNOWN. Neither case is an affirmative clearance of the wallet.

Scores measure exposure, not guilt. A heavily used, fully compliant exchange wallet can still show a high score because it has indirect exposure to risky funds somewhere in its history. A band can also be driven by a very small amount: scoring takes the most severe finding rather than weighting by volume, so a few dollars of exposure to one bad counterparty can set a CRITICAL band on a wallet that has moved six figures. Read risk_drivers for the amount, and anchor decisions on sanctions_hit and on direct exposure (is_direct: true) rather than on the total score alone.

Truncation

Wallets with large transaction histories can produce very long exposure lists. To keep responses fast, source_of_funds, destination_of_funds and counterparty_connections are trimmed, with separate ceilings for the two kinds of entry:

• Entries that name something adverse are kept up to a ceiling set far above the longest breakdown yet measured, and are ordered first in each list. In practice they are not trimmed.
• The remaining entries are kept up to a much smaller ceiling, largest share first. On a busy address these are the ones that fall off the end, and the ones kept still cover the large majority of the wallet's attributed volume.

What counts as adverse is decided by exclusion, not by a fixed list of bad categories: an entry is treated as benign only when its category, entity type and entity subtype are all recognized as benign, and anything else counts as adverse. A category or entity we have not seen before is therefore kept rather than trimmed.

When a list was trimmed, its matching *_truncated flag is true and its *_total field carries the entry count before trimming. Entries with no attributed entity, no risk level and no amounts carry no information, so they are dropped before any of this and are not counted in *_total.

Entry shapes

source_of_funds and destination_of_funds are fund-flow breakdowns. Each entry contains category, entity_name, entity_type, entity_subtype, description, exposure_direction, exposure_type, is_direct, amount_usd, percentage, hops and country.

counterparty_connections is a different shape: categories (a list), entity_name, entity_type, entity_subtype, risk_level, received_usd, sent_usd, received_hops, sent_hops, is_direct, percentage and country. Note the plural categories and the per-direction amounts; risk_level appears only here.

percentage on any entry is a share of that list's attributed total, not of the wallet's volume. On a high-volume address it can round to 0.0 for an entry still worth thousands of dollars, so read amount_usd alongside it.

Sandbox vs. production

In sandbox, each account gets a small number of free screenings per month; once used up, this endpoint returns 429 until next month, and sandbox screenings are never billed. In production, every successful screening (status: SCREENED) is metered and appears on your monthly invoice.

Errors