This endpoint processes multiple blockchain addresses in the background, allowing for larger batch sizes.

🚧

Gated Endpoint

This endpoint is limited to specific customers.

If you'd like to get access to the batch processing endpoint, contact a Webacy team member.

How to Use:

Purpose:

This endpoint processes multiple blockchain addresses in the background, allowing for larger batch sizes.

Process:

  • Submit a list of addresses (up to 500) to create a batch job
  • Record the returned batchId
  • Implement polling to periodically check the status of your batch using the batchId
  • When status is "completed", all results are available

Features:

  • Supports addresses from different blockchains in one request
  • Paginated results

Best for:

Background processing of large address lists, comprehensive risk analysis, and integration with your own systems.

Polling Implementation:

Batch processing is asynchronous, requiring you to implement polling to retrieve results. Here's how to do it:

Initial Request:

Submit your batch of addresses using the POST endpoint and save the returned batchId.

Polling Strategy:

  • Use the GET endpoint with your batchId to check the status
  • Start with a reasonable interval (e.g., 2-5 seconds)
  • Check the status field in the response:
    • If status is "processing", continue polling
    • If status is "completed", process the results
    • If status is "failed", handle the error appropriately

Example Polling Implementation below.

Handling Large Batches:

  • For larger batches (approaching 500 addresses), increase your maximum polling attempts
  • Consider implementing exponential backoff for more efficient polling
  • Monitor the scanned vs total fields to track progress

Best Practices:

  • Don't poll too frequently (avoid intervals shorter than 1 second)
  • Implement proper error handling and timeouts
  • Consider setting a reasonable maximum time for very large batches
  • Store the batchId in your system to resume checking if your application restarts

To Submit Batch Addresses

curl -X POST "https://api.webacy.com/batch" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY_HERE" \
  -d '{
    "addresses": [
      {"address": "0x1234567890abcdef1234567890abcdef12345678", "chain": "eth"},
      {"address": "0xabcdef1234567890abcdef1234567890abcdef12", "chain": "bsc"}
    ],
  }'

------
Response:

{
  "batchId": "c5d2a8e7-f619-4f5b-9a52-3d1b7c6802e4",
  "status": "processing",
  "total": 2,
  "scanned": 0,
  "results": []
}

To Check Batch Status

curl --location 'https://api.webacy.com/batches/batchId' --header 'x-api-key: YOUR_API_KEY_HERE'

Example Polling Implementation

async function pollBatchStatus(batchId, apiKey, maxAttempts = 30, intervalMs = 3000) {
  let attempts = 0;
  
  while (attempts < maxAttempts) {
    attempts++;
    
    try {
      const response = await fetch(`https://api.webacy.com/batch/${batchId}`, {
        method: 'GET',
        headers: {
          'x-api-key': apiKey
        }
      });
      
      const data = await response.json();
      
      if (data.status === 'completed') {
        console.log('Batch processing complete!');
        return data;
      } else if (data.status === 'failed') {
        throw new Error('Batch processing failed');
      }
      
      console.log(`Batch still processing... (${data.scanned}/${data.total} addresses scanned)`);
      
      // Wait before the next poll
      await new Promise(resolve => setTimeout(resolve, intervalMs));
    } catch (error) {
      console.error('Error polling batch status:', error);
      throw error;
    }
  }
  
  throw new Error('Maximum polling attempts reached');
}