Every Ethereum address has a reputation. Some are sanctioned entities. Some are known phishing operators. Some have interacted with Tornado Cash or other mixers. If you send funds to or receive funds from these addresses, you may trigger compliance alerts, get flagged by exchanges, or lose your funds entirely.

This guide explains how address risk scoring works and how to use the Onchain Diary Risk API to check any address in seconds.

The API aggregates signals from three independent data sources:

• GoPlus Security API — 20+ security signals including phishing flags, sanctions lists, money laundering tags, and cybercrime associations

• Etherscan API — Contract source code verification, transaction history, dangerous function detection, and deployer reputation

• Community blacklists — 715+ addresses from MyEtherWallet/ethereum-lists and Tornado Cash contract registries

It combines these signals into a single 0-100 risk score with a plain-text risk level: low, medium, high, or critical.

No payment required. Get the risk score, risk level, and blacklist status for any address:

cur​l -s https://theonchaindiary.com/api/v1/risk/address/0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 | jq .

Response:

{ "address": "0xd8da6bf26964afd7eed9e03e53415d37aa96045", "chain": "ethereum", "is_contract": false, "score": 15, "risk_level": "low", "blacklisted": false, "data_sources": ["Etherscan", "GoPlus"], "tier": "free", "signals_count": 4 }

Key fields:

• score: 15 — 0 is clean, 100 is maximum risk. Most legitimate EOA addresses score below 30.

• blacklisted: false — If true, this address appears on a community blacklist. Do not interact.

• is_contract: false — Distinguishes EOA wallets from smart contracts. Contract interactions carry additional risk.

• risk_level — Quick glance indicator. low = safe to interact; critical = stay away.

For $0.01 per request (via x402 payment), you get the complete signal breakdown — each risk factor individually weighted, plus a risk narrative:

{
  "address": "0x12d66f87a04a9e220743712ce6d9bb1b5616b8fc",
  "score": 100,
  "risk_level": "critical",
  "blacklisted": true,
  "signals": [
    {
      "type": "blacklist_mixer",
      "detail": "Address is a known mixer contract (Tornado Cash)",
      "weight": 55,
      "source": "internal"
    },
    {
      "type": "mixer_interaction",
      "detail": "Interacted with known mixer (12 txs in recent activity)",
      "weight": 35,
      "source": "Etherscan"
    }
  ],
  "labels": ["mixer", "mixer_user"],
  "summary": "High-risk contract. Address is a known mixer contract..."
}

Each signal has a type, detail explanation, weight (contribution to the score), and source. The summary field gives you a human-readable risk narrative — useful for dashboards or compliance reports.

The score is additive — each detected signal contributes its weight to the total, capped at 100:

Score = min(Σ(signal_weights), 100)

This means:

• A single blacklist signal (weight 55) puts an address at high risk

• Multiple interaction signals compound — a sanctioned address that also interacted with mixers will score 100

• A clean address with no signals scores 0

An address may be clean on Ethereum but flagged on Base or Arbitrum. Always check the chain you're actually transacting on:

cur​l -s "https://theonchaindiary.com/api/v1/risk/address/0x...?chain=base" cur​l -s "https://theonchaindiary.com/api/v1/risk/address/0x...?chain=arbitrum"

Before sending funds to an unknown address, run a free check. If score > 50 or blacklisted: true, stop and investigate.

If you're selling crypto peer-to-peer, screen the buyer's address first. A mixer_interaction signal means the funds may be tainted — accepting them could get your exchange account frozen.

Before interacting with a new DeFi protocol, check the contract address. The premium tier reveals dangerous functions, proxy patterns, and deployer reputation that a surface-level Etherscan check might miss.

For businesses handling crypto payments, the API provides a programmatic risk score that can be logged for compliance. The signals array and summary field are suitable for audit trails.

import requests

def check_address_risk(address, chain='ethereum'):
    url = f'https://theonchaindiary.com/api/v1/risk/address/{address}?chain={chain}'
    res = requests.get(url)
    data = res.json()

    if data.get('blacklisted'):
        return {'action': 'block', 'reason': 'Address is blacklisted'}

    if data.get('score', 0) >= 75:
        return {'action': 'block', 'reason': f"Critical risk score: {data['score']}"}

    if data.get('score', 0) >= 50:
        return {'action': 'review', 'reason': f"High risk score: {data['score']}"}

    return {'action': 'allow', 'data': data}

• The free tier is enough for go/no-go decisions. If blacklisted: true or score > 75, don't interact — no payment needed to know that.

• Interaction signals are directional, not deterministic. A mixer_interaction flag means the address has touched a mixer, not that the address itself is malicious. Use judgment.

• Always check the right chain. An address can be clean on Ethereum and flagged on L2s.

• Scores update over time. The checked_at timestamp tells you when the data was last refreshed. For high-value transactions, request a fresh check.

For the full API reference including x402 payment details, see the Developer API documentation. To understand how on-chain analysis fits into a broader workflow, read our complete on-chain analysis workflow guide.

Originally published at https://theonchaindiary.com/articles/address-risk-scoring-api-guide/. More Web3 security guides and risk-scoring tools at Onchain Diary.