> ## 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": "malicious_attributed_recipient",
      "risk_level": "high",
      "description": "Recipient is a known malicious entity: SOLANA Lazarus Hacker Address (89WJ) (Hack, Hacker)"
    },
    {
      "factor": "first_interaction",
      "risk_level": "medium",
      "description": "First ever interaction between these addresses"
    },
    {
      "factor": "established_wallet_recipient",
      "risk_level": "low",
      "description": "Recipient has on-chain signatures; last activity 489 days ago"
    },
    {
      "factor": "no_address_poisoning",
      "risk_level": "low",
      "description": "No suspicious address patterns detected"
    },
    {
      "factor": "known_safe_address_sender",
      "risk_level": "low",
      "description": "Sender: This is a known coretoken address: Token Program. Risk overridden to very low."
    },
    {
      "factor": "known_attributed_sender",
      "risk_level": "low",
      "description": "Sender is a known entity: Token Program (CoreToken, Solana Program)"
    }
  ],
  "processing_time_ms": 637.094,
  "errors": [],
  "request_summary": {
    "sender_address": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
    "recipient_address": "2oP36hojo3spVLvrhqNVW8ERUEYMKFAS2XVAmFv289WJ",
    "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.

    * `first_interaction`, **MEDIUM**: 0 interactions (first time transacting)
    * `limited_interaction_history`, **MEDIUM**: 1-2 interactions
    * `established_interaction_history`, **LOW**: 3+ interactions (established relationship)

    A first interaction returns MEDIUM, not HIGH. Do not gate a reject on `first_interaction` being HIGH.

    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 returned by live responses:** `directly_malicious_address`, `clean_address_sender`, `clean_address_recipient`, `known_safe_address_sender`, `known_safe_address_recipient`

    `directly_malicious_address` is a single name used for either side. Its `description` begins `Sender:` or `Recipient:` to identify which address is flagged.

    * `directly_malicious_address`, **HIGH**: address is directly flagged, or is within 2 hops of a flagged address
    * **MEDIUM**: 3 hops from malicious addresses. This band was not observed, so its factor name is unconfirmed.
    * `clean_address_sender` / `clean_address_recipient`, **LOW**: no suspicious paths found
    * `known_safe_address_sender` / `known_safe_address_recipient`, **LOW**: attribution override, the address belongs to a known safe entity

    **Also documented, not observed:** `malicious_connection_sender_direct`, `malicious_connection_sender_high`, `malicious_connection_sender_medium`, `malicious_connection_sender_low` and the `_recipient_` counterparts. No response used to verify this page returned them. Handle them defensively rather than relying on them.

    Example descriptions: `"Recipient: Address is directly flagged for malicious activity."`, `"Sender: No suspicious paths found within 5 hops."`, `"Recipient: This is a known cex address: Binance Deposit (6Awu) (Binance). Risk overridden to very low."`
  </Accordion>

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

    **Factor names returned by live responses:** `malicious_attributed_sender`, `malicious_attributed_recipient`, `known_attributed_sender`, `known_attributed_recipient`

    * `malicious_attributed_sender` / `malicious_attributed_recipient`, **HIGH**: address matched an entity flagged with `malicious=True`
    * `known_attributed_sender` / `known_attributed_recipient`, **LOW**: known attributed entity (exchange, protocol, token, system address)

    **Also documented, not observed:** `malicious_address_sender`, `malicious_address_recipient`, `attributed_address_sender`, `attributed_address_recipient`. No response used to verify this page returned them. Match them alongside the four names above rather than dropping them from your handler.

    Example descriptions: `"Recipient is a known malicious entity: Lazarus Group (Hack, Hacker)"`, `"Sender is a known entity: Token Program (CoreToken, Solana Program)"`, `"Recipient is a known entity: Binance Deposit (6Awu) (cex, deposit_wallet)"`
  </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

### Medium Risk, First Interaction

```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": "medium",
  "risk_factors": [
    {
      "factor": "first_interaction",
      "risk_level": "medium",
      "description": "First ever interaction between these addresses"
    },
    {
      "factor": "established_wallet_recipient",
      "risk_level": "low",
      "description": "Recipient has on-chain signatures; last activity 259 days ago"
    },
    {
      "factor": "no_address_poisoning",
      "risk_level": "low",
      "description": "No suspicious address patterns detected"
    },
    {
      "factor": "known_safe_address_sender",
      "risk_level": "low",
      "description": "Sender: This is a known coretoken address: Token Program. Risk overridden to very low."
    },
    {
      "factor": "clean_address_recipient",
      "risk_level": "low",
      "description": "Recipient: No suspicious paths found within 5 hops."
    },
    {
      "factor": "known_attributed_sender",
      "risk_level": "low",
      "description": "Sender is a known entity: Token Program (CoreToken, Solana Program)"
    }
  ],
  "processing_time_ms": 167.29,
  "errors": []
}
```

### Attributed Addresses on Both Sides

```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": "medium",
  "risk_factors": [
    {
      "factor": "first_interaction",
      "risk_level": "medium",
      "description": "First ever interaction between these addresses"
    },
    {
      "factor": "established_wallet_recipient",
      "risk_level": "low",
      "description": "Recipient has on-chain signatures; last activity 0 days ago"
    },
    {
      "factor": "no_address_poisoning",
      "risk_level": "low",
      "description": "No suspicious address patterns detected"
    },
    {
      "factor": "known_safe_address_sender",
      "risk_level": "low",
      "description": "Sender: This is a known address: BONK (Bonk) SPL token mint. Risk overridden to very low."
    },
    {
      "factor": "known_safe_address_recipient",
      "risk_level": "low",
      "description": "Recipient: This is a known token address: USD Coin (USDC) (Circle). Risk overridden to very low."
    },
    {
      "factor": "known_attributed_sender",
      "risk_level": "low",
      "description": "Sender is a known entity: BONK (Bonk) SPL token mint"
    },
    {
      "factor": "known_attributed_recipient",
      "risk_level": "low",
      "description": "Recipient is a known entity: USD Coin (USDC) (Token, token_contract)"
    }
  ],
  "processing_time_ms": 125.73
}
```

<Note>
  Both addresses here are attributed, so both sides return LOW attribution factors, but the pair has no prior interaction history, which returns `first_interaction` at MEDIUM and carries the overall level to `"medium"`. Attribution alone does not produce a `"low"` overall level.
</Note>

### 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": "medium",
      "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.29
  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.
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:
            type: string
            example: solana
        - name: recipient_network
          required: true
          in: query
          description: Recipient blockchain network
          schema:
            type: string
            example: solana
        - 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:
      type: apiKey
      in: header
      name: X-API-KEY
      description: Authorization method required to allow user to access the api endpoints.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.