Skip to content

Scan Risk

Analyzes the risk of one or multiple blockchain addresses in real-time, detecting suspicious patterns and generating risk scores.

Regulatory Compliance

This endpoint is essential for compliance with regulations such as FATF, Travel Rule, Mexico's Fintech Law, and LFPIORPI.

Endpoint

POST /v1/projects/{projectId}/addresses/scan-risk

Authentication

Header Format
x-api-key ApiKey {your-api-key}

Path Parameters

Parameter Type Description
projectId string Project ID

Request Body

{
    "addresses": [
        {
            "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            "chainId": "1"
        }
    ],
    "maxDepth": 3,
    "skipExisting": true
}

Fields

Field Type Required Default Description
addresses array Yes - List of addresses to analyze (1-50)
addresses[].address string Yes - Wallet address (minimum 10 characters)
addresses[].chainId string Yes - Blockchain ID
maxDepth number No 3 Graph analysis depth (1-7)
skipExisting boolean No true Skip already analyzed addresses

Supported Chains

Check the Chains endpoint to get the full list of enabled blockchains and their chainId.

Response

{
    "success": true,
    "data": {
        "summary": {
            "total": 1,
            "completed": 1,
            "skipped": 0,
            "failed": 0,
            "duration": 50758
        },
        "results": [
            {
                "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
                "chainId": "1",
                "status": "completed",
                "analysisId": "600f2937-2c54-445d-900d-4bffa69982f5",
                "riskScore": 5,
                "riskLevel": "minimal",
                "riskReason": "Normal activity, no suspicious patterns detected",
                "suspiciousActivity": false,
                "patterns": [],
                "transactionGraph": {
                    "rootAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
                    "totalNodes": 1107,
                    "totalEdges": 2000,
                    "maxDepth": 3
                },
                "analysisEvidence": {
                    "transactionsAnalyzed": 2000,
                    "uniqueAddressesFound": 1107,
                    "analysisDuration": 44950
                }
            }
        ]
    }
}

Response Fields

Field Type Description
status string Analysis status: completed, skipped, failed
analysisId string Unique analysis UUID
riskScore number Risk score (0-100)
riskLevel string Risk level: minimal, low, medium, high, critical
riskReason string Risk level explanation
suspiciousActivity boolean Indicates if suspicious activity was detected
patterns array Detected risk patterns (wash trading, mixing, etc.)
transactionGraph object Transaction graph information
analysisEvidence object Analysis evidence and metrics

Risk Levels

Level Score Description
minimal 0-19 No risk indicators
low 20-39 Normal activity with minimal alerts
medium 40-59 Requires manual review
high 60-79 High probability of suspicious activity
critical 80-100 Direct connection to illicit activities

Example

curl -X POST "https://api.wavynode.com/v1/projects/{projectId}/addresses/scan-risk" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ApiKey wavy_xxxxx" \
  -d '{
    "addresses": [
      {
        "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "chainId": "1"
      }
    ],
    "maxDepth": 3
  }'

Errors

Code Message Description
400 Invalid body Body does not match required schema
401 The api key is invalid Invalid or missing API key
403 Forbidden Insufficient permissions (requires Developer role)
500 Internal server error Internal server error

Detected Patterns

The analysis can identify the following risk patterns:

Pattern Description
wash_trading Artificial transactions to simulate volume
mixing Use of mixing services to hide fund origins
peel_chain Transaction chains to fragment funds
round_tripping Funds returning to origin after multiple hops
exchange_hopping Movement between multiple exchanges to evade detection