Buy/Sell Tax Support

Overview

Fee-on-Transfer (FoT) tokens, which impose automatic Transfer Fees or Buy/Sell Taxes, can complicate transactions, 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.

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.

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

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:

1
"tokenMetadata": {
2
  "buyToken": {
3
    "buyTaxBps": "200",
4
    "sellTaxBps": "147"
5
  },
6
  "sellToken": {
7
    "buyTaxBps": "0",
8
    "sellTaxBps": "0"
9
  }
10
}

1
// Helper function to format tax basis points to percentage
2
const formatTax = (taxBps: string) => (parseFloat(taxBps) / 100).toFixed(2);
3
4
// Display Tax Information in UI
5
<div className="text-slate-400">
6
  {quote.tokenMetadata.buyToken.buyTaxBps &&
7
    quote.tokenMetadata.buyToken.buyTaxBps !== "0" && (
8
      <p>
9
        {buyTokenInfo(chainId).symbol +
10
          ` Buy Tax: ${formatTax(quote.tokenMetadata.buyToken.buyTaxBps)}%`}
11
      </p>
12
    )}
13
  {quote.tokenMetadata.sellToken.sellTaxBps &&
14
    quote.tokenMetadata.sellToken.sellTaxBps !== "0" && (
15
      <p>
16
        {sellTokenInfo(chainId).symbol +
17
          ` Sell Tax: ${formatTax(quote.tokenMetadata.sellToken.sellTaxBps)}%`}
18
      </p>
19
    )}
20
</div>

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.

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