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

# Risk API Quick Start

> Make your first Risk API calls and learn how to interpret the responses.

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.

<Info>
  **You'll need an API key.** All requests require a Bearer token. If you don't have one yet, [get your API key →](/introduction/getting-started)
</Info>

***

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

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

***

## 1. Screen an Address

The [Address Risk Score](/risk-api/risk/get-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](/risk-api/product-info/supported-chains).

<CodeGroup>
  ```bash cURL 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"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<Accordion title="Example Response">
  ```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"
    }
  }
  ```
</Accordion>

### 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](/risk-api/risk/get-sanctions-blacklist-check) endpoint screens an address against OFAC sanctions and stablecoin issuer blacklists (Tether, Circle, Coinbase, Paxos).

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.range.org/v1/risk/sanctions/0x1da5821544e25c636c1417ba96ade4cf6d2f9b5a" \
    --data-urlencode "include_details=false" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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();
  ```

  ```python Python theme={null}
  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()
  ```
</CodeGroup>

<Accordion title="Example Response (Minimal)">
  ```json theme={null}
  {
    "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
  }
  ```
</Accordion>

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

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

***

## 3. Assess Payment Risk

The [Payment Risk Assessment](/risk-api/risk/get-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.

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    sender_address: "[To Do]",
    recipient_address: "[To Do]",
    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();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.range.org/v1/risk/payment",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={
          "sender_address": "[To Do]",
          "recipient_address": "[To Do]",
          "amount": "1000.0",
          "sender_network": "solana",
          "recipient_network": "solana",
      },
  )
  data = response.json()
  ```
</CodeGroup>

<Accordion title="Example Response">
  ```json theme={null}
  {
    "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": []
  }
  ```
</Accordion>

### 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](/risk-api/risk/get-token-risk-assessment) endpoint evaluates up to 17 risk factors for Solana tokens. Try it with USDC:

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    mint_address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    network: "solana",
  });

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

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.range.org/api/v1/ml/risk/assessment/token",
      headers={"Authorization": "Bearer YOUR_API_KEY"},
      params={
          "mint_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
          "network": "solana",
      },
  )
  data = response.json()
  ```
</CodeGroup>

<Accordion title="Example Response (Abbreviated)">
  ```json theme={null}
  {
    "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"
    ]
  }
  ```
</Accordion>

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

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

***

## 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](/risk-api/product-info/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](/risk-api/product-info/rate-limits).             |
|   **5xx** | Server error                                         | Retry after a delay. Contact support if persistent.                                               |

***

## What's Next

<CardGroup cols={2}>
  <Card title="Test Addresses" icon="vial" href="/risk-api/product-info/test-addresses">
    More test addresses across all endpoints and networks for verifying your integration.
  </Card>

  <Card title="Understanding Risk Scores" icon="input-numeric" href="/risk-api/product-info/understanding-risk-scores">
    Deep dive into how scores are calculated and how to interpret them.
  </Card>

  <Card title="Compliance Pipeline" icon="gavel" href="/risk-api/guides/compliance-screening-pipeline">
    Build a multi-layered screening workflow combining multiple endpoints.
  </Card>

  <Card title="Wallet Integration" icon="wallet" href="/risk-api/guides/wallet-dapp-integration">
    Add real-time risk protection to wallets and dApps.
  </Card>
</CardGroup>