POST /api/bulk/scan — Scan Multiple Wallets

The bulk scan endpoint lets you submit up to 1,000 wallet addresses in a single request and receive RiskScore™ results for each one. This is useful for exchanges screening depositing users, dApps validating counterparties before a transaction, or any workflow where you need threat data on many wallets without making hundreds of individual calls. Bulk scan is available on the Growth and Enterprise plans.

Endpoint

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

Available on: Growth and Enterprise plans.

Request body

wallets

string[]

required

An array of wallet addresses to scan. Accepts EVM and Solana addresses. Maximum 1,000 addresses per request.

chain

string

Chain identifier to apply to all addresses in the request, e.g., "ethereum" or "polygon". When omitted, NZOChain auto-detects the chain for each address individually.

Example request

{
  "wallets": [
    "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
    "0xAbC123dEf456GhI789jKl012MnO345pQr678StU9",
    "0xDef789GhI012JkL345MnO678pQr901StU234vWx5"
  ],
  "chain": "ethereum"
}

Response fields

The response contains a results array. Each entry corresponds to one wallet from your request and matches the structure of a single /api/risk/scan response.

results

object[]

required

Array of scan results, one per submitted wallet address.

Hide result properties

wallet

string

The wallet address this result corresponds to.

riskScore

number

Score from 0 to 100 for this wallet.

status

string

Threat status: "SAFE", "WARNING", "HIGH RISK", or "CRITICAL".

warnings

string[]

List of detected threat descriptions for this wallet.

scannedAt

string

ISO 8601 timestamp of when this wallet was scanned.

chain

string

The chain on which this wallet was scanned.

Example response

{
  "results": [
    {
      "wallet": "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
      "riskScore": 87,
      "status": "HIGH RISK",
      "warnings": [
        "Infinite approval detected",
        "Malicious contract detected"
      ],
      "scannedAt": "2024-01-15T10:30:00Z",
      "chain": "ethereum"
    },
    {
      "wallet": "0xAbC123dEf456GhI789jKl012MnO345pQr678StU9",
      "riskScore": 5,
      "status": "SAFE",
      "warnings": [],
      "scannedAt": "2024-01-15T10:30:01Z",
      "chain": "ethereum"
    },
    {
      "wallet": "0xDef789GhI012JkL345MnO678pQr901StU234vWx5",
      "riskScore": 41,
      "status": "WARNING",
      "warnings": ["Interaction with flagged contract in past 30 days"],
      "scannedAt": "2024-01-15T10:30:01Z",
      "chain": "ethereum"
    }
  ]
}

Asynchronous processing

For requests with large numbers of addresses, NZOChain processes the batch asynchronously. The API response may include a jobId for large batches — use the job ID to poll for results or configure a webhook to receive them when processing is complete. For smaller batches (typically under 50 addresses), results are returned synchronously in the response.

Code examples

curl -X POST https://api.nzochain.com/v1/api/bulk/scan \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallets": [
      "0x742d35Cc6634C0532925a3b8D4C9B5e55d7b1234",
      "0xAbC123dEf456GhI789jKl012MnO345pQr678StU9",
      "0xDef789GhI012JkL345MnO678pQr901StU234vWx5"
    ],
    "chain": "ethereum"
  }'

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

const { results } = await response.json();

const flagged = results.filter(
  (r) => r.status === 'HIGH RISK' || r.status === 'CRITICAL'
);
console.log(`${flagged.length} of ${results.length} wallets flagged`);

import os
import requests

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

results = response.json()['results']
for wallet_result in results:
    print(f"{wallet_result['wallet'][:10]}... → {wallet_result['status']} ({wallet_result['riskScore']})")

Limits

Maximum 1,000 addresses per request.
Each address in the batch counts as one API call against your monthly limit.

Bulk scan counts every address you submit as one API call. A request with 500 wallets consumes 500 of your monthly quota. Plan your batch sizes accordingly and use the wallet monitor endpoint for wallets you check frequently to avoid redundant scans.

Overview

Endpoints

POST /api/bulk/scan — Scan Multiple Wallets

Endpoint

Request body

Example request

Response fields

Example response

Asynchronous processing

Code examples

Limits

​Endpoint

​Request body

​Example request

​Response fields

​Example response

​Asynchronous processing

​Code examples

​Limits

Endpoint

Request body

Example request

Response fields

Example response

Asynchronous processing

Code examples

Limits