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

# Payment Risk Assessment

> End-to-end risk assessment for payments across and within chains, powered by advanced heuristic rules and machine-learning analysis.


Returns a comprehensive risk assessment for blockchain payments by analyzing both sender and recipient addresses across 8 independent risk dimensions. Provides real-time risk evaluation for payment flows across multiple blockchain networks. See [Understanding Risk Scores](/risk-api/product-info/understanding-risk-scores) for general methodology.

The **overall risk level** uses a **maximum risk approach**: if any individual assessment returns "high", the overall risk is "high".

<Note>
  **This is the most comprehensive risk endpoint.** It includes address risk scoring (malicious connection analysis) and attributed address checks (including sanctions and blacklist data) for both sender and recipient, plus payment-specific risk factors.

  If you only need to screen a single address without payment context, use the simpler [Address Risk Score](/risk-api/risk/get-address-risk-score) endpoint. For sanctions-only pass/fail checks, use [Sanctions & Blacklist Check](/risk-api/risk/get-sanctions-blacklist-check).
</Note>

***

## Query Parameters

| Name                | Type   | Required | Description                                                                                                 |
| ------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------- |
| `sender_address`    | string | Yes      | Blockchain address of the sender (min 10 characters)                                                        |
| `recipient_address` | string | Yes      | Blockchain address of the recipient (min 10 characters)                                                     |
| `amount`            | number | Yes      | Payment amount in USD equivalent (must be >0)                                                               |
| `sender_network`    | string | Yes      | Sender's blockchain network identifier. See [Supported Chains](/risk-api/product-info/supported-chains).    |
| `recipient_network` | string | Yes      | Recipient's blockchain network identifier. See [Supported Chains](/risk-api/product-info/supported-chains). |
| `sender_token`      | string | No       | Token/denom being sent (enables token risk assessment for Solana)                                           |
| `recipient_token`   | string | No       | Token/denom being received                                                                                  |
| `timestamp`         | string | No       | Payment timestamp in ISO 8601 format (e.g., `2025-01-15T10:30:00Z`)                                         |

**Validation:**

* Sender and recipient addresses must be different
* Amount must be greater than 0
* Address minimum length: 10 characters

### Supported Networks

Full payment data support for: `solana`, `stellar`, and all Cosmos ecosystem chains (`celestia`, `osmosis-1`, `cosmoshub-4`, `dydx-mainnet-1`, `neutron-1`, and others). See [Supported Chains](/risk-api/product-info/supported-chains) for the full list.

Networks without full payment data (EVM chains, Bitcoin, Tron) still benefit from attribution checks and malicious connection analysis.

***

## Response Schema

| Field                | Type   | Description                                                             |
| -------------------- | ------ | ----------------------------------------------------------------------- |
| `overall_risk_level` | string | Final risk determination: `"low"`, `"medium"`, `"high"`, or `"unknown"` |
| `risk_factors`       | array  | Individual risk assessments performed (see below)                       |
| `processing_time_ms` | number | Processing time in milliseconds                                         |
| `errors`             | array  | Errors encountered during analysis (empty if none)                      |
| `request_summary`    | object | Echo of the original request parameters                                 |

### Risk Factor Object

| Field         | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| `factor`      | string | Unique identifier (e.g., `new_wallet_recipient`, `first_interaction`) |
| `risk_level`  | string | Risk level: `"low"`, `"medium"`, or `"high"`                          |
| `description` | string | Human-readable explanation                                            |

### Example Response Structure

```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"
    },
    {
      "factor": "connected_to_malicious_address",
      "risk_level": "high",
      "description": "Sender is 2 hops away from known malicious addresses"
    }
  ],
  "processing_time_ms": 4159.017,
  "errors": [],
  "request_summary": {
    "sender_address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "recipient_address": "7UX2i7SucgLMQcfZ75s3VXmZZY4YRUyJN9X1RgfMoDUi",
    "amount": 1000.0,
    "sender_network": "solana",
    "recipient_network": "solana",
    "sender_token": null,
    "recipient_token": null,
    "timestamp": null
  }
}
```

***

## Risk Assessments Performed

<AccordionGroup>
  <Accordion title="New Wallet Detection">
    Analyzes recipient's transaction history to determine if the wallet is newly created or established.

    **Factor names:** `new_wallet_recipient`, `established_wallet_recipient`

    * **HIGH**: 0 transactions (completely new wallet)
    * **MEDIUM**: \<3 transactions OR first transaction \<7 days ago
    * **LOW**: ≥3 transactions AND >7 days old

    Example descriptions: `"Recipient is a completely new wallet with no transaction history"`, `"Recipient has substantial transaction history (500+ transactions over 6 months)"`
  </Accordion>

  <Accordion title="Dormant Wallet Detection">
    Checks if recipient has been inactive for an extended period and is now reactivating.

    **Factor names:** `dormant_wallet_recipient`, `active_wallet_recipient`

    * **MEDIUM**: Last transaction >180 days ago
    * **LOW**: Active within 180 days

    Example descriptions: `"Recipient wallet was dormant for 200+ days and is now reactivating"`, `"Recipient wallet was active within the last 7 days"`
  </Accordion>

  <Accordion title="Address Poisoning Detection">
    Detects if the recipient address matches poison address patterns associated with the sender (4-char prefix/suffix matching).

    **Factor names:** `address_poisoning_attack`, `no_address_poisoning`

    * **HIGH**: Recipient matches a poison address pattern
    * **LOW**: No poisoning pattern detected

    Example descriptions: `"Potential address poisoning attack detected - recipient matches poison address pattern"`, `"No address poisoning pattern detected between sender and recipient"`
  </Accordion>

  <Accordion title="Interaction History">
    Examines previous transaction relationships between sender and recipient. Uses network-specific index for same-network payments and `payments_interchain` index for cross-chain.

    **Factor names:** `first_interaction`, `limited_interaction_history`, `established_interaction_history`

    * **HIGH**: 0 interactions (first time transacting)
    * **MEDIUM**: 1–2 interactions
    * **LOW**: 3+ interactions (established relationship)

    Example descriptions: `"First ever interaction between these addresses"`, `"Limited interaction history: 2 previous interactions found"`, `"Strong interaction history: 15 previous interactions found"`
  </Accordion>

  <Accordion title="Malicious Connection Analysis">
    Uses Range's ML-powered malicious distance endpoint to identify connections to known malicious addresses for both sender and recipient.

    **Factor names (sender):** `malicious_connection_sender_direct`, `malicious_connection_sender_high`, `malicious_connection_sender_medium`, `malicious_connection_sender_low`, `clean_address_sender`

    **Factor names (recipient):** Same pattern with `_recipient_` suffix.

    * **HIGH**: 0–2 hops from malicious addresses
    * **MEDIUM**: 3 hops from malicious addresses
    * **LOW**: 4+ hops OR no connections found

    Example descriptions: `"Sender is directly connected to known malicious addresses (0 hops)"`, `"Sender is 2 hops away from known malicious addresses (riskScore: 1)"`, `"Sender address has no known connections to malicious addresses"`
  </Accordion>

  <Accordion title="Attributed Address Check">
    Verifies both addresses against known entity databases. Network-independent, runs even for unsupported networks.

    **Factor names:** `malicious_address_sender`, `malicious_address_recipient`, `attributed_address_sender`, `attributed_address_recipient`, `known_attributed_sender`, `known_attributed_recipient`

    * **HIGH**: Address flagged with `malicious=True`
    * **LOW**: Known attributed entity (exchange, protocol, system address)

    Example descriptions: `"Address attributed to 'Binance Hot Wallet' (Entity: Binance, Category: Exchange, Role: Hot Wallet)"`, `"Sender is a known attributed address | identified as 'Token Program' | (entity: Solana) | Category: SYSTEM | Role: Program | Not flagged as malicious"`
  </Accordion>

  <Accordion title="Token Risk Assessment">
    When `sender_token` or `recipient_token` is provided, evaluates token-specific risk factors. Currently Solana only.

    **Factor names:** `token_risk_sender_low`, `token_risk_sender_medium`, `token_risk_sender_high` (and `_recipient_` variants)

    Maps from token risk score to payment risk level (low/medium/high).

    Example descriptions: `"Sender token EPjFWdd5Au... has low risk (established stablecoin)"`, `"Recipient token shows medium risk factors"`
  </Accordion>

  <Accordion title="Cross-Chain Support">
    Handles both same-network and cross-chain payment scenarios with appropriate index selection.

    * Same network: Uses network-specific index (e.g., `payments_solana`)
    * Cross-chain: Uses `payments_interchain` index
  </Accordion>
</AccordionGroup>

***

## Network Support

| Scenario                      | Coverage                                               | Processing Time |
| ----------------------------- | ------------------------------------------------------ | --------------- |
| Both networks fully supported | All risk factors assessed                              | \~1000–3000ms   |
| One network supported         | Partial assessment + attribution for both              | \~200–600ms     |
| Neither network supported     | Attribution check only; returns `"unknown"` if no data | \~130–500ms     |

***

## Examples

### High Risk, First Interaction with New Wallet

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

```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": []
}
```

### Low Risk, Established Relationship

```bash theme={null}
curl -G https://api.range.org/v1/risk/payment \
  --data-urlencode "sender_address=DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" \
  --data-urlencode "recipient_address=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v" \
  --data-urlencode "amount=250.0" \
  --data-urlencode "sender_network=solana" \
  --data-urlencode "recipient_network=solana" \
  --data-urlencode "sender_token=So11111111111111111111111111111111111111112" \
  --data-urlencode "timestamp=2025-01-15T10:30:00Z" \
  -H "Authorization: Bearer your_api_key_here"
```

```json theme={null}
{
  "overall_risk_level": "low",
  "risk_factors": [
    {
      "factor": "established_wallet_recipient",
      "risk_level": "low",
      "description": "Recipient has substantial transaction history"
    },
    {
      "factor": "established_interaction_history",
      "risk_level": "low",
      "description": "Strong interaction history: 15 previous interactions found"
    }
  ],
  "processing_time_ms": 1876.45
}
```

### Cross-Chain Payment

```bash theme={null}
curl -G https://api.range.org/v1/risk/payment \
  --data-urlencode "sender_address=osmo1abc123def456ghi789jkl012mno345pqr678stu" \
  --data-urlencode "recipient_address=cosmos1xyz987uvw654rst321nmo098lkj765ihg432fed" \
  --data-urlencode "amount=5000.0" \
  --data-urlencode "sender_network=osmosis" \
  --data-urlencode "recipient_network=cosmoshub" \
  --data-urlencode "sender_token=OSMO" \
  --data-urlencode "recipient_token=ATOM" \
  -H "Authorization: Bearer your_api_key_here"
```

```json theme={null}
{
  "overall_risk_level": "medium",
  "risk_factors": [
    {
      "factor": "first_interaction",
      "risk_level": "high",
      "description": "First cross-chain interaction between these addresses (interchain index)"
    }
  ],
  "processing_time_ms": 3124.78
}
```

***

## Errors

| HTTP Code | Cause                                                 | Recommended Action                                  |
| --------: | ----------------------------------------------------- | --------------------------------------------------- |
|   **400** | Invalid parameters (same addresses, amount ≤ 0, etc.) | Validate parameters before requesting.              |
|   **422** | Request validation error                              | Check parameter types and formats.                  |
|   **429** | Rate limit exceeded                                   | Implement exponential backoff.                      |
|   **5xx** | Server error                                          | Retry after a delay; contact support if persistent. |

***

## Best Practices

* The overall risk is determined by the **highest** individual risk factor, a single "high" factor makes the entire payment "high" risk.
* Always pass `sender_token`/`recipient_token` for Solana payments to get token-level risk assessment.
* For cross-chain payments, provide the correct network identifiers for both sides.
* Use `processing_time_ms` to monitor API performance and set appropriate timeouts.
* An `"unknown"` overall risk level means insufficient data, not safety, treat it with caution.

<Accordion title="TypeScript Types">
  ```typescript theme={null}
  type PaymentRiskLevel = "low" | "medium" | "high" | "unknown";

  interface PaymentRiskFactor {
    factor: string;
    risk_level: PaymentRiskLevel;
    description: string;
  }

  interface PaymentRiskResponse {
    overall_risk_level: PaymentRiskLevel;
    risk_factors: PaymentRiskFactor[];
    processing_time_ms: number;
    errors: string[];
    request_summary: {
      sender_address: string;
      recipient_address: string;
      amount: number;
      sender_network: string;
      recipient_network: string;
      sender_token: string | null;
      recipient_token: string | null;
      timestamp: string | null;
    };
  }
  ```
</Accordion>


## OpenAPI

````yaml get /v1/risk/payment
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/payment:
    get:
      tags:
        - Risk
      summary: Get Payment Risk Assessment
      description: >-
        Analyzes cross-chain payments to assess risk using advanced heuristic
        rules and ML-powered analysis. Evaluates sender and recipient addresses
        based on transaction history, behavioral patterns, interaction history,
        address poisoning detection, malicious connections, and security
        indicators.
      operationId: getPaymentRiskAssessment
      parameters:
        - name: sender_address
          required: true
          in: query
          description: Sender blockchain address
          schema:
            example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
            type: string
        - name: recipient_address
          required: true
          in: query
          description: Recipient blockchain address
          schema:
            example: 7UX2i7SucgLMQcfZ75s3VXmZZY4YRUyJN9X1RgfMoDUi
            type: string
        - name: amount
          required: true
          in: query
          description: Payment amount in USD equivalent (must be positive)
          schema:
            minimum: 0.01
            example: 1000
            type: number
        - name: sender_network
          required: true
          in: query
          description: Sender blockchain network (e.g., solana, osmosis, ethereum)
          schema:
            example: solana
            type: string
        - name: recipient_network
          required: true
          in: query
          description: Recipient blockchain network
          schema:
            example: solana
            type: string
        - name: sender_token
          required: false
          in: query
          description: Token/denom being sent (optional, enables token risk assessment)
          schema:
            example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
            type: string
        - name: recipient_token
          required: false
          in: query
          description: Token/denom being received (optional)
          schema:
            example: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
            type: string
        - name: timestamp
          required: false
          in: query
          description: Payment timestamp in ISO 8601 format (optional)
          schema:
            example: '2025-01-15T10:30:00Z'
            type: string
      responses:
        '200':
          description: >-
            Payment risk assessment with individual risk factors and overall
            risk level
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentRiskResponse'
components:
  schemas:
    PaymentRiskResponse:
      type: object
      properties:
        overall_risk_level:
          enum:
            - low
            - medium
            - high
            - unknown
          type: string
          description: >-
            Overall risk level determined by maximum risk approach. Possible
            values: low, medium, high, unknown
          example: high
        risk_factors:
          description: List of individual risk assessments performed
          type: array
          items:
            $ref: '#/components/schemas/PaymentRiskFactor'
        processing_time_ms:
          type: number
          description: Processing time in milliseconds
          example: 4159.017
        errors:
          description: List of errors encountered during analysis (empty if no errors)
          type: array
          items:
            type: string
        request_summary:
          description: Echo of the original request parameters for verification
          allOf:
            - $ref: '#/components/schemas/PaymentRequestSummary'
      required:
        - overall_risk_level
        - risk_factors
        - processing_time_ms
        - errors
        - request_summary
    PaymentRiskFactor:
      type: object
      properties:
        risk_context:
          enum:
            - sender
            - recipient
            - interaction
          type: string
          description: >-
            Categorizes whether the risk is related to sender address only,
            recipient address only, or their interaction
          example: recipient
        factor:
          type: string
          description: Unique identifier for the risk factor
          example: new_wallet_recipient
        risk_level:
          enum:
            - low
            - medium
            - high
            - unknown
          type: string
          description: Risk level classification of this factor
          example: medium
        description:
          type: string
          description: Human-readable explanation of the risk factor
          example: Recipient is a new wallet with minimal transaction history
      required:
        - risk_context
        - factor
        - risk_level
        - description
    PaymentRequestSummary:
      type: object
      properties:
        sender_address:
          type: string
          description: Sender blockchain address
          example: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
        recipient_address:
          type: string
          description: Recipient blockchain address
          example: 7UX2i7SucgLMQcfZ75s3VXmZZY4YRUyJN9X1RgfMoDUi
        amount:
          type: number
          description: Payment amount in USD equivalent
          example: 1000
        sender_network:
          type: string
          description: Sender blockchain network
          example: solana
        recipient_network:
          type: string
          description: Recipient blockchain network
          example: solana
        sender_token:
          type: string
          nullable: true
          description: Token/denom being sent (optional)
        recipient_token:
          type: string
          nullable: true
          description: Token/denom being received (optional)
        timestamp:
          type: string
          nullable: true
          description: Payment timestamp (optional)
      required:
        - sender_address
        - recipient_address
        - amount
        - sender_network
        - recipient_network
  securitySchemes:
    Authorization:
      scheme: bearer
      bearerFormat: API Key
      description: 'Use Authorization: Bearer <api-key>'
      type: http

````