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

# Token Risk Assessment

> Comprehensive risk assessment for Solana tokens using advanced heuristic analysis.

Evaluates up to 17 independent risk factors across multiple categories to identify potential threats, vulnerabilities, and suspicious attributes in tokens. See [Understanding Risk Scores](/risk-api/product-info/understanding-risk-scores) for general methodology.

**Key features:**

* Multi-factor analysis across 17 distinct risk dimensions
* Real-time assessment with typical response times under 500ms
* Graceful degradation when some data sources are unavailable
* Human-readable explanations for each risk factor

<Info>
  **Currently supports Solana.** Ethereum support is in development. Base, Arbitrum, and Polygon are on the roadmap.
</Info>

***

## Parameters

| Parameter      | Type   | Required | Description                                                                 |
| -------------- | ------ | -------- | --------------------------------------------------------------------------- |
| `mint_address` | string | Yes      | Solana token mint address (32-44 character base58 string)                   |
| `network`      | string | No       | Blockchain network (default: `solana`). Currently only Solana is supported. |

***

## Response Schema

### Top-Level Fields

| Field                | Type   | Description                                                                               |
| -------------------- | ------ | ----------------------------------------------------------------------------------------- |
| `token_info`         | object | Token metadata: `mint_address`, `name`, `symbol`                                          |
| `overall_assessment` | object | Risk result: `risk_level` (LOW/MEDIUM/HIGH), `risk_score`, `max_score`, `risk_percentage` |
| `summary`            | object | Factor counts: `total_factors`, `high_risk_count`, `medium_risk_count`, `low_risk_count`  |
| `risk_factors`       | object | Individual assessments keyed by factor name. Each contains `level` and `explanation`.     |
| `processing_time_ms` | number | Processing time in milliseconds.                                                          |
| `errors`             | array  | Non-fatal errors (e.g., skipped assessments due to missing data).                         |

### Scoring System

Each risk factor scores: **LOW** = 0 points, **MEDIUM** = 1 point, **HIGH** = 2 points.

Risk percentage = `(total_score / max_possible_score) × 100`

| Classification | Threshold                      |
| -------------- | ------------------------------ |
| **HIGH**       | ≥60% of maximum possible score |
| **MEDIUM**     | ≥30% but \<60%                 |
| **LOW**        | \<30%                          |

Custom threshold configuration is available for enterprise clients, contact [info@range.org](mailto:info@range.org).

***

## Risk Factors

The API evaluates up to 17 risk factors across 5 categories. Not all factors may be assessed for every token due to data availability.

<AccordionGroup>
  <Accordion title="Authority & Control (3 factors)">
    **Circulating Supply Ratio**: Detects dilution risk from centralized mint authority control. LOW: >95% circulating, MEDIUM: 80–95%, HIGH: \<80%.

    **Freeze Authority**: Identifies trading restriction risk. Freeze authority allows token accounts to be frozen, preventing trading. HIGH: present, LOW: absent/disabled.

    **Mint Authority**: Assesses supply inflation risk. Active mint authority enables unlimited token creation. HIGH: present, LOW: absent/disabled.
  </Accordion>

  <Accordion title="Market Structure (5 factors)">
    **Market Capitalization**: Smaller caps are more susceptible to manipulation. HIGH: \<$1M, MEDIUM: $1M–$100M, LOW: \>$100M.

    **Token Verification**: Unverified tokens lack institutional due diligence. HIGH: unverified, LOW: verified.

    **Liquidity**: Low liquidity can trap holders. HIGH: \<$10K, MEDIUM: $10K–$100K, LOW: \>$100K.

    **Holder Count**: Few holders indicate high concentration risk. HIGH: \<100, MEDIUM: 100–1000, LOW: >1000.

    **Top Holder Concentration**: Extreme concentration enables coordinated dump attacks. HIGH: >90%, MEDIUM: 80–90%, LOW: \<80%.
  </Accordion>

  <Accordion title="Trading Patterns (3 factors)">
    **Price Volatility**: Extreme swings suggest instability or manipulation. HIGH: >50%, MEDIUM: 20–50%, LOW: \<20%.

    **Wash Trading**: Detects artificial trading creating false liquidity impressions. HIGH: suspicious in ≥2 timeframes, LOW: normal patterns.

    **Organic Activity**: Evaluates authentic demand vs bot-driven trading. HIGH: low organic score, MEDIUM: medium, LOW: high organic score.
  </Accordion>

  <Accordion title="Platform & Social (4 factors)">
    **Developer Migrations**: Frequent team migrations indicate instability. HIGH: ≥5, MEDIUM: 2–4, LOW: \<2.

    **Exchange Listings**: Major exchanges require due diligence. HIGH: no listings, MEDIUM: \<3 or no major, LOW: major exchange listings.

    **Launchpad Platform**: Some platforms have higher historical fraud rates. HIGH: high-risk platforms (e.g., pump.fun), LOW: other platforms.

    **Social Media Presence**: Team transparency reduces exit scam risk. HIGH: no presence, LOW: active presence.
  </Accordion>

  <Accordion title="Temporal (2 factors)">
    **Token Age**: New tokens lack operational track record. HIGH: \<7 days, MEDIUM: 7–30 days, LOW: >30 days.

    **Graduation Status**: Recent launchpad graduations can create price volatility. MEDIUM: \<7 days since graduation, LOW: >7 days or N/A.
  </Accordion>
</AccordionGroup>

### Risk Factor Summary

| Factor                   | Category            | HIGH                 | MEDIUM       | LOW             |
| ------------------------ | ------------------- | -------------------- | ------------ | --------------- |
| Circulating Supply Ratio | Authority & Control | \<80%                | 80–95%       | >95%            |
| Freeze Authority         | Authority & Control | Present              | —            | Absent/Disabled |
| Mint Authority           | Authority & Control | Present              | —            | Absent/Disabled |
| Market Capitalization    | Market Structure    | \<\$1M               | $1M–$100M    | >\$100M         |
| Token Verification       | Market Structure    | Unverified           | —            | Verified        |
| Liquidity                | Market Structure    | \<\$10K              | $10K–$100K   | >\$100K         |
| Holder Count             | Market Structure    | \<100                | 100–1000     | >1000           |
| Top Holder Concentration | Market Structure    | >90%                 | 80–90%       | \<80%           |
| Price Volatility         | Trading Patterns    | >50%                 | 20–50%       | \<20%           |
| Wash Trading             | Trading Patterns    | Suspicious ≥2 TF     | —            | Normal          |
| Organic Activity         | Trading Patterns    | Low                  | Medium       | High            |
| Developer Migrations     | Platform & Social   | ≥5                   | 2–4          | \<2             |
| Exchange Listings        | Platform & Social   | No listings          | \<3/no major | Major exchanges |
| Launchpad Platform       | Platform & Social   | High-risk (pump.fun) | —            | Other platforms |
| Social Media Presence    | Platform & Social   | No presence          | —            | Active presence |
| Token Age                | Temporal            | \<7 days             | 7–30 days    | >30 days        |
| Graduation Status        | Temporal            | —                    | \<7 days     | >7 days/N/A     |

***

## Examples

### Low-Risk Token (USDC)

```bash theme={null}
curl -X GET "https://api.range.org/api/v1/ml/risk/assessment/token?mint_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&network=solana" \
  -H "Authorization: Bearer your-api-key"
```

```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": {
    "circulating_ratio": {
      "level": "LOW",
      "explanation": ">95% circulating - minimal mint authority usage"
    },
    "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"
    },
    "token_verification": {
      "level": "LOW",
      "explanation": "Token verified - passed institutional due diligence"
    }
  },
  "processing_time_ms": 378.2,
  "errors": [
    "Dev migration data not available - dev_migrations assessment skipped",
    "Exchange listing data not available - exchange_listings assessment skipped"
  ]
}
```

USDC shows LOW overall risk (23.1%) despite having freeze/mint authorities, demonstrating how multiple factors contribute to the final assessment.

### Medium-Risk Token (Limited Data)

```bash theme={null}
curl -X GET "https://api.range.org/api/v1/ml/risk/assessment/token?mint_address=5aaHbSR47rtH7m7pV5FEyoqkvGjGRE1xv3kzEjVw4YBx&network=solana" \
  -H "Authorization: Bearer your-api-key"
```

```json theme={null}
{
  "token_info": {
    "mint_address": "5aaHbSR47rtH7m7pV5FEyoqkvGjGRE1xv3kzEjVw4YBx",
    "name": "DEAD LAND SURVIVAL",
    "symbol": "$DEADLAND"
  },
  "overall_assessment": {
    "risk_level": "MEDIUM",
    "risk_score": 2,
    "max_score": 6,
    "risk_percentage": 33.3
  },
  "summary": {
    "total_factors": 3,
    "high_risk_count": 1,
    "medium_risk_count": 0,
    "low_risk_count": 2
  },
  "risk_factors": {
    "freeze_authority": {
      "level": "LOW",
      "explanation": "No freeze authority - accounts cannot be frozen"
    },
    "minting_authority": {
      "level": "LOW",
      "explanation": "No mint authority - token supply is fixed"
    },
    "organic_activity": {
      "level": "HIGH",
      "explanation": "Low organic score - indicates bot-driven trading activity"
    }
  },
  "processing_time_ms": 403.6,
  "errors": [
    "Circulating supply data not available - circulating_ratio assessment skipped",
    "Market cap data not available - market_cap assessment skipped",
    "Token verification data not available - token_verification assessment skipped",
    "Liquidity data not available - liquidity assessment skipped"
  ]
}
```

Tokens with limited data result in fewer assessed factors. The API adjusts the maximum possible score accordingly, but partial assessments should be treated with additional caution.

***

## Errors

### Invalid Address Format (422)

```json theme={null}
{
  "detail": [
    {
      "type": "string_pattern_mismatch",
      "loc": ["query", "mint_address"],
      "msg": "String should match pattern '^[1-9A-HJ-NP-Za-km-z]{32,44}$'",
      "input": "invalid_address",
      "ctx": { "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$" }
    }
  ]
}
```

### Unsupported Network (400)

```json theme={null}
{
  "error": "Unsupported network",
  "error_type": "validation_error",
  "detail": "Only 'solana' network is supported",
  "mint_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
```

***

## Best Practices

* Use the `errors` array to understand which risk factors were skipped due to data unavailability.
* Tokens with fewer assessed factors may need additional manual review, a low score based on 3 factors is less reliable than one based on 13.
* For compliance workflows, combine token risk assessment with the [Address Risk Score](/risk-api/risk/get-address-risk-score) for the token's deployer address.
* Test with known tokens (USDC, USDT, BONK) to understand response patterns before integrating.

<Accordion title="Test Token Addresses">
  **Stablecoins:**

  * USDC: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
  * USDT: `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB`

  **Infrastructure:**

  * Wrapped SOL: `So11111111111111111111111111111111111111112`
  * JUP: `JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN`
  * Pyth: `HZ1JovNiVvGrGNiiYvEozEVgZ58xaU3RKwX8eACQBCt3`

  **Meme Tokens:**

  * BONK: `DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263`
  * WIF: `EKpQGSJtjMFqKZ9KQanSqYXRcF8fBopzLHYxdM65zcjm`
  * POPCAT: `7GCihgDB8fe6KNjn2MYtkzZcRjQy3t9GHdC8uHYmW2hr`
</Accordion>

<Accordion title="TypeScript Types">
  ```ts theme={null}
  interface TokenRiskResponse {
    token_info: {
      mint_address: string;
      name: string;
      symbol: string;
    };
    overall_assessment: {
      risk_level: "LOW" | "MEDIUM" | "HIGH";
      risk_score: number;
      max_score: number;
      risk_percentage: number;
    };
    summary: {
      total_factors: number;
      high_risk_count: number;
      medium_risk_count: number;
      low_risk_count: number;
    };
    risk_factors: Record<string, {
      level: "LOW" | "MEDIUM" | "HIGH";
      explanation: string;
    }>;
    processing_time_ms: number;
    errors: string[];
  }
  ```
</Accordion>


## OpenAPI

````yaml get /v1/risk/token
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/token:
    get:
      tags:
        - Risk
      summary: Get Token Risk Assessment
      description: >-
        Returns comprehensive risk assessment for a Solana token using ML
        analysis.
      operationId: getTokenRiskAssessment
      parameters:
        - name: asset_address
          required: true
          in: query
          description: >-
            Asset identifier (chain-agnostic). Currently only Solana token mint
            (base58, 32–44 chars) is supported.
          schema:
            example: So11111111111111111111111111111111111111112
            type: string
        - name: network
          required: true
          in: query
          description: Blockchain network for token risk (only solana supported)
          schema:
            example: solana
            type: string
            enum:
              - solana
      responses:
        '200':
          description: Token risk assessment with detailed factors and scoring
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenRiskResponse'
components:
  schemas:
    TokenRiskResponse:
      type: object
      properties:
        token_info:
          description: Basic token identification details
          allOf:
            - $ref: '#/components/schemas/TokenInfo'
        overall_assessment:
          description: Overall risk assessment aggregation
          allOf:
            - $ref: '#/components/schemas/OverallAssessment'
        summary:
          description: Summary counts of risk factor severity levels
          allOf:
            - $ref: '#/components/schemas/Summary'
        risk_factors:
          type: object
          description: Map of risk factor key to its detailed assessment
          additionalProperties:
            oneOf:
              - $ref: '#/components/schemas/RiskFactorDetail'
        processing_time_ms:
          type: number
          description: Processing time in milliseconds for the assessment
          example: 154
        errors:
          description: List of non-fatal errors encountered while computing the assessment
          type: array
          items:
            type: string
      required:
        - token_info
        - overall_assessment
        - summary
        - risk_factors
        - processing_time_ms
        - errors
    TokenInfo:
      type: object
      properties:
        asset_address:
          type: string
          description: >-
            Asset identifier (Solana mint / EVM contract / Cosmos denom).
            Currently Solana mint.
          example: So11111111111111111111111111111111111111112
        name:
          type: string
          description: Token name
          example: Wrapped SOL
        symbol:
          type: string
          description: Ticker symbol
          example: SOL
      required:
        - asset_address
        - name
        - symbol
    OverallAssessment:
      type: object
      properties:
        risk_level:
          enum:
            - LOW
            - MEDIUM
            - HIGH
          type: string
          description: Overall risk level derived from weighted factors
        risk_score:
          type: number
          description: Aggregate risk score for the token
        max_score:
          type: number
          description: Maximum theoretical score used for normalization
        risk_percentage:
          type: number
          description: Percentage representation of the risk score (0-100)
          example: 72.5
      required:
        - risk_level
        - risk_score
        - max_score
        - risk_percentage
    Summary:
      type: object
      properties:
        total_factors:
          type: number
          description: Total number of evaluated risk factors
        high_risk_count:
          type: number
          description: Number of high risk factors
        medium_risk_count:
          type: number
          description: Number of medium risk factors
        low_risk_count:
          type: number
          description: Number of low risk factors
      required:
        - total_factors
        - high_risk_count
        - medium_risk_count
        - low_risk_count
    RiskFactorDetail:
      type: object
      properties:
        level:
          enum:
            - LOW
            - MEDIUM
            - HIGH
          type: string
          description: Risk level classification of this factor
        explanation:
          type: string
          description: Explanation detailing why this factor has its assigned level
      required:
        - level
        - explanation
  securitySchemes:
    Authorization:
      scheme: bearer
      bearerFormat: API Key
      description: 'Use Authorization: Bearer <api-key>'
      type: http

````