Get Address Risk Score

Methodology

Our risk assessment leverages peer-reviewed research establishing that legitimate and malicious blockchain activity exhibit distinguishable network patterns. The approach is grounded in three empirically-validated behavioral characteristics: (1) malicious actors demonstrate clustering behavior through coordinated operations, shared infrastructure, or interconnected money laundering chains; (2) direct transactional relationships with malicious addresses correlate with elevated risk profiles; and (3) legitimate users maintain significantly shorter network distances to regulated cryptocurrency exchanges. Empirical analysis of the Ethereum blockchain substantiates these patterns: 56% of high-value USDC wallets maintain direct links to regulated exchanges, while 83% of confirmed exploiter addresses operate at greater distances from these entities (Liao et al., 2025). Our proprietary machine learning models augment this proximity analysis by extracting behavioral signatures from verified malicious addresses, enabling identification of previously undetected threats and substantially expanding coverage of malicious actors beyond conventional threat intelligence sources.

Enhanced Capabilities

We’re soon releasing enhanced capabilities that solve the core limitations of traditional risk scoring: inability to detect novel threats, excessive false positives on legitimate services, and lack of transaction context. Our multi-layered approach combines machine learning, intelligent entity recognition, and context-aware analysis to provide more accurate, actionable risk intelligence.

Query Parameters

Name	Type	Required	Description
address	string	✅	The blockchain address to assess.
network	string	✅	Canonical network identifier. The value must match the address format.

Supported Networks

The following networks are fully supported:

solana - Solana
celestia - Celestia
osmosis-1 - Osmosis
dydx-mainnet-1 - dYdX
cosmoshub-4 - Cosmos Hub
neutron-1 - Neutron
union-testnet-9 - Union Testnet
dymension_1100-1 - Dymension
agoric-3 - Agoric
mantra-1 - MANTRA
stride-1 - Stride
pio-mainnet-1 - Provenance
mantra-dukong-1 - MANTRA Dukong
noble-1 - Noble
zig-test-1 - Zig Test
union-1 - Union
stellar - Stellar

Partial Network Support

Other networks may be partially supported and can yield results in two scenarios:

Direct Attribution: When we have direct attribution data for an address on that network (e.g., a known malicious contract address)
Cross-Chain Propagation: When malicious activity propagates through inter-chain bridges or cross-chain transactions (e.g., a malicious Solana address that sends assets cross-chain)

Note: The network identifier must exactly match the format of the address being assessed. For optimal results, use one of the fully supported networks listed above.

Response Schema

A successful request returns a JSON object with the following structure:

{
  "riskScore": 10,
  "riskLevel": "CRITICAL RISK (Directly malicious)",
  "numHops": 0,
  "maliciousAddressesFound": [
    {
      "address": "AuZrspySopxfZUiXY6YxDyfS211KvXLe197kj3M2cLpq",
      "distance": 0,
      "name_tag": "Layering, Swapping",
      "entity": null,
      "category": "hack_funds"
    }
  ],
  "reasoning": "Address is directly flagged for malicious activity.",
  "attribution": null
}

Field Definitions

riskScore (number, 1–10) – A numerical value where higher scores indicate greater risk. The score reflects whether the address itself is malicious, or how close and well-connected it is to one or more malicious addresses.
riskLevel (string) – A human‑readable description of the risk, aligned to the riskScore.
numHops (integer ≥ 0) – The minimum number of token‑transfer steps connecting the input address to any known malicious address. A value of 0 means the address itself is malicious; 1 means it has directly transacted with a malicious address; 2 means there’s one intermediary address between it and a malicious address; and so on. Higher values indicate greater separation from threats and typically result in lower risk scores.
maliciousAddressesFound (array) – Evidence used in scoring. List of the malicious addresses that the address to assess is connected to. Each object contains:
- address (string) – A malicious or ML-flagged address encountered on the path.
- distance (integer ≥ 0) – Number of hops from the input address to this malicious address.
- name_tag (string | null) – A human‑readable label describing activity.
- entity (string | null) – Known organization or cluster controlling the malicious address.
- category (string) – Type of malicious activity.
Note: When fields like name_tag, entity, or category are blank or null, this indicates one of two scenarios: (1) the data comes from confidential intelligence sources where specific attribution details cannot be disclosed, or (2) the address was identified through our machine learning models and lacks traditional attribution data. In both cases, we can confirm the address presents potential risk, but detailed attribution may be limited.
reasoning (string) – Plain‑English explanation of why the score was assigned. This may include information about direct malicious activity, proximity to malicious addresses, or other insights.
attribution (object | null) – Attribution metadata for known non-malicious addresses (e.g., system programs, well-known protocols). When present, indicates the address is a verified non-malicious entity, which may override proximity-based risk scoring. Contains:
- name_tag (string) – Human-readable name (e.g., “Token Program”)
- entity (string) – Organization or protocol (e.g., “Solana”)
- category (string) – Classification type (e.g., “SYSTEM”)
- address_role (string) – Functional role (e.g., “Program”)

Risk Scoring Logic

The risk score is computed using a combination of:

Attribution override – Known non-malicious addresses (system programs, verified protocols) receive the minimum risk score regardless of proximity to malicious addresses.
Direct maliciousness – If the address is itself flagged, it receives the maximum score.
Hop distance – The shortest path (numHops) to any malicious address. Fewer hops imply higher risk.
Hits – The total number of malicious addresses found on the shortest and near‑shortest paths.

The table below maps score ranges to risk levels and typical situations:

riskScore	riskLevel	Typical situation
10	CRITICAL RISK (directly malicious)	Address itself is flagged (0 hops)
9–8	Extremely high risk	1 hop from malicious; ≥ 3 hits ⇒ 9, otherwise 8
7–6	High risk	2 hops; ≥ 3 hits ⇒ 7, otherwise 6
5–4	Medium risk	3 hops; ≥ 3 hits ⇒ 5, otherwise 4
3–2	Low risk	4 hops; ≥ 3 hits ⇒ 3, otherwise 2
1	Very low risk	≥ 5 hops OR known attributed non-malicious address

Where “hits” refers to the number of malicious addresses found along the relevant paths. Note: Addresses identified as known non-malicious entities (system programs, verified protocols) receive a risk score of 1 regardless of graph proximity to malicious addresses. This attribution override prevents false positives for legitimate infrastructure that naturally has high transaction volumes and diverse counterparties. Search Limitations: Risk analysis examines paths up to 5 hops from the input address. Addresses with no connections to malicious entities within this range receive the lowest risk score (1).

Data Sources & Machine Learning

The risk score leverages multiple data sources: confirmed malicious addresses from threat intelligence, high-probability malicious addresses identified through machine learning, and verified non-malicious addresses (system programs, protocols, exchanges). This multi-faceted approach creates a comprehensive attribution dataset that significantly expands coverage beyond traditional threat intelligence while reducing false positives.

Data Attribution

Our attribution dataset provides off-chain information (name_tag, category, entity, address_role, malicious status) from multiple sources including internal research, community reports, government sanctions lists, partnerships with security companies, and other public/private sources. Attribution Override: Known non-malicious addresses (system programs like Token Program, verified protocols, major exchanges) are identified in our attribution database. When an address is confirmed as a non-malicious entity, the risk score is automatically overridden to the minimum value (1, “Very low risk”), regardless of graph proximity to malicious addresses. This prevents false positives where legitimate system infrastructure appears risky due to high transaction volumes with diverse counterparties. The attribution field in the response provides transparency about this override.

Machine Learning Enhancement

Our ML algorithms enhance traditional address matching by learning behavioral patterns from known malicious addresses. The process involves:

Behavioral Fingerprinting: Analyzing transaction history to generate 100+ address-level features that capture payment patterns, timing behaviors, and counterparty interactions.
Pattern Recognition: Training classifiers to recognize behavioral patterns that distinguish malicious actors from legitimate users
Ensemble Classification: Combining multiple ML models to improve accuracy in identifying potentially malicious addresses.

This approach helps us identify addresses that exhibit malicious behavior patterns but haven’t yet been tagged through traditional sources. Addresses flagged as potentially malicious by our ML models are treated in the same way as the foundational attribution dataset in this service.

Examples

High‑risk (score = 10)

curl -G https://api.range.org/v1/risk/address \
  --data-urlencode "address=AuZrspySopxfZUiXY6YxDyfS211KvXLe197kj3M2cLpq" \
  --data-urlencode "network=solana" \
  -H "X-API-KEY: your_api_key_here"

Response:

{
  "riskScore": 10,
  "riskLevel": "CRITICAL RISK (Directly malicious)",
  "numHops": 0,
  "maliciousAddressesFound": [
    {
      "address": "AuZrspySopxfZUiXY6YxDyfS211KvXLe197kj3M2cLpq",
      "distance": 0,
      "name_tag": "Layering, Swapping",
      "entity": null,
      "category": "hack_funds"
    }
  ],
  "reasoning": "Address is directly flagged for malicious activity."
}

Low‑risk Solana Address

curl --location 'https://api.range.org/v1/risk/address?address=2oP36hojo3spVLvrhqNVW8ERUEYMKFAS2XVAmFv289WJ&network=solana' \
  --header 'X-API-KEY: your_api_key_here'

Response:

{
  "riskScore": 1,
  "riskLevel": "Very low risk",
  "numHops": 5,
  "maliciousAddressesFound": [],
  "reasoning": "No suspicious paths found within 5 hops."
}

Solana Token Program (System Address)

curl --location 'https://api.range.org/v1/risk/address?address=TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA&network=solana' \
  --header 'X-API-KEY: your_api_key_here'

Response:

{
  "riskScore": 1,
  "riskLevel": "Very low risk",
  "numHops": 2,
  "maliciousAddressesFound": [
    {
      "address": "CPMMoo8L3F4NbTegBCKVNunggL7H1ZpdTHKxQB5qKP1C",
      "distance": 2,
      "name_tag": "",
      "entity": "",
      "category": ""
    }
  ],
  "reasoning": "Despite being 2 hop(s) from malicious addresses, this is a known system address (Token Program - Solana). Risk overridden to very low.",
  "attribution": {
    "name_tag": "Token Program",
    "entity": "Solana",
    "category": "SYSTEM",
    "address_role": "Program"
  }
}

Celestia Network Example

curl --location 'https://api.range.org/v1/risk/address?address=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263&network=celestia' \
  --header 'X-API-KEY: your_api_key_here'

Response:

{
  "riskScore": 1,
  "riskLevel": "Very low risk",
  "numHops": 5,
  "maliciousAddressesFound": [],
  "reasoning": "No malicious addresses found within 5 hops. This Celestia address shows no direct or indirect connections to known threats."
}

Cross-Chain Address Example

This example shows a 0x-prefixed address that may have risk data due to direct attribution or cross-chain activity:

curl --location 'https://api.range.org/v1/risk/address?address=0x5d87eaeb84c694a12e01c445fca0b1c527613c25&network=eth' \
  --header 'X-API-KEY: your_api_key_here'

Response:

{
  "riskScore": 3,
  "riskLevel": "Low risk",
  "numHops": 4,
  "maliciousAddressesFound": [
    {
      "address": "0xSuspicious...",
      "distance": 4,
      "name_tag": "Flagged Contract",
      "entity": "",
      "category": "Suspected"
    }
  ],
  "reasoning": "This address is 4 hops away from 1 suspected address, indicating low risk."
}

Another Solana Example

curl --location 'https://api.range.org/v1/risk/address?address=7AmvTQJAQAseV53Sqbnwxm3MTKKy6chZa1rhT1FqRkfL&network=solana' \
  --header 'X-API-KEY: your_api_key_here'

TypeScript Types (Suggested)

Developers using TypeScript can define types to model the API responses. The following interfaces mirror the fields returned by this endpoint:

type RiskLevel =
  | "CRITICAL RISK (Directly malicious)"
  | "Extremely high risk"
  | "High risk"
  | "Medium risk"
  | "Low risk"
  | "Very low risk";

interface MaliciousEvidence {
  address: string;
  distance: number;
  name_tag: string | null;
  entity: string | null;
  category: string;
}

interface Attribution {
  name_tag: string;
  entity: string;
  category: string;
  address_role: string;
}

interface AddressRiskResponse {
  riskScore: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10;
  riskLevel: RiskLevel;
  numHops: number;
  maliciousAddressesFound: MaliciousEvidence[];
  reasoning: string;
  attribution?: Attribution | null;
}

These types can help ensure that your client code accurately models the API’s structure.

Errors

HTTP Code	Cause	Example Body	Recommended Action
400	Missing or invalid `address`/`network`	`{ "error": "BadRequest", "message": "address is required" }`	Validate parameters before requesting.
404	Address/network not found or unsupported	`{ "error": "NotFound", "message": "network unsupported" }`	Use a supported `network` value; ensure address correctness.
429	Rate limited	`{ "error": "RateLimitExceeded" }`	Reduce request rate; follow `Retry-After` header for backoff.
5xx	Server error	`{ "error": "ServerError" }`	Retry after a delay; contact support if persistent.

Notes & Best Practices

Always provide a network value consistent with the address format.
Interpret numHops as the minimum transfer distance; greater distances generally reduce risk.
Use both riskScore and riskLevel in your UI, and display reasoning as explanatory text.
When multiple malicious addresses are found, display at least the entry with the smallest distance.
Check the attribution field: when present, it indicates a verified non-malicious address with risk override applied.
The term hops is retained from an earlier Neo4j-based implementation but simply refers to token‑transfer steps in a transaction graph.

Use Cases

Real‑time address screening ahead of payment execution.
Compliance monitoring (AML/KYC) with proximity plus behavioral heuristics.
Fraud prevention by detecting address poisoning and suspicious reactivations.
Security analysis of counterpart interactions within and across chains.

Authorizations

X-API-KEY

string

header

required

Authorization method required to allow user to access the api endpoints.

Query Parameters

address

string

Address to search

network

string

default:solana

Network ID of the address. Supports multiple networks including solana, osmosis-1, dydx-mainnet-1, cosmoshub-4, neutron-1, stellar, and others.

Example:

"solana"

Response

200 - application/json

Transactions associated with a specific address. This includes both incoming and outgoing transactions.

riskScore

number | null

required

Calculated normalized risk score (higher = riskier)

Example:

8

riskLevel

enum<string>

required

Human readable risk level classification

Available options:

CRITICAL RISK (Directly malicious),

Extremely high risk,

High risk,

Medium risk,

Low risk,

Very low risk

numHops

number | null

required

Minimum number of hops to the closest malicious address

maliciousAddressesFound

object[]

required

List of malicious or related addresses discovered in the path

Show child attributes

maliciousAddressesFound.address

string

required

On-chain address flagged as malicious or related

maliciousAddressesFound.distance

number

required

Distance in hops from the queried address (0 = directly malicious)

maliciousAddressesFound.name_tag

string | null

required

Known name tag or label for the address

maliciousAddressesFound.entity

string | null

required

Entity or organization associated with the address

maliciousAddressesFound.category

string | null

required

Category of malicious behavior (e.g. scam, exploit, mixer)

reasoning

string

required

Explanation of why the risk level/score was assigned

attribution

object

Attribution information for known non-malicious addresses

Show child attributes

attribution.name_tag

string

required

Name or label for the attributed address

Example:

"Token Program"

attribution.entity

string

required

Entity or organization associated with the address

Example:

"Solana"

attribution.category

string

required

Category of the attributed address

Example:

"SYSTEM"

attribution.address_role

string

required

Role or function of the address

Example:

"Program"

Overview

Risk

Simulator

Get Address Risk Score

Methodology

Enhanced Capabilities

Query Parameters

Supported Networks

Partial Network Support

Response Schema

Field Definitions

Risk Scoring Logic

Data Sources & Machine Learning

Data Attribution

Machine Learning Enhancement

Examples

High‑risk (score = 10)

Low‑risk Solana Address

Solana Token Program (System Address)

Celestia Network Example

Cross-Chain Address Example

Another Solana Example

TypeScript Types (Suggested)

Errors

Notes & Best Practices

Use Cases

Authorizations

Query Parameters

Response

Overview

Risk

Simulator

​Methodology

​Enhanced Capabilities

​Query Parameters

​Supported Networks

​Partial Network Support

​Response Schema

​Field Definitions

​Risk Scoring Logic

​Data Sources & Machine Learning

​Data Attribution

​Machine Learning Enhancement

​Examples

​High‑risk (score = 10)

​Low‑risk Solana Address

​Solana Token Program (System Address)

​Celestia Network Example

​Cross-Chain Address Example

​Another Solana Example

​TypeScript Types (Suggested)

​Errors

​Notes & Best Practices

​Use Cases

Authorizations

Query Parameters

Response

Methodology

Enhanced Capabilities

Query Parameters

Supported Networks

Partial Network Support

Response Schema

Field Definitions

Risk Scoring Logic

Data Sources & Machine Learning

Data Attribution

Machine Learning Enhancement

Examples

High‑risk (score = 10)

Low‑risk Solana Address

Solana Token Program (System Address)

Celestia Network Example

Cross-Chain Address Example

Another Solana Example

TypeScript Types (Suggested)

Errors

Notes & Best Practices

Use Cases