Risk API Quick Start

This guide walks you through your first calls to each Risk API endpoint. By the end, you’ll understand the request format, response structure, and key fields for each endpoint.

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"

Example 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"
  }
}

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 OFAC sanctions and stablecoin issuer blacklists (Tether, Circle, Coinbase, Paxos).

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

Example Response (Minimal)

{
  "address": "0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a",
  "network": null,
  "is_token_blacklisted": true,
  "is_ofac_sanctioned": false,
  "checked_at": "2025-12-01T16:07:27.972840Z",
  "token_status_summary": null,
  "blacklist_event_history": null,
  "ofac_info": null,
  "attribution": null
}

Key Response Fields

Field	What It Tells You
`is_token_blacklisted`	`true` if currently blacklisted by any stablecoin issuer.
`is_ofac_sanctioned`	`true` if the address appears on the OFAC SDN list.
`token_status_summary`	Per-token breakdown (which issuers, when blacklisted). Only with `include_details=true`.
`blacklist_event_history`	Full chronological event log. Only with `include_details=true`.
`ofac_info`	Sanction details including name, entity, and official OFAC URL.

Two Modes

Mode	Use Case
`include_details=true` (default)	Compliance workflows where you need full event history and attribution data
`include_details=false`	High-volume screening where you only need a pass/fail result

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=[To Do]" \
  --data-urlencode "recipient_address=[To Do]" \
  --data-urlencode "amount=1000.0" \
  --data-urlencode "sender_network=solana" \
  --data-urlencode "recipient_network=solana" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "overall_risk_level": "high",
  "risk_factors": [
    {
      "factor": "new_wallet_recipient",
      "risk_level": "medium",
      "description": "Recipient is a completely new wallet with no transaction history"
    },
    {
      "factor": "first_interaction",
      "risk_level": "high",
      "description": "First ever interaction between these addresses"
    }
  ],
  "processing_time_ms": 2456.78,
  "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 evaluates up to 17 risk factors for Solana tokens. Try it with USDC:

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

Example Response (Abbreviated)

{
  "token_info": {
    "mint_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "name": "USD Coin",
    "symbol": "USDC"
  },
  "overall_assessment": {
    "risk_level": "LOW",
    "risk_score": 6,
    "max_score": 26,
    "risk_percentage": 23.1
  },
  "summary": {
    "total_factors": 13,
    "high_risk_count": 3,
    "medium_risk_count": 0,
    "low_risk_count": 10
  },
  "risk_factors": {
    "freeze_authority": {
      "level": "HIGH",
      "explanation": "Freeze authority present - token accounts can be frozen by authority"
    },
    "minting_authority": {
      "level": "HIGH",
      "explanation": "Mint authority present - new tokens can be created, diluting existing holders"
    },
    "market_cap": {
      "level": "LOW",
      "explanation": "Market cap >$100,000,000 - established project"
    }
  },
  "processing_time_ms": 378.2,
  "errors": [
    "Dev migration data not available - dev_migrations assessment skipped"
  ]
}

Key Response Fields

Field	What It Tells You
`overall_assessment.risk_level`	`"LOW"`, `"MEDIUM"`, or `"HIGH"` based on the aggregate score.
`overall_assessment.risk_percentage`	Percentage of maximum possible risk. LOW <30%, MEDIUM 30-60%, HIGH ≥60%.
`summary`	How many factors were assessed and how many triggered at each level.
`risk_factors`	Individual assessments with `level` and `explanation` for each factor.
`errors`	Which factors were skipped due to missing data. Fewer assessed factors = less reliable result.

USDC shows HIGH for freeze_authority and minting_authority - this is expected for regulated stablecoins and doesn’t indicate a problem. The overall score accounts for all factors together.

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.
422	Validation error (e.g., invalid mint address format)	Check input format requirements in the endpoint docs.
429	Rate limit exceeded	Implement exponential backoff. See Rate Limits.
5xx	Server error	Retry after a delay. Contact support if persistent.

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

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

Two Modes

3. Assess Payment Risk

Key Response Fields

Risk Dimensions Checked

4. Evaluate a Token

Key Response Fields

Common Errors

What’s Next

Test Addresses

Understanding Risk Scores

Compliance Pipeline

Wallet Integration

Overview

Guides

Risk Endpoints

Simulator

Product Information

​Authentication

​1. Screen an Address

​Key Response Fields

​What the Scores Mean

​2. Check Sanctions & Blacklists

​Key Response Fields

​Two Modes

​3. Assess Payment Risk

​Key Response Fields

​Risk Dimensions Checked

​4. Evaluate a Token

​Key Response Fields

​Common Errors

​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

Two Modes

3. Assess Payment Risk

Key Response Fields

Risk Dimensions Checked

4. Evaluate a Token

Key Response Fields

Common Errors

What’s Next