Risk API Quick Start

This guide walks you through your first calls to each Risk API endpoint. It covers request formats, address and payment response fields, sanctions results, and token validation errors.

You’ll need an API key. All requests require a Bearer token. If you don’t have one yet, get your API key →

Authentication

Every Risk API request uses the same authentication pattern. Pass your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Base URL: https://api.range.org

Keep your API key server-side. Never expose it in client-side code or public repositories.

1. Screen an Address

The Address Risk Score endpoint is the most commonly used starting point. It returns a risk score (1-10) for any blockchain address across 27 supported networks.

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

const params = new URLSearchParams({
  address: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  network: "solana",
});

const response = await fetch(
  `https://api.range.org/v1/risk/address?${params}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();

import requests

response = requests.get(
    "https://api.range.org/v1/risk/address",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
        "network": "solana",
    },
)
data = response.json()

Example Response (Abbreviated)

{
  "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": "CoreToken"
  }
}

Key Response Fields

Field	What It Tells You
`riskScore`	Numerical risk (1-10). Higher = more dangerous.
`riskLevel`	Human-readable label for the score.
`numHops`	Shortest path distance to a known malicious address. `0` means the address itself is malicious.
`maliciousAddressesFound`	The evidence - which malicious addresses were found and how far away they are.
`reasoning`	Plain-English explanation of why the score was assigned. Display this to users.
`attribution`	If present, this is a verified non-malicious entity (exchange, system program, protocol). The score is overridden to 1.

What the Scores Mean

Score	Meaning	Typical Action
10	Directly malicious (0 hops)	Block
8-9	1 hop from malicious	Block or flag
6-7	2 hops from malicious	Flag for review
4-5	3 hops from malicious	Monitor
1-3	Low risk or verified entity	Allow

2. Check Sanctions & Blacklists

The Sanctions & Blacklist Check endpoint screens an address against every sanctions list Range ingests (OFAC, UK, EU, France, Japan, and more) and token issuer blacklists (Tether, Circle, Coinbase, PayPal, Paxos, Agora, Ripple).

curl -G "https://api.range.org/v1/risk/sanctions/0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a" \
  --data-urlencode "include_details=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

const address = "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a";

const response = await fetch(
  `https://api.range.org/v1/risk/sanctions/${address}?include_details=false`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();

import requests

address = "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a"

response = requests.get(
    f"https://api.range.org/v1/risk/sanctions/{address}",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"include_details": "false"},
)
data = response.json()

Example Response (Abbreviated)

The detail arrays below show only their first entry.

{
  "address": "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a",
  "network": "eth",
  "is_token_blacklisted": true,
  "is_ofac_sanctioned": true,
  "token_status_summary": [
    {
      "token": "USDC",
      "issuer": "Circle",
      "network": "eth",
      "is_currently_blacklisted": true,
      "first_blacklisted_date": "2021-04-21",
      "last_event_date": "2021-04-21",
      "last_event_type": "blacklist"
    }
  ],
  "blacklist_event_history": [
    {
      "event_type": "blacklist",
      "token": "USDC",
      "issuer": "Circle",
      "network": "eth",
      "date": "2021-04-21",
      "block_number": 12285873,
      "block_timestamp": "2021-04-21T21:04:36.000Z",
      "transaction_hash": "0x72959622df120df8cfe27fa371c5b82542cda695d09568975259c0cf70430bf9"
    }
  ],
  "ofac_info": {
    "is_sanctioned": true,
    "name_tag": "Secondeye Solution",
    "category": "OFAC Sanctioned",
    "entity": "OFAC",
    "address_role": "Entity",
    "first_sanctioned_date": "2021-04-15",
    "programs": [
      "CYBER2",
      "ELECTION-EO13848"
    ],
    "aliases": [
      "Forwarderz"
    ]
  },
  "attribution": {
    "name": "Secondeye Solution",
    "category": "Multi-Provider Blacklist & OFAC Sanctioned",
    "malicious": true
  },
  "checked_at": "2026-10-03T15:45:58.379Z",
  "lists_checked": true,
  "sanctions": [
    {
      "signal_id": "ofac-sanctioned",
      "source": "OFAC SDN",
      "jurisdiction": "US",
      "listed_at": "2021-04-15",
      "programs": [
        "CYBER2",
        "ELECTION-EO13848"
      ],
      "basis": "direct"
    }
  ],
  "is_sanctioned": true
}

Key Response Fields

Field	What It Tells You
`is_token_blacklisted`	`true` if currently blacklisted by any stablecoin issuer.
`is_sanctioned`	`true` if the address is on any government sanctions list (OFAC, UK, EU, France, Japan). `null` when a list could not be read: treat as unknown, not clean.
`is_ofac_sanctioned`	`true` if the address appears on the OFAC SDN list. OFAC only.
`sanctions`	One entry per list the address is on, with `source`, `jurisdiction`, `listed_at`, `programs`, and `basis`.
`lists_checked`	`false` when a sanctions or blacklist store could not be read and the result may be incomplete.
`token_status_summary`	Per-token breakdown (which issuers, when blacklisted). Returned when blacklist data exists.
`blacklist_event_history`	Full chronological event log. Returned when blacklist data exists.
`ofac_info`	Sanction details including name, entity, and official OFAC URL.

Compatibility Parameter

include_details is accepted for compatibility but ignored. Both true and false return the same detail fields; false does not produce a minimal response.

The Address Risk Score endpoint already includes sanctions and blacklist data in its scoring. Use this standalone endpoint when you need explicit sanctions documentation for audit trails, or the detailed event history.

3. Assess Payment Risk

The Payment Risk Assessment endpoint is the most comprehensive check. It analyzes both sender and recipient across 8 independent risk dimensions - including everything Address Risk Score does, plus payment-specific checks.

curl -G https://api.range.org/v1/risk/payment \
  --data-urlencode "sender_address=TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" \
  --data-urlencode "recipient_address=7UX2i7SucgLMQcfZ75s3VXmZZY4YRUyJN9X1RgfMoDUi" \
  --data-urlencode "amount=1000.0" \
  --data-urlencode "sender_network=solana" \
  --data-urlencode "recipient_network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  sender_address: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  recipient_address: "7UX2i7SucgLMQcfZ75s3VXmZZY4YRUyJN9X1RgfMoDUi",
  amount: "1000.0",
  sender_network: "solana",
  recipient_network: "solana",
});

const response = await fetch(
  `https://api.range.org/v1/risk/payment?${params}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();

import requests

response = requests.get(
    "https://api.range.org/v1/risk/payment",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "sender_address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
        "recipient_address": "7UX2i7SucgLMQcfZ75s3VXmZZY4YRUyJN9X1RgfMoDUi",
        "amount": "1000.0",
        "sender_network": "solana",
        "recipient_network": "solana",
    },
)
data = response.json()

Example Response (Abbreviated)

Only the first two risk factors are shown. Timing values vary between requests.

{
  "overall_risk_level": "medium",
  "risk_factors": [
    {
      "risk_context": "interaction",
      "factor": "first_interaction",
      "risk_level": "medium",
      "description": "First ever interaction between these addresses"
    },
    {
      "risk_context": "recipient",
      "factor": "established_wallet_recipient",
      "risk_level": "low",
      "description": "Recipient has on-chain signatures; last activity 270 days ago"
    }
  ],
  "processing_time_ms": 120.26670202612877,
  "errors": []
}

Key Response Fields

Field	What It Tells You
`overall_risk_level`	Final verdict: `"low"`, `"medium"`, `"high"`, or `"unknown"`. Uses maximum-risk approach - if any factor is high, the overall level is high.
`risk_factors`	Array of individual assessments. Each has a `factor` name, `risk_level`, and `description`.
`errors`	Non-empty if some checks couldn’t be performed (e.g., unsupported network for some checks).

Risk Dimensions Checked

Check	What It Detects
New wallet detection	Recipient has no transaction history
Dormant wallet detection	Recipient inactive for 180+ days
Address poisoning	Recipient matches a lookalike scam address
Interaction history	Sender and recipient have never transacted before
Malicious connections	Sender or recipient is close to known malicious addresses
Attributed address check	Sender or recipient is a known sanctioned or blacklisted entity
Token risk	Sender/recipient tokens have risk factors (Solana, requires `sender_token`/`recipient_token`)
Cross-chain analysis	Appropriate checks for same-network vs cross-chain payments

4. Evaluate a Token

The Token Risk Assessment endpoint accepts a Solana token mint as asset_address and requires network=solana. The request below uses USDC:

curl -G "https://api.range.org/v1/risk/token" \
  --data-urlencode "asset_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
  --data-urlencode "network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY"

const params = new URLSearchParams({
  asset_address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  network: "solana",
});

const response = await fetch(
  `https://api.range.org/v1/risk/token?${params}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);
const data = await response.json();

import requests

response = requests.get(
    "https://api.range.org/v1/risk/token",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "asset_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "network": "solana",
    },
)
data = response.json()

Common Errors

HTTP Code	Meaning	What to Do
400	Invalid parameters (missing address, bad format)	Check your query parameters.
401	Invalid or missing API key	Verify your `Authorization: Bearer` header.
404	Address or network not found	Check the network identifier against Supported Chains.
429	Rate limit exceeded	Implement exponential backoff. See Rate Limits.
5xx	Server error	Retry after a delay. Contact support if persistent.

Invalid Token Address

GET /v1/risk/token returns HTTP 400 for asset_address=not_a_real_address with network=solana:

curl -G https://api.range.org/v1/risk/token \
  --data-urlencode "asset_address=not_a_real_address" \
  --data-urlencode "network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "message": [
    "asset_address must be a valid Solana base58 address (32-44 chars, no 0 O I l)"
  ],
  "error": "Bad Request",
  "statusCode": 400
}

What’s Next

Test Addresses

More test addresses across all endpoints and networks for verifying your integration.

Understanding Risk Scores

Deep dive into how scores are calculated and how to interpret them.

Compliance Pipeline

Build a multi-layered screening workflow combining multiple endpoints.

Wallet Integration

Add real-time risk protection to wallets and dApps.

Overview

Guides

Risk Endpoints

Risk v2 Endpoints

Alerts

Simulator

Product Information

Risk API Quick Start

Authentication

1. Screen an Address

Key Response Fields

What the Scores Mean

2. Check Sanctions & Blacklists

Key Response Fields

Compatibility Parameter

3. Assess Payment Risk

Key Response Fields

Risk Dimensions Checked

4. Evaluate a Token

Common Errors

Invalid Token Address

What’s Next

Test Addresses

Understanding Risk Scores

Compliance Pipeline

Wallet Integration

​Authentication

​1. Screen an Address

​Key Response Fields

​What the Scores Mean

​2. Check Sanctions & Blacklists

​Key Response Fields

​Compatibility Parameter

​3. Assess Payment Risk

​Key Response Fields

​Risk Dimensions Checked

​4. Evaluate a Token

​Common Errors

​Invalid Token Address

​What’s Next

Test Addresses

Understanding Risk Scores

Compliance Pipeline

Wallet Integration

Authentication

1. Screen an Address

Key Response Fields

What the Scores Mean

2. Check Sanctions & Blacklists

Key Response Fields

Compatibility Parameter

3. Assess Payment Risk

Key Response Fields

Risk Dimensions Checked

4. Evaluate a Token

Common Errors

Invalid Token Address

What’s Next