Skip to main content
The Operator Allowlist restricts which addresses can transfer your tokens, ensuring royalties are enforced by only allowing transfers through compliant marketplaces.

Contracts Repository

View the Operator Allowlist source code

Why It’s Required

The Operator Allowlist protects game studios from:
  • Vampire attacks: Unauthorized marketplaces bypassing royalties
  • Protocol fee evasion: Trading outside Immutable’s ecosystem
  • Revenue loss: Transactions that don’t pay creator royalties
Mandatory Compliance: All ERC-721 and ERC-1155 collections on Immutable Chain must implement the Operator Allowlist.

Non-Compliance Consequences

  • Forfeit any token grants received
  • Passport users see warnings that your collection may be counterfeit
  • Exclusion from ecosystem marketplaces (TokenTrove, GameStop NFT, etc.)

How It Works

The allowlist is a registry of approved operator addresses:
Address TypeExample
Contract AddressSeaport settlement contract
Bytecode HashSmart contract wallet implementations
Implementation AddressProxy contract targets

Enforcement Flows

Approvals (approve, setApprovalForAll):
ScenarioAllowed
Target is an EOA (user wallet)
Target has approved bytecode
Target has approved address
Unapproved smart contract
Transfers (transferFrom, safeTransferFrom):
ScenarioAllowed
Caller is an EOA
Caller is approved marketplace
Unapproved contract

Implementation

Using Preset Contracts

All Immutable preset contracts and contracts deployed via Hub include Operator Allowlist protection by default.

Custom Contracts

For custom contracts, inherit from OperatorAllowlistEnforced.sol:
import "@imtbl/contracts/contracts/allowlist/OperatorAllowlistEnforced.sol";

contract MyNFT is ERC721, OperatorAllowlistEnforced {
    constructor(address allowlist) {
        _setOperatorAllowlistRegistry(allowlist);
    }
    
    function _beforeTokenTransfer(
        address from,
        address to,
        uint256 tokenId
    ) internal override {
        // Check operator allowlist for transfers
        if (from != address(0) && to != address(0)) {
            require(
                _isAllowlisted(msg.sender),
                "Operator not allowlisted"
            );
        }
        super._beforeTokenTransfer(from, to, tokenId);
    }
}

Operator Allowlist Addresses

Get the current address from the Immutable API:
NetworkChain IDAPI Endpoint
Testneteip155:13473https://api.sandbox.immutable.com/v1/chainsoperator_allowlist_address
Mainneteip155:13371https://api.immutable.com/v1/chainsoperator_allowlist_address
# Get testnet address
curl https://api.sandbox.immutable.com/v1/chains | jq '.result[] | select(.name == "imtbl-zkevm-testnet") | .operator_allowlist_address'

# Get mainnet address  
curl https://api.immutable.com/v1/chains | jq '.result[] | select(.name == "imtbl-zkevm-mainnet") | .operator_allowlist_address'
Immutable manages the allowlist with pre-approved addresses including Seaport and smart contract wallet deployments. Use this instead of deploying your own.

Request Allowlist Addition

To add your contract to the Operator Allowlist:
1

Verify Contract

Verify your contract on Immutable Explorer. See the verification guide.
2

Link Contract

In Hub, go to Contracts and click Link Contract.
3

Request OAL Addition

On your contract’s detail page, click Add to OAL and follow the instructions.
4

Wait for Approval

  • Testnet: Typically seconds (automated)
  • Mainnet: Up to one week (manual review)

Pre-Approved Operators

The following are already on the Operator Allowlist:
  • Immutable Seaport
  • Immutable smart contract wallets
  • Major ecosystem marketplaces

Interface

The IOperatorAllowlist interface provides:
interface IOperatorAllowlist {
    /// @notice Check if an address is allowlisted
    /// @param target The address to check
    /// @return bool True if allowlisted
    function isAllowlisted(address target) external view returns (bool);
}