> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nzochain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /api/risk/scan — Wallet Threat Scan

> Scan a wallet address for threats and receive a RiskScore™ with detailed warnings. Accepts EVM and Solana addresses. Returns score 0–100.

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

<ParamField body="wallet" type="string" required>
  The wallet address to scan. Accepts EVM addresses (starting with `0x`) and Solana public keys.
</ParamField>

<ParamField body="chain" type="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.
</ParamField>

<ParamField body="include_details" type="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`.
</ParamField>

### Example request

```json theme={null}
{
  "wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
  "chain": "ethereum",
  "include_details": true
}
```

## Response fields

<ResponseField name="riskScore" type="number" required>
  A score from 0 to 100 representing the overall threat level of the wallet. Higher scores indicate greater risk.
</ResponseField>

<ResponseField name="status" type="string" required>
  Categorical threat status derived from the risk score. One of `"SAFE"`, `"WARNING"`, `"HIGH RISK"`, or `"CRITICAL"`.
</ResponseField>

<ResponseField name="warnings" type="string[]" required>
  A list of human-readable threat descriptions detected during the scan. Empty when no threats are found.
</ResponseField>

<ResponseField name="scannedAt" type="string" required>
  ISO 8601 timestamp indicating when the scan was performed, e.g., `"2024-01-15T10:30:00Z"`.
</ResponseField>

<ResponseField name="chain" type="string" required>
  The chain on which the scan was performed, e.g., `"ethereum"`.
</ResponseField>

### Example response — HIGH RISK

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

### Example response — SAFE

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

## Code examples

<CodeGroup>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```javascript JavaScript theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  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}")
  ```
</CodeGroup>