Troubleshooting Swap API

Swap Requirements

Here's a quick pre-flight checklist of things that need to be in order for a swap to properly execute.

API Issues

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

Sufficient Liquidity

You may receive the INSUFFICIENT_ASSET_LIQUIDITY error if there is not enough of the asset on the network to make the trade. This is common for very long-tail tokens or if you are building on 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.

Balances and Allowances

The taker (the address which holds the sellToken balance and is executing the swap transaction) should hold at least the sellAmount of sellToken. The taker also should approve the issues.allowance.spender (typically the Permit2 contract) to spend at least the same amount for that token.

Gas Limits

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_estimateGas RPC call returns. The quoted response will return transacation.gas which is the estimated limit that should be used to send the transaction to guarntee settlement. Any unused gas will be refunded to the transaction submitter.

Gas Price

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.

Slippage Tolerance

The slippage tolerance is determined by the slippageBps query parameter, whose possible values are [0...10000]. It indicates the maximum acceptable slippage of the buyToken in Bps. If this parameter is set to 0, no slippage will be tolerated. If not provided, the default slippage tolerance is 100Bps (= 1% slippage tolerance).

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 slippageBps values 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.

Generated Signature

Before submitting the quote order to the blockchain, you need to sign the permit2.eip712 object from your quote response. Make sure the generated siganture is formatted properly.

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

More Resources

For the Troubleshooting list, see FAQs & Troubleshooting