Incoming, Outgoing and Self Token Transfers
Classify wallet transfer direction with sender and recipient comparisons, while handling self-transfers, fees and multiple movements in one transaction.
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.
Direction is relative to the wallet being viewed. The same transfer can be outgoing for one account and incoming for another. A self-transfer needs special handling because both comparisons match.
Define direction at movement level
Compare normalised sender and recipient identities against the selected wallet on the same network. Do not use transaction sender alone: a contract call can cause movements between other addresses. Keep incoming, outgoing and self categories distinct, and preserve raw participant addresses so the classification can be recomputed.
Worked example: a self-transfer
Wallet W sends ten token units from W to W. The event is both sender-matched and recipient-matched, but it does not increase the token balance by ten or decrease it by ten overall. Record the gross movement and net zero token effect. Any native-currency execution fee belongs to a separate asset movement.
Test transaction-level aggregation
A swap can contain several incoming and outgoing events. Derive each movement first, then group related movements without erasing their identities. Test address normalisation, zero-value transfers and transfers involving multiple watched wallets. A direction label describes the selected view; it is not sufficient evidence of revenue, expense, ownership change or another accounting classification.
A practical acceptance test
Use one incoming transfer, one outgoing transfer and one self-transfer for the selected wallet. Verify gross classification and net quantity independently. Add a second watched wallet that participates in the same event: each wallet view can have a different direction, but the underlying event identity must remain stable and must not become two global transfers.
Questions about the topic
Frequently asked questions
Does incoming mean income?
No. Direction alone does not establish economic or accounting treatment.
Should a self-transfer be discarded?
Keep the evidence, while preventing it from inflating net balance changes.
Standards & technical documentation
