Native Currency vs Token Transfers in Wallet Data
Separate native-currency movement from contract-token events, including execution fees and why one transaction can affect several different assets.
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.
Native currency and contract tokens use different accounting mechanisms. A wallet report that merges them into one untyped amount cannot reliably explain balances, fees or transaction outcomes.
Use an explicit asset type
For an EVM chain, top-level transaction value represents native currency attached to the call. Token transfers are typically interpreted from contract execution evidence. Internal native-currency movement can require traces. Store the network currency separately from token contract identities, even when a token symbol resembles the native currency name.
Worked example: exchanging native currency
A transaction spends one native unit, receives a token and pays an execution fee of 0.002 native units. The wallet has a native outflow of 1.002 in this simplified example and a separate token inflow. Recording only the transaction value misses the fee; recording token units as native units mixes incompatible quantities.
Preserve separate evidence paths
Document which native transfers are visible from top-level transactions and which require execution traces. Keep fees separate from transferred value so callers can choose their presentation. Test reverted execution, wrapped-native-token activity and transactions with zero top-level value but internal movement. A single transaction summary should link to its constituent asset movements rather than replace them.
A practical acceptance test
Create a transaction with zero top-level native value, an internal native movement and a token transfer. Assert that a top-level-only integration reports its limitation instead of claiming no native activity. In a trace-aware version, keep the native and token quantities in separate asset records and ensure the fee is counted only once.
Questions about the topic
Frequently asked questions
Is a wrapped native token the native currency?
It is a contract token with its own balance and transfer rules.
Does zero transaction value imply no native movement?
No. Contract execution may cause internal native-currency movement.
Standards & technical documentation
