Skip to main content

How it works

A check is one request in and one verdict out. This page follows that path end to end, so you know what happens between the two and which parts of it you can rely on later.

The path of a check​

  1. Your backend sends a check. An address check or a transaction check, authenticated with an API key.
  2. The request is admitted or refused up front. The key, its scope, the rate limit and the quota or prepaid balance are checked before any screening starts. A refused request answers with an error and is never charged.
  3. The screening engine collects findings. It matches the address against public authority lists and Leeri's own label set, follows the funds through the address's counterparties for the assets with full coverage, and uses a third-party data source where one is available. Every finding names its source.
  4. The verdict is derived and pinned. The findings are weighted by a published ruleset into a score and a band. The verdict records the ruleset version, the label snapshot and the chain height it was derived at, so it can be reproduced later.
  5. You get the answer, a report and, if registered, a webhook. The response carries the verdict. An evidence report for it is included in the check, and a webhook delivers check.completed once the check is final.

Synchronous or pending​

Most checks answer in the same response. When one needs more time than a request should hold, the API accepts it and answers status: "pending" with the same body shape and a check_id. The verdict is produced in the background. Read the result by polling or, better, by webhook: see Pending and polling. A pending check has no verdict yet, is not charged and sends no completion webhook; everything is settled once, when it finishes.

Partial verdicts​

If a data source is unavailable, a check does not fail with a server error and does not pretend to be clean. It returns a partial verdict that says it is partial and lists the reasons. A partial verdict caused by an outage is not charged, and you can run the check again later. A partial verdict that only states a bound of the analysis, such as the depth of the traversal on an asset, is the full service for that address and is charged. See Rate limits and quotas for the billing rules and Address checks for the fields.

Sandbox and live​

The environment is chosen by the key. A sandbox key runs the same engine against your own data without using quota or balance, at a lower rate limit, and has a designated test address that always answers pending. A live key is billed. Nothing else changes when you switch. See Sandbox and live.

What Leeri stores, and why​

A verdict is stored as its findings and the references to the evidence behind them, together with the pin, and not as a bare number. That is what makes a verdict explainable and reproducible months later: Rederive replays it under the ruleset and label snapshot it was issued with, and the evidence report can be verified as genuine. Answers from third-party data sources become sourced entries in Leeri's own label set; nothing about your account, your customers or your check is stored with them.

Next​