Address Risk Score

Get Address Risk Score

curl --request GET \
  --url https://api.range.org/v1/risk/address \
  --header 'X-API-KEY: <api-key>'

import requests

url = "https://api.range.org/v1/risk/address"

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.range.org/v1/risk/address', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.range.org/v1/risk/address",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.range.org/v1/risk/address"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.range.org/v1/risk/address")
  .header("X-API-KEY", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.range.org/v1/risk/address")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "riskScore": 8,
  "numHops": 123,
  "maliciousAddressesFound": [
    {
      "address": "<string>",
      "distance": 123,
      "name_tag": "<string>",
      "entity": "<string>",
      "category": "<string>"
    }
  ],
  "reasoning": "<string>",
  "attribution": {
    "name_tag": "Token Program",
    "entity": "Solana",
    "category": "SYSTEM",
    "address_role": "Program"
  }
}

GET

risk

address

Get Address Risk Score

curl --request GET \
  --url https://api.range.org/v1/risk/address \
  --header 'X-API-KEY: <api-key>'

import requests

url = "https://api.range.org/v1/risk/address"

headers = {"X-API-KEY": "<api-key>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {'X-API-KEY': '<api-key>'}};

fetch('https://api.range.org/v1/risk/address', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.range.org/v1/risk/address",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-KEY: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.range.org/v1/risk/address"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.range.org/v1/risk/address")
  .header("X-API-KEY", "<api-key>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.range.org/v1/risk/address")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<api-key>'

response = http.request(request)
puts response.read_body

{
  "riskScore": 8,
  "numHops": 123,
  "maliciousAddressesFound": [
    {
      "address": "<string>",
      "distance": 123,
      "name_tag": "<string>",
      "entity": "<string>",
      "category": "<string>"
    }
  ],
  "reasoning": "<string>",
  "attribution": {
    "name_tag": "Token Program",
    "entity": "Solana",
    "category": "SYSTEM",
    "address_role": "Program"
  }
}

Returns a risk score (1–10) for a blockchain address based on its proximity to known malicious actors, ML-based behavioral analysis, and threat intelligence data. See Understanding Risk Scores for methodology details.

This endpoint includes sanctions and blacklist screening. You do not need to call the Sanctions & Blacklist Check separately, addresses flagged by OFAC or stablecoin issuer blacklists are already factored into the risk score.For payment flows where you need to assess both sender and recipient in the context of a transaction, use the Payment Risk Assessment instead. It includes everything this endpoint does, plus additional payment-specific checks: new wallet detection, dormant wallet detection, address poisoning detection, interaction history between sender and recipient, token risk assessment, and cross-chain analysis.

Query Parameters

Name	Type	Required	Description
`address`	string	Yes	The blockchain address to assess.
`network`	string	Yes	Blockchain network identifier. Must match the address format. See Supported Chains for the full list.

Supported Networks

The following 27 networks are fully supported with complete transaction graph analysis and proximity scoring: Solana

Network	Identifier
Solana	`solana`

EVM Chains

Network	Identifier
Ethereum Mainnet	`eth`
Optimism Mainnet	`oeth`
BNB Smart Chain	`bnb`
Polygon Mainnet	`pol`
Polygon zkEVM	`zkevm`
Moonbeam	`moonbeam`
Base	`base`
Arbitrum One	`arb1`
Celo Mainnet	`celo`
Avalanche C-Chain	`avax`

Other

Network	Identifier
Stellar	`stellar`
Bitcoin Mainnet	`bitcoin`
Tron	`tron`

Cosmos Ecosystem

Network	Identifier
Celestia	`celestia`
Osmosis	`osmosis-1`
Cosmos Hub	`cosmoshub-4`
dYdX Mainnet	`dydx-mainnet-1`
Neutron	`neutron-1`
Dymension	`dymension_1100-1`
Agoric	`agoric-3`
Mantra	`mantra-1`
Stride	`stride-1`
PIO Mainnet	`pio-mainnet-1`
Noble	`noble-1`
ZigChain	`zigchain-1`
Union	`union-1`

Partial Network Support

Other networks may 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

For optimal results, use one of the fully supported networks listed above.

Response Schema

Field	Type	Description
`riskScore`	number (1–10)	Numerical risk value. Higher scores indicate greater risk.
`riskLevel`	string	Human-readable risk description aligned to the score.
`numHops`	integer (≥0)	Minimum token-transfer steps to any known malicious address. `0` means the address itself is malicious.
`maliciousAddressesFound`	array	Evidence used in scoring (see below).
`reasoning`	string	Plain-English explanation of why the score was assigned.
`attribution`	object \| null	Attribution metadata for known non-malicious addresses. When present, indicates a verified entity with risk override applied.

Malicious Evidence Object

Field	Type	Description
`address`	string	Malicious or ML-flagged address on the path.
`distance`	integer (≥0)	Number of hops from the input address.
`name_tag`	string \| null	Human-readable label describing the activity.
`entity`	string \| null	Known organization or cluster.
`category`	string	Type of malicious activity.

When name_tag, entity, or category are blank or null, this indicates either: (1) data from confidential intelligence sources where attribution details cannot be disclosed, or (2) the address was identified through ML models and lacks traditional attribution data. In both cases, the address presents potential risk but detailed attribution may be limited.

Attribution Object

When present, indicates the address is a verified non-malicious entity with risk override to score 1.

Field	Type	Description
`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

Score	Risk Level	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. Risk analysis examines paths up to 5 hops from the input address.

Examples

High-Risk Address (Score 10)

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

{
  "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 (Score 1)

curl -G https://api.range.org/v1/risk/address \
  --data-urlencode "address=2oP36hojo3spVLvrhqNVW8ERUEYMKFAS2XVAmFv289WJ" \
  --data-urlencode "network=solana" \
  -H "Authorization: Bearer your_api_key_here"

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

System Address with Attribution Override

curl -G https://api.range.org/v1/risk/address \
  --data-urlencode "address=TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" \
  --data-urlencode "network=solana" \
  -H "Authorization: Bearer your_api_key_here"

{
  "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

curl -G https://api.range.org/v1/risk/address \
  --data-urlencode "address=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" \
  --data-urlencode "network=celestia" \
  -H "Authorization: Bearer your_api_key_here"

{
  "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

curl -G https://api.range.org/v1/risk/address \
  --data-urlencode "address=0x5d87eaeb84c694a12e01c445fca0b1c527613c25" \
  --data-urlencode "network=eth" \
  -H "Authorization: Bearer your_api_key_here"

{
  "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."
}

Errors

HTTP Code	Cause	Recommended Action
400	Missing or invalid `address`/`network`	Validate parameters before requesting.
404	Address/network not found or unsupported	Use a supported `network` value; ensure address correctness.
429	Rate limited	Reduce request rate; follow `Retry-After` header for backoff.
5xx	Server error	Retry after a delay; contact support if persistent.

Best Practices

Always provide a network value consistent with the address format.
Use both riskScore and riskLevel in your UI, and display reasoning as explanatory text.
Check the attribution field, when present, it indicates a verified non-malicious address with risk override applied.
When multiple malicious addresses are found, display at least the entry with the smallest distance.
numHops represents the minimum token-transfer distance; greater distances generally reduce risk.

TypeScript Types

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;
}

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

Network ID of the address. Supports multiple networks including eth, solana, stellar, osmosis-1, dydx-mainnet-1, cosmoshub-4, neutron-1, and others. If omitted, will attempt to automatically infer from address format (eth, stellar, solana).

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

reasoning

string

required

Explanation of why the risk level/score was assigned

attribution

object | null

Attribution information for known non-malicious addresses

Show child attributes

Last modified on June 17, 2026

Privacy Protocol Screening Token Risk Assessment

Overview

Guides

Risk Endpoints

Risk v2 Endpoints

Alerts

Simulator

Product Information

Query Parameters

Supported Networks

Response Schema

Malicious Evidence Object

Attribution Object

Risk Scoring Logic

Examples

High-Risk Address (Score 10)

Low-Risk Solana Address (Score 1)

System Address with Attribution Override

Celestia Network

Cross-Chain Address

Errors

Best Practices

Authorizations

Query Parameters

Response

​Query Parameters

​Supported Networks

​Response Schema

​Malicious Evidence Object

​Attribution Object

​Risk Scoring Logic

​Examples

​High-Risk Address (Score 10)

​Low-Risk Solana Address (Score 1)

​System Address with Attribution Override

​Celestia Network

​Cross-Chain Address

​Errors

​Best Practices

Authorizations

Query Parameters

Response

Query Parameters

Supported Networks

Response Schema

Malicious Evidence Object

Attribution Object

Risk Scoring Logic

Examples

High-Risk Address (Score 10)

Low-Risk Solana Address (Score 1)

System Address with Attribution Override

Celestia Network

Cross-Chain Address

Errors

Best Practices