Skip to main content
The BlockDB JavaScript/TypeScript SDK supports Node ≥ 18 (native fetch) and browsers. It ships as ESM and CJS with complete TypeScript types and zero required runtime dependencies.

​
Where it’s available

​
Installation

npm install @blockdb/sdk

​
Quick example

import { BlockDbClient } from "@blockdb/sdk";

const client = new BlockDbClient({
  clientId: process.env.BLOCKDB_CLIENT_ID!,
  clientSecret: process.env.BLOCKDB_CLIENT_SECRET!,
});

// Fetch a single page of blocks
const result = await client.primitives.getBlocks({
  chain_id: 1,
  from_block: 21_000_000,
  to_block: 21_001_000,
  limit: 50,
});

console.log(`Got ${result.count} blocks. Next cursor: ${result.cursor}`);
result.data.forEach((b) => console.log(b.block_number, b.block_hash));

​
Prices example

// WETH/USDC VWAP over a block range
const vwap = await client.prices.crypto.getVwap({
  chain_id: 1,
  base_token_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",  // WETH
  quote_token_address: "a0b86991c6218b36c1d19d4a2e9eb0ce3606eb48", // USDC
  from_block: 21_000_000,
  to_block: 21_010_000,
});

console.log(`WETH/USDC VWAP: ${vwap.data[0]?.vwap}`);

​
Pagination

Every endpoint returns a cursor field. Pass it back to fetch the next page, or use the built-in paginate* async generators to iterate all pages automatically. 
let cursor: string | null | undefined;

do {
  const page = await client.primitives.getBlocks({
    chain_id: 1,
    from_block: 21_000_000,
    to_block: 21_001_000,
    limit: 100,
    cursor,
  });

  page.data.forEach((b) => process(b));
  cursor = page.cursor;
} while (cursor);

​
Cancellation

Every request accepts an AbortSignal via the optional second options argument: 
const controller = new AbortController();
setTimeout(() => controller.abort(), 3_000);

const tokens = await client.entities.getErc20Tokens(
  { chain_id: 1, contract_address: "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" },
  { signal: controller.signal }
);

​
Configuration reference

new BlockDbClient({
  // Required
  clientId: "...",
  clientSecret: "...",

  // Optional overrides
  baseUrl:   "https://api.blockdb.io/v1",                       // default
  authUrl:   "https://user.blockdb.io/api/authorization/token", // default
  scopes:    "offline_access api",                              // default
  timeoutMs: 30_000,                                            // 30 s

  retry: {
    maxAttempts:      3,
    initialDelayMs:   500,
    maxDelayMs:       30_000,
    backoffMultiplier: 2,
  },

  // Inject a custom fetch (Node <18, test mocks, proxies, …)
  fetch: myCustomFetch,

  // Structured log hook
  onLog: (entry) => logger.debug(entry),
});
Last modified on March 20, 2026