curl -X POST "https://api.blockdb.io/v1/evm/swaps/fees" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"from_block": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
}'
#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\":19000000,\"to_block\":19000100,\"pool_uids\":[\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}";
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/swaps/fees");
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\":19000000,\"to_block\":19000100,\"pool_uids\":[\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/swaps/fees", 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/swaps/fees",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'chain_id': 1,
'from_block': 19000000,
'to_block': 19000100,
'pool_uids': ['00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640'],
'token_in_addresses': ['c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'],
'token_out_addresses': ['a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'],
'limit': 250}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/swaps/fees", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"from_block": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
})
});
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": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/swaps/fees", 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": 19000000,
"to_block": 19000100
},
"resolved_window": {
"from_block": 19000000,
"to_block": 19000100
},
"filters": {
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250,
"cursor": null
}
},
"data": [
{
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"exchange_id": 3,
"type_id": 302,
"block_number": 19000042,
"block_time": "2025-12-20T12:34:56Z",
"tx_index": 15,
"log_index": 88,
"token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"fee_token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"amount_in_raw": "5000000000000000000",
"amount_in": "5",
"amount_out_raw": "15850000000",
"amount_out": "15850",
"fee_amount_total_raw": "15000000000000000",
"fee_amount_total": "0.015",
"fee_amount_user_raw": "12000000000000000",
"fee_amount_user": "0.012",
"fee_amount_protocol_raw": "3000000000000000",
"fee_amount_protocol": "0.003",
"fee_amount_extra_raw": "0",
"fee_amount_extra": "0",
"_tracing_id": "030300000000000000000000000000007401",
"_parent_tracing_ids": ["010300000000000000000000000000007401", "020400000000000000000000000000007401"],
"_created_at": "2025-12-20T12:35:01Z",
"_updated_at": "2025-12-20T12:35:01Z"
}
],
"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"
}
}
Swaps
Swap Fees
Read per-swap fee accounting (executed sizes + computed fee amounts) for pool economics and yield modeling.
POST
/
v1
/
evm
/
swaps
/
fees
curl -X POST "https://api.blockdb.io/v1/evm/swaps/fees" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"from_block": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
}'
#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\":19000000,\"to_block\":19000100,\"pool_uids\":[\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}";
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/swaps/fees");
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\":19000000,\"to_block\":19000100,\"pool_uids\":[\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/swaps/fees", 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/swaps/fees",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'chain_id': 1,
'from_block': 19000000,
'to_block': 19000100,
'pool_uids': ['00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640'],
'token_in_addresses': ['c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'],
'token_out_addresses': ['a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'],
'limit': 250}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/swaps/fees", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"from_block": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
})
});
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": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/swaps/fees", 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": 19000000,
"to_block": 19000100
},
"resolved_window": {
"from_block": 19000000,
"to_block": 19000100
},
"filters": {
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250,
"cursor": null
}
},
"data": [
{
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"exchange_id": 3,
"type_id": 302,
"block_number": 19000042,
"block_time": "2025-12-20T12:34:56Z",
"tx_index": 15,
"log_index": 88,
"token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"fee_token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"amount_in_raw": "5000000000000000000",
"amount_in": "5",
"amount_out_raw": "15850000000",
"amount_out": "15850",
"fee_amount_total_raw": "15000000000000000",
"fee_amount_total": "0.015",
"fee_amount_user_raw": "12000000000000000",
"fee_amount_user": "0.012",
"fee_amount_protocol_raw": "3000000000000000",
"fee_amount_protocol": "0.003",
"fee_amount_extra_raw": "0",
"fee_amount_extra": "0",
"_tracing_id": "030300000000000000000000000000007401",
"_parent_tracing_ids": ["010300000000000000000000000000007401", "020400000000000000000000000000007401"],
"_created_at": "2025-12-20T12:35:01Z",
"_updated_at": "2025-12-20T12:35:01Z"
}
],
"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:
0303 - Liquidity Pool Swap Fees - Description: Per-swap fee accounting: executed swap sizes plus computed fee amounts using the pool’s fee terms (
blockdb_evm.b0212_liquidity_pools_fee_terms_v1). - 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: Provide exactly one of:
- Block range —
from_blockandto_block - Time range —
from_timestampandto_timestamp - Direct selectors — presented below
Pool Selectors
number[]
Filter swaps by exchange IDs. See the DigitalExchange enumeration for supported values.
string[]
Filter by BlockDB pool identifiers (
uid from /evm/entities/pools).string[]
Filter by pool contract addresses (hex string, 20 bytes, no
0x prefix).string[]
Filter by protocol-specific pool identifiers (e.g., Uniswap V4
pool_id).Token Selectors (directional)
string[]
Restrict to swaps where the input token is in this set (hex string, 20 bytes, no
0x prefix).string[]
Restrict to swaps where the output token is in this set (hex string, 20 bytes, no
0x prefix).string[]
Restrict to swaps where the fee is denominated in one of these tokens (hex string, 20 bytes, no
0x prefix).Pagination Controls
number
default:"250"
Recommended default
250; maximum 1000 to stay under ~10 MB responses.string
Pagination cursor from a prior call.
Decimals-Adjusted Amounts
boolean
default:"false"
Off by default. When set to
true, the response includes decimals-adjusted siblings of every *_raw field (amount_in, amount_out, fee_amount_total, fee_amount_user, fee_amount_protocol, fee_amount_extra). Enabling it adds a per-request ERC-20 decimals lookup (extra join) that increases latency, so it is opt-in; when omitted or false, those fields are returned as null and only the always-present *_raw fields are populated.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 (selectors, pagination state, etc.).
Data
object[]
Array of per-swap fee records matching the request. There is no separate numeric
id field.string
BlockDB pool identifier (
uid from /evm/entities/pools).number
Exchange/DEX identifier.
number
Pool type identifier.
string
20-byte address of the input token (direction of trade).
string
20-byte address of the output token for this swap direction.
string
Token address the fee is denominated in (typically
token_in).string
Executed input amount as a raw integer in
token_in’s smallest denomination. String-encoded to preserve uint256 precision.string | null
Decimals-adjusted form of
amount_in_raw (amount_in_raw / 10^decimals resolved against token_in). null when decimals are unknown or include_adjusted_amounts=false.string
Executed output amount as a raw integer in
token_out’s smallest denomination.string | null
Decimals-adjusted form of
amount_out_raw (resolved against token_out). null when decimals are unknown or include_adjusted_amounts=false.string
Total fee amount as a raw integer in
fee_token’s smallest denomination.string | null
Decimals-adjusted form of
fee_amount_total_raw (resolved against fee_token). null when decimals are unknown or include_adjusted_amounts=false.string | null
User/LP share of the fee as a raw integer in
fee_token units. null when the protocol does not split.string | null
Decimals-adjusted form of
fee_amount_user_raw. null when the raw value is null, when decimals are unknown, or when include_adjusted_amounts=false.string | null
Protocol share of the fee as a raw integer in
fee_token units. null when the protocol does not split.string | null
Decimals-adjusted form of
fee_amount_protocol_raw. Same null semantics as the user field.string | null
Extra-destination share of the fee as a raw integer in
fee_token units. null when not applicable.string | null
Decimals-adjusted form of
fee_amount_extra_raw. Same null semantics as the user field.number
Block height where the swap event was observed.
string
UTC timestamp of the block containing the swap.
number
Zero-based transaction index within the block.
number
Zero-based log index within the transaction.
string
Row-level lineage hash (hex string, no
0x prefix).string[]
Lineage references of immediate parents.
string
Record creation timestamp (ISO-8601).
string
Last update timestamp (ISO-8601).
Envelope Fields
string | null
Cursor token for pagination.
number
Number of records returned in
data.curl -X POST "https://api.blockdb.io/v1/evm/swaps/fees" \
-H "Authorization: Bearer $BLOCKDB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"chain_id": 1,
"from_block": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
}'
#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\":19000000,\"to_block\":19000100,\"pool_uids\":[\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}";
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/swaps/fees");
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\":19000000,\"to_block\":19000100,\"pool_uids\":[\"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640\"],\"token_in_addresses\":[\"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2\"],\"token_out_addresses\":[\"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48\"],\"limit\":250}",
Encoding.UTF8,
"application/json"
);
var response = await client.PostAsync("https://api.blockdb.io/v1/evm/swaps/fees", 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/swaps/fees",
headers={
"Authorization": f"Bearer {os.getenv('BLOCKDB_API_KEY')}",
"Content-Type": "application/json"
},
json={'chain_id': 1,
'from_block': 19000000,
'to_block': 19000100,
'pool_uids': ['00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640'],
'token_in_addresses': ['c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2'],
'token_out_addresses': ['a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48'],
'limit': 250}
)
data = response.json()
print(data)
const response = await fetch("https://api.blockdb.io/v1/evm/swaps/fees", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.BLOCKDB_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"chain_id": 1,
"from_block": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
})
});
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": 19000000,
"to_block": 19000100,
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250
}`)
req, _ := http.NewRequest("POST", "https://api.blockdb.io/v1/evm/swaps/fees", 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": 19000000,
"to_block": 19000100
},
"resolved_window": {
"from_block": 19000000,
"to_block": 19000100
},
"filters": {
"pool_uids": [
"00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640"
],
"token_in_addresses": [
"c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"
],
"token_out_addresses": [
"a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
],
"limit": 250,
"cursor": null
}
},
"data": [
{
"pool_uid": "00000000000000000000000088e6a0c2ddd26feeb64f039a2c41296fcb3f5640",
"exchange_id": 3,
"type_id": 302,
"block_number": 19000042,
"block_time": "2025-12-20T12:34:56Z",
"tx_index": 15,
"log_index": 88,
"token_in": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"token_out": "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"fee_token": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"amount_in_raw": "5000000000000000000",
"amount_in": "5",
"amount_out_raw": "15850000000",
"amount_out": "15850",
"fee_amount_total_raw": "15000000000000000",
"fee_amount_total": "0.015",
"fee_amount_user_raw": "12000000000000000",
"fee_amount_user": "0.012",
"fee_amount_protocol_raw": "3000000000000000",
"fee_amount_protocol": "0.003",
"fee_amount_extra_raw": "0",
"fee_amount_extra": "0",
"_tracing_id": "030300000000000000000000000000007401",
"_parent_tracing_ids": ["010300000000000000000000000000007401", "020400000000000000000000000000007401"],
"_created_at": "2025-12-20T12:35:01Z",
"_updated_at": "2025-12-20T12:35:01Z"
}
],
"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