Screen a Wallet for Risk

Wallet screening is a common first step in onchain due diligence. Before interacting with an address, processing a transaction, onboarding a counterparty, or investigating activity, you can use Webacy to understand the risks associated with that wallet. This guide walks through a basic wallet screening workflow.

What you’ll learn

By the end of this guide, you’ll know how to:

Screen a wallet address
Interpret its overall risk score
Identify the risk factors contributing to that score
Review historical transaction activity
Understand exposure to risky counterparties
Trace where a wallet’s funds came from
Use the results in an automated decision workflow

Get your API key

Follow this guide to get an API key.Create or log in to your Webacy Developer account and generate an API key from your dashboard. Your API key authenticates requests to the Webacy API and determines the usage associated with your account.Keep your API key secure and never expose it in client-side code or public repositories.Once you have your key, you’re ready to make your first request.

Submit a wallet for screening

Pass the wallet address you want to evaluate to the Webacy wallet screening endpoint.Webacy analyzes the address using its onchain activity, transaction history, counterparties, known entities, and proprietary risk intelligence.Try this example:

# DPRK-linked wallet on Ethereum
curl -X GET "https://api.webacy.com/addresses/0x0fa09c3a328792253f8dee7116848723b72a6d2e?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  'https://api.webacy.com/addresses/0x0fa09c3a328792253f8dee7116848723b72a6d2e?chain=eth',
  { headers: { 'x-api-key': process.env.WEBACY_API_KEY } }
);
const analysis = await response.json();

console.log(`Overall Risk: ${analysis.overallRisk}/100`);
console.log(`High-severity flags: ${analysis.high}`);
console.log(`Tags: ${analysis.issues.flatMap(i => i.tags.map(t => t.name)).join(', ')}`);

import requests

response = requests.get(
    "https://api.webacy.com/addresses/0x0fa09c3a328792253f8dee7116848723b72a6d2e",
    params={"chain": "eth"},
    headers={"x-api-key": "YOUR_API_KEY"}
)
analysis = response.json()

You’ll use the example wallet 0x0fa09c3a328792253f8dee7116848723b72a6d2e on Ethereum. See example addresses for more.

Because risk changes continuously onchain, Webacy evaluates wallets against the latest available data rather than relying solely on a static historical assessment.

Tip: A wallet’s risk profile can change at any time. An address that appears safe today may later interact with a sanctioned entity, exploit, scam, or other high-risk address.

Check the overall risk score

Start with the wallet’s overall risk assessment. This provides a quick indication of whether Webacy has identified potentially concerning activity associated with the address.A lower-risk wallet may have few or no significant indicators, while an elevated assessment means one or more risk factors warrant additional attention.For the example above, below is an example response:

{
  "high": 2,
  "count": 2,
  "issues": [
    {
      "tags": [
        {
          "key": "DPRK",
          "name": "DPRK",
          "type": "addressRisk",
          "context": {
            "detected_at": "2026-08-11T15:35:11.620Z"
          },
          "severity": 10,
          "description": "This address has been identified as having connections to North Korean (DPRK) entities or activities. DPRK-linked addresses are considered extremely high risk due to international sanctions and the regime's involvement in cybercrime, including cryptocurrency theft, ransomware operations, and illicit financing. Interaction with these addresses may violate sanctions regulations and expose users to significant legal and financial risks."
        },
        {
          "key": "HACK",
          "name": "Hack Related",
          "type": "addressRisk",
          "context": {
            "detected_at": "2026-08-11T15:35:11.620Z"
          },
          "severity": 10,
          "description": "This address is associated with a known hack or security incident."
        }
      ],
      "score": 100,
      "riskScore": "High Risk",
      "categories": {
        "fraudulent_malicious": {
          "key": "fraudulent_malicious",
          "name": "Fraudulent/Malicious",
          "tags": {
            "DPRK": true,
            "HACK": true
          },
          "gradedDescription": {
            "low": "Properties of this transaction indicate the possibility of nefarious activity, but we have not detected anything that would constitute elevated risk",
            "high": "The smart contract/address in this transaction has been used in and is associated with confirmed fraud and malicious activity, or the asset is a known malicious token. Interacting with it may also cause your address to be marked as fraudulent.",
            "medium": "Elements of the smart contract in this transaction can be used a fraudulent and malicious fashion, or the address in this transaction has been involved in some risk activity."
          }
        }
      }
    }
  ],
  "medium": 0,
  "details": {
    "fund_flows": null,
    "marketData": {
      "market_cap": 0
    },
    "token_risk": {},
    "address_info": {
      "dprk": true,
      "hack": true,
      "balance": 0.07983634986921333,
      "flagged": false,
      "sanctioned": false,
      "time_1st_tx": "2025-02-18T14:53:23.000Z",
      "time_verified": 1761344633930,
      "has_no_balance": false,
      "open_sanctions": false,
      "ofac_sanctioned": false,
      "automated_trading": false,
      "transaction_count": 60,
      "has_no_transactions": false,
      "usdt_banned": false,
      "usdc_banned": false,
      "eurc_banned": false,
      "busd_banned": false,
      "pyusd_banned": false,
      "usdp_banned": false
    },
    "buy_sell_taxes": {
      "has_buy_tax": false,
      "has_sell_tax": false
    }
  },
  "expiresAt": 1786548911638,
  "isContract": false,
  "addressType": "EOA",
  "analyzed_at": "2026-08-11T15:35:11.434Z",
  "overallRisk": 100
}

In this example, overallRisk: 100 which means this address is HIGH RISK.

The overall score is a useful starting point, but deeper due diligence should also consider the underlying signals contributing to it.

Review the risk factors

Next, inspect the individual risk factors identified for the wallet.Webacy evaluates hundreds of proprietary risk signals across areas such as:

Sanctions exposure
Known scams and malicious addresses
Hacks and exploits
Stolen funds
Suspicious transaction patterns
High-risk counterparties
Address poisoning
Indirect or multi-hop exposure
Other anomalous onchain behavior

These signals provide context for why a wallet received its risk assessment.This allows you to distinguish between different types and severities of risk rather than treating every flagged wallet the same way.

...
  "issues": [
    {
      "tags": [
        {
          "key": "DPRK",
...
        },
        {
          "key": "HACK",
...
      ],
...
  "details": {
...
    },
    "token_risk": {},
    "address_info": {
      "dprk": true,
      "hack": true,
...
}

In this example, under "issues" and "tags" you will see risk factors associated with the address. This one has the risk factors "DPRK" and "HACK" associated with it, which provides insight into why the overall score is high.Additionally in the “details” and “address_info” section, you can find a quick list of risk-associated factors in boolean format. For this example, you can see "dprk": true and "hack": true.

Trace where the funds came from (optional)

A wallet can carry no risk labels of its own and still be funded by a sanctioned entity, a hack, or a mixer. Add fund_flow_exposure=true to the same request and Webacy screens the wallet’s incoming transfers up to two hops back for senders in its risk labels: sanctions, DPRK, hacks, scams and phishing, mixers, money laundering, FBI IC3 reports, address poisoning and analyst flags.Fund-flow exposure is opt-in and available on Ethereum, BSC, Arbitrum, Base and Polygon (chain=eth, bsc, arb, base, pol). On other chains the block comes back as status: unavailable with reason: unsupported_chain, at the standard wallet screening price.This step uses a different wallet from the one above. The DPRK wallet already scores 100, so any lift would be invisible; 0x811fb2a04ccc066bed2b944bdda22a15bb1e7439 looks almost clean on its own labels (one address-poisoning tag, overallRisk of 7) and only its funding history gives it away.

curl -X GET "https://api.webacy.com/addresses/0x811fb2a04ccc066bed2b944bdda22a15bb1e7439?chain=eth&fund_flow_exposure=true" \
  -H "x-api-key: YOUR_API_KEY"

const url =
  'https://api.webacy.com/addresses/0x811fb2a04ccc066bed2b944bdda22a15bb1e7439?chain=eth&fund_flow_exposure=true';
const headers = { 'x-api-key': process.env.WEBACY_API_KEY };

// A 202 means the wallet's own risk analysis is still running (no
// fund_flow_exposure block yet); "pending" means the trace is.
// Every poll is billed, so stop after about two minutes.
let res = await fetch(url, { headers });
let analysis = await res.json();
for (let attempt = 0; attempt < 8; attempt++) {
  const analysisPending = res.status === 202;
  if (!analysisPending && analysis.fund_flow_exposure?.status !== 'pending') break;
  const wait = analysisPending
    ? Number(res.headers.get('retry-after') ?? 15)
    : analysis.fund_flow_exposure.retry_after_seconds ?? 15;
  await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  res = await fetch(url, { headers });
  analysis = await res.json();
}

const exposure = analysis.fund_flow_exposure;
if (!exposure || exposure.status === 'pending' || exposure.status === 'unavailable') {
  console.log(`No exposure result: ${exposure?.reason ?? exposure?.status ?? `HTTP ${res.status}`}`);
} else {
  console.log(`Status: ${exposure.status}, tier: ${exposure.tier ?? 'none'}`);
  for (const f of exposure.findings ?? []) {
    if (!f.scored) continue;
    console.log(`hop ${f.hop} ${f.category}: ${f.inflow_share_pct}% of ${f.token.symbol} inflow from ${f.counterparty_address}`);
  }
}

The first call for a wallet starts the trace in the background and returns the normal risk response with the block in pending. Poll the same request after retry_after_seconds:

"fund_flow_exposure": {
  "status": "pending",
  "retry_after_seconds": 15,
  "max_hops": 2
}

Once the trace completes, the block lists the flagged senders it found (the 20 most severe; findings_truncated tells you when there were more). If any finding scores and the wallet is not a verified or trusted address, it also picks up a fund_flow_exposure tag under issues and its overall score is raised to at least the medium or high range; score_applied tells you whether that happened. Below is the response for the example above, trimmed to three of its findings:

{
  "overallRisk": 44.721359549995796,
  "high": 0,
  "medium": 1,
  "count": 2,
  "issues": [
    {
      "score": 4,
      "riskScore": "Medium Risk",
      "tags": [
        {
          "key": "fund_flow_exposure",
          "name": "Received Funds from Flagged Address",
          "type": "addressRisk",
          "severity": 5,
          "reason": "2.08% of USDT inflow directly from an address flagged scam_phishing",
          "description": "This address received funds, directly or through one intermediary, from an address flagged for malicious activity.",
          "context": {
            "detected_at": "2026-10-07T19:34:11.308Z",
            "counterparty_address": "0xfb19ffd1ff9316b7f5bba076ef4b78e4bbedf4e1",
            "category": "scam_phishing",
            "hop": 1,
            "inflow_share_pct": 2.08
          }
        },
        {
          "key": "address_poisoning",
...
        }
      ],
...
    }
  ],
...
  "fund_flow_exposure": {
    "status": "complete",
    "tier": "medium",
    "findings": [
      {
        "counterparty_address": "0xfb19ffd1ff9316b7f5bba076ef4b78e4bbedf4e1",
        "category": "scam_phishing",
        "labels": ["phishing_activities"],
        "hop": 1,
        "inflow_share_pct": 2.08,
        "token": {
          "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
          "symbol": "USDT",
          "recognised": true,
          "material": true
        },
        "scored": true
      },
      {
        "counterparty_address": "0x4e5b2e1dc63f6b91cb6cd759936495434c7e972f",
        "category": "mixers",
        "labels": ["mixer"],
        "hop": 2,
        "inflow_share_pct": 25.82,
        "token": {
          "address": "@native",
          "symbol": "ETH",
          "recognised": true,
          "material": true
        },
        "via": ["0x3db0e86515057ff2e32a039992c574ba87dc747e"],
        "scored": true
      },
      {
        "counterparty_address": "0xe9690ae2a2e863a569937572d2c66b31a68776fd",
        "category": "address_poisoning",
        "labels": ["address_poisoning"],
        "hop": 1,
        "inflow_share_pct": 38.26,
        "token": {
          "address": "@native",
          "symbol": "ETH",
          "recognised": true,
          "material": true
        },
        "scored": false
      },
...
    ],
    "findings_truncated": false,
    "inflow_truncated": false,
    "max_hops": 2,
    "computed_at": "2026-10-07T19:34:11.308Z",
    "score_applied": true
  }
}

In this example the wallet received 2.08% of its USDT directly from an address flagged for phishing, and 25.82% of its ETH through an intermediary that was funded by a mixer. Both findings score, so the wallet is medium tier and overallRisk rose to 44.7. The address-poisoning senders are listed with "scored": false — they explain the inflow but never affect the score, because a poisoning attempt says nothing about the recipient.

How to read the block:

Field	Meaning
`status`	`complete`: findings exist. `none`: traced, nothing found (check `inflow_truncated` before treating it as clean). `pending`: poll again after `retry_after_seconds`. `unavailable`: see `reason` (`unsupported_chain`, `disabled`, `not_cached`, `cache_unavailable`, `provider_unavailable`).
`tier`	`high` when a direct sender accounts for at least 5% of the wallet’s inflow of a token it is funded in, `medium` for any other scoring finding. Absent when nothing scored.
`findings[]`	One entry per flagged sender, most severe first, at most 20 (`findings_truncated` is `true` when there were more).
`hop`, `via`	`1`: the flagged address sent funds straight to the wallet. `2`: it funded one of the wallet’s senders. `via` lists the intermediaries whose transfers count toward `inflow_share_pct` — for a scored finding, only the senders it funded materially; for an information-only finding, every path.
`inflow_share_pct`	Share of the wallet’s inflow of `token` that came from this sender, directly or through its intermediaries.
`token.recognised`, `token.material`	Only recognised tokens (the chain’s native coin, verified tokens and community-listed tokens) that the wallet is actually funded in — its most-received recognised token, or one it received at least five times — can score. Dust in an unknown token never moves the score.
`scored`	Whether the finding counts toward `tier`. `false` means information only: under 1% of inflow, an unrecognised or immaterial token, an address-poisoning or analyst-flagged sender, or a sender that is a contract (routers, settlement and bridge contracts are not actors).
`inflow_truncated`	The wallet, or one of its senders, has more history than the trace could read, so findings come from a partial sample. With `status: none` this means exposure could not be ruled out — treat it as not determined, not as clean.
`score_applied`	Whether `tier` raised the wallet’s score. `false` when no finding scored, or for verified and trusted addresses, which get the findings for information only.

A hop-2 finding scores only when the flagged address was also a material funder of the intermediary — at least 1% of the intermediary’s inflow of a token the intermediary is funded in — so a wallet is not penalised because one of its senders once received dust from a mixer.Results are cached for 24 hours (2 hours when inflow_truncated is true). An unavailable outcome, or a none from a trace that could not read everything it needed, is kept for only about two minutes, so the next request re-traces. refreshCache=true refreshes the whole screening, not just the exposure — it may answer 202 while the wallet is re-analysed — and the exposure block keeps serving the last outcome while the fresh trace runs; a wallet is re-traced at most once every couple of minutes.

Fund-flow exposure is priced as its own, higher-priced request. On a supported chain, every 200 response with fund_flow_exposure=true draws the fund-flow rate from your allocation — including each pending response you poll and an unavailable outcome — so wait the full retry_after_seconds between polls, cap how many times you poll, and back off when the block is unavailable. A 202 response (the wallet’s own risk analysis is still being computed) is not billed. See Pricing.

Take action based on the result

Once you’ve evaluated the wallet, you can incorporate Webacy’s risk intelligence into your own application or policy engine. The appropriate action depends on your use case, jurisdiction, risk tolerance, and internal policies.Webacy provides the underlying intelligence so your system can determine what happens next.

In this example, you should block this wallet address from interaction with your platform, transaction, asset, or other activity.

Continue monitoring

A wallet screening represents the risk associated with an address at the time of analysis. For many applications, screening once is not enough. New transactions can introduce new counterparties, exposures, and risk factors at any time. For ongoing protection, combine wallet screening with Webacy’s transaction monitoring and Wallet Watch capabilities to identify changes in risk as new activity occurs.

Common use cases

Wallet screening can be incorporated anywhere your application needs to make a decision about an onchain address, including:

User onboarding — evaluate wallets before allowing access or activity
Deposits and withdrawals — assess addresses before processing funds
Compliance workflows — identify sanctions and other high-risk exposure
Investigations — analyze suspicious wallets and related activity
Trading platforms — evaluate addresses interacting with your platform
Treasury operations — assess counterparties before sending funds
AI agents — evaluate wallet risk before executing an autonomous action

Monitor

Agentic

Digital Assets

Wallets and Accounts

Transactions

Tokens

Apps

DD.xyz

Screen a Wallet for Risk

What you’ll learn

Continue monitoring

Common use cases

​What you’ll learn

​Continue monitoring

​Common use cases

What you’ll learn

Continue monitoring

Common use cases