curl -X POST "https://api.blockdb.io/v1/evm/verify/receipt-root" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
}'
#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,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\"],\"data\":\"0x\"}]}]}";
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/verify/receipt-root");
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,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\"],\"data\":\"0x\"}]}]}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/verify/receipt-root", 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/verify/receipt-root",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'block_hash': '7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0',
'block_number': 18767124,
'chain_id': 1,
'receipt_root': 'b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f',
'transactions': [{'cumulative_gas_used': 21000,
'index': 0,
'logs': [{'contract_address': '0000000000000000000000000000000000000000',
'data': '0x',
'topics': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
'000000000000000000000000000000000000000100000bb875f0074000000000000',
'000000000000000000000000000000000000000100000bb875f0074000000000000']}],
'root': None,
'status': 1}]}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/verify/receipt-root", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/verify/receipt-root", 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
},
"data": [
{
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"parent_block_hash": "8a1e67f5d30a6a56f5afc7f9deee5ee97d6af872637dcf71aa41cc403baba2d2",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"computed_receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"is_identical": true
}
],
"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"
}
}
Verification
Verify Receipt Root
Recompute and compare canonical receipt trie roots.
POST
/
v1
/
evm
/
verify
/
receipt-root
curl -X POST "https://api.blockdb.io/v1/evm/verify/receipt-root" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
}'
#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,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\"],\"data\":\"0x\"}]}]}";
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/verify/receipt-root");
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,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\"],\"data\":\"0x\"}]}]}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/verify/receipt-root", 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/verify/receipt-root",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'block_hash': '7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0',
'block_number': 18767124,
'chain_id': 1,
'receipt_root': 'b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f',
'transactions': [{'cumulative_gas_used': 21000,
'index': 0,
'logs': [{'contract_address': '0000000000000000000000000000000000000000',
'data': '0x',
'topics': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
'000000000000000000000000000000000000000100000bb875f0074000000000000',
'000000000000000000000000000000000000000100000bb875f0074000000000000']}],
'root': None,
'status': 1}]}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/verify/receipt-root", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/verify/receipt-root", 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
},
"data": [
{
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"parent_block_hash": "8a1e67f5d30a6a56f5afc7f9deee5ee97d6af872637dcf71aa41cc403baba2d2",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"computed_receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"is_identical": true
}
],
"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
Validates a block’s receipt Merkle root by recomputing it from the receipts you provide. Use this endpoint to independently confirm that BlockDB (or any upstream source) delivered a complete, ordered receipt set.Parameters
Block Context
number
required
Canonical block height whose receipts you want to verify.
string
required
Block hash (hex string, 32 bytes, no
0x prefix). Acts as a guard to ensure you are verifying the intended block.string
required
Receipt trie root reported by your data source (e.g., the block header). The endpoint recomputes the root from the supplied receipts and compares it to this value.
Transaction Inputs
object[]
required
Complete list of transaction receipts for the block (order-insensitive).
number
required
Zero-based transaction index within the block.
number
Post-Byzantium execution status (
1 = success, 0 = revert). Mutually exclusive with root.string
Pre-Byzantium state root (hex string, 32 bytes, no
0x prefix). Provide only for receipts before Byzantium; omit or set to null for modern blocks.number
required
Total gas consumed in the block up to and including this transaction.
object[]
required
Logs emitted by the transaction.
string
required
Address emitting the log (hex string, 20 bytes, no
0x prefix).string[]
required
0-4 indexed topics (hex string, 32 bytes each, no
0x prefix) in emission order. May be empty.string
required
Hex-encoded ABI payload (hex string, even length, no
0x prefix). Use "0x" when empty.Pagination Controls
number
default:"250"
Recommended default
250; maximum 1000 to stay under ~10 MB responses.string
Pagination cursor from a prior call.
Response Fields
Meta
object
Echo of request metadata applied to the response.
number
EVM chain ID echoed from the request.
Data
object[]
Array of verification results (currently one per request).
number
Sequential block height.
string
Keccak-256 hash of the block header (hex string, 32 bytes, no
0x prefix).string
Keccak-256 hash of the parent block.
string
Receipt trie root sourced from the request.
string
Root recomputed from the supplied receipts.
boolean
true when computed_receipt_root matches receipt_root; otherwise false.Envelope Fields
string | null
Reserved for future pagination.
number
Number of result objects in
data.curl -X POST "https://api.blockdb.io/v1/evm/verify/receipt-root" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
}'
#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,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\"],\"data\":\"0x\"}]}]}";
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/verify/receipt-root");
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,\"block_number\":18767124,\"block_hash\":\"7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0\",\"receipt_root\":\"b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f\",\"transactions\":[{\"index\":0,\"status\":1,\"root\":null,\"cumulative_gas_used\":21000,\"logs\":[{\"contract_address\":\"0000000000000000000000000000000000000000\",\"topics\":[\"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\",\"000000000000000000000000000000000000000100000bb875f0074000000000000\"],\"data\":\"0x\"}]}]}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/verify/receipt-root", 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/verify/receipt-root",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'block_hash': '7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0',
'block_number': 18767124,
'chain_id': 1,
'receipt_root': 'b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f',
'transactions': [{'cumulative_gas_used': 21000,
'index': 0,
'logs': [{'contract_address': '0000000000000000000000000000000000000000',
'data': '0x',
'topics': ['ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef',
'000000000000000000000000000000000000000100000bb875f0074000000000000',
'000000000000000000000000000000000000000100000bb875f0074000000000000']}],
'root': None,
'status': 1}]}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/verify/receipt-root", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
})
});
const data = await response.json();
console.log(data);
package main
import (
"fmt"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"chain_id": 1,
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"transactions": [
{
"index": 0,
"status": 1,
"root": null,
"cumulative_gas_used": 21000,
"logs": [
{
"contract_address": "0000000000000000000000000000000000000000",
"topics": [
"ddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
"000000000000000000000000000000000000000100000bb875f0074000000000000",
"000000000000000000000000000000000000000100000bb875f0074000000000000"
],
"data": ""
}
]
}
]
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/verify/receipt-root", 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
},
"data": [
{
"block_number": 18767124,
"block_hash": "7b5c0972efb6a0b5be4a4d4a0de5d1abd922478a53f32b2c717a800c862ba9e0",
"parent_block_hash": "8a1e67f5d30a6a56f5afc7f9deee5ee97d6af872637dcf71aa41cc403baba2d2",
"receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"computed_receipt_root": "b4d8cfe4b87590afe7ed95fbf7798142e8fb1ce86307ff0eb6580b8bc23de92f",
"is_identical": true
}
],
"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