curl -X POST "https://api.blockdb.io/v1/evm/raw/logs" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
}'
#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>
int main(void) {
CURL *curl = curl_easy_init();
if (!curl) return 1;
const char *token = getenv("BLOCKDB_API_KEY");
char auth_header[256];
snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}";
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, auth_header);
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/logs");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return res == CURLE_OK ? 0 : 1;
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));
var payload = new StringContent(
"{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/logs", payload);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
}
import os
import requests
response = requests.post(
"https://api.blockdb.io/v1/evm/raw/logs",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'block_numbers': [12345678, 12345679],
'chain_id': 1,
'contract_addresses': ['0000000000000000000000000000000000000000'],
'from_block': 12345678,
'from_timestamp': '2025-10-29T00:00:00Z',
'to_block': 12345999,
'to_timestamp': '2025-11-11T00:00:00Z',
'topic_zeros': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
'tx_hashes': ['7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0'],
'limit': 200,
'cursor': None}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/raw/logs", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/logs", payload)
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
// Handle response
}
{
"meta": {
"chain_id": 1,
"request_window": {
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z"
},
"filters": {
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
]
}
},
"data": [
{
"block_number": 12345678,
"block_time": "2025-11-11T18:42:15.123Z",
"tx_index": 4,
"log_index": 0,
"contract_address": "0000000000000000000000000000000000000000",
"topic_zero": "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"data_topics": [
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000001"
],
"data": "000000000000000000000000000000000000000100000bb875f00740000000003e8",
"_tracing_id": "010300000000000000000000000000000000",
"_created_at": "2025-11-11T18:42:15.123Z",
"_updated_at": "2025-11-11T18:42:15.123Z"
}
],
"cursor": null,
"page_count": 1
}
{
"error": {
"code": "BAD_REQUEST",
"http_status": 400,
"message": "The request contains invalid or missing parameters.",
"hint": "Validate all required parameters against the endpoint specification before retrying.",
"severity": "error",
"retryable": false,
"details": {
"invalid_parameters": [
{
"name": "chain_id",
"location": "query",
"reason": "missing",
"expected": "positive integer, e.g. 1"
},
{
"name": "from_timestamp",
"location": "query",
"reason": "invalid_format",
"expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
}
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/home"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"http_status": 401,
"message": "Invalid or missing API key.",
"hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
"severity": "error",
"retryable": false,
"details": {
"auth_scheme": "bearer",
"expected_header": "Authorization: Bearer <API_KEY>",
"provided_header": "Authorization: <REDACTED_OR_MISSING>",
"token_status": "invalid_or_missing",
"recommendation": "Regenerate the API key if you suspect it is expired or compromised."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
}
}
{
"error": {
"code": "FORBIDDEN",
"http_status": 403,
"message": "Your API key does not have permission to access this endpoint.",
"hint": "Upgrade your subscription tier or request additional access.",
"severity": "warning",
"retryable": false,
"details": {
"required_plan": "production",
"your_plan": null,
"contact": "support@blockdb.io",
"recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "NOT_FOUND",
"http_status": 404,
"message": "The requested resource does not exist.",
"hint": "Verify the API endpoint",
"severity": "warning",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "PAYLOAD_TOO_LARGE",
"http_status": 413,
"message": "The requested response exceeds the maximum allowed size of 10 MB.",
"hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
"details": {
"max_allowed_bytes": 10485760,
"estimated_response_bytes": 15360000,
"recommended_actions": [
"Decrease the 'limit' parameter value",
"Shorten the block range or time window",
"Filter by fewer pools or exchanges"
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
}
}
{
"error": {
"code": "CHAIN_NOT_SUPPORTED",
"http_status": 422,
"message": "chain_id=137 is not supported.",
"hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
"severity": "error",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"http_status": 429,
"message": "You have exceeded the allowed request rate.",
"hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
"details": {
"limit_rps": 1000, # configured rate limit
"current_estimated_rps": 73,
"retry_after_seconds": 2,
"limit_scope": "api_key",
"limit_window_seconds": 1
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"http_status": 500,
"message": "An unexpected server error occurred.",
"hint": "This error is not caused by your request. You may retry after a short delay.",
"severity": "critical",
"retryable": true,
"details": {
"incident_id": "INC-2025-11-11-123456",
"temporary_issue": true,
"expected_recovery_seconds": 5
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"http_status": 503,
"message": "The service is temporarily unable to handle the request.",
"hint": "The database connection pool is briefly saturated. Retry after a short delay.",
"severity": "warning",
"retryable": true,
"details": null,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
Primitives
Logs
Query decoded EVM log events with flexible topic filters.
POST
/
v1
/
evm
/
raw
/
logs
curl -X POST "https://api.blockdb.io/v1/evm/raw/logs" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
}'
#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>
int main(void) {
CURL *curl = curl_easy_init();
if (!curl) return 1;
const char *token = getenv("BLOCKDB_API_KEY");
char auth_header[256];
snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}";
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, auth_header);
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/logs");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return res == CURLE_OK ? 0 : 1;
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));
var payload = new StringContent(
"{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/logs", payload);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
}
import os
import requests
response = requests.post(
"https://api.blockdb.io/v1/evm/raw/logs",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'block_numbers': [12345678, 12345679],
'chain_id': 1,
'contract_addresses': ['0000000000000000000000000000000000000000'],
'from_block': 12345678,
'from_timestamp': '2025-10-29T00:00:00Z',
'to_block': 12345999,
'to_timestamp': '2025-11-11T00:00:00Z',
'topic_zeros': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
'tx_hashes': ['7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0'],
'limit': 200,
'cursor': None}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/raw/logs", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/logs", payload)
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
// Handle response
}
{
"meta": {
"chain_id": 1,
"request_window": {
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z"
},
"filters": {
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
]
}
},
"data": [
{
"block_number": 12345678,
"block_time": "2025-11-11T18:42:15.123Z",
"tx_index": 4,
"log_index": 0,
"contract_address": "0000000000000000000000000000000000000000",
"topic_zero": "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"data_topics": [
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000001"
],
"data": "000000000000000000000000000000000000000100000bb875f00740000000003e8",
"_tracing_id": "010300000000000000000000000000000000",
"_created_at": "2025-11-11T18:42:15.123Z",
"_updated_at": "2025-11-11T18:42:15.123Z"
}
],
"cursor": null,
"page_count": 1
}
{
"error": {
"code": "BAD_REQUEST",
"http_status": 400,
"message": "The request contains invalid or missing parameters.",
"hint": "Validate all required parameters against the endpoint specification before retrying.",
"severity": "error",
"retryable": false,
"details": {
"invalid_parameters": [
{
"name": "chain_id",
"location": "query",
"reason": "missing",
"expected": "positive integer, e.g. 1"
},
{
"name": "from_timestamp",
"location": "query",
"reason": "invalid_format",
"expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
}
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/home"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"http_status": 401,
"message": "Invalid or missing API key.",
"hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
"severity": "error",
"retryable": false,
"details": {
"auth_scheme": "bearer",
"expected_header": "Authorization: Bearer <API_KEY>",
"provided_header": "Authorization: <REDACTED_OR_MISSING>",
"token_status": "invalid_or_missing",
"recommendation": "Regenerate the API key if you suspect it is expired or compromised."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
}
}
{
"error": {
"code": "FORBIDDEN",
"http_status": 403,
"message": "Your API key does not have permission to access this endpoint.",
"hint": "Upgrade your subscription tier or request additional access.",
"severity": "warning",
"retryable": false,
"details": {
"required_plan": "production",
"your_plan": null,
"contact": "support@blockdb.io",
"recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "NOT_FOUND",
"http_status": 404,
"message": "The requested resource does not exist.",
"hint": "Verify the API endpoint",
"severity": "warning",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "PAYLOAD_TOO_LARGE",
"http_status": 413,
"message": "The requested response exceeds the maximum allowed size of 10 MB.",
"hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
"details": {
"max_allowed_bytes": 10485760,
"estimated_response_bytes": 15360000,
"recommended_actions": [
"Decrease the 'limit' parameter value",
"Shorten the block range or time window",
"Filter by fewer pools or exchanges"
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
}
}
{
"error": {
"code": "CHAIN_NOT_SUPPORTED",
"http_status": 422,
"message": "chain_id=137 is not supported.",
"hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
"severity": "error",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"http_status": 429,
"message": "You have exceeded the allowed request rate.",
"hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
"details": {
"limit_rps": 1000, # configured rate limit
"current_estimated_rps": 73,
"retry_after_seconds": 2,
"limit_scope": "api_key",
"limit_window_seconds": 1
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"http_status": 500,
"message": "An unexpected server error occurred.",
"hint": "This error is not caused by your request. You may retry after a short delay.",
"severity": "critical",
"retryable": true,
"details": {
"incident_id": "INC-2025-11-11-123456",
"temporary_issue": true,
"expected_recovery_seconds": 5
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"http_status": 503,
"message": "The service is temporarily unable to handle the request.",
"hint": "The database connection pool is briefly saturated. Retry after a short delay.",
"severity": "warning",
"retryable": true,
"details": null,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
Overview
- Dataset ID:
0103 - Logs - Description: Event logs emitted by contract transactions.
- CSV Sample: Download
- JSON Sample: Download
Parameters
Range Filters (mutually exclusive)
number
Starting block number (inclusive) for the query. Use with
to_block.number
Ending block number (inclusive) for the query. Use with
from_block.string
Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used. Use with
to_timestamp.string
Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used. Use with
from_timestamp.Scoping rule: Every request must include at least one primary criterion: a block range (
from_block/to_block), a time range (from_timestamp/to_timestamp), block_numbers, or tx_hashes. A block range and a time range are mutually exclusive, as are block_numbers and tx_hashes.contract_addresses and topic_zeros are refinement filters that require a block range or time range specifically — they cannot be used on their own, and a block_numbers/tx_hashes set does not satisfy this (an unbounded scan over a hot contract or topic would time out).Providing none of the above returns HTTP 400.Bounding Windows
number[]
Explicit set of block numbers (a bounding window). Mutually exclusive with
tx_hashes.string[]
Filter logs by parent transaction hash (hex string, 32 bytes, no
0x prefix); a bounding window. Mutually exclusive with block_numbers.Contract & Topic Filters
string[]
Filter by emitting contract address (hex string, 20 bytes, no
0x prefix). Requires a block range or time range.string[]
Filter by the primary event topic. Anonymous events have
topic_zero = null. Requires a block range or time range.Pagination Controls
number
default:"250"
Recommended default
250; maximum 1000 to stay under ~10 MB responses.string
Opaque pagination cursor supplied by a previous response.
Response Fields
Meta
object
Echo of request metadata applied to the response.
number
EVM chain ID echoed from the request.
object
Pure echo of the window you sent (
from_block/to_block/from_timestamp/to_timestamp); unset bounds are null.object | null
The concrete window the query actually executed against, after resolving the request. For a block range on a time-bucketed endpoint (OHLC/VWAP/VWAP-aggregate/fiat VWAP),
from_timestamp/to_timestamp hold the resolved timestamp window (and from_block/to_block echo your request). For a time range on a block-keyed endpoint, from_block/to_block hold the resolved block range (and the timestamps echo your request). null for selector-only requests (no window). No extra database work is done — these are the values the query already computed.number | null
Resolved/echoed start block of the executed window.
number | null
Resolved/echoed end block of the executed window.
string | null
Resolved/echoed start timestamp (ISO-8601) of the executed window.
string | null
Resolved/echoed end timestamp (ISO-8601) of the executed window.
object
Filters echoed from the request (block numbers, tx hashes, contract addresses, topics).
Data
object[]
Each element mirrors the table columns (chain implied by
meta.chain_id). Resolve transaction hash via block_number + tx_index and the transactions dataset if needed — there is no tx_hash column in SQL.number
Block height containing the log.
string
Block timestamp joined from the
blocks table for easier aggregation.number
Zero-based index of the parent transaction within the block.
number
Position of the log within the transaction.
string
Address of the emitting contract (20 bytes).
string
Primary topic hash identifying the event (32 bytes).
null for anonymous events.string[]
Subsequent event topics (
topics[1..n]), each stored as a 32-byte hex string.string
Raw event data payload (hex string (no
0x prefix)).string
Tracing identifier for the canonical transaction record (hex string, no
0x prefix).string
Record creation timestamp.
string
Record last update timestamp.
Envelope Fields
string | null
Cursor token for pagination.
number
Number of records returned in
data.curl -X POST "https://api.blockdb.io/v1/evm/raw/logs" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
}'
#include <curl/curl.h>
#include <stdio.h>
#include <stdlib.h>
int main(void) {
CURL *curl = curl_easy_init();
if (!curl) return 1;
const char *token = getenv("BLOCKDB_API_KEY");
char auth_header[256];
snprintf(auth_header, sizeof(auth_header), "Authorization: Bearer %s", token ? token : "");
const char *payload = "{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}";
struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, auth_header);
headers = curl_slist_append(headers, "Content-Type: application/json");
curl_easy_setopt(curl, CURLOPT_URL, "https://api.blockdb.io/v1/evm/raw/logs");
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, payload);
CURLcode res = curl_easy_perform(curl);
curl_slist_free_all(headers);
curl_easy_cleanup(curl);
return res == CURLE_OK ? 0 : 1;
}
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
class Program
{
static async Task Main()
{
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization =
new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("BLOCKDB_API_KEY"));
var payload = new StringContent(
"{\"chain_id\":1,\"from_block\":12345678,\"to_block\":12345999,\"from_timestamp\":\"2025-10-29T00:00:00Z\",\"to_timestamp\":\"2025-11-11T00:00:00Z\",\"block_numbers\":[12345678,12345679],\"tx_hashes\":[\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\"],\"contract_addresses\":[\"0000000000000000000000000000000000000000\"],\"topic_zeros\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\"],\"limit\":200,\"cursor\":null}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/raw/logs", payload);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
}
import os
import requests
response = requests.post(
"https://api.blockdb.io/v1/evm/raw/logs",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'block_numbers': [12345678, 12345679],
'chain_id': 1,
'contract_addresses': ['0000000000000000000000000000000000000000'],
'from_block': 12345678,
'from_timestamp': '2025-10-29T00:00:00Z',
'to_block': 12345999,
'to_timestamp': '2025-11-11T00:00:00Z',
'topic_zeros': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'],
'tx_hashes': ['7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0'],
'limit': 200,
'cursor': None}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/raw/logs", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z",
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
],
"limit": 200,
"cursor": null
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/raw/logs", payload)
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", os.Getenv("BLOCKDB_API_KEY")))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, _ := client.Do(req)
defer resp.Body.Close()
// Handle response
}
{
"meta": {
"chain_id": 1,
"request_window": {
"from_block": 12345678,
"to_block": 12345999,
"from_timestamp": "2025-10-29T00:00:00Z",
"to_timestamp": "2025-11-11T00:00:00Z"
},
"filters": {
"block_numbers": [
12345678,
12345679
],
"tx_hashes": [
"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0"
],
"contract_addresses": [
"0000000000000000000000000000000000000000"
],
"topic_zeros": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
]
}
},
"data": [
{
"block_number": 12345678,
"block_time": "2025-11-11T18:42:15.123Z",
"tx_index": 4,
"log_index": 0,
"contract_address": "0000000000000000000000000000000000000000",
"topic_zero": "ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"data_topics": [
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000001"
],
"data": "000000000000000000000000000000000000000100000bb875f00740000000003e8",
"_tracing_id": "010300000000000000000000000000000000",
"_created_at": "2025-11-11T18:42:15.123Z",
"_updated_at": "2025-11-11T18:42:15.123Z"
}
],
"cursor": null,
"page_count": 1
}
{
"error": {
"code": "BAD_REQUEST",
"http_status": 400,
"message": "The request contains invalid or missing parameters.",
"hint": "Validate all required parameters against the endpoint specification before retrying.",
"severity": "error",
"retryable": false,
"details": {
"invalid_parameters": [
{
"name": "chain_id",
"location": "query",
"reason": "missing",
"expected": "positive integer, e.g. 1"
},
{
"name": "from_timestamp",
"location": "query",
"reason": "invalid_format",
"expected": "ISO-8601 UTC timestamp, e.g. 2025-11-11T00:00:00Z"
}
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/home"
}
}
{
"error": {
"code": "UNAUTHORIZED",
"http_status": 401,
"message": "Invalid or missing API key.",
"hint": "Ensure you send 'Authorization: Bearer <API_KEY>' in every request to this endpoint.",
"severity": "error",
"retryable": false,
"details": {
"auth_scheme": "bearer",
"expected_header": "Authorization: Bearer <API_KEY>",
"provided_header": "Authorization: <REDACTED_OR_MISSING>",
"token_status": "invalid_or_missing",
"recommendation": "Regenerate the API key if you suspect it is expired or compromised."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/authorization"
}
}
{
"error": {
"code": "FORBIDDEN",
"http_status": 403,
"message": "Your API key does not have permission to access this endpoint.",
"hint": "Upgrade your subscription tier or request additional access.",
"severity": "warning",
"retryable": false,
"details": {
"required_plan": "production",
"your_plan": null,
"contact": "support@blockdb.io",
"recommendation": "Contact BlockDB Support Team via email support@blockdb.io."
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "NOT_FOUND",
"http_status": 404,
"message": "The requested resource does not exist.",
"hint": "Verify the API endpoint",
"severity": "warning",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "PAYLOAD_TOO_LARGE",
"http_status": 413,
"message": "The requested response exceeds the maximum allowed size of 10 MB.",
"hint": "Reduce the limit, narrow the block or time window, or apply additional filters before retrying.",
"details": {
"max_allowed_bytes": 10485760,
"estimated_response_bytes": 15360000,
"recommended_actions": [
"Decrease the 'limit' parameter value",
"Shorten the block range or time window",
"Filter by fewer pools or exchanges"
]
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/pagination-and-limits"
}
}
{
"error": {
"code": "CHAIN_NOT_SUPPORTED",
"http_status": 422,
"message": "chain_id=137 is not supported.",
"hint": "Use a supported chain_id. Consult the documentation for the list of available chains.",
"severity": "error",
"retryable": false,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"http_status": 429,
"message": "You have exceeded the allowed request rate.",
"hint": "Introduce client-side throttling or exponential backoff and respect the retry_after_seconds value.",
"details": {
"limit_rps": 1000, # configured rate limit
"current_estimated_rps": 73,
"retry_after_seconds": 2,
"limit_scope": "api_key",
"limit_window_seconds": 1
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/rate-limiting"
}
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"http_status": 500,
"message": "An unexpected server error occurred.",
"hint": "This error is not caused by your request. You may retry after a short delay.",
"severity": "critical",
"retryable": true,
"details": {
"incident_id": "INC-2025-11-11-123456",
"temporary_issue": true,
"expected_recovery_seconds": 5
},
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"http_status": 503,
"message": "The service is temporarily unable to handle the request.",
"hint": "The database connection pool is briefly saturated. Retry after a short delay.",
"severity": "warning",
"retryable": true,
"details": null,
"docs_url": "https://docs.blockdb.io/api-reference/overview/error-codes"
}
}
Last modified on July 19, 2026
Was this page helpful?
⌘I