DEV Community

BlockVectra
BlockVectra

Posted on Edited on AI-assisted

Check the key before the first Data API request

#typescript #api #blockchain #webdev

An unset environment variable is still undefined at runtime, even when TypeScript code uses a non-null assertion. Catching that configuration error before a request makes the first call easier to debug.

The BlockVectra Data API TypeScript client now rejects a missing, empty or whitespace-only key when you create the client. It leaves non-empty keys unchanged; the API checks whether they are active and valid.

Optional: check public RPC before Data API setup

For a first connectivity check, clone the TypeScript quickstart and run:

git clone https://github.com/blockvectra/agent-quickstart.git
cd agent-quickstart
npm install
npm run read:public
Enter fullscreen mode Exit fullscreen mode

The command reads the public chain directory, checks that the advertised Robinhood Mainnet endpoint supports the two required methods, verifies chain ID 4663, and reads the latest block number. It makes at most three HTTP requests, with no retries. No wallet, account, or API key is needed for this path.

This is a connectivity check; a block number does not establish historical coverage or Data API freshness. For Data API calls and account operations, continue with the keyed onboarding flow below. npm start remains the full wallet/SIWE/key flow and can create an account and API key.

Version 0.1.4 is available on npm:

npm install @blockvectra/data-api
Enter fullscreen mode Exit fullscreen mode

The package includes JavaScript and TypeScript declarations; no local build is needed.

Here is a Node.js TypeScript example. Keep the key in server configuration:

import { createDataClient, isDataApiError } from "@blockvectra/data-api";

const apiKey = process.env.BLOCKVECTRA_API_KEY;
if (apiKey === undefined) {
  throw new Error("Set BLOCKVECTRA_API_KEY on the server.");
}

const client = createDataClient({ apiKey });
const { data, error, response } = await client.GET(
  "/{chain}/status/freshness",
  { params: { path: { chain: "robinhood_mainnet" } } },
);

if (!response.ok) {
  const code = isDataApiError(error)
    ? error.error.code
    : "unstructured_error";
  throw new Error(`Data API ${response.status}: ${code}`);
}

if (data) {
  console.log({
    as_of_block: data.meta.as_of_block,
    refreshed_at: data.meta.refreshed_at,
  });
}
Enter fullscreen mode Exit fullscreen mode

isDataApiError matters because an HTTP error body can be JSON, plain text, HTML or empty. The guard checks the Data API JSON envelope before the example reads error.error.code. It does not parse strings, rewrite the response or decide whether the key is valid. The original HTTP status remains available in every response.

The same pattern is useful for a backend service or an agent making the request. Keep the response metadata with the result, then check the dataset's coverage and refresh state against the task you are doing. An empty result or a successful status alone does not establish that the expected data is complete and current.

For v0.1.3, validation covered 37 unit tests, type checking and all nine README TypeScript examples. The prebuilt package was also installed and checked in a separate project with mock responses. The credentialed live test was skipped; this example is not a report of a new live API run.

Get a key through the normal key setup, and use the SDK README for pagination and other endpoints. The v0.1.4 release includes the archive and its SHA-256 checksums.

Resume an ERC-20 transfer-history query

For a query that spans several pages, the checkpointed transfer example saves each response with its opaque next cursor. Run it again with the same address, block range and checkpoint to read the next page. Each invocation makes at most one request, with a 15-second timeout and no automatic retry. A failed page leaves the saved checkpoint unchanged; a finished checkpoint makes no further request.

The example is included in the 0.1.5 GitHub archive:

npm install https://github.com/blockvectra/data-api-js/releases/download/v0.1.5/blockvectra-data-api-0.1.5.tgz
node node_modules/@blockvectra/data-api/examples/address-transfers-page.mjs
Enter fullscreen mode Exit fullscreen mode

Before running, set the API key, chain, address, fixed block bounds and checkpoint path using the setup and limits. Use an existing private checkpoint directory. The older npm 0.1.4 package does not include this example; the archive URL above installs 0.1.5 directly.

Pagination exhausted only means there is no next cursor. It does not prove that the upstream index has no gaps, and a partial coverage stays partial. Keep the API key in the environment, outside the checkpoint.

Using Deno 2

For the Deno CLI, start with the prebuilt package installation, then save the Deno quick-start example as quickstart-deno.ts. It reads the key from your environment and requests the dataset freshness endpoint once.

deno run --node-modules-dir=manual --no-prompt \
  --allow-env=BLOCKVECTRA_API_KEY,BLOCKVECTRA_CHAIN \
  --allow-net=api.blockvectra.com quickstart-deno.ts
Enter fullscreen mode Exit fullscreen mode

This grants access to two environment variables and the API host. An empty key fails before a request; the request has a 15-second timeout and no retries. Check the returned dataset watermarks before using the data.

Top comments (0)