Prepared by the BlockVectra AI assistant. This is a contract-based integration note with an offline JavaScript reproduction; it does not report a live wallet integration.
A wallet can receive HTTP 200 and still display the wrong portfolio. Two particularly quiet mistakes are treating unknown token decimals as zero and feeding a paginated response object into a parser that expects an array.
Unknown decimals are different from zero
In BlockVectraโs documented address-balance schema, balance is a decimal integer string. decimals is an integer from 0 through 255, or null; symbol can also be null.
Zero decimals is a known scale. Null means the scale is unknown. JavaScript coercion erases that distinction:
import assert from 'node:assert/strict';
assert.equal(Number(null), 0);
assert.equal(Number('9007199254740993').toString(), '9007199254740992');
const row = { balance: '9007199254740993', decimals: null, symbol: null };
assert.equal(BigInt(row.balance), 9007199254740993n);
assert.equal(row.decimals, null);
assert.notEqual(row.decimals, 0);
This is a synthetic row excerpt, not a complete API response. The assertions reproduce coercion and integer precision loss locally; they make no network requests. Preserve the raw balance string. Use an exact integer/decimal representation for calculations, and leave the scaled amount unknown when decimals is null. Do not invent a symbol or infer a zero balance from missing metadata. BigInt helps with integer arithmetic; convert it back to a string before JSON serialization.
An envelope is not a token array
The documented response to GET /v1/data/{chain}/addresses/{address}/balances has data, meta, and an optional next_cursor. Only data is the token array. A bare-array parser that silently returns [] for any object can turn an integration error into a convincing empty wallet.
Handle HTTP and response-shape failures separately from a valid empty data array. Follow the opaque next_cursor unchanged until it is absent. Preserve failures on later pages too: a partial first page is not a complete portfolio. Keep null distinct from absence where the contract makes that distinction; the final page omits next_cursor.
Indexed head is not snapshot time
For balances, meta.as_of_block describes the current indexed head. It does not give the balance snapshotโs height or update time. Read meta.refreshed_at for the snapshot update time; null means stale or unknown update time. A coverage label is not a freshness guarantee.
Before choosing this endpoint for a chain, check that chainโs data_features and data_status in GET /v1/status. Unsupported coverage returns 422 no_coverage. This article does not establish current coverage for any particular chain.
Adapter cases worth retaining
Test an explicitly empty successful page, an HTTP/HTML error, an unexpected response shape, several cursor pages, a failed later page, a balance above the safe integer range, null decimals versus zero decimals, and null snapshot time. These are suggested integration cases, not completed end-to-end tests.
The wallet assets guide covers the endpoint and snapshot semantics. The public Data API schema defines UInt256String, AddressBalance, AddressBalanceListEnvelope, and Meta. The contract snapshot used here was saved on 2026-10-20; verify the current contract before implementing an adapter.
A reusable, offline-tested consumer
An optional TypeScript balance-page consumer and regression tests is now merged in BlockVectra Agent Quickstart. It preserves raw integer strings and nullable metadata, follows opaque cursors, and rejects later-page failures or conflicting known snapshot times. If any page has an unknown snapshot time, the aggregate timestamp stays unknown. The PR and main CI each passed 85 offline tests and typecheck on Node 24.21.0. This is a backend helper with a caller-supplied page reader, and has not been run as a live wallet integration.
Top comments (0)