The Operator Allowlist restricts which addresses can transfer your tokens, ensuring royalties are enforced by only allowing transfers through compliant marketplaces like Immutable’s Orderbook.Documentation Index
Fetch the complete documentation index at: https://docs.immutable.com/llms.txt
Use this file to discover all available pages before exploring further.
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
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 Type | Example |
|---|---|
| Contract Address | Seaport settlement contract |
| Bytecode Hash | Smart contract wallet implementations |
| Implementation Address | Proxy contract targets |
Enforcement Flows
Approvals (approve, setApprovalForAll):
| Scenario | Allowed |
|---|---|
| Target is an EOA (user wallet) | ✅ |
| Target has approved bytecode | ✅ |
| Target has approved address | ✅ |
| Unapproved smart contract | ❌ |
transferFrom, safeTransferFrom):
| Scenario | Allowed |
|---|---|
| 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 fromOperatorAllowlistEnforced.sol:
Operator Allowlist Addresses
Get the current address from the Immutable API:| Network | Chain ID | API Endpoint |
|---|---|---|
| Testnet | eip155:13473 | https://api.sandbox.immutable.com/v1/chains → operator_allowlist_address |
| Mainnet | eip155:13371 | https://api.immutable.com/v1/chains → 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:Verify Contract
Verify your contract on Immutable Explorer. See the verification guide.
Link Contract
In Hub, go to Contracts and click Link Contract.
Pre-Approved Operators
The following are already on the Operator Allowlist:- Immutable Orderbook
- Immutable smart contract wallets
- Major ecosystem marketplaces
Interface
TheIOperatorAllowlist interface provides:
Royalties
Configure royalty payments
Deploy Contract
Deploy a compliant contract