Why Transfer-Tax Tokens Change Swap Quotes

A transfer-tax token swap quote must account for tokens lost to a fee when they move between wallets or contracts. The quote path starts with the amount the user offers, follows each transfer through the token contract and trading route, then estimates what reaches the pool and what the user receives. If the token deducts a tax during one of those transfers, the amount entering the swap can be smaller than the amount sent.

That distinction matters because a standard quote often assumes the full transfer amount arrives. For background on the cross-chain design, see how omnichain routes token swaps. Here, the key integration problem is narrower: make the quoted amount match the token’s transfer behavior closely enough that the transaction can execute and the user can understand the result.

What changes when a token charges a transfer tax?

The token contract can take a cut when it processes a transfer, so the sender’s debit, recipient’s credit and amount received by a pool may differ. A contract might send part of the transfer to a fee recipient or remove it from circulation. A swap route can involve several transfers, so integrators need to account for where a fee applies: on the user’s sale, the purchase, or another movement along the route.

Think of the quoted amount as a parcel sent through a sorting hub: the label shows what left the sender, while the pool can only trade what arrived. A conventional estimate based on the label can overstate the pool’s input. The result may be an inaccurate output estimate or a transaction revert if the swap’s execution conditions expect more tokens than the pool receives.

How should an integrator build the quote?

An integrator should identify the token behavior, estimate the tax that applies to the trade, and calculate output from the net amount that reaches the swap venue. The first check is whether the quote source detects transfer fees or buy and sell taxes. The next is whether its response distinguishes the two tokens and reports fees as known values or unknown values.

For example, 0x’s API documentation describes a tokenMetadata object with separate buy and sell token fields, including buyTaxBps and sellTaxBps. It says these values are expressed in basis points and can be null when undetermined. That is an example of the information an integrator can surface; it does not mean every quote service uses the same fields or method.

A practical quote flow should keep these moving parts distinct:

• Input amount: the quantity the user asks to sell or spend.
• Tax estimate: the fee expected for the relevant transfer or trade direction.
• Net swap input: the amount expected to reach the pool after applicable deductions.
• Estimated output: the amount calculated from that net input and the route’s available liquidity.

Tax settings can be conditional or change, so a cached estimate may stop matching the contract’s behavior. Where available, use current detection or transaction simulation and make sure the executable transaction is built for the same amounts and route as the displayed quote. Keep a separate execution bound, such as a minimum acceptable output, to account for price movement between quote and execution. Raising slippage tolerance does not calculate the token tax; it only loosens that bound and can expose the user to a worse execution price.

What should the user see before signing?

Show the estimated tax separately from the swap’s expected output, and label whether the displayed input is before or after the fee. If both the sold and purchased tokens can be taxed, show the direction for each; a single “fee” line can hide which transfer reduces the user’s proceeds. If the tax is unknown, say so and avoid presenting the output as a guaranteed amount.

The quote should also make clear which value the transaction enforces at execution. The user needs to know the estimated net output and the minimum output the swap will accept, plus the fact that a token’s tax behavior may affect the result. A transparent quote gives the user a useful comparison; the signed transaction still needs to enforce a defensible execution limit.