Authorization

curl -X POST 'https://api.blockdb.io/v1/evm/raw/blocks' \
  -H 'Authorization: Bearer <BLOCKDB_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999
  }'

{
  "meta": {
    "chain_id": 1,
    "request_window": {
      "from_block": 12345678,
      "to_block": 12345999
    },
    "filters": {
      "limit": 10,
      "cursor": null
    }
  },
  "data": [],
  "cursor": null,
  "page_count": 0
}

{
  "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,
      "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"
  }
}

curl -X POST 'https://api.blockdb.io/v1/evm/raw/blocks' \
  -H 'Authorization: Bearer <BLOCKDB_API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{
    "chain_id": 1,
    "from_block": 12345678,
    "to_block": 12345999
  }'

{
  "meta": {
    "chain_id": 1,
    "request_window": {
      "from_block": 12345678,
      "to_block": 12345999
    },
    "filters": {
      "limit": 10,
      "cursor": null
    }
  },
  "data": [],
  "cursor": null,
  "page_count": 0
}

{
  "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,
      "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

BlockDB authenticates REST and WebSocket traffic with API keys. Send your key in the Authorization header on every request that requires authentication. Keys are tied to your subscription: which datasets and chains you can query, your compute unit allowance, and your rate limit. See the dataset index and Dataset ID for how products map to blockdb_evm tables.

There is no separate token endpoint and no OAuth flow. The key issued to you is the credential you pass as Bearer <key>.

Get an account and API keys

Choose a plan

API access is available on a custom plan. Email support@blockdb.io with the datasets, chains, and volume you need.

Receive and manage your keys

Your API key is issued when your plan is activated. Email support@blockdb.io to:

Request additional keys (up to 5 active keys per account)
Label keys (for example production vs staging)
Rotate a key when you need a new secret while phasing out an old one
Revoke a key that is compromised or no longer needed

Store keys only in environment variables or a secret manager—never commit them to source control.

Send the key on each request

Use the HTTP Authorization header with the Bearer scheme:

Authorization: Bearer <your_api_key>

Code examples: call the API with an API key

Set BLOCKDB_API_KEY in your environment (or substitute your key directly). These examples use the historic REST base URL https://api.blockdb.io/v1.

# Usage (no body)
curl -sS "https://api.blockdb.io/v1/usage" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY"

# Example data request
curl -sS -X POST "https://api.blockdb.io/v1/evm/raw/blocks" \
  -H "Authorization: Bearer $BLOCKDB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chain_id":1,"from_block":12345678,"to_block":12345999,"limit":10}'

import os
import requests

API_BASE = "https://api.blockdb.io/v1"
KEY = os.environ["BLOCKDB_API_KEY"]

h = {"Authorization": f"Bearer {KEY}"}

r = requests.get(f"{API_BASE}/usage", headers=h, timeout=30)
r.raise_for_status()
print(r.json())

r2 = requests.post(
    f"{API_BASE}/evm/raw/blocks",
    headers={**h, "Content-Type": "application/json"},
    json={"chain_id": 1, "from_block": 12345678, "to_block": 12345999, "limit": 10},
    timeout=30,
)
r2.raise_for_status()
print(r2.json())

const API_BASE = "https://api.blockdb.io/v1";
const key = process.env.BLOCKDB_API_KEY;
if (!key) throw new Error("Set BLOCKDB_API_KEY");

const headers = { Authorization: `Bearer ${key}` };

const usage = await fetch(`${API_BASE}/usage`, { headers });
console.log(await usage.json());

const blocks = await fetch(`${API_BASE}/evm/raw/blocks`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify({
    chain_id: 1,
    from_block: 12345678,
    to_block: 12345999,
    limit: 10,
  }),
});
console.log(await blocks.json());

using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var key = Environment.GetEnvironmentVariable("BLOCKDB_API_KEY")
    ?? throw new InvalidOperationException("Set BLOCKDB_API_KEY");

using var http = new HttpClient { BaseAddress = new Uri("https://api.blockdb.io/v1/") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", key);

var usage = await http.GetAsync("usage");
usage.EnsureSuccessStatusCode();
Console.WriteLine(await usage.Content.ReadAsStringAsync());

var body = new StringContent(
    """{"chain_id":1,"from_block":12345678,"to_block":12345999,"limit":10}""",
    Encoding.UTF8,
    "application/json");
var blocks = await http.PostAsync("evm/raw/blocks", body);
blocks.EnsureSuccessStatusCode();
Console.WriteLine(await blocks.Content.ReadAsStringAsync());

Official SDKs

The .NET, Python, and JavaScript SDKs accept your API key and attach Authorization: Bearer for you. See each SDK page for the exact constructor and configuration options.

Security practices

Rotation: Request a new key from support, deploy it, then ask for the old key to be revoked.
Least privilege: Use separate keys for production and non-production when possible (within the five-key limit).
Incidents: If a key leaks, email support@blockdb.io immediately to revoke it and issue a replacement.

{
  "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,
      "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 May 29, 2026

Overview

SDKs

Account & Usage

EVM Endpoints

Enumerations

Overview

Get an account and API keys

Code examples: call the API with an API key

Official SDKs

Security practices

See Also

​Overview

​Get an account and API keys

​Code examples: call the API with an API key

​Official SDKs

​Security practices

​See Also

Overview

Get an account and API keys

Code examples: call the API with an API key

Official SDKs

Security practices

See Also