Skip to main content

​
Use an official client

The client libraries for TypeScript, Python and Rust already do most of this checklist: pagination, prepared queries, retries with Retry-After, truncation checks and amount encoding. If you use one, the items marked (client) are handled for you.

​
Correctness

Every response may end early: at 50,000 blocks, about 8 MB, maxObjects objects, or the head. Continue from next_block until it passes the end you want. Pagination
toBlock past the head is lowered silently. Use from_block, to_block and next_block from the response.
A response has one stream per row type. Read bl.streams of them, and compare the total rows with bl.objects to catch a truncated body. Reading Arrow
The server closes the connection if a query fails mid-response. Discard partial results and retry. Errors and retries
Rows above finalized_block can change. Either only use finalized rows, or re-read the unfinalized tail on every poll. Finality and reorgs
An address in a topic is 32 bytes: 0x + 24 zeros + the address.
value and other amounts are 128-bit (16 bytes in Arrow, decimal strings in JSON). They overflow 64-bit integers and JavaScript numbers. Data types
A field in unavailable_fields is null on the whole chain; other nulls are real. Fields a chain doesn’t have

​
Resilience

Honor Retry-After. 400, 401, 402 and 403 need a fix, not a retry.
Prepared queries expire after 30 minutes unused; sets after 7 days, or sooner when a new set needs the room. Resend the filter or re-create the set, then retry.
Save next_block after each page you’ve stored. On restart, continue from it.
balance_exhausted and overage_limit_reached won’t fix themselves. Page a person, and check GET /v1/account (free) before large jobs.
Log the request id with every error. It’s how we find your request in our logs.

​
Cost and speed

The same rows cost 2–2.5× less and decode faster. Arrow vs JSON
input, data, logsBloom and accessList are large. Use sighash instead of input if you only need the function. Selecting fields
Fewer matched rows means less data. Filter the rest client-side.
If you only need each log’s time.
Smaller requests, cached work on the server. Sets, Prepared queries
Faster polling returns empty responses that still count toward the rate limit and the 10 KB minimum. Following the head
Finalized history never changes. Read it once.
A response holds a query slot until it’s read; slow readers are cut off. Read first, process after.

​
Security

Never in browsers, mobile apps or repositories. Use a secret store. API keys
Rotating revokes the old key at once, so have the new key’s deployment ready (or accept a short interruption) before you rotate. If a key leaks, rotate right away. API keys
Each gets its own keys, limits, usage and billing.