Get Payment Risk Assessment

Returns a comprehensive risk assessment for blockchain payments by analyzing both sender and recipient addresses using advanced heuristic rules, transaction history analysis, behavioral pattern recognition, and ML-powered malicious connection detection. This endpoint provides real-time risk evaluation for payment flows across multiple blockchain networks.

Methodology

Payment risk assessment employs a multi-layered approach combining eight independent risk assessments to provide a holistic view of payment safety:

New Wallet Detection – Identifies recipients with minimal or no transaction history, indicating potentially higher risk
Dormant Wallet Detection – Flags recipient addresses reactivating after extended periods (>180 days) of inactivity
Address Poisoning Detection – Analyzes sender’s potential poison addresses and checks if recipient matches poisoning patterns
Interaction History Analysis – Examines previous transaction relationships between sender and recipient addresses
Malicious Connection Analysis – Leverages Range Security’s ML-powered distance-to-malicious endpoint to identify connections to known malicious addresses
Attributed Address Check – Verifies addresses against known attribution databases (exchanges, protocols, system addresses)
Token Risk Assessment – When token parameters are provided, evaluates token-specific risk factors for Solana tokens
Cross-Chain Support – Handles both same-network and cross-chain payment scenarios with appropriate index selection

The overall risk level is determined using a maximum risk approach: if any individual assessment returns “high”, the overall risk is “high”; if the highest is “medium”, overall is “medium”; if all are “low”, overall is “low”.

Supported Networks

Full payment data support for: solana, osmosis, cosmoshub, dydx, neutron, celestia, dymension, agoric, mantra, stride, noble, union, stellar, and others. Networks without payment data still benefit from attribution checks and malicious connection analysis, providing limited but valuable risk intelligence.

Query Parameters

Name	Type	Required	Description
sender_address	string	✅	Blockchain address of the sender (minimum 10 characters)
recipient_address	string	✅	Blockchain address of the recipient (minimum 10 characters)
amount	number	✅	Payment amount in USD equivalent (must be greater than 0)
sender_network	string	✅	Sender’s blockchain network (e.g., `solana`, `osmosis`, `ethereum`)
recipient_network	string	✅	Recipient’s blockchain network
sender_token	string	❌	Token/denom being sent (optional, enables token risk assessment for Solana)
recipient_token	string	❌	Token/denom being received (optional)
timestamp	string	❌	Payment timestamp in ISO 8601 format (e.g., `2025-01-15T10:30:00Z`)

Validation Rules:

Sender and recipient addresses must be different
Amount must be greater than 0
Address minimum length: 10 characters
Network minimum length: 3 characters
Timestamp format: ISO 8601 (if provided)

Response Schema

A successful request returns a JSON object with the following structure:

{
  "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
  }
}

Field Definitions

overall_risk_level (string) – Final risk determination using maximum risk approach. Possible values:
- "low" – Payment appears safe based on all risk factors
- "medium" – Some risk factors detected, proceed with caution
- "high" – Significant risk factors detected, high risk payment
- "unknown" – Unable to assess (unsupported networks with no attribution data)
risk_factors (array) – List of individual risk assessments performed. Each factor contains:
- factor (string) – Unique identifier for the risk factor (e.g., new_wallet_recipient, first_interaction)
- risk_level (string) – Risk level for this specific factor ("low", "medium", "high")
- description (string) – Human-readable explanation of the risk
processing_time_ms (number) – Processing time in milliseconds. Typical ranges:
- Fully supported networks: 1000-3000ms
- Partially supported: 200-600ms
- Unsupported networks: 130-500ms
errors (array of strings) – List of errors encountered during analysis. Empty array if no errors. May contain informational messages about network support limitations.
request_summary (object) – Echo of the original request parameters for verification and logging purposes.

Risk Assessment Details

Individual Risk Factors

1. New Wallet Detection (Recipient)

Factor Names: new_wallet_recipient, established_wallet_recipient Analyzes recipient’s transaction history to determine if the wallet is newly created or established. Risk Levels:

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

Example Descriptions:

"Recipient is a completely new wallet with no transaction history"
"Recipient has substantial transaction history (500+ transactions over 6 months)"

2. Dormant Wallet Detection (Recipient)

Factor Names: dormant_wallet_recipient, active_wallet_recipient Checks if recipient has been inactive for an extended period and is now reactivating. Risk Levels:

MEDIUM: Last transaction > 180 days ago (dormant reactivation)
LOW: Recent activity (< 180 days)

Example Descriptions:

"Recipient wallet was dormant for 200+ days and is now reactivating"
"Recipient wallet was active within the last 7 days"

3. Address Poisoning Detection (Sender)

Factor Names: address_poisoning_attack, no_address_poisoning Detects if the recipient address matches poison address patterns associated with the sender. Risk Levels:

HIGH: Recipient matches a poison address pattern (4-char prefix/suffix matching)
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"

4. Interaction History Analysis (Sender-Recipient Pair)

Factor Names: first_interaction, limited_interaction_history, established_interaction_history Analyzes previous transaction relationships between the sender and recipient addresses. Index Selection:

Same network: Uses network-specific index (e.g., payments_solana)
Cross-chain: Uses payments_interchain index

Risk Levels:

HIGH: 0 interactions (first time transacting)
MEDIUM: 1-2 interactions (limited history)
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"

5. Malicious Connection Analysis (Both)

Factor Names:

Sender: malicious_connection_sender_direct, malicious_connection_sender_high, malicious_connection_sender_medium, malicious_connection_sender_low
Recipient: malicious_connection_recipient_* (same pattern)
Clean: clean_address_sender, clean_address_recipient

Uses Range Security’s ML-powered malicious distance endpoint to identify connections. Risk Levels:

HIGH: 0-2 hops from malicious addresses
MEDIUM: 3 hops from malicious addresses
LOW: 4 hops from malicious addresses 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"

6. Attributed Address Check (Both)

Factor Names: malicious_address_sender, malicious_address_recipient, attributed_address_sender, attributed_address_recipient, known_attributed_sender, known_attributed_recipient Checks addresses against attribution databases for known entities. Risk Levels:

HIGH: Address found with malicious=True flag
LOW: Address found with known attribution (exchanges, protocols, system addresses)

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"

Note: This assessment is network-independent and runs even for unsupported networks.

7 & 8. Token Risk Assessment (Sender/Recipient)

Factor Names: token_risk_sender_low, token_risk_sender_medium, token_risk_sender_high (and _recipient_* variants) When sender_token or recipient_token parameters are provided, evaluates token-specific risk factors. Supported Networks: Currently Solana only Risk Levels: 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"

Network Support Scenarios

Fully Supported Networks

Both sender and recipient networks have payment data available. Result: Full risk assessment with all applicable risk factors
Processing Time: ~1000-3000ms
Example: sender_network=solana, recipient_network=solana

Partially Supported Networks

One network has payment data, the other doesn’t. Result: Limited assessment

Assessments run for the supported side
Attribution checks run for both
Interaction analysis skipped

Processing Time: ~200-600ms
Errors Array: Contains limitation messages

Unsupported Networks

Neither network has payment data. Result:

Returns overall_risk_level: "unknown" if no attribution data found
Attribution check still runs (network-independent)
Returns actual risk level if malicious addresses found

Processing Time: ~130-500ms (fastest, minimal queries)
Errors Array: Contains limitation messages and list of supported networks

Examples

Example 1: High Risk - First Interaction with New Wallet

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"

Response:

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

Example 2: Low Risk - Established Relationship

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"

Response:

{
  "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
}

Example 3: Cross-Chain Payment

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"

Response:

{
  "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

400 Bad Request

Invalid request parameters or validation failure. Common Causes:

Sender and recipient addresses are the same
Invalid timestamp format
Amount < = 0
Address or network too short

Example Response:

{
  "statusCode": 400,
  "message": "Sender and recipient addresses cannot be the same",
  "error": "Bad Request"
}

422 Unprocessable Entity

Validation error in request parameters (FastAPI automatic validation).

500 Internal Server Error

Unexpected server error during risk assessment. Example Response:

{
  "statusCode": 500,
  "message": "An unexpected error occurred: Connection timeout",
  "error": "Internal Server Error"
}

Notes & Best Practices

Maximum Risk Approach: Overall risk is determined by the highest individual risk factor
Network Validation: Delegated to ML API - pass through network identifiers as provided
Response Format: Lowercase risk levels ("low", "medium", "high", "unknown") match ML API format
Error Handling: Graceful degradation - partial results returned if some assessments fail
Caching: GET endpoint enables HTTP caching for improved performance
Authentication: Uses same authentication as other risk endpoints (API key via X-API-KEY header)

Use Cases

Real-Time Payment Screening: Risk assessment before payment execution in wallets and exchanges
Compliance Monitoring: AML/KYC risk evaluation for financial institutions
Fraud Prevention: Identify potentially fraudulent payment patterns and address poisoning attacks
Security Analysis: Detect connections to malicious addresses before fund transfers
Cross-Chain Risk: Evaluate risk for cross-chain bridging and swaps

Performance

Real-Time: Designed for sub-3-second processing for fully supported networks
Efficient: GET with query parameters enables CDN/caching for repeated lookups
Scalable: Modular architecture supports future optimizations and parallel assessment execution
Network-Dependent: Processing time varies based on network support level

Address Risk Score Endpoint (/v1/risk/address) – Returns risk score for individual addresses
Transaction Risk Score Endpoint (/v1/risk/transaction) – Analyzes transaction risk based on involved addresses
Token Risk Assessment Endpoint (/v1/risk/token) – Comprehensive Solana token risk analysis
Risk API Overview – General documentation for all risk endpoints and authentication

TypeScript Types (Suggested)

Developers using TypeScript can define types to model the API responses:

type PaymentRiskLevel = "low" | "medium" | "high" | "unknown";

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

interface PaymentRequestSummary {
  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;
}

interface PaymentRiskResponse {
  overall_risk_level: PaymentRiskLevel;
  risk_factors: PaymentRiskFactor[];
  processing_time_ms: number;
  errors: string[];
  request_summary: PaymentRequestSummary;
}

Authorizations

X-API-KEY

string

header

required

Authorization method required to allow user to access the api endpoints.

Query Parameters

sender_address

string

required

Sender blockchain address

Example:

"TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"

recipient_address

string

required

Recipient blockchain address

Example:

"7UX2i7SucgLMQcfZ75s3VXmZZY4YRUyJN9X1RgfMoDUi"

amount

number

required

Payment amount in USD equivalent (must be positive)

Required range: x >= 0.01

Example:

1000

sender_network

string

required

Sender blockchain network (e.g., solana, osmosis, ethereum)

Example:

"solana"

recipient_network

string

required

Recipient blockchain network

Example:

"solana"

sender_token

string

Token/denom being sent (optional, enables token risk assessment)

Example:

"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

recipient_token

string

Token/denom being received (optional)

Example:

"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"

timestamp

string

Payment timestamp in ISO 8601 format (optional)

Example:

"2025-01-15T10:30:00Z"

Response

200 - application/json

Payment risk assessment with individual risk factors and overall risk level

overall_risk_level

enum<string>

required

Overall risk level determined by maximum risk approach. Possible values: low, medium, high, unknown

Available options:

low,

medium,

high,

unknown

Example:

"high"

risk_factors

object[]

required

List of individual risk assessments performed

Show child attributes

processing_time_ms

number

required

Processing time in milliseconds

Example:

4159.017

errors

string[]

required

List of errors encountered during analysis (empty if no errors)

request_summary

object

required

Echo of the original request parameters for verification

Show child attributes

Overview

Risk

Simulator

​Methodology

​Supported Networks

​Query Parameters

​Response Schema

​Field Definitions

​Risk Assessment Details

​Individual Risk Factors

​1. New Wallet Detection (Recipient)

​2. Dormant Wallet Detection (Recipient)

​3. Address Poisoning Detection (Sender)

​4. Interaction History Analysis (Sender-Recipient Pair)

​5. Malicious Connection Analysis (Both)

​6. Attributed Address Check (Both)

​7 & 8. Token Risk Assessment (Sender/Recipient)

​Network Support Scenarios

​Fully Supported Networks

​Partially Supported Networks

​Unsupported Networks

​Examples

​Example 1: High Risk - First Interaction with New Wallet

​Example 2: Low Risk - Established Relationship

​Example 3: Cross-Chain Payment

​Errors

​400 Bad Request

​422 Unprocessable Entity

​500 Internal Server Error

​Notes & Best Practices

​Use Cases

​Performance

​Related Documents

​TypeScript Types (Suggested)

Authorizations

Query Parameters

Response

Methodology

Supported Networks

Query Parameters

Response Schema

Field Definitions

Risk Assessment Details

Individual Risk Factors

1. New Wallet Detection (Recipient)

2. Dormant Wallet Detection (Recipient)

3. Address Poisoning Detection (Sender)

4. Interaction History Analysis (Sender-Recipient Pair)

5. Malicious Connection Analysis (Both)

6. Attributed Address Check (Both)

7 & 8. Token Risk Assessment (Sender/Recipient)

Network Support Scenarios

Fully Supported Networks

Partially Supported Networks

Unsupported Networks

Examples

Example 1: High Risk - First Interaction with New Wallet

Example 2: Low Risk - Established Relationship

Example 3: Cross-Chain Payment

Errors

400 Bad Request

422 Unprocessable Entity

500 Internal Server Error

Notes & Best Practices

Use Cases

Performance

Related Documents

TypeScript Types (Suggested)