Fee-on-Transfer Tokens: Requested vs Received Amounts
Handle tokens that deduct transfer fees by separating requested amounts, actual recipient changes and the contract-specific evidence behind each value.
Overview
When translating these concepts into an integration, keep the scope described by the normalized transactions api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
A token transfer request and the amount ultimately credited to a recipient need not be equal. Fee-on-transfer behaviour makes that distinction important for payment monitors, portfolio records and reconciliation.
Do not trust the input amount alone
The requested calldata amount describes an intention. Contract rules can allocate some quantity to a fee recipient, burn it or apply another adjustment. Event conventions and implementation details vary. Validate the actual evidence for the specific token instead of assuming that one generic transfer decoder captures every balance effect.
Worked example: a two-unit deduction
A sender requests a transfer of 100 units. The recipient is credited 98 and two units are allocated elsewhere under the token rules. An invoice requiring 100 received units is not fully paid merely because the input requested 100. Store requested, debited and credited amounts separately when the evidence supports those distinctions.
Test the receiving policy
Define whether a product accepts gross requested value or net received value. Compare relevant before-and-after state only at consistent boundaries and account for unrelated movements in the same transaction. Test multiple fee destinations, rounding and exemptions. When the implementation is unknown, expose uncertainty instead of silently normalising the recipient amount to the request.
A practical acceptance test
Use requested value 100, recipient credit 98 and a separate two-unit fee allocation. A payment rule requiring 100 received units should remain underpaid. Repeat with a network execution fee in another asset and assert that it does not alter the token’s credited quantity. Keep each amount linked to the evidence supporting its role.
Questions about the topic
Frequently asked questions
Is calldata enough to determine received value?
No. Execution and token-specific accounting can change the credited amount.
Is a token transfer fee the network gas fee?
No. They are separate costs, potentially in different assets.
Standards & technical documentation
