Wallet & dApp Integration

This guide shows how to integrate Risk API into a Solana wallet or dApp to protect users from malicious addresses and risky transactions. The flow screens recipients before sending and scans the unsigned transaction before signing.

Prerequisites: You need a Risk API key and familiarity with Address Risk Score and Scan an Unsigned Transaction. For raw simulation without a risk verdict, see the Transaction Simulator.

Integration Flow

A typical wallet integration adds two risk gates to the send flow:

User enters recipient + amount
      │
      ▼
┌─────────────────────────┐
│  Screen recipient       │──── High risk? → Show warning
│  (Address Risk Score)   │
└─────────────────────────┘
      │
      ▼
  User constructs transaction
      │
      ▼
┌─────────────────────────┐
│  Scan unsigned tx       │──── High severity? → Show warning
│  (Transaction Scan)     │     Findings / failed sim? → Show detail
└─────────────────────────┘
      │
      ▼
  User reviews risk info → Confirm or Cancel
      │
      ▼
  Sign and broadcast

Step 1: Screen the Recipient

Before the user constructs a transaction, check the recipient address for connections to known malicious actors.

async function screenRecipient(address: string, network: string = 'solana') {
  const params = new URLSearchParams({ address, network });
  const response = await fetch(
    `https://api.range.org/v1/risk/address?${params}`,
    { headers: { Authorization: `Bearer ${API_KEY}` } },
  );
  const data = await response.json();

  return {
    score: data.riskScore,
    level: data.riskLevel,
    reasoning: data.reasoning,
    isSafe: data.riskScore <= 3,
    isAttributed: data.attribution !== null,
    attribution: data.attribution,
  };
}

What to Show the User

Score	UI Treatment
1–3	Green indicator. Proceed normally. If `attribution` is present, optionally show the entity name (e.g., “Token Program - Solana”).
4–5	Yellow warning. Show `reasoning` and let the user decide.
6–7	Orange warning. Recommend against proceeding. Show `reasoning` and the number of hops to malicious addresses.
8–10	Red block. Strongly warn. Show `reasoning` and `maliciousAddressesFound` details. Require explicit confirmation.

Check the attribution field - when present, it means the address is a verified non-malicious entity (like a system program or major exchange). You can display the entity name to reassure the user.

Step 2: Scan the Unsigned Transaction

After the user constructs but before they sign the transaction, scan it. The scan simulates the payload, screens every counterparty through Address Risk v2, checks recipients for address poisoning, and extracts the declared intent. Solana only in this version.

async function scanUnsignedTransaction(encodedTransaction: string) {
  const response = await fetch(
    'https://api.range.org/v2/risk/transaction/scan',
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        network: 'solana',
        transaction: encodedTransaction,
        encoding: 'base64',
      }),
    },
  );
  return response.json();
}

Key Response Fields to Display

Field	What to Show
`severity`	Worst single-signal severity (`none` / `low` / `medium` / `high` / `severe`)
`findings`	Transaction-native rules that fired (`signal` + `caption`)
`counterparties`	Each touched address with its Address Risk v2 severity
`simulation`	Predicted asset diffs. `null` when simulation failed
`intent`	Declared intent summary from the payload
`notes`	Coverage caveats such as `coverage-truncated`
`screen_id`	Fetch full evidence later via Fetch Assessment Evidence

For a raw simulation without a combined risk verdict, see the Transaction Simulation Guide.

Findings and Failed Simulations

Treat a non-none/low severity, a non-empty findings list, or a missing simulation as a warning:

function checkScanRisk(scan: {
  severity: string;
  findings: { signal: string; caption: string }[];
  simulation?: { simulation_success: boolean } | null;
}) {
  const warnings: string[] = [];

  if (scan.severity !== 'none' && scan.severity !== 'low') {
    warnings.push(`Transaction severity: ${scan.severity}`);
  }

  for (const finding of scan.findings || []) {
    warnings.push(finding.caption || finding.signal);
  }

  if (!scan.simulation || scan.simulation.simulation_success === false) {
    warnings.push('Simulation failed');
  }

  return {
    hasRisk: warnings.length > 0,
    warnings,
  };
}

Step 3: Display Risk Information

Combine the address screening and scan results into a confirmation screen. The goal is to give users enough information to make an informed decision without overwhelming them.

Recommended UI Pattern

┌─────────────────────────────────────────┐
│  Transaction Preview                    │
│                                         │
│  Sending: 100 USDC                      │
│  To: 7xKX...3mN2                        │
│  Fee: ~0.00025 SOL                      │
│                                         │
│  ┌─────────────────────────────────┐    │
│  │ ⚠ Recipient Risk: Medium (5/10) │    │
│  │ 3 hops from flagged address     │    │
│  └─────────────────────────────────┘    │
│                                         │
│  Scan severity: high                    │
│  Intent: Swap 100 USDC for SOL          │
│                                         │
│  Balance Changes:                       │
│  · USDC: -100.00                        │
│  · SOL:  -0.00025 (fee)                 │
│                                         │
│  [Cancel]              [Send Anyway]    │
└─────────────────────────────────────────┘

Best Practices

Don’t block silently. Always explain why a transaction is flagged. Show reasoning from the address screen and findings / intent from the scan.
Let users override with warning. Even high-risk transactions should be possible to send if the user explicitly confirms - they may know something the scoring doesn’t.
Show entity attribution. If the recipient is a known entity (exchange, protocol), display its name.
Cache address risk cautiously. Risk scores change as new intelligence is incorporated. For high-value transfers, always query fresh.

Step 4: Handle Edge Cases

Network Errors and Timeouts

async function screenWithFallback(address: string, network: string) {
  try {
    const result = await Promise.race([
      screenRecipient(address, network),
      new Promise((_, reject) =>
        setTimeout(() => reject(new Error('timeout')), 5000),
      ),
    ]);
    return result;
  } catch (error) {
    // If the risk check fails, inform the user but don't block
    return {
      score: null,
      level: 'unknown',
      reasoning: 'Risk check unavailable - proceed with caution',
      isSafe: null,
    };
  }
}

Rate Limits

If you hit rate limits (429 responses), show a degraded state rather than blocking the user. See Rate Limits & Plans for retry strategies.

Unsupported Networks

Address Risk Score returns results for 18+ supported networks. For unsupported networks, partial results may be available through direct attribution or cross-chain propagation. Transaction scan is Solana only in this version.

Complete Send Flow

async function protectedSend(
  recipient: string,
  amount: number,
  network: string,
) {
  // Screen the recipient
  const risk = await screenWithFallback(recipient, network);

  if (risk.score >= 8) {
    // Require explicit user confirmation for high-risk
    const confirmed = await showHighRiskWarning(risk);
    if (!confirmed) return { status: 'cancelled' };
  } else if (risk.score >= 4) {
    // Show warning for medium-risk
    const confirmed = await showMediumRiskWarning(risk);
    if (!confirmed) return { status: 'cancelled' };
  }

  // Build and encode the transaction (see Transaction Simulation guide for SDK examples)
  const transaction = await buildTransaction(recipient, amount);
  const encoded = encodeTransactionBase64(transaction);

  // Scan before signing
  const scan = await scanUnsignedTransaction(encoded);

  if (!scan.simulation || scan.simulation.simulation_success === false) {
    return { status: 'error', reason: 'Simulation failed' };
  }

  const scanRisk = checkScanRisk(scan);
  if (scanRisk.hasRisk) {
    const confirmed = await showExploitWarning(scanRisk.warnings);
    if (!confirmed) return { status: 'cancelled' };
  }

  // Show confirmation with all risk data
  const confirmed = await showConfirmation({ risk, scan });
  if (!confirmed) return { status: 'cancelled' };

  // Sign and send
  return await signAndSend(transaction);
}

For SDK-specific transaction building and encoding examples using @solana/kit or @solana/web3.js, see the Transaction Simulation Guide.

Overview

Guides

Risk Endpoints

Risk v2 Endpoints

Alerts

Simulator

Product Information

Wallet & dApp Integration

Integration Flow

Step 1: Screen the Recipient

What to Show the User

Step 2: Scan the Unsigned Transaction

Key Response Fields to Display

Findings and Failed Simulations

Step 3: Display Risk Information

Recommended UI Pattern

Best Practices

Step 4: Handle Edge Cases

Network Errors and Timeouts

Rate Limits

Unsupported Networks

Complete Send Flow

What’s Next

Scan an Unsigned Transaction

Transaction Simulation Guide

​Integration Flow

​Step 1: Screen the Recipient

​What to Show the User

​Step 2: Scan the Unsigned Transaction

​Key Response Fields to Display

​Findings and Failed Simulations

​Step 3: Display Risk Information

​Recommended UI Pattern

​Best Practices

​Step 4: Handle Edge Cases

​Network Errors and Timeouts

​Rate Limits

​Unsupported Networks

​Complete Send Flow

​What’s Next

Scan an Unsigned Transaction

Transaction Simulation Guide

Integration Flow

Step 1: Screen the Recipient

What to Show the User

Step 2: Scan the Unsigned Transaction

Key Response Fields to Display

Findings and Failed Simulations

Step 3: Display Risk Information

Recommended UI Pattern

Best Practices

Step 4: Handle Edge Cases

Network Errors and Timeouts

Rate Limits

Unsupported Networks

Complete Send Flow

What’s Next