Get Payment Risk Assessment

Endpoint: GET /v1/risk/payment

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:

1. New Wallet Detection – Identifies recipients with minimal or no transaction history, indicating potentially higher risk
2. Dormant Wallet Detection – Flags recipient addresses reactivating after extended periods (>180 days) of inactivity
3. Address Poisoning Detection – Analyzes sender's potential poison addresses and checks if recipient matches poisoning patterns
4. Interaction History Analysis – Examines previous transaction relationships between sender and recipient addresses
5. Malicious Connection Analysis – Leverages Range Security's ML-powered distance-to-malicious endpoint to identify connections to known malicious addresses
6. Attributed Address Check – Verifies addresses against known attribution databases (exchanges, protocols, system addresses)
7. Token Risk Assessment – When token parameters are provided, evaluates token-specific risk factors for Solana tokens
8. 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

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

1. Maximum Risk Approach: Overall risk is determined by the highest individual risk factor
2. Network Validation: Delegated to ML API - pass through network identifiers as provided
3. Response Format: Lowercase risk levels ("low", "medium", "high", "unknown") match ML API format
4. Error Handling: Graceful degradation - partial results returned if some assessments fail
5. Caching: GET endpoint enables HTTP caching for improved performance
6. 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

Related Documents

• 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;
}