Null, Zero and Missing Fields in Blockchain APIs
Represent unknown, unavailable and observed-zero values distinctly, preserving response compatibility and preventing false balances or valuations.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
Zero is a value. Null, an omitted field and an explicit unavailable status can express different conditions. An integration that converts them all to zero loses information needed for reliable decisions.
Define the state of each field
A balance can be observed zero, not requested, unavailable at the selected block or undecodable. A schema should state how these conditions are represented. Preserve the API contract when normalising inputs; adding a required interpretation to an old optional field can break consumers even if its name stays unchanged.
Worked example: an unknown token price
A wallet holds five units, but no eligible historical price is available. The quantity is known while valuation is unknown. Returning value zero implies the asset was observed to be worthless. Keep price and valuation unresolved, and let the UI explain why the portfolio total is partial.
Test every reader
Include old clients, exports and database defaults. Verify that missing decimal metadata does not become a zero-decimal assertion and that a null receipt does not become a failed transaction. Use explicit status fields where needed, and document whether a partial response can still contain usable known values.
A practical acceptance test
Test observed zero balance, absent optional balance, explicit unavailable history and malformed amount as four separate cases. Follow each through the API, UI and export. Known quantity with missing price must retain unknown valuation. A database default or spreadsheet conversion must not turn those uncertain states into asserted zeros.
Questions about the topic
Frequently asked questions
Is missing price equivalent to price zero?
No. It represents absent evidence, not an observed price.
Can omitted and null fields have different meanings?
Yes. Their contract should be defined and tested.
Standards & technical documentation