*** title: Buy/Sell Tax Support description: Learn best practices for how to implement 0x's buy/sell tax support. --------------------------------------------------------------------------------- ## Overview Fee-on-Transfer (FoT) tokens, which impose automatic *Transfer Fees* or *Buy/Sell Taxes*, can [complicate transactions](https://0x.org/post/0x-v2-buy-sell-tax-swap-support), leading to inaccurate quotes and failed swaps. This guide explains how 0x v2 addresses these challenges with real-time detection and tax calculation, ensuring accurate quotes and reliable on-chain execution for a smoother user experience. FoT (Fee-on-Transfer) Tokens are a category of tokens with Custom Properties either: * a **Transfer Fee** (user pays a fee any time the token is transferred to another wallet) or, * a **Buy/Sell Tax** (user pays a fee as a % of a swap when the token is bought or sold). ## The Problem Tokens with buy/sell tax properties disrupt standard token transfer assumptions, leading to: * Revert rates as high as 30% * High error rates (the #1 cause of custom token related errors) * Inaccurate quotes * A poor user experience When handling buy/sell tax tokens, integrators face two main challenges: * **Exact Matching**: The sent amount must match the received amount to avoid transaction reverts, but many tools used for detecting buy/sell tax and other custom token properties provide incomplete or outdated data which complicates this process. * **User Experience**: Users must know if a token has a buy/sell tax upfront. Without reliable detection, integrators may adjust slippage to account for fees, but setting slippage too low risks reverts, while setting it too high exposes users to MEV attacks, undermining trust in your app. ![Generic Swap Error](https://files.buildwithfern.com/0x.docs.buildwithfern.com/89984ab7a1dae535769bcb8ee52b8958b946fbc80c352ab8d3383d91c3393cfe/docs/assets/img/0x-swap-api/generic-swap-error.png) ## How 0x Solves the Problem 0x v2 API provides a robust solution, available on both Swap API and Gasless API: * **Automatic Detection & Optimized Routing**: 0x detects buy/sell tax tokens and optimizes trade routes, minimizing errors and transaction reverts. The API automatically includes the token’s buy/sell tax in its response. * **Real-Time Tax Calculation**: 0x simulates each token transfer to provide precise, real-time tax information, ensuring accurate quotes and enhancing the user experience. The API returns valid quotes and calldata for tokens with buy/sell taxes in both `/price` and `/quote` endpoints. * **User-Friendly Responses**: The API returns tax values in a format that’s easy to display to your end users, making it simple to communicate costs transparently. ## Implementation Best Practices ⚡️ Explore the Swap API v2 [demo code repo](https://github.com/0xProject/0x-examples/blob/main/swap-v2-allowance-holder-next-app/app/components/price.tsx#L362-L375) to see how to display the buy/sell tax for a selected token. ⚡️ See how [Matcha displays buy/sell tax](https://matcha.xyz/tokens/ethereum/eth?sellAmount=1\&buyChain=1\&buyAddress=0xcf0c122c6b73ff809c693db761e7baebe62b6a2e) in their UI. ### Display Buy/Sell Tax Information To build trust with users, it's crucial to display buy/sell tax information transparently in the UI. Here's how to effectively integrate the buy/sell tax information provided by the 0x API into your application: Decide how to best display the buy/sell taxes for tokens directly in the UI to improve transparency and user trust. If both the buy and sell tokens have taxes, be sure to indicate this. Below are some UI examples from the [Matcha](https://matcha.xyz/tokens/ethereum/eth?sellAmount=1\&buyChain=1\&buyAddress=0xcf0c122c6b73ff809c693db761e7baebe62b6a2e) app: Example 1: Sell token (FLOKI) has a sell tax. See live trade [here](https://matcha.xyz/tokens/ethereum/eth?buyChain=1\&buyAddress=0xcf0c122c6b73ff809c693db761e7baebe62b6a2e\&sellAmount=1) ![Matcha Buy Tax UI](https://files.buildwithfern.com/0x.docs.buildwithfern.com/c6a74812bd0b26672d03a4eb702f486f5b5ed1f83534d7699fea7ec62da52227/docs/assets/img/0x-swap-api/matcha-buy-tax-ui.png) Example 2: Both buy (SMI) and sell tokens (FLOKI) have buy and sell taxes, respectively. See live trade [here](https://matcha.xyz/tokens/ethereum/0xcd7492db29e2ab436e819b249452ee1bbdf52214?sellAmount=1\&buyChain=1\&buyAddress=0xcf0c122c6b73ff809c693db761e7baebe62b6a2e) ![Matcha Buy Sell Tax UI](https://files.buildwithfern.com/0x.docs.buildwithfern.com/6881bd02c48cb33d9a7fc60dd9a550a3af3def85ddcfffe4f39be8aad19bc5d4/docs/assets/img/0x-swap-api/matcha-buy-sell-tax-ui.png) Use the `tokenMetadata` object returned in the `/price` and `/quote` endpoints for both [Swap and Gasless API calls](/api-reference/openapi-yaml/swap/allowanceholder-getprice). This object contains the buy/sell tax information for the tokens involved in the swap. Example response: ```json "tokenMetadata": { "buyToken": { "buyTaxBps": "200", "sellTaxBps": "147" }, "sellToken": { "buyTaxBps": "0", "sellTaxBps": "0" } } ``` **Key Fields**: * **tokenMetadata**: Contains metadata for the buy and sell tokens in the swap. * **buyToken/sellToken**: Each contains `buyTaxBps` and `sellTaxBps`, representing the buy/sell tax in basis points for buying or selling the token. * **buyTaxBps/sellTaxBps**: The buy/sell tax in basis points. If undetermined, this will be set to null. Convert the buy/sell tax basis points to a percentage and display them in the UI. Example code to format and display tax information: ```js // Helper function to format tax basis points to percentage const formatTax = (taxBps: string) => (parseFloat(taxBps) / 100).toFixed(2); // Display Tax Information in UI
{quote.tokenMetadata.buyToken.buyTaxBps && quote.tokenMetadata.buyToken.buyTaxBps !== "0" && (

{buyTokenInfo(chainId).symbol + ` Buy Tax: ${formatTax(quote.tokenMetadata.buyToken.buyTaxBps)}%`}

)} {quote.tokenMetadata.sellToken.sellTaxBps && quote.tokenMetadata.sellToken.sellTaxBps !== "0" && (

{sellTokenInfo(chainId).symbol + ` Sell Tax: ${formatTax(quote.tokenMetadata.sellToken.sellTaxBps)}%`}

)}
``` ### Route All Tokens with Buy/Sell Taxes Through 0x Many of our meta-aggregator integrators automatically route all tokens with buy/sell taxes through 0x by default. The 0x APIs are specifically designed to handle the complexities of tokens with buy/sell taxes by leveraging real-time tax detection and trade route optimization. This ensures accurate fee calculations for each transaction and keeps your application up-to-date with any changes to token tax structures, eliminating the need for manual updates or custom implementations. ### Educating Your Users Consider including either links or pop-up modals next to buy/sell tax information to direct users to resources explaining these fees. For example, Matcha uses such links to guide users to blog posts or documentation, enhancing transparency and understanding. This approach helps users grasp the implications of taxes, reduces confusion, and builds trust in your platform. 👉 Try it on Matcha out [here](https://matcha.xyz/tokens/ethereum/eth?buyChain=1\&buyAddress=0xcf0c122c6b73ff809c693db761e7baebe62b6a2e\&sellAmount=1) ![Matcha Transfer Fee Info](https://files.buildwithfern.com/0x.docs.buildwithfern.com/45214f2e259419cd35015f120bddef0f03bc051a9906493a8f027c939fe1c6f6/docs/assets/img/0x-swap-api/matcha-transfer-fee-info.png) ### Deciding on Terminology There’s no standard for how to label buy/sell token taxes. You may see it referred to as - "fee", "buy/sell tax", "transfer fee" on different platforms. Your choice should fit your project and user base. * **Be Consistent:** Stick with the same term throughout your app. * **Know Your Users:** Use terms your audience will easily understand. * **Educate:** Provide links to explain the impact of buy/sell taxes. Clear, consistent terminology builds trust and improves user experience. ## Learn More * [(Blog) Introducing State-of-the-art Buy/Sell Tax support](https://0x.org/post/0x-v2-buy-sell-tax-swap-support)