Skip to main content
Version: 2.0

🤔 FAQ & Troubleshooting

Categories

🧰 Troubleshooting​

I received an issue in my API response. Help!

See API issues for a full list of common 0x issue types and how to resolve them.

Why does my 0x transaction revert?

If your 0x quote is reverting, besides the standard revert issues related to ETH transactions, we recommend check the following are set correctly:

  • Are allowances properly set for the user to trade the sellToken?
  • Does the user have enough sellToken balance to execute the swap?
  • Do users have enough to pay the gas?
  • The slippage tolerance may be too low if the liquidity is very shallow for the token the user is trying to swap. Read here for how to handle this.
  • Did the RFQ Quote expire? RFQ quotes from Market Makers are only valid for a short period of time, for example roughly 60s on mainnet. See "Did my order revert because the RFQ quote expired?" below for more details.
  • Working in testnet? Only a subset of DEX sources are available. Be aware that token you want to use for testing must have liquidity on at least one of these sources; otherwise, you will receive an error. Read here for how to handle this.

For more details on addressing common issues, read Troubleshooting.

Did my order revert because the RFQ quote expired?

RFQ quotes from Market Makers are only valid for a short period of time, for example roughly 60s on mainnet.

Two ways to check if this was the reason for your order reverting, you can use the Tenderly debugger on the transaction, search for order info by looking at the getOTCOrderInfo step in the trace look for the expiryAndNonce field. You may need to reach out to 0x support to help you decode the expiryAndNonce field.

Therefore, as a best practice we highly recommend adding an in-app mechanism that refreshes the quotes, approximately every 30s, to make sure RFQ orders don’t expire. See Matcha.xyz for an example of this in action.

0x orders are reverting but my transaction is fine, what is happening?

Developers may note when analyzing their transactions that some subset of 0x orders may revert (not filled) but the whole transaction is successful. This is expected behavior as implied earlier, some orders due to timing, and the pricing may be filled or expired before a users attempt to fill the order. This would result in a revert and 0x protocol will utilize fallback orders to compensate for the reverted order. This will result in a successful transaction even though reverts occur within the transactions.

How does including taker, the address which holds the sellToken, in the API call help with catching issues?

By passing a taker parameter, 0x API can provide a more bespoke quote and help catch revert issues:

  • 0x API will estimate the gas cost for taker to execute the provided quote.
  • If successfully called, the gas parameter in the quote will be an accurate amount of gas needed to execute the swap.
  • If unsuccessful for revert reasons suggested above, then 0x API will throw a gas cost estimation error, alluding to an issue with the taker executing the quote.

TLDR Pass taker to get the quote validated before provided to you, assuring that a number of revert cases will not occur.

I received an INPUT_INVALID error. Help!

Check that the API request was formatted properly. If the issue persists, contact support to resolve the issue.

I received an BUY_TOKEN_NOT_AUTHORIZED_FOR_TRADE or SELL_TOKEN_NOT_AUTHORIZED_FOR_TRADE error. Help!

The buy token is not authorized for trade due to legal restrictions

I received an INTERNAL_SERVER_ERROR error. Help!

An internal server error occurred.

Check that the API request was formatted properly. Check 0x system status.

If the issue persists, contact support to resolve the issue.

How will I know if the trade is not possible due to insufficient asset liquidity?

The API will return liquidityAvailable=false and not return any of the other response params if there is not enough liquidity avilable for the quote requested.

liquidityAvailable parameter

🔄 Swap API​

About Swap API​

Is there a fee to use Swap API?

The Swap API has a powerful free plan that you can access by creating an account via the 0x Dashboard; however, we also offer paid plans with higher throughput to support you as your user base and transactions grow. You can review and select the perfect plan for your team's needs on our pricing page.


0x also takes an on-chain fee on swaps involving a select few token pairs for the Free and Starter tiers. This fee is charged on-chain to the users of your app during the transaction. If you are on the Growth tier, we completely waive this fee for your customers. In cases where we charge a fee, we'll return the value of the fee in the API response in the zeroExFee parameter. You can find more details about this in the Swap API reference.

How does Swap API select the best orders for me?

Beyond simply sampling each liquidity source for their respective prices, Swap API adjusts for the gas consumption of each liquidity source with the specified gas price (if none is provided Swap API will use ethGasStation's fast amount of gwei) and any associated fees with the specific liquidity source. By sampling through varying compositions of liquidity sources, Swap API selects the best set of orders to give you the best price. Swap API also creates another set of fallback orders to ensure that the quote can be executed by users.

Ex: Swap API will adjust the price potentially received from Curve Finance by gas * gasPrice and its fees. Because of Curve Finance’s costly gas consumption, its nominal price may not be the best price when settled.

How can I find the Swap API liquidity sources for each chain?

Use the http://api.org/sources endpoint to get the list of supported sources for each chain. To specify the chain, use the chainId query parameter, for example, http://api.org/sources?chainId=1. See here for the list of support chains.

How can I find the tokens that 0x supports for trading?

0x supports all tokens by default except for tokens blocked for compliance reasons.

Is it possible to use the Swap API to trade custom ERC20 tokens or altcoins?

If you would like to trade a custom token, you will need to create the liquidity either by using 0x limit orders or by creating a Liquidity Pool for your token on one of the various AMM sources that the API sources from, such as Uniswap, SushiSwap, or Curve. Learn more about creating limit orders

Monetizing your Swap Integration​

I am building a DEX app using Swap API. Can I charge my users a trading fee/commission when using the Swap API?

TL;DR You have full flexibility on the fees you collect on your trades via either collecting affiliate fees or collecting trade surplus. Read our full guide on monetizing your swap integration.


Option 1: Collect affiliate fees

To collect affiliate fees, set the swapFeeRecipient, swapFeeBps, and swapFeeToken parameters in a Swap API request.

  • Set swapFeeRecipient which is the wallet address to receive the specified trading fees
  • Set the swapFeeBps which represents the amount in Bps (between 0 - 1000, where 1000 Bps equals 10%) to charge and deliver to the swapFeeRecipient
  • Set swapFeeToken which is the contract address of the token to receive the trading fees in. This must be set to either the buyToken or the sellToken.

When the transaction has gone through, the fee amount will be sent to the swapFeeRecipient address you've set. The fee is received in the swapFeeToken If you would like to receive a specific type of token different from either the buyToken or sellToken, you will need to convert it on your own.


If you would like to display the fee to your end users separately, the quote response will return a fees.integratorFee object with the amount property that can be displayed.


Option 2: Collect trade surplus

Trade surplus, also known as positive slippage, occurs when the user ends up receiving more tokens than their quoted amount. 0x Swap API can be easily configured so that you collect the trade surplus and send that to a specified address.

This can be done by setting the tradeSurplusRecipient parameter in a Swap API request. If specified, this address will receive trade surplus when applicable. Otherwise, the taker will receive the surplus.

The fee is received in the buyToken. If you would like to receive a specific type of token (e.g. USDC), you will need to make that conversion on your own.

Read our full guide on monetizing your swap integration.

How is the trading fee/commission I charge returned by Swap API - is it part of the quoted price or is it a separate parameter?

If the swapFeeRecipient, swapFeeBps, and swapFeeToken parameters are set when making a Swap API request, the returned response will return a fees.integratorFee object with the amount property that can be displayed to your end user.

The amount is calculated from (swapFeeBps/10000) * sellAmount (in the sellToken base unit).

For example, to take a 1% fee on selling 100 USDC,

  • sellToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 (USDC)
  • swapFeeToken=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
  • sellAmount=100000000 (USDC has a base unit of 6 decimals)
  • swapFeeBps=100 (1% fee)

The fee amount would be 1000000, which is 1 USDC.

// Example quote response with fee.integratorFee object
...
"fees": {
    "integratorFee": {
      "amount": "1000",
      "token": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
      "type": "volume"
    },
    ...

For examples and details, read our full guide on monetizing your swap integration. In API V2, you can charge opt to take your fee on either the buyToken or the sellToken in order to aggregate your revenue in a few tokens.

Can I collect trade surplus (a.k.a. positive slippage)?

Yes, you can collect the trade surplus and send it to a specified address.

Trade surplus, also known as positive slippage, occurs when the user ends up receiving more tokens than their quoted amount. 0x Swap API can be easily configured so that you collect the trade surplus and send that to a specified address.

This can be done by setting the tradeSurplusRecipient parameter in a Swap API request. If specified, this address will receive trade surplus when applicable. Otherwise, the taker will receive the surplus.

The fee is received in the buyToken. If you would like to receive a specific type of token (e.g. USDC), you will need to make that conversion on your own.

Read our full guide on monetizing your swap integration.

Permit2 and AllowanceHolder​

What is the difference between using Permit2 and AllowanceHolder for Swap API?

0x Swap API allows you to choose between two allowance methods: Permit2 or AllowanceHolder.

The decision when choosing between Permit2 or AllowanceHolder boils down to mainly UX and integration type.

When to Use Permit2

For most applications, we recommend using Permit2. This method requires two user signatures per trade:

  • A signature for limited approval
  • A signature for the trade itself

Permit2 is also recommended for setups involving multisig or smart contract wallets, as long as the smart contract supports EIP-1271, which most do.

Additionally, Permit2 is a standard that allows users to share token approvals across smart contracts. If a user has an infinite allowance set on Permite2 via another app, they don't need to reset the allowance.

When to Use AllowanceHolder

We recommend using Permit2 for most situations. However, if your integration doesn't support a double-signature flow, such as with smart contracts that aren't compatible with EIP-1271, AllowanceHolder is a better choice. It works best for single-signature use cases, including:

  • Projects integrating the Swap API into smart contracts without EIP-1271 support.
  • Teams aggregating across multiple sources and aiming for a consistent user experience across all integrations.

If you're concerned about upgrade speed, consider using AllowanceHolder, as it closely resembles the 0x Swap v1 integration. This approach can help streamline the upgrade process for teams that previously used Swap v1.

Read more about using Permit2 and AllowanceHolder contracts.

Key Points:

  • Permit2: Ideal for for most applications. Involves two signatures, one signature for limited approval and one signature for the trade itself. Also recommended for multisig or smart contract wallets.
  • AllowanceHolder: Best for single-signature use cases, especially in smart contracts that don't support EIP-1271 or meta-aggregators.

Permit2 Resources

AllowanceHolder

For more details, check out the Permit2 and AllowanceHolder contracts

Should I use AllowanceHolder or Permit2 for my meta-aggregator project?

The decision when choosing between Permit2 or AllowanceHolder boils down to mainly UX and integration type.

  • AllowanceHolder is ideal for single-signature use cases and provides a consistent user experience when aggregating across multiple sources. It also closely resembles the 0x Swap v1 integration, making it quicker to implement.

  • Permit2 is a universal standard that allows users to share token approvals across smart contracts (i.e. if users have an infinite allowance via another app, no reset is needed). However, Permit2 requires two signatures per trade (one for approval, one for the trade), which may impact user experience.

Evaluate your project’s needs and the desired user experience to make the best decision.

If an allowance is needed when using AllowanceHolder, which contract will issues.allowance.spender return?

The AllowanceHolder contract will be returned.

Parameter Questions​

What is gas?

Gas refers to the fee required to successfully conduct a transaction on the Ethereum blockchain. Gas fees are paid in Ether (ETH) and denominated in Gwei, which is a denomination of Ether (1 ETH = 1,000,000,000 Gwei).

What is the significance of this address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE ?

The address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE is used for representing native tokens in blockchain transactions. Since native tokens do not have an address, this address has become the standard that dapps use when needing to interact with a native token. Native tokens are the foundational digital currencies of their respective blockchains. Each blockchain has its own native token, such as ETH on Ethereum, BNB on Binance Smart Chain, and MATIC on Polygon.

Specifically for Ethereum, this address is utilized to represent Ether (ETH) since ETH is not an ERC-20 token. For more information, you can read further here and here.

Additionally, check out the Handling native tokens with 0x Swap API guide, which explains how to manage native tokens when using the 0x Swap API, as their handling differs from that of standard ERC-20 tokens.

Is it possible to quote by the buyAmount?

No, only quoting by sellAmount is supported.

The buyAmount parameter has been deprecated starting in v2 in favor of purely sellAmount for more deterministic and user-friendly behavior. Using sellAmount ensures any unused tokens are refunded, while buyAmount can result in over-purchasing due to slippage and inconsistencies across liquidity sources. Additionally, some sources (e.g., Kyber) do not support quoting by buyAmount, reducing available liquidity. By transitioning to sellAmount, we align with industry trends and offer more predictable execution for users.

Can I skip validation for the /quote endpoint by leaving the takerparameter blank?

No, the taker parameter is required in v2 for /quote. It enables us to return calldata and any issues that may have caused a failure during quote validation.

Why does the value of the to field in the /swap/quote response vary?

The to field value varies based on the current Settler contract address. The Settler contract is designed to be redeployed, resulting in different target addresses. See here for how to find the latest Settler address list of current and future 0x Settler addresses.

Best Practices​

What is the best way to query swap prices for many asset pairs without exceeding the rate limit?

Contact 0x to discuss a solution that best suits your use case.

How can I display the 0x Swap Fee to my end users?

The 0x fee amount is returned in the zeroExFee parameter in the quotes where we charge the fee. You are responsible for ensuring your end users are aware of such fees, and may return the amount and token to your end users in your app. Read more about the zeroExFee parameter in the `/quote response.

The applicable fee for each plan is detailed in our Pricing Page.

Is there a way to sell assets via Swap API if the exact sellToken amount is not known before the transaction is executed?

Not currently, but we are exploring this feature.

Is there a way to sell assets via Swap API if the exact sellToken amount is not known before the transaction is executed?

Not currently, but we are exploring this feature.

How should the signed the Permit2 EIP-712 (permit2.eip712) message look?

The standard encoding of a signature in Ethereum decomposes the secp256k1 signature into 3 values: r, s, and v. Typically these are ordered as v, r, s, but Permit2 requires that they be ordered as r, s, and v, where

  • r is less than secp256k1n
  • s is less than secp256k1n / 2 + 1, and
  • v is either 0 or 1 to indicate the sign (or equivalently the parity) of the y coordinate. However, the convention on the EVM is that v is actually encoded as 27 + v (i.e. either 27 or 28). Make sure your signature adds 27 to v

Then, all 3 values are packed and encoded as 65 bytes (bytes 0 through 31 represent r, 32 through 63 represent s, and byte 64 represents v).

⛽️ Gasless API​

See here for Gasless API FAQ

💻 0x Dashboard​

Does the 0x Dashboard support having multiple user accounts for our team?

For now we only support one user per team account, but we will add support for multiple users in the coming weeks.

What is an App?

An app is a self-contained unit for each individual application that you’re building. You can set up multiple apps, each with its unique API keys and configurations on the 0x Dashboard.

🌐 Smart Contracts​

Are the smart contracts audited?

Yes, see details on the audits page.

🏗 Building with 0x​

My project would like to integrate 0x. How can I contact the 0x team?

We appreciate your interest in building with our APIs. To get an API key and start building for free, please create an account on the 0x Dashboard. You may also check out all our available plans and contact our team for more custom needs. Our team will review and respond to you.

My project is interested to apply as a liquidity source in 0x ecosystem. How can I contact the 0x team?

Thank you for your interest in providing liquidity to the 0x ecosystem. Please fill out the relevant form below for our team to review and reach out to you.