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:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| page | number | No | 1 | The page number to retrieve (starts at 1) |
| pageSize | number | No | 10 | The 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