Screen a wallet from your own stack.
One endpoint takes a chain and an address and returns the same report the interface shows: score, tier, findings with evidence, exposure and hops. Ethereum and BNB Smart Chain are accepted on the same endpoint with the same response shape.
Overview
Base URL https://api.traceline.example. All requests are JSON over HTTPS. Every screen is logged and returns an audit_id you can cite in a compliance file.
Authentication
Pass your key as a bearer token. Keys are scoped per environment and per plan; preview traffic does not require a key.
# header on every request
Authorization: Bearer tl_live_••••••••
Screen an address
chain accepts ethereum or bsc and is required: the same address can behave differently on each chain, so a screen is always scoped to one chain.
curl -X POST https://api.traceline.example/v1/screen \
-H "Authorization: Bearer tl_live_••••••••" \
-H "Content-Type: application/json" \
-d '{
"chain": "bsc",
"address": "0xb41d0e7c58a926f3d16b8e04c7a2f9d5e63c18b0",
"hops": 6
}'
Response
200 returns a report object. score is an integer 0–100, tier is derived from it, and weighting_version identifies the model that produced the number.
{
"audit_id": "TL-8F42-01C9",
"chain": { "id": "bsc", "name": "BNB Smart Chain", "chain_id": 56 },
"address": "0xb41d…c18b0",
"score": 68,
"tier": "high",
"weighting_version": "w-2.4",
"screened_at": "2026-10-26T14:08:12Z",
"findings": [
{
"category": "sanctions",
"severity": "severe",
"match": "indirect",
"hops": 2,
"exposure_share": 0.048,
"source": { "name": "US Treasury SDN", "dataset": "2026.10.24" }
}
],
"exposure": { "severe": 0.124, "high": 0.182, "moderate": 0.246, "unrated": 0.448 },
"source_of_funds": { "summary": "…", "transfers": 148 }
}
| Field | Type | Notes |
|---|---|---|
tier | string | low 0–24 · moderate 25–49 · high 50–74 · severe 75–100 |
findings[].match | string | direct or indirect; indirect always carries hops |
insufficient_data | boolean | true when history is below 10 transfers or 30 days; score is then null |
audit_id | string | stable identifier for the log entry, printable in the report |
Errors
Errors return a machine code and a human message. None of these consume a check.
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_address | Not a 42-character EVM address, or chain and address format disagree |
| 401 | unauthorized | Missing, revoked or environment-mismatched key |
| 422 | unsupported_chain | Chain not in scope for this release; response lists supported chains |
| 429 | rate_limited | Includes retry_after in seconds |
| 503 | upstream_unavailable | Dataset refresh in progress; retry with backoff |
Rate limits
Analyst plans allow 10 requests per second and 100 concurrent. Batch screening on Institution runs asynchronously and returns a job id. Limits are per key, and every response carries X-RateLimit-Remaining.
Methodology
The composite score is a weighted sum of category exposures, capped per category and normalised to 0–100. The weights below are from w-2.4 and are repeated on every report so a reviewer can reproduce the arithmetic.
| Category | Weight | Cap |
|---|---|---|
| Sanctions and designated parties | 0.34 | 1.00 |
| Mixer and tumbler exposure | 0.22 | 0.60 |
| Darknet and scam tags | 0.18 | 0.55 |
| PEP and related persons | 0.12 | 0.40 |
| Bridge and cross-chain hops | 0.08 | 0.30 |
| Counterparty depth | 0.06 | 0.25 |
Data sources
Every finding names its source and dataset date. Sources include designated-party lists published by US, EU, UN and UK authorities, PEP records, and chain-analytics datasets for mixing services, marketplace clusters and reported fraud addresses. Traceline is an independent product: naming a list means the list was consulted, not that the publisher endorses or partners with Traceline.
Changelog
2026.10 Weighting w-2.4: sanctions cap raised, bridge weight reduced. 2026.08 BNB Smart Chain reaches parity with Ethereum, including bridge hops. 2026.06 insufficient_data introduced for new wallets. 2026.04 Public v1.