How to Set a Token Allowance

To allow a third party move your ERC-20 tokens using the 0x API, you need to set a token allowance. For 0x API, this means giving permission to one of two smart contracts — Permit2 or AllowanceHolder — to spend tokens on your behalf.

Which contract to approve depends on the API endpoint you're using:

• /swap/permit2 → Permit2
• /swap/allowance-holder → AllowanceHolder

The wallet address that holds the tokens (called the taker) must approve the contract address returned in issues.allowance.spender, which is included in the /price or /quote API response.

danger

• NEVER set an allowance on the Settler contract. Doing so may result in unintended consequences, including potential loss of tokens or exposure to security risks. The Settler contract does not support or require token allowances for its operation. Setting an allowance on the Settler contract will lead to misuse by other parties.

• ONLY set allowances on Permit2 or AllowanceHolder contracts, as indicated by the API responses.

• The correct allowance target is returned in issues.allowance.spender.

Allowance Target vs. Entry Point

In API v2, the allowance target and the entry point contract serve different roles:

• The allowance target is either Permit2 or AllowanceHolder, depending on the approval method. This address is returned inissues.allowance.spender.

• The entry point contract is where you send the data payload. It is returned under transaction.to and dynamically changes based on the latest Settler deployment (API reference).

Example response from /swap/permit2/quote will return back the contract address if an allowance needs to be set:

"issues": {
  "allowance": {
  "actual": "0",
  "spender": "0x000000000022d473030f116ddee9f6b43ac78ba3"
},

info

No allowance is required for wrapping or unwrapping ETH (e.g., WETH ⇄ ETH). In these cases, allowance will be null.

How to Set a Token Allowance

You can approve allowances programmatically or via UI:

• Using wagmi
• Using viem
• Using Etherscan

Using wagmi

wagmi provides a clean interface for reading and writing allowances:

1. Read current allowance using useReadContract.
2. Simulate and write approval with useSimulateContract and useWriteContract.
3. Wait for transaction confirmation using useWaitForTransactionReceipt.

Here’s a minimal example:

const { data: allowance } = useReadContract({
    address: sellTokenAddress,
    abi: erc20Abi,
    functionName: 'allowance',
    args: [taker, PERMIT2_ADDRESS],
});

const { data } = useSimulateContract({
    address: sellTokenAddress,
    abi: erc20Abi,
    functionName: 'approve',
    args: [PERMIT2_ADDRESS, MAX_ALLOWANCE],
});

const { writeContractAsync } = useWriteContract();
const { data: receipt } = useWaitForTransactionReceipt({
    hash: writeContractResult,
});

info

For a full implementation, see the Swap v2 Demo App and guide.

Using Etherscan

You can manually set allowances via Etherscan:

1. Navigate to the token’s contract page (e.g., WETH).
2. Go to Write Contract > approve
3. Enter:

• _spender: the issues.allowance.spender address from the API.
• _value: the maximum uint256 value (2^256 - 1).

Revoking Allowances

To revoke an allowance, you will need to set the allowance to 0. This can be done programmatically or through a UI such as https://revoke.cash/ .

Common Issues

When setting the token allowance, make sure to provide enough allowance for the buy or sell amount as well as the gas; otherwise, you may receive a 'Gas estimation failed' error.