> ## Documentation Index
> Fetch the complete documentation index at: https://docs.range.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Address Risk Score

> Returns the risk score for a specific blockchain address based on network proximity analysis, machine learning, and behavioral pattern recognition.


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](/risk-api/product-info/understanding-risk-scores) for methodology details.

<Note>
  **This endpoint includes sanctions and blacklist screening.** You do not need to call the [Sanctions & Blacklist Check](/risk-api/risk/get-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](/risk-api/risk/get-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.
</Note>

***

## 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](/risk-api/product-info/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`          |

<Accordion title="Partial Network Support">
  Other networks may yield results in two scenarios:

  1. **Direct Attribution**: When we have direct attribution data for an address on that network (e.g., a known malicious contract address)
  2. **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.
</Accordion>

***

## 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.                   |

<Note>
  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.
</Note>

### 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)

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

```json theme={null}
{
  "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)

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

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

### System Address with Attribution Override

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

```json theme={null}
{
  "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

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

```json theme={null}
{
  "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

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

```json theme={null}
{
  "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.

<Accordion title="TypeScript Types">
  ```ts theme={null}
  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;
  }
  ```
</Accordion>


## OpenAPI

````yaml get /v1/risk/address
openapi: 3.0.0
info:
  title: Range Risk API
  description: The Range Risk API for risk assessment of crypto addresses.
  version: 1.7.8
  contact: {}
servers:
  - url: https://api.range.org
    description: Range API Server
security:
  - Authorization: []
tags:
  - name: Risk
    description: Get risk information about a crypto address.
  - name: Risk v2
    description: >-
      Address risk assessment, workspace configuration, and signals catalogue
      (API v2).
  - name: Simulator
    description: Simulate a transaction on a network.
  - name: Alert Templates
    description: Browse alert rule templates available to the workspace.
  - name: Alert Rules
    description: Create and manage workspace alert rules.
  - name: Alert Events
    description: List and retrieve fired alert events.
  - name: Channels
    description: Configure alert delivery channels.
paths:
  /v1/risk/address:
    get:
      tags:
        - Risk
      summary: Get Address Risk Score
      description: Returns the risk score associated with the specified address.
      operationId: getRiskPath
      parameters:
        - name: address
          required: false
          in: query
          description: Address to search
          schema:
            type: string
        - name: network
          required: false
          in: query
          description: >-
            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).
          schema:
            example: solana
            type: string
      responses:
        '200':
          description: >-
            Transactions associated with a specific address. This includes both
            incoming and outgoing transactions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskScore'
components:
  schemas:
    RiskScore:
      type: object
      properties:
        riskScore:
          type: number
          nullable: true
          description: Calculated normalized risk score (higher = riskier)
          example: 8
        riskLevel:
          enum:
            - CRITICAL RISK (Directly malicious)
            - Extremely high risk
            - High risk
            - Medium risk
            - Low risk
            - Very low risk
          type: string
          description: Human readable risk level classification
        numHops:
          type: number
          nullable: true
          description: Minimum number of hops to the closest malicious address
        maliciousAddressesFound:
          description: List of malicious or related addresses discovered in the path
          type: array
          items:
            $ref: '#/components/schemas/MaliciousMetadata'
        reasoning:
          type: string
          description: Explanation of why the risk level/score was assigned
        attribution:
          description: Attribution information for known non-malicious addresses
          nullable: true
          type: object
          allOf:
            - $ref: '#/components/schemas/Attribution'
      required:
        - riskScore
        - riskLevel
        - numHops
        - maliciousAddressesFound
        - reasoning
    MaliciousMetadata:
      type: object
      properties:
        address:
          type: string
          description: On-chain address flagged as malicious or related
        distance:
          type: number
          description: Distance in hops from the queried address (0 = directly malicious)
        name_tag:
          type: string
          description: Known name tag or label for the address
          nullable: true
        entity:
          type: string
          description: Entity or organization associated with the address
          nullable: true
        category:
          type: string
          description: Category of malicious behavior (e.g. scam, exploit, mixer)
          nullable: true
      required:
        - address
        - distance
        - name_tag
        - entity
        - category
    Attribution:
      type: object
      properties:
        name_tag:
          type: string
          description: Name or label for the attributed address
          example: Token Program
        entity:
          type: string
          description: Entity or organization associated with the address
          example: Solana
        category:
          type: string
          description: Category of the attributed address
          example: SYSTEM
        address_role:
          type: string
          description: Role or function of the address
          example: Program
      required:
        - name_tag
        - entity
        - category
        - address_role
  securitySchemes:
    Authorization:
      scheme: bearer
      bearerFormat: API Key
      description: 'Use Authorization: Bearer <api-key>'
      type: http

````