DEV Community: BlockVectra

Four transactions, eight transfers: an ERC-20 ingestion regression fixture

BlockVectra — Sun, 08 Nov 2026 05:58:24 +0000

A transfer table keyed only by transaction hash can lose valid rows while every RPC call succeeds.

Here is a small, real fixture that catches that mistake: eight ERC-20 Transfer logs across four Base transactions. The per-transaction counts are 1, 1, 2 and 4. Put those logs into a dictionary keyed only by transaction hash and only four rows survive.

Run the check without an RPC key

Download cadd-raw-logs.jsonl from the fixed sample revision. Save the following as verify-sample.py in the same directory and run it with Python 3:

import json
from collections import Counter
from pathlib import Path

logs = [json.loads(line) for line in
        Path("cadd-raw-logs.jsonl").read_text().splitlines() if line.strip()]

by_transaction = {log["transactionHash"].lower(): log for log in logs}
event_keys = [(log["transactionHash"].lower(), int(log["logIndex"], 16))
              for log in logs]

assert len(logs) == 8
assert len(by_transaction) == 4
assert len(set(event_keys)) == 8
assert sorted(Counter(key[0] for key in event_keys).values()) == [1, 1, 2, 4]
print("8 logs; 4 transactions; 8 distinct event keys")

The code intentionally constructs the lossy transaction-keyed dictionary, then checks the event-level keys separately. No package installation, wallet, key or network request is needed once the sample is downloaded.

For this single-chain fixture, use transaction hash and log index to distinguish events. A dataset spanning chains should also carry chain identity. Keep block identity and removed/reorg handling as separate concerns: a distinct row key does not prove that an event is still canonical.

What the sample actually contains

BlockVectra's keyed Base endpoint returned these eight logs on November 8, 2026 at 04:25 UTC, for CADD at:

0x16f93ebc5320c89efc8701577efe49d14a276a06

The request filtered the ERC-20 Transfer topic over the inclusive range 53,758,000–53,758,999. The sample includes the raw result entries and expected rows from the unchanged decoder in this pinned upstream loader.

Only one event was independently compared with BaseScan: block 53,758,011, log index 6, contract/from/to, and raw amount 57370140000000000000000. The other seven are provider-returned samples. This does not establish that the window contains every event.

Keep raw amounts as integers or decimal strings. The fixture does not use floating-point conversion to normalize token amounts.

Timestamp and receipt checks are separate

At 05:02 UTC, two additional calls returned:

decimals() at latest: 18, agreeing with the project seed.
A one-element JSON-RPC batch for block 53,758,011: timestamp 1793941977, or 2026-11-06T05:12:57Z, matching the independently saved BaseScan time.

Those request/response bodies are in loader-method-requests-responses.json in the same sample. The header hash agrees with the earlier log response, which is a same-provider cross-check rather than independent canonical verification. One batch item does not establish compatibility for the loader's usual 50-item batches.

The earlier lookup of that transaction's receipt returned null. That result remains tracked separately; the upstream log loader does not directly call receipts. Safe-head selection, timestamps for the other sample blocks, February-onward history and the full database backfill have not been validated here.

This fixture is useful for a narrow regression: preserving multiple transfers in one transaction. It is not a backfill benchmark, a complete ingestion test or evidence of customer adoption.

Why viem event logs break JSON.stringify—and how to keep uint256 exact

BlockVectra — Mon, 26 Oct 2026 07:39:34 +0000

A script can fetch event logs successfully and still crash when it prints them:

TypeError: Do not know how to serialize a BigInt

An empty result may pass the same code path. There is simply no decoded integer in [] to trigger the failure.

That is the distinction in four-meme-ai issue #3: non-empty BSC event results broke JSON output in two scripts. We submitted PR #4 with a two-line serialization fix and regression tests. The PR is open as of October 26, 2026; it has not been accepted upstream.

Keep decoded integers exact

In this case, viem decodes the events' uint256 arguments as JavaScript bigint. Raw JSON-RPC logs contain hex strings; the BigInts appear in the decoded JavaScript values. A successful RPC response does not guarantee that those values can be passed directly to JSON.stringify.

Use a replacer at the output boundary:

const args = { amount: 9007199254740993n, fee: 0n };

const json = JSON.stringify(
  args,
  (_key, value) => typeof value === 'bigint' ? value.toString() : value,
  2,
);

console.log(json);
// { "amount": "9007199254740993", "fee": "0" }

The replacer also reaches BigInts nested inside event arrays and argument objects. It leaves ordinary strings, booleans and existing numbers unchanged. This addresses BigInts; it does not make circular references or other unsupported structures serializable.

Avoid converting token amounts to Number just to make JSON work. For example, Number(9007199254740993n) becomes 9007199254740992. The exception disappears, but the value has changed. MDN explains the BigInt serialization error and replacer options.

The JSON contract now contains decimal strings. A consumer that knows a field represents an integer can use BigInt(parsed.amount) for arithmetic. Do not convert every decimal-looking string indiscriminately: identifiers and other textual fields may also contain digits. Decimal places still come from the token's metadata, not from serialization.

Test a non-empty result, an empty result, and an error

The patch's tests run both actual TypeScript scripts against a loopback JSON-RPC server:

Case, for each script	Expected result
Four synthetic event types with zero, values above the safe-integer limit, and `uint256` max	Valid JSON with exact decimal-string arguments
Empty log array	Successful empty output
RPC error	Non-zero exit, without empty-success output

The event types are TokenCreate, TokenPurchase, TokenSale and LiquidityAdded. Each non-empty test checks all four; these are six tests total, not eight separate event tests.

Before the fix, both non-empty tests failed: four passed and two failed. After the fix, all six passed. The TypeScript build also passed. The fixtures are synthetic and encoded with viem, so this verifies the scripts' serialization and error behavior—not the ABI against an independent source, a live BSC provider, or the complete CLI wrapper.

To run the same tests from the proposed patch, install Node.js 24 and check out the fixed commit:

git clone --branch fix/event-bigint-json https://github.com/gjwang/four-meme-ai.git
cd four-meme-ai
git checkout e797b768307250ac59065dd646739c4750dc3e3d
npm ci --ignore-scripts
node --test test/events-json.test.mjs
npm run build

Dependency installation needs network access. The regression tests use local synthetic responses and need no RPC key, wallet or transaction.

For a log reader, transport errors, valid empty results and output failures need separate handling. If you are also building a historical scan, our eth_getLogs block-range and recovery guide covers bounded queries and saved progress. Fixing serialization does not prove that an empty response is complete, and this patch does not change the default BSC RPC provider.

Build a Robinhood Chain stock-token activity dashboard with one API request

BlockVectra — Sun, 25 Oct 2026 21:38:40 +0000

To build a daily stock-token activity view on Robinhood Chain, start with transfer counts and holder counts for the latest recorded UTC day. The example below fetches them with one authenticated Data API request. Its default run makes no JSON-RPC calls.

Run the first request

Use Node.js 24 or newer. Clone the example, install locked dependencies, and export a key in your own shell:

git clone https://github.com/blockvectra/robinhood-stock-tokens.git
cd robinhood-stock-tokens
npm ci
export BLOCKVECTRA_API_KEY='replace-with-your-key'
npm start -- --limit 5

Get a BlockVectra API key and keep it in your environment; do not paste it into chat or commit it. Installation downloads are setup work, not API runtime traffic. The first npm start calls GET /v1/data/robinhood_mainnet/stocks?limit=5.

Read what comes back

Omitting --day asks for the latest recorded day, not today's date or a live quote. The CLI prints the requested day, response metadata, then rows with the recorded Day and token Address alongside activity fields. The API rows include day, token, symbol, transfers, and holder_count; the stock token data guide documents the full response.

This is a capped list of indexed activity, with up to five rows for this command. The default budget is one Data GET and zero RPC calls, and the stocks leaderboard has no cursor pagination. Each request has a 10-second timeout, and the CLI does not retry. meta.refreshed_at is the snapshot's refresh time. If it is missing or null, the CLI prints unknown and says to treat the data as stale. meta.as_of_block is the current indexed watermark; it does not prove that the daily table is fresh or complete.

An empty data array means there are no recorded rows for that request. That can be a normal quiet day; it does not, by itself, prove the ingestion pipeline is broken. Conversely, a populated response does not guarantee every token is covered. Check the actual day and freshness fields before using the result.

Add the multiplier only when needed

Pass --with-multiplier to create an RPC client. The CLI first checks eth_chainId equals 4663, then reads uiMultiplier() for at most the first 10 rows, sequentially and without retries. That optional path can use at most 12 runtime requests: one Data GET, one chain-ID check, and ten calls. A chain mismatch or unverifiable chain ID exits before any eth_call; a failed per-token read appears as unavailable, and rows past the cap appear as not queried (limit 10).

The multiplier is current contract state, not the historical value for a past day. It cannot supply the historical multiplier needed to calculate adjusted values for that past date. For the exact implementation, see the source at commit 12f341c.

Diagnosing eth_getLogs Returning [] When the Receipt Shows the Event

BlockVectra — Sun, 25 Oct 2026 17:28:40 +0000

An empty eth_getLogs result can be valid, but a successful response does not establish that the provider served a complete view. If a receipt contains the event you expected, compare the chain, block and exact filter before changing providers.

The pattern is familiar from BSC #3853, where a reporter described eth_getLogs returning [] against legacy BSC endpoints despite receipt evidence. That is their observation, not a cause we reproduced. It reminds us to separate what a receipt proves from what a log query returned.

Check the query before the endpoint

Start with the exact chain. A filter that looks right on BSC mainnet (chain ID 56) can be meaningless on a testnet or another EVM chain. Then compare the same block: the receipt's blockHash against the blockHash in returned logs, and whether you are looking at the same canonical block or a stale, reorged view. The sample below is a single fixed-block observation; it does not independently prove canonicality. Confirm the exact address and every topic position, including case normalization and whether you intended a wildcard. Finally, check whether the endpoint supports the method and range you requested. An explicit rejection is different from a successful empty result; policy alone does not explain why a particular query returned no logs.

A reproducible fixed-block sample

BlockVectra operates BSC infrastructure. Our keyed BSC internal QA observed this at UTC 2026-10-25T13:26:21.586695Z. Three serial HTTP/RPC calls ran: eth_chainId, eth_getTransactionReceipt, then eth_getLogs. chainId returned chain 56. The receipt was for a transaction in fixed block 129476271 (0x7b7a6af). The getLogs filter used only the contract address and that fixed block range, with no topics. It returned four logs. One selected ERC-721 Transfer for token 1811 matches the receipt event across address, topics, data, blockHash, blockNumber, transactionHash, transactionIndex, and logIndex. The other three are not individually receipt-validated here.

The saved check runs offline, with no key or network after download. Download the pinned ZIP snapshot, extract its ten files, open the extracted directory, and run with Node.js 22+:

node verify-sample.mjs observed-sample.json

Expected output:

PASS 1 receipt event matched among 4 returned logs

Live requests are separate: they need your endpoint, permissions, and method policy. Never paste API keys or other secrets into issue comments.

What the saved response can and cannot tell you

This is a consistency check within one saved observation. It does not prove independent canonicality, cover full history, explain the original incident, or measure speed. Use it to verify that a known receipt event and a fixed-block log response can be reconciled, then apply the same checks—chain, block hash, exact filter, method policy—to your own case.

If this is useful, start with the fixed artifact revision and the public BSC #3853 thread. Both are public.

For a live comparison, the snapshot also includes an optional client that makes up to three requests to your chosen provider without retries. Read its README before using it. BSC connection options are available for BlockVectra; access policy and historical retention can differ from the saved observation.

Read Robinhood Chain mainnet RPC without an API key (TypeScript)

BlockVectra — Sun, 25 Oct 2026 16:06:04 +0000

You can read Robinhood Chain mainnet without an API key. The script is TypeScript and requires Node.js 18 or newer. Clone the public quickstart, install dependencies, and run its public-read script:

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

The command first fetches https://api.blockvectra.com/v1/chains. It requires a robinhood_mainnet entry whose public.url is exactly https://api.blockvectra.com/v1/robinhood_mainnet/public, and whose public.methods list contains eth_chainId and eth_blockNumber.

That directory check happens before any RPC call. If the endpoint or either method is no longer advertised, the script stops. Otherwise it calls eth_chainId and verifies 4663 before reading the latest block. It makes at most three HTTP requests: one directory read and two JSON-RPC calls, with no retries, a 15-second timeout and a 128 KiB response cap per call. No wallet, private key, login, account or key creation is involved, and the block number stays an exact decimal string.

One internal QA run of the pinned version, observed on 2026-10-25 at 15:24 UTC, returned:

{"chain":"robinhood_mainnet","chainId":4663,"blockNumber":"97687425"}

Block height changes. That block number does not establish finality, historical data or data freshness. This is mainnet chain 4663, not testnet 46630.

Do not confuse npm run read:public with npm start, which runs full SIWE/wallet/key onboarding and may create an account or key. The Data API and account operations remain keyed.

For the project's own setup and usage notes, see the existing README. The public-read source is pinned at src/public-read.ts.

Install the native BlockVectra MCP plugin in Antigravity

BlockVectra — Sun, 25 Oct 2026 11:53:49 +0000

Install in one project

Run these commands from your project root:

mkdir -p .agents/plugins/blockvectra-docs
curl --fail --location https://raw.githubusercontent.com/blockvectra/mcp/antigravity-v0.1.0/plugin.json --output .agents/plugins/blockvectra-docs/plugin.json
curl --fail --location https://raw.githubusercontent.com/blockvectra/mcp/antigravity-v0.1.0/mcp_config.json --output .agents/plugins/blockvectra-docs/mcp_config.json

Start agy in that directory. For a first check, ask it to call search_docs with {"query":"Antigravity","lang":"en","limit":1}. Project-local loading and this single keyless documentation search were verified with Antigravity CLI 1.4.7.

The official plugin guide describes project-local and global installation. The commands above place the plugin in this project's .agents/plugins/ directory.

CLI-managed global installation

This walkthrough assumes Antigravity CLI is already installed and signed in. Install the BlockVectra plugin from its GitHub repository:

agy plugin install https://github.com/blockvectra/mcp

The plugin is named blockvectra-docs. It connects to https://docs.blockvectra.com/mcp over remote HTTP, so there is no local npm bridge to start or keep running. If you want to confirm what Antigravity recorded, the optional inventory command is:

agy plugin list --json

Check that the plugin appears as enabled and note its version and source. If the install command fails, fix that before relying on the plugin.

Check what the client loaded

For a CLI-managed installation, restart Antigravity, run /plugin to confirm blockvectra-docs is enabled, then /mcp to inspect the server and the tools it exposes. For the project-local setup, start Antigravity from that project directory and inspect /mcp.

Keep two levels of success separate. The lists in /plugin and /mcp confirm that the client registered and loaded the plugin; they do not prove the remote endpoint is reachable right now. The client's live server status shows whether the connection is up, and a tool has worked only when a call returns the data you asked for. Follow the client's normal tool permission prompts.

Run a keyless discovery check

Ask Antigravity to make two calls in plain language:

Call list_chains, then call read_doc with path=quickstart and lang=en.

A successful list_chains response confirms chain discovery. A successful read_doc response confirms documentation retrieval. Both are keyless. Connecting, reading docs, discovery, pricing, and status tools do not need an API key.

That does not make every RPC method keyless. Public methods vary by chain, so check the relevant chain's policy before assuming a call will run without credentials. Data API and account tools need your own key. Configure it only in your MCP client's private HTTP headers (x-api-key or Authorization); never put it in command arguments, tool arguments, or chat.

If /mcp does not list the server, check /plugin, the install output, and whether the client was restarted after install. If read_doc fails, check the path and lang arguments, then read the tool's error. For background and the full tool list, see the BlockVectra MCP server guide. Antigravity's own documentation covers plugins and MCP configuration.

Resume ERC-20 transfer history without skipping a failed page

BlockVectra — Sat, 24 Oct 2026 18:05:04 +0000

A transfer-history export should resume from its last saved page after a timeout. It should not start over, and it should not advance past a page it never received.

The useful unit of progress is the response and its next cursor, saved together. A cursor on its own tells you where to continue, but not whether you kept the data that came before it.

This BlockVectra example reads ERC-20 transfers for one address in a fixed block window. It makes at most one request per invocation, saves the original response envelope, and resumes when you run it again.

Install the packaged example

The example is included in the 0.1.5 GitHub release archive:

npm install https://github.com/blockvectra/data-api-js/releases/download/v0.1.5/blockvectra-data-api-0.1.5.tgz
umask 077
mkdir -p .checkpoints
chmod 700 .checkpoints

Use this archive for the example. The npm 0.1.4 package does not include it.

Provide these environment variables before running:

Variable	Value
`BLOCKVECTRA_API_KEY`	Your BlockVectra API key, supplied through your environment or secret manager
`BLOCKVECTRA_CHAIN`	A chain slug supporting the transfers dataset
`BLOCKVECTRA_ADDRESS`	The address whose ERC-20 transfers you want
`BLOCKVECTRA_FROM_BLOCK`	First block, as a non-negative decimal integer
`BLOCKVECTRA_TO_BLOCK`	Last block, inclusive; the window must contain at most 100,000 blocks

Use a fixed historical window for this run. The example does not look up the latest head or silently move the bounds. Check dataset support and coverage for the chain you choose.

Then run:

export BLOCKVECTRA_STATE="$PWD/.checkpoints/transfers.json"
node node_modules/@blockvectra/data-api/examples/address-transfers-page.mjs

Run the same command again, with the same inputs, to request the next page. Keep the checkpoint directory private and outside version control. The API key stays outside the checkpoint.

What happens when a page fails?

Suppose page one is saved and page two times out. The saved page and cursor remain unchanged. A later invocation tries from that same cursor; it does not skip ahead or reset to page one.

Outcome	Checkpoint behavior
Valid response with a next cursor	Save the response and cursor together
HTTP error, timeout or malformed response	Stop without advancing
Different address, chain or block bounds	Reject the mismatched checkpoint
Saved last page has no next cursor	Exit without sending another request

There is a 15-second timeout and no automatic retry. You decide when to run again. Cursor values are opaque: do not decode, edit or manufacture the next one.

The example fixes ERC-20, both transfer directions and 100 rows per page. It stops at 20 saved pages and also bounds response and checkpoint sizes. These are limits of this example, not service-wide guarantees. A stale lock needs deliberate review; the script does not remove it automatically.

Pagination finished is not history complete

The checkpoint keeps each page's original meta fields. If coverage is partial, it stays partial.

Even coverage=full and an exhausted cursor do not independently prove that the upstream index has no gaps. An ascending backfill can still have a hole that returns HTTP 200 with empty data. Treat pagination state, dataset coverage and your application's completeness checks as separate evidence.

Checkpoint replacement is atomic for process interruption; it is not a power-loss, reorg-recovery or snapshot-isolation guarantee. Run one invocation per checkpoint at a time.

The published archive was installed and checked with mocked pages, including cursor resume, mismatched inputs, a completed checkpoint and preserved partial coverage. That verifies the example's local behavior, not the completeness of a live transfer history.

The source and setup notes explain the bounds if you want to adapt it for a scheduled export.

Working directly with RPC logs instead? The resumable eth_getLogs guide covers fixed block chunks; the transfer example above follows an indexed API cursor.

Check the key before the first Data API request

BlockVectra — Fri, 23 Oct 2026 02:03:25 +0000

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

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

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,
  });
}

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

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

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.

Smithery's October 2026 Change: Point BlockVectra MCP Directly

BlockVectra — Thu, 22 Oct 2026 17:27:17 +0000

Smithery has announced that on October 31, 2026, it will stop connection management. According to its official announcement, that change covers the run.tools and server.smithery.ai proxy endpoints, managed identity, accounts and API keys, the API/Connect/Toolbox surfaces, and its CLI and SDK. Its public, non-proxy MCP registry will remain.

If your client uses Smithery to reach BlockVectra, plan to point it directly at the vendor endpoint instead. This is not a universal replacement for every MCP server: only BlockVectra's own MCP endpoint is covered here, and other servers should move to their respective official endpoints.

Use the direct BlockVectra endpoint

The endpoint is https://docs.blockvectra.com/mcp. The current guide describes a stateless Streamable HTTP transport using JSON-RPC 2.0 over POST. Update your existing client entry rather than adding a duplicate connection. Config keys differ across clients, so use the guide's client-specific examples rather than copying a universal JSON shape or inventing local CLI flags.

A browser GET to the endpoint returns 405. That response alone does not prove an outage; the endpoint expects POST.

To list tools without credentials, run:

curl -sS --max-time 20 \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  https://docs.blockvectra.com/mcp

This lists tools; it does not prove that a business RPC will succeed.

Verify before removing the old connection

Connecting, listing tools and reading documentation need no API key. As one small client-side check, call the read_doc tool with arguments path=quickstart and lang=en. It reads documentation only. Check for JSON-RPC errors and the tool's isError value, not just HTTP 200.

Indexed data and account tools need your own BlockVectra API key in the client's HTTP x-api-key header; Authorization: Bearer is also documented. Public RPC eligibility depends on the actual chain's public.methods. Do not assume every tool, transaction or dataset is keyless, and do not hard-code a tool count.

Do not carry a Smithery key into BlockVectra headers. Never place an API key or private key in tool arguments, URLs or chat. Avoid changing global permissions as a shortcut.

Complete the client handshake, tool list and doc read first. Then separately validate any authenticated or business tasks against the chains and methods you actually need before deleting the old connection. A successful doc read does not establish business-RPC or dataset coverage.

Client install choices and auth details: BlockVectra MCP server guide.

Why Decimal Can Round a UInt256 Token Amount, and an Exact Alternative

BlockVectra — Thu, 22 Oct 2026 03:45:28 +0000

The documented raw balance is a UInt256String: an unsigned integer string that can reach 78 digits. When you display one in Python, Decimal looks like the obvious tool. The trap is subtle: building a Decimal from a string is exact, but arithmetic on it can round.

Where the rounding happens

Decimal(raw) keeps every digit, because construction ignores the context precision. Operations such as scaleb, normalize, multiplication, or division round their result to the context precision, which defaults to 28 significant digits. That holds even at scale 0, where you intend no change at all.

The proof below takes the maximum UInt256 value and runs it through scaleb(0).normalize() with precision set to 28 inside localcontext(). The global context is not mutated. The result keeps the leading digits and replaces the rest with zeros, and nothing raises an error.

This does not make Decimal the wrong tool. Decimal calculations need a context appropriate to the inputs and operations. For this display-only task, integer formatting avoids depending on that context.

Exact integer formatting

Python integers have arbitrary precision. int(raw) parses the string exactly, and divmod(value, 10 ** decimals) splits the whole and fractional parts with no rounding. The remainder is left-padded to decimals digits, trailing zeros are stripped, and the parts are joined. No Decimal context is involved in this formatting step.

from decimal import Decimal, localcontext

def to_display_amount(raw: str, decimals: int | None) -> str:
    if decimals is None:
        return raw  # no decimals metadata: keep the raw integer
    value = int(raw)  # parse the decimal string exactly
    whole, remainder = divmod(value, 10 ** decimals)
    fraction = str(remainder).rjust(decimals, "0").rstrip("0")
    return f"{whole}.{fraction}" if fraction else str(whole)

raw = "115792089237316195423570985008687907853269984665640564039457584007913129639935"
with localcontext() as context:
    context.prec = 28
    rounded = format(Decimal(raw).scaleb(0).normalize(), "f")

assert rounded != raw  # Arithmetic rounded an exact Decimal input.
assert to_display_amount(raw, 0) == raw
assert to_display_amount(raw, None) == raw  # Raw units; the scale is still unknown.
assert to_display_amount(raw, 18) == "115792089237316195423570985008687907853269984665640564039457.584007913129639935"
print("rounded:", rounded)
print("exact:  ", to_display_amount(raw, 0))
print("PASS: 4 offline assertions; no network requests")

On Python 3.14.8 this exits with status 0, makes no network requests, and passes four assertions: the Decimal path differs from the input, scale 0 returns the exact string, None returns the raw string, and scale 18 yields the expected 18-digit fraction.

Nullable scale

The documented decimals value is an integer from 0 to 255, or null. When it is None, the formatter returns the raw integer string unchanged. That output is in raw units. It is not a scaled amount, and the scale is still unknown, so label it as raw instead of assuming 18.

Limits

The formatter assumes the input is already a valid unsigned integer string under the documented UInt256String format. It is a formatter, not a validator, so check input at your boundary first. The field definitions are in the wallet assets guide, and the standalone function is in this gist.

Resumable eth_getLogs scans: fixed chunks, saved checkpoints, safe restarts

BlockVectra — Wed, 21 Oct 2026 10:25:58 +0000

A rate limit, malformed response, or process restart can interrupt a log scan after successful chunks. The useful question then is not "how do I re-run the query?" but "which blocks are already saved, and where does the next request begin?"

The first response is not a saved checkpoint

A returned eth_getLogs result is only candidate data. The client advances to the next block only after two things happen in order: the HTTP status and JSON-RPC envelope pass validation (jsonrpc, id, no error, and result is an array), and a new checkpoint containing that chunk has been committed to disk. A successful empty array is valid. If either validation or the commit fails, the run stops at that chunk. It does not shrink the range, retry, skip ahead, swap checkpoint files, or open a new task.

Run a fixed window

Before adding a fallback, list the calls your scanner actually makes: for example, eth_blockNumber, eth_getLogs, and any block or transaction lookups in your processor. Matching eth_chainId alone doesn't confirm those methods, permitted block ranges, or historical coverage. Check public and keyed endpoint policies separately. RPC workflow checklist.

Use Node.js 24 or later. Get your API key from the BlockVectra console, then download the client example first.

Pick a chain, address, and inclusive fromBlock/toBlock that you have confirmed and that the node currently serves.

# Supply BLOCKVECTRA_API_KEY through your secret manager/environment.
export CHAIN="<confirmed-chain-slug>"
export LOG_ADDRESS="<confirmed-address>"
export FROM_BLOCK="<confirmed-start-block>"
export TO_BLOCK="<confirmed-end-block>"
export CHECKPOINT_FILE="./getlogs-checkpoint.json"
# optional: export CHUNK_BLOCKS=100
node getlogs-resumable.mjs

Replace every placeholder with your own confirmed values. BLOCKVECTRA_API_KEY is read from your own environment; the client does not create accounts. CHUNK_BLOCKS is optional and must be a positive decimal integer. Each request spans min(CHUNK_BLOCKS, max_logs_block_range) blocks, where the limit is read live from GET /v1/chains; without CHUNK_BLOCKS, the catalog value is used. Block span, result count, and the 2 MiB response/checkpoint caps are separate limits. The task allows 20 saved chunks, including restored ones.

Stop, then continue the same task

Change nothing in the task identity: same chain, address, and complete window. Keep the same checkpoint file and run again. The client re-validates the checkpoint's task binding, contiguous chunk order, and nextBlock, then requests only blocks not yet saved. You may change CHUNK_BLOCKS on resume; it only affects how the remaining range is split and never re-fetches saved chunks.

One process holds the checkpoint at a time through CHECKPOINT_FILE.lock; if a crash leaves the lock behind, confirm that no process owns it, then remove it manually. Checkpoints are written through a 0600 temporary file, fsync, and an atomic rename. The client does not claim exactly-once behavior across power loss or database commits.

A final complete status means the client read every block in that fixed window successfully. It does not prove that upstream data has no missing logs, that archive data covers the range, or that finality and reorgs are handled. Persist idempotently and verify chain hashes on the consumer side.

Check one block against its receipts

A saved checkpoint tells you where a scan stopped. It does not tell you whether an RPC returned every log. For a suspicious block, the new offline checker compares the complete transaction-hash list and one receipt per transaction with your saved eth_getLogs result.

node getlogs-reconcile-block.mjs block-material.json

Use Node.js 24 or later; the script makes no network calls and does not modify checkpoints. The guide describes the input format and optional address/topic filter. It returns consistent, inconsistent or unresolved. Keep a range unresolved on either of the latter two results. Agreement between the supplied files does not establish canonicality, validate a receipts root or prove complete history.

The full walkthrough, limits, and recovery rules are in the resumable eth_getLogs guide. You can also download the public client example and check its 35 synthetic response fixtures with a mock transport.

For two-direction wallet scans, the six offline checkpoint cases cover joint progress, persistence failures and gaps between parallel pages. These synthetic cases use no live RPC and are separate from the client's 35 response fixtures.

When a cancelled writer finishes late

Cancellation can leave an old write in flight. In a small synthetic example, writer B saves watermark 120; cancelled writer A resumes and overwrites it with 110. Checking ownership before an await still allows this race.

Four runnable writer-fencing cases compare cancellation alone, an early ownership check, a synchronous commit-time fence, and a current-writer control. Clone or download that revision, then run with Node.js 22 or later:

node --test writer-fencing.test.mjs

The model compares the writer's generation and replaces the cache without an await between them. It uses an in-memory cache; database transactions, crash recovery and reorg handling need their own checks.

When `eth_getLogs` returns an empty array

An empty response is not, by itself, a completeness check. If you have a transaction receipt with the event you expected, compare it with an address-filtered log request for that exact block. Check the chain and block hash as well as the address, topics, data and event position before widening the range.

Here is a downloadable BSC observation with raw responses and an offline checker. Download all files into one directory, then use Node.js 22+:

node verify-sample.mjs observed-sample.json

The saved check returns PASS 1 receipt event matched among 4 returned logs. It compares the selected receipt event across eight fields. The original RPC request filtered by address and one fixed block; event selection happens offline. No key or network is needed to run the checker.

These are three historical QA requests from 2026-10-25, not a rerun of the reporter's failing provider. They show consistency for one saved event, not complete history or the cause of the reported empty-result issue.

Gasless transactions: separate the signer, gas payer, and token owner

BlockVectra — Wed, 21 Oct 2026 01:28:57 +0000

AI-generated engineering note from BlockVectra.

"Gasless" describes an experience, not a protocol. Before writing any test, name four roles. In a demo they are often one address; in production they usually are not.

Signer: the key that authorizes an action off-chain.
Gas payer: in the direct EOA-relaying model used for this discussion, the transaction-sending EOA that pays native gas. Other sponsorship architectures can separate these roles.
Token owner: the account whose tokens are spent or whose allowance is authorized.
Contract caller: the address the target contract sees as msg.sender.

Many bugs come from treating two of these as one. A contract that reads the caller as the owner works when the owner sends the transaction and breaks when a relayer does.

Two token authorization patterns are useful to distinguish. A signed approval, as in ERC-2612, only changes an allowance; a transfer must still follow. A signed transfer, as in ERC-3009, binds sender, recipient, amount, validity window and nonce into one authorization that a third party can submit. Both need a token or wrapper that implements them, since plain ERC-20 does not. The official ERC-3009 page currently marks it Draft.

Assert roles, not just outcomes

A passing "transfer succeeded" check hides which account paid for what. Assert each role's balance and allowance separately, before and after, and use distinct token-owner/signer, relayer, and recipient addresses so a mix-up cannot pass by accident.

A proposed test matrix

This is a suggested plan, not a record of executed results.

Scenario	Setup	Assert
Zero-native user	Owner holds tokens and no native coin; relayer pays gas	Call succeeds; owner token balance drops by the exact amount
Zero-token sponsor	Relayer holds gas funds but zero tokens	Relayer token balance is zero before and after
Actor binding	Token-owner/signer, relayer, and recipient are distinct	A signed transfer debits the authorized owner and credits the authorized recipient; a permit updates the authorized owner-to-spender allowance without transferring tokens
Authorization lifecycle	Valid, expired, then replayed signature	Valid works once; the others revert and leave state unchanged
Vault accounting	Tokens credited directly to a vault	Deposit counters match what the design says they should mean

One public case

The 16ane repository test, pinned to one commit, has a relayer holding zero mock tANE submit a signed ERC-3009 transfer. The owner's balance falls from 10000 to 8400, the vault holds 1600, and owner principal stays 0, an accepted accounting gap because the deposit method never ran. A second test has the owner sign a permit while the relayer calls the vault's fundWithPermit wrapper. The second test expects an insufficient-allowance revert, because that wrapper treats the caller as the permit owner. That limits the wrapper, not ERC-2612 relaying in general. The tests do not assert that the owner holds zero native coin.

Verifying for real

Read balanceOf and allowance for the caller and the owner separately, and compare receipts and state deltas, one branch at a time. A simulation or a log status is not end-to-end proof. Also scope "atomic" carefully: a reverted transaction can still cost the sponsor gas, so atomicity here means application state is unchanged, not that fees come back.

If you are wiring agents to onchain actions, the BlockVectra agent integration documentation covers the integration side.