POST /api/risk/scan — Wallet Threat Scan

The risk scan endpoint analyzes a wallet address and returns a RiskScore™ between 0 and 100, a categorical threat status, and a list of specific warnings describing any detected threats. Use it to gate transactions, display risk indicators in your UI, or trigger downstream alerts in your application. Both EVM-compatible addresses (e.g., Ethereum, Polygon) and Solana addresses are supported.

Endpoint

POST https://api.nzochain.com/v1/api/risk/scan

Request body

wallet

string

required

The wallet address to scan. Accepts EVM addresses (starting with 0x) and Solana public keys.

chain

string

Chain identifier to scope the scan, such as "ethereum", "polygon", or "solana". When omitted, NZOChain auto-detects the chain based on the address format. Default: auto-detect.

include_details

boolean

default:"false"

When true, the response includes a detailed breakdown of individual contract interactions and token approvals that contributed to the score. Default: false.

Example request

{
  "wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
  "chain": "ethereum",
  "include_details": true
}

Response fields

riskScore

number

required

A score from 0 to 100 representing the overall threat level of the wallet. Higher scores indicate greater risk.

status

string

required

Categorical threat status derived from the risk score. One of "SAFE", "WARNING", "HIGH RISK", or "CRITICAL".

warnings

string[]

required

A list of human-readable threat descriptions detected during the scan. Empty when no threats are found.

scannedAt

string

required

ISO 8601 timestamp indicating when the scan was performed, e.g., "2024-01-15T10:30:00Z".

chain

string

required

The chain on which the scan was performed, e.g., "ethereum".

Example response — HIGH RISK

{
  "riskScore": 87,
  "status": "HIGH RISK",
  "warnings": [
    "Infinite approval detected",
    "Malicious contract detected"
  ],
  "scannedAt": "2024-01-15T10:30:00Z",
  "chain": "ethereum"
}

Example response — SAFE

{
  "riskScore": 12,
  "status": "SAFE",
  "warnings": [],
  "scannedAt": "2024-01-15T10:30:00Z",
  "chain": "ethereum"
}

Code examples

curl -X POST https://api.nzochain.com/v1/api/risk/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
    "chain": "ethereum",
    "include_details": true
  }'

const response = await fetch('https://api.nzochain.com/v1/api/risk/scan', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.NZOCHAIN_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    wallet: '0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234',
    chain: 'ethereum',
    include_details: true,
  }),
});

const { riskScore, status, warnings } = await response.json();

if (status === 'HIGH RISK' || status === 'CRITICAL') {
  console.warn(`Wallet flagged: ${status} (score ${riskScore})`);
  console.warn('Warnings:', warnings);
}

import os
import requests

response = requests.post(
    'https://api.nzochain.com/v1/api/risk/scan',
    headers={
        'Authorization': f'Bearer {os.environ["NZOCHAIN_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'wallet': '0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234',
        'chain': 'ethereum',
        'include_details': True,
    },
)

result = response.json()
print(f"Risk score: {result['riskScore']} — {result['status']}")
for warning in result['warnings']:
    print(f"  • {warning}")

Overview

Endpoints

POST /api/risk/scan — Wallet Threat Scan

Endpoint

Request body

Example request

Response fields

Example response — HIGH RISK

Example response — SAFE

Code examples

​Endpoint

​Request body

​Example request

​Response fields

​Example response — HIGH RISK

​Example response — SAFE

​Code examples

Endpoint

Request body

Example request

Response fields

Example response — HIGH RISK

Example response — SAFE

Code examples