Troubleshooting 0x API Swaps
Addressing common issues that come up with 0x API swaps.
Here's a quick pre-flight checklist of things that need to be in order for a swap to properly execute.
The taker (whomever is executing the swap transaction) should hold at least the
sellToken. They also should approve the
allowanceTarget(typically the Exchange Proxy) to spend at least the same amount for that token.
The transaction needs to be submitted with enough gas. Due to the nondeterministic nature of the on-chain settlement process, the swap may require more than what an
eth_estimateGasRPC call returns. Adding a 20-50% buffer to the estimated gas is recommended. Any unused gas will be refunded to the transaction submitter.
Swap quotes are based off liquidity available at quote time and the transactions are designed to revert if a change in liquidity causes the price to drop below a chosen threshold. This is more likely to happen as the the delay increases between generating a quote and the transaction being mined. Submitting with a "fast" gas price will typically give your transaction priority with miners so the price has less chance of moving.
The slippage tolerance is determined by the
slippagePercentagequery parameter, and is denominated such that
1 = 100%,
0.01 = 1%(the name is misleading). By default this value is
0.01 = 1%. This is the maximum amount the price is allowed to drift during settlement, which can happen as other transactions interact with on-chain liquidity. The transaction will revert if this threshold is exceeded.
Depending on the network/chain you're using and tokens you're swapping, liquidity may be more shallow or volatile and the default 1% slippage tolerance may be too low. You can experiment with higher
slippagePercentagevalues until the transaction succeeds, but understand that this also exposes your swap to potentially settling at what may no longer be considered a fair price.
Some exotic tokens will take fees when any transfer of the token is performed. This often wreaks havoc on our settlement contracts as they are not aware of this mechanism and wind up attempting to sell less or receiving less than what the quote demands. In some circumstances you can buy these tokens by setting a high enough
slippagePercentageto accommodate the transfer fee, but your mileage may vary.