Skip to main content

0x Contracts: Settler, AllowanceHolder & Permit2

A Note about Setting Token Allowances​

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 AllowanceHolder or Permit2 contracts, as indicated by the API responses.

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

Allowance Target vs. Entry Point​

In API v2, allowance management and swap execution are handled by different contracts.

1. Allowance Target Contract​

  • Purpose: The contract where token approvals are set.
  • Which contract: Permit2 (/swap/permit2) or AllowanceHolder (/swap/allowance-holder), depending on the approval method.
  • How to find it: Returned in issues.allowance.spender or allowanceTarget.

2. Entry Point Contract​

  • Purpose: Executes swaps; send the data payload here.
  • Which contract: 0x Settler (/swap/permit2) or AllowanceHolder (/swap/allowance-holder), depending on the approval method.
  • How to find it: Returned in transaction.to.

This separation enhances security by isolating allowance management from swap execution.

0x Settler Contract​

0x v2 is built on 0x Settler, a new set of smart contracts designed to enable the secure and continuous deployment of new features. 0x Settler uses Permit2 and the AllowanceHolder contracts to perform swaps without any passive allowances to the contract.

tip

Learn more about 0x Settler. These contracts have been fully audited with four audits from three separate firms, including Ourovoros, Trail of Bits, OpenZeppelin, and Trail of Bits a second time.

Finding 0x Settler Contracts Addresses​

For v2, we strongly advise against hardcoding any entry point contract addresses. These addresses are dynamic and depend on the current Settler deployment. Below are the recommended and alternative ways to obtain the latest Settler address.

Option 1: Recommended - Use value returned by transaction.to​

  • This is the recommended and most reliable method.

  • The entry point contracts returned in the APIs as transaction.to (see the API reference) will always reflect the current Settler deployment automatically. No manual updates are needed.

Option 2: Check the dashboard​

Option 3: Query the Settler address registry​

  • You can query the on-chain Settler address registry directly to find the latest deployment by running this this code.

  • This is the same trustless data source used by the dashboard above.

Option 4: Advanced - Manually copy-paste addresses (Not Recommended)​

  • This is an advanced and error-prone method. Avoid hardcoding any Settler address in your integration, as addresses can change with new deployments. For accuracy and maintainability, we strongly recommend using Option 1 to always get the latest Settler address automatically.

  • Below is a historical list of Settler addresses (past, current, and predicted next hundred).

  • For a comprehensive list of all Settler addresses, download the list here (.tar.xz file).

  • Each chain includes the following address types:

    • Taker Address (tokenId = 2) — Used by users or smart contracts submitting swaps or trades. This is the address used when the taker (caller or end user) submits the transaction.
    • Metatransaction Address (tokenId = 3) — Used when transactions are relayed or batched—e.g., for Gasless API flows. This is the address used by the meta-tx relayer
    • Ignore (tokenId = 4) - Ignore this address type. Not used for integrations.
tip

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

AllowanceHolder is the default and recommended allowance contract for most integrators. It provides a better UX, lower gas costs, and is designed to minimize common integration pitfalls that can occur with using Permit2.

Key Benefits​

  • ✅ Gas efficiency: Lower approval and execution costs than Permit2.
  • ✅ Safer defaults: Reduces the chance of errors during integration.
  • ✅ Simple UX: Works with standard approval flows without requiring double signatures, unlike Permit2.
  • ✅ Equal Safety: Security guarantees are equivalent to Permit2.

Endpoints​

Who Should Use AllowanceHolder?​

AllowanceHolder is recommended for most integrators, and it is especially well-suited for:

  • Teams aggregating multiple liquidity sources and aiming for a consistent user experience across wallets.
  • Developers upgrading from Swap v1 (similar integration flow).
  • Integration with advanced wallets (multisigs, smart contract wallets)

How AllowanceHolder Works​

The AllowanceHolder contract sits in front of 0x Settler and maintains a one-way trust relationship.

When using the Swap API with AllowanceHolder, the AllowanceHolder contract is the allowance target (spender). It manages approvals while also serving as the entry point contract for executing swaps.

If the taker doesn't have an allowance set to the contract, the AllowanceHolder contract address will be returned in the issues object. For example,

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

AllowanceHolder Addresses​

The AllowanceHolder contract has chain-specific addresses that can be safely hardcoded. Always verify with the official documentation before doing so:

  • Cancun hardfork:
    0x0000000000001fF3684f28c67538d4D072C22734
    (Ethereum Mainnet, Ethereum Sepolia, Polygon, Base, Optimism, Arbitrum, Avalanche, Blast, BNB)
  • Shanghai hardfork:
    0x0000000000005E88410CcDFaDe4a5EfaE4b49562
    (Scroll, Mantle)
  • London hardfork:
    0x000000000000175a8b9bC6d539B3708EEd92EA6c
    (Linea)
tip

Learn more in our AllowanceHolder integration guide and the AllowanceHolder example code.

Permit2 (Advanced Use Only)​

Permit2 was developed by Uniswap, based on work from 0x alumnus Lawrence Forman. It provides a secure and efficient way to manage token approvals across multiple smart contracts. Permit2 is immutable, thoroughly audited, trusted by protocols like Uniswap, and backed by a $3M bug bounty.

Key Benefits​

Permit2 offers flexible approvals with features like time-limited and granular allowances. It can be powerful, but it introduces risks that new integrators must be careful with.

⚠️ Permit2 is for advanced integrators only.

Endpoints​

Who Should Use Permit2?​

Consider Permit2 if:

  • Your app needs time-limited or granular approvals not supported by AllowanceHolder.
  • Your users already have infinite allowances set on Permit2 via another app — no reset is needed.

Note: Each trade requires two user signatures — one for limited approval and one for the trade itself. This is more complex to integrate but allows for features like time-limited approvals.

How Permit2 Works​

Permit2 is made up of two modules:

  • AllowanceTransfer → Manages token approvals with limits on time and value, reducing user friction.
  • SignatureTransfer → Provides single-use approvals that virtually eliminate allowance risk.

When using Swap API with Permit2:

  • The Permit2 contract is the allowance target (spender).
  • The 0x Settler contract is the entry point for executing swaps.

If the taker hasn’t granted an allowance, the Permit2 contract address will be returned in issues.allowance.spender. For example:

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

For more details, see this Permit2 explanation.

Permit2 Address​

Permit2 is deployed to 0x000000000022D473030F116dDEE9F6B43aC78BA3 across all chains. You can hardcode this address in your integration.

tip

Learn more in our Permit2 integration guide and the Permit2 example code.