Version: 1.0

🤔 FAQ & Troubleshooting

Categories

🧰 Troubleshooting

I received an error code. Help!

See Error codes for a full list of common 0x error codes 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.
Fee-on-transfer tokens may wreak havoc on our contracts. Read here for how to handle this
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.

Read here for best practices when presenting firm quotes.

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 takerAddress help with catching issues?

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

0x API will estimate the gas cost for takerAddress 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 takerAddress executing the quote.

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

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

0x API selects the best 0x protocol interface to interact with based on the provided parameters and the smart order routing logic.

There are two main interfaces that 0x API will provide quotes for:

Exchange contract - the main entry-point of the 0x protocol, all swap quotes are settled by the exchange contract.

Forwarder extension contract - a payable interface allowing swaps between native ETH (as a sellToken) and another ERC20 asset.

Find the currently deployed contracts here.

I received an `INSUFFICIENT_BALANCE` error. Help!

For insufficient balance errors, check the following:

the connected wallet as enough of the funds to cover the trade plus gas for the transaction
the connected wallet has given a token allowance to the 0x Exchange Proxy on the specified chain for the token to be traded

I received an `INSUFFICIENT_ASSET_LIQUIDITY` error. Help!

This error indicates there is not enough of the asset on the network to make this trade. This is common for very long-tail tokens or if you are building in a testnet (e.g. Sepolia). On testnets, only a subset of DEX sources available on Ethereum mainnet are available on testnet, so not all token pairs may be available.

🔄 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 API endpoint /swap/v1/sources to get the liquidity sources per chain. You will need to specify the root-endpoint for the chain you are interested in, for example, https://polygon.api.0x.org/swap/v1/sources for the Polygon Network or https://api.0x.org/swap/v1/sources for Ethereum Mainnet. See the Swap API References Overview for a full list of endpoints we support.

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

0x supports trades for all ERC20 tokens that are aggregated from our aggregated liquidity sources. Note that the Swap API does not support fee-on-transfer tokens.

To see the tokens that 0x supports for trading, you can refer to the CoinGecko tokenlist. This tokenlist provides a list of all available ERC20 tokens that are supported by 0x. You can access the CoinGecko tokenlist at tokenlists.org, specifically the CoinGecko tokenlist for a list of all available ERC20 tokens.

What are the differences when quoting by sellAmount vs by buyAmount?

TLDR Whenever possible, use sellAmount over buyAmount to get more deterministic behavior.

If sellToken is utilized, then any unused sellToken will be refunded to the user.
When buyAmount is used, the only guarantee is that at least the amount specified is bought. 0x API will not terminate early in the case where one order fills at a better price, so the user can in effect go over buy the specified amount. This is somewhat amplified by usage of slippagePercentage which underestimates the on-chain price by a percentage.

Also, some liquidity sources do not enable querying by buyAmount (i.e Kyber), these sources are ignored when quoting for buyAmounts

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. Read our full guide on monetizing your swap integration.

Yes, this can be done by setting the feeRecipient and buyTokenPercentageFee parameters in a Swap API request. Set a buyTokenPercentageFee on your DEX trades which represents the percentage (between 0 - 1.0) of the buyAmount (tokens being received) that should be attributed to feeRecipient (your wallet) as an affiliate fee.

When the transaction has gone through, the fee amount will be sent to the feeRecipient address you've set. The fee is received in the buyToken (the token that the user will receive). If you would like to receive a specific type of token (e.g. USDC), you will need to convert those on your own.

If you would like to display the fee to your end users separately, just display the amount returned by grossBuyAmount * buyTokenPercentageFee.

Details about these parameters can be found in GET /swap/v1/quote.

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?

The fee amount is incorporated as part of the quoted price. Two recommended methods of displaying the fees are:

display the amount returned by grossBuyAmount * buyTokenPercentageFee
display the grossBuyAmount and the buyTokenPercentageFee separately

For examples and details, read our full guide on monetizing your swap integration.

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

Trade surplus occurs when the user ends up receiving more tokens than their quoted amount. 0x API is configurable such that you collect trade surplus on your trades to a specified address.

This can be done by setting the feeRecipientTradeSurplus parameter in a Swap API request. feeRecipientTradeSurplus represents the wallet address you want to collect the fee in. When a transaction produces trade surplus, 100% of it will be collected in that wallet. The fee is received in the buyToken (the token that the user will receive). If you would like to receive a specific type of token (e.g. USDC), you will need to make that conversion on your own.

When feeRecipientTradeSurplus is not specified, the feature is effectively OFF and all trade surplus will be passed back to the user.

Note: Trade surplus is only sent to feeRecipientTradeSurplus for SELLs (when the sellAmount is specified). It is a no-op for BUYs (when the buyAmount is specified), which means the user will always receive the trade surplus.

Details about these parameters can be found in GET /swap/v1/quote.

Read our full guide on monetizing your swap integration.

Working in the Testnet

I'm building on a testnet, but have issues with certain liquidity pairs. Are there certain pairs I should test when building on a testnet?

At the time of writing this guide the following liquidity sources are supported on Sepolia: MultiHop and Uniswap_V3. The token you want to use for testing must have liquidity on at least one of these sources; otherwise, you will receive an error.

In addition, only certain pairs are deployed on testnests and available for testing. At the time of writing, the recommended testing pair is WETH <> UNI deployed by Uniswap on Sepolia.

To view all currently supported sources on each network, you can use the /sources endpoint.

Note the following:

Testnet liquidity is more limited than on mainnet
Liquidity sources are also different between mainnets and testnets
Not all pairs on mainnet are deployed on testnet, so the token pair availability is more limited

See our recommended lists of tokens for Sepolia in the our Working in the Testnet Guide.

Where can I get testnet funds?

List of Sepolia Faucets
Alchemy Sepolia Faucet
Sepolia POW Faucet
Paradigm MultiFaucet - Funds a wallet with ETH, WETH, DAI, and NFTS across 4 testnets
Even more faucets
Also see our Working in Testnet Guide

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 ?

Each blockchain typically has its own native token, for example, ETH on Ethereum, BNB on Binance Smart Chain, and MATIC on Polygon.

Native tokens are not ERC20 tokens so there are no contract addresses to represent them, thus it became common practice in DeFi to use the contract address 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE to represent the native tokens.

For 0x APIs, you can use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE to represent the native token address for either the sellToken or buyToken parameters.

For example, here is selling 100 USDC for ETH on Base:

https://api.0x.org/gasless/price?chainId=8453&sellToken=0x833589fcd6edb6e08f4c7c32d4f71b54bda02913&buyToken=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&sellAmount=100000000

Best Practices

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

Contact 0x for a custom plan that best suits your needs.

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

How do I query what tokens are available to be swapped through the API?

0x supports trades for all ERC20 tokens that are aggregated from our aggregated liquidity sources. Note that the Swap API does not support fee-on-transfer tokens.

To see the tokens that 0x supports for trading, you can refer to the CoinGecko tokenlist. This tokenlist provides a list of all available ERC20 tokens that are supported by 0x. You can access the CoinGecko tokenlist at tokenlist.org, specifically the CoinGecko tokenlist for a list of all available ERC20 tokens.

How do I dispaly 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 feeAmount and feeToken to your end users in your app. 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?

Yes, you can set shouldSellEntireBalance=true when making a Swap /quote request. This will sell the entirety of the caller's takerToken balance. A sellAmount is still required, even if it is a best guess, because it is how a reasonable minimum received amount is determined after slippage.

Here is an example two-step transaction use case:

Withdraw collateral from a lending protocol

the lending protcol is volatile, so the exact amount of collateral withdrawn is not known before the transaction is executed

Swap that collateral into a different asset using Swap API

set shouldSellEntireBalance=true to sell the entire collateral balance

⛽️ Gasless API

Gasless API FAQs found here

💻 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.

🌐 Protocol

What is the protocolFee ?

The community voted to remove protocol fees in ZEIP-91 which removed the the protocol fee, lowering it from the previous value (70,000) to zero (0) for v3 onward, for all order types.

The following is kept for historical reference but no longer applies

TLDR; 0x API handled the heavy lifting related to protocol fees and provides a value field.

A protocol fee was paid by takers and ultimately rebated to market makers when their orders are filled.

Protocol fees were calculated per order using the gas price multiplied by a constant (currently 70,000). 0x API calculated the required protocol fees to be paid and returns this in the value field. Since we recommended using a high gas price, in the event where the taker fills at a lower gas price, the excess was returned.

It was possible for the protocol fees to be paid in WETH rather than sent in the transaction as ETH. This could be achieved by the taker having a WETH balance and setting a WETH allowance to the Protocol fee collector address. This address can be read on the Exchange contract: Exchange.protocolFeeCollector.

Are the smart contracts audited?

Yes, 0x protocol’s contracts are open source and extensively tested by 0x core team’s internal protocol team and by external auditors (Consensys dilligence, Trail of Bits).

The Exchange contract, because they are the main entry point of the 0x protocol, is versioned, and governed by ZRX token holders. Because of its critical place in 0x infrastructure, the 0x core team employs a number of external audits to ensure the safe and intended usage of the 0x contract.

The Forwarder contract is internally audited and constantly improved upon by the 0x core team. Forwarder, an optional extension contract that users can opt in/out of using when swapping, has a minimized attack surface because no approval of user funds is needed.

What is the return of executing the provided calldata? fillResults?

0x protocol returns a FillResults object that returns the result of executing a 0x swap:

struct FillResults {
    uint256 makerAssetFilledAmount;  // Total amount of buyToken filled.
    uint256 takerAssetFilledAmount;  // Total amount of sellToken filled.
    uint256 protocolFeePaid;         // Total amount of protocolFee pair in WETH or ETH
    ...
}

On-chain, easily decode the result of executing the calldata like so:

import "@0x/contracts-exchange-libs/contracts/src/LibFillResults.sol";

...

(bool success, bytes memory data) = address(exchange).call.value(quote.protocolFee)(quote.calldataHex);
require(success, "Swap not filled");
 fillResults = abi.decode(data, (LibFillResults.FillResults));

🏗 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.

If you are looking provide AMM Liquidity
If you are looking to provide RFQ Liquidity

🤔 FAQ & Troubleshooting

🧰 Troubleshooting​

🔄 Swap API​

About Swap API​

Monetizing your Swap Integration​

Working in the Testnet​

Parameter Questions​

Best Practices​

⛽️ Gasless API​

💻 0x Dashboard​

🌐 Protocol​

🏗 Building with 0x​