Batch Processing

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.

❗️

API Considerations

For this endpoint, API credits are counted towards the number of addresses included in the batch.

Ex. a single batch API with 50 addresses is counted as 50 API calls.

How to Use:

Purpose:

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

Sample Request:

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"}
    ]
  }'

Sample Response (Creation):

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

Batch Status Check:

curl -X GET "https://api.webacy.com/batch/c5d2a8e7-f619-4f5b-9a52-3d1b7c6802e4" \
  -H "x-api-key: YOUR_API_KEY_HERE"

Available Query Params:

This endpoint supports pagination through the following query parameters:

ParameterTypeRequiredDefaultDescription
pagenumberNo1The page number to retrieve (starts at 1)
pageSizenumberNo10The number of items per page (number of results to return)

Sample Response (Status Check):

{
    "batchId": "30033cbb-5817-45b0-a660-e8f8e2043c95",
    "status": "completed",
    "total": 2,
    "scanned": 2,
    "results": [
        {
            "count": 1,
            "medium": 0,
            "high": 1,
            "overallRisk": 70.71067811865476,
            "issues": [
                {
                    "score": 10,
                    "tags": [
                        {
                            "name": "Phishing",
                            "description": "This address has been involved in phishing activities and is known to be dangerous. Proceed with extreme caution.",
                            "type": "addressRisk",
                            "severity": 10,
                            "key": "phishing_activities"
                        }
                    ],
                    "categories": {
                        "fraudulent_malicious": {
                            "key": "fraudulent_malicious",
                            "name": "Fraudulent/Malicious",
                            "gradedDescription": {
                                "high": "The smart contract/address in this transaction has been used in and is associated with confirmed fraud and malicious activity, or the asset is a known malicious token. Interacting with it may also cause your address to be marked as fraudulent.",
                                "medium": "Elements of the smart contract in this transaction can be used a fraudulent and malicious fashion, or the address in this transaction has been involved in some risk activity.",
                                "low": "Properties of this transaction indicate the possibility of nefarious activity, but we have not detected anything that would constitute elevated risk"
                            },
                            "tags": {
                                "phishing_activities": true
                            }
                        }
                    },
                    "riskScore": "High Risk"
                }
            ],
            "details": {
                "fund_flows": {
                    "risk": {
                        "ofac": false,
                        "hacker": false,
                        "mixers": false,
                        "drainer": false,
                        "fbi_ic3": false,
                        "tornado": false
                    },
                    "flows": [
                        {
                            "to": "0x1234567890AbcdEF1234567890aBcdef12345678",
                            "from": "0xbB4D1DC5c1ABec4Ea11166ec97E714862863aD1D",
                            "type": "transfer",
                            "token": "0x55d398326f99059fF775485246999027B3197955",
                            "amount": 10.01726289,
                            "txhash": "0xe9f01a9cb93f672dde7250b1d7a981575cd4554f19a241430478efe8947adcb3",
                            "risk_score": 0
                        },
                        {
                            "to": "0x1234567890AbcdEF1234567890aBcdef12345678",
                            "from": "0xD9abebd25EA85E3887640574a9C8a165221C1C8e",
                            "type": "transfer",
                            "token": "@native",
                            "amount": 0.01,
                            "txhash": "0xb16702061fb320e916e44210da5599d8b68dd6f83a097ca48426d1e11d76c6c3",
                            "risk_score": 0
                        },
                        {
                            "to": "0x1234567890AbcdEF1234567890aBcdef12345678",
                            "from": "0xD9abebd25EA85E3887640574a9C8a165221C1C8e",
                            "type": "transfer",
                            "token": "@native",
                            "amount": 0.01,
                            "txhash": "0x9305dbec63ac7432a90ef5b52bda11f7180272f73843aa4ff4367ce41f99921e",
                            "risk_score": 0
                        },
                        {
                            "to": "0x1234567890AbcdEF1234567890aBcdef12345678",
                            "from": "0xD9abebd25EA85E3887640574a9C8a165221C1C8e",
                            "type": "transfer",
                            "token": "@native",
                            "amount": 0.01,
                            "txhash": "0xeab3cc418d6369c4d0d0a85775de03c33a60b7a449f5d10d66787b44f0e16ec0",
                            "risk_score": 0
                        },
                        {
                            "to": "0x1234567890AbcdEF1234567890aBcdef12345678",
                            "from": "0xBD612a3f30dcA67bF60a39Fd0D35e39B7aB80774",
                            "type": "transfer",
                            "token": "@native",
                            "amount": 0.03834818,
                            "txhash": "0x6a4569f0e8691c5aa3bb9c631d6a460eb64534925886ecb270b412901d3bfcf1",
                            "risk_score": 0
                        }
                    ],
                    "label": "0x1234567890AbcdEF1234567890aBcdef12345678",
                    "accounts": {
                        "0x0283A33FC3cafA2168956d04b5c5743a5Da09077": {
                            "type": "eoa",
                            "label": "0x0283A33FC3cafA2168956d04b5c5743a5Da09077",
                            "address": "0x0283A33FC3cafA2168956d04b5c5743a5Da09077",
                            "risk_score": 0,
                            "additional_labels": {
                                "ofac": false,
                                "hacker": false,
                                "mixers": false,
                                "drainer": false,
                                "fbi_ic3": false,
                                "tornado": false
                            }
                        },
                        "0xfBF507D1803014b4C5796Ed1197B90dBEfFEfe8A": {
                            "type": "eoa",
                            "label": "0xfBF507D1803014b4C5796Ed1197B90dBEfFEfe8A",
                            "address": "0xfBF507D1803014b4C5796Ed1197B90dBEfFEfe8A",
                            "risk_score": 0,
                            "additional_labels": {
                                "ofac": false,
                                "hacker": false,
                                "mixers": false,
                                "drainer": false,
                                "fbi_ic3": false,
                                "tornado": false
                            }
                        }
                    },
                    "fund_flow_risk": {
                        "ofac": false,
                        "hacker": false,
                        "mixers": false,
                        "drainer": false,
                        "fbi_ic3": false,
                        "tornado": false
                    }
                },
                "address_info": {
                    "balance": 0.2328581111276178,
                    "expiresAt": 1744992583032,
                    "time_1st_tx": "2024-02-28T07:55:23.000Z",
                    "time_verified": 1744906183032,
                    "has_no_balance": false,
                    "automated_trading": false,
                    "transaction_count": 101,
                    "has_no_transactions": false
                },
                "token_risk": {},
                "token_metadata_risk": {},
                "marketData": {},
                "buy_sell_taxes": {
                    "has_buy_tax": false,
                    "has_sell_tax": false
                },
                "dev_launched_tokens_in_24_hours": null
            },
            "isContract": false,
            "address": "0x1234567890abcdef1234567890abcdef12345678",
            "chain": "eth"
        },
        {
            "count": 1,
            "medium": 0,
            "high": 0,
            "overallRisk": 0,
            "issues": [],
            "details": {
                "fund_flows": {
                    "risk": {
                        "ofac": false,
                        "hacker": false,
                        "mixers": false,
                        "drainer": false,
                        "fbi_ic3": false,
                        "tornado": false
                    },
                    "flows": [],
                    "label": null,
                    "accounts": {},
                    "fund_flow_risk": {
                        "ofac": false,
                        "hacker": false,
                        "mixers": false,
                        "drainer": false,
                        "fbi_ic3": false,
                        "tornado": false
                    }
                },
                "address_info": {
                    "balance": 0,
                    "expiresAt": 1744992582961,
                    "time_1st_tx": "2025-04-17T16:09:42.961Z",
                    "time_verified": 1744906182961,
                    "has_no_balance": true,
                    "automated_trading": false,
                    "transaction_count": 0,
                    "has_no_transactions": true
                },
                "token_risk": {},
                "token_metadata_risk": {},
                "marketData": {},
                "buy_sell_taxes": {
                    "has_buy_tax": false,
                    "has_sell_tax": false
                },
                "dev_launched_tokens_in_24_hours": null
            },
            "isContract": false,
            "address": "0xabcdef1234567890abcdef1234567890abcdef12",
            "chain": "bsc"
        }
    ],
    "page": 1,
    "size": 2
}

How to Use

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