Documentation

What it does

Bots spam collection offers below fair value, camp the cheapest listing, and cancel and relist every time someone undercuts them. Blocking them on a marketplace doesn't work, because the marketplace isn't the asset. They simply trade elsewhere.

If your collection is ERC721-C, it already ships with the fix: Limit Break's transfer validator includes an account-freezing mode. A frozen account cannot send or receive tokens of that collection, enforced by the contract on every transfer. BotFreeze works out which wallets deserve it, and drives that switch for you through a permission narrow enough that you never hand over control of your collection.

Requirements

AlloPass

opensea.io/collection/allopass

1180 APE floor350 holders555 items

• An ERC721-C collection using Limit Break's CreatorTokenTransferValidator. Not sure? Open a ticket and we'll check it in a minute.
• Ethereum, ApeChain or Robinhood Chain. The validator, Safe and Zodiac contracts deploy to identical addresses on all three.
• The wallet that currently owns the collection, in a browser wallet, plus gas on that chain.
• The collection indexed on OpenSea, since detection reads its order flow.

Setup guide

The setup wizard walks through this in your browser. Around 15 minutes and six or seven signatures. The order matters: nothing is handed over before the thing receiving it has been proven to work.

After setup

Detection starts on its own, using a live marketplace stream plus a periodic full scan. Your dashboard shows:

• Open findings: flagged wallets, their score, and the named signals behind each one. Filter by whether this collection caught them or the swarm brought them in. A wallet holding your tokens sits here and is not frozen while it holds.
• Frozen accounts: split by who decided, so freezes by detection, freezes carried in by the swarm, and freezes you made by hand are three separate lists. Each row carries the signals it rested on and its freeze transaction. Tick several and unfreeze them in one go.
• Unfrozen: wallets that were frozen and have since been released, and who released them: you, an admin, or the system itself when it found one holding tokens. A freeze that was undone stays visible instead of disappearing.
• Search: paste an address or a username and both tables filter to it. This is where a report from a frozen collector starts.
• Case file: click any wallet for what it actually did, which signals fired with their measurements, and its recent order history from OpenSea.
• Manual freeze: for wallets you identify yourself. Balances are checked first, and freezing one that still holds your tokens asks you to confirm.
• Freezer wallet: its gas balance, with a top-up button and a low-balance warning.
• Export: open findings and frozen wallets as CSV.

Your controls

Two switches sit at the top of your dashboard. Both are yours, and neither needs us.

• Auto-freeze. On by default: a wallet that qualifies is frozen the moment it holds nothing. Turn it off and nothing is ever frozen without you. Detection keeps running, findings keep arriving, and each one waits for you to press Freeze. Turning it back on picks up everything that qualified while it was off.
• Swarm. On by default: a wallet that detection froze on another collection we protect arrives here as a finding, and the wallets your collection catches are shared the same way. Freezes made by hand are never shared, because one owner's decision about their own collection is not evidence about anyone else's. Leave the swarm and it stops in both directions, and anything it had already brought in is dropped on the next pass.

How detection works

Wallets are scored on behaviour, not identity. No blocklists, no reputation database. A wallet that stops behaving like a bot stops scoring like one, and a fresh wallet gets no clean slate because there was never a slate.

The two shapes of bot

The loud ones are easy: bursts of offers, one token relisted five times, cancel-and-relist loops. The interesting ones pace themselves under any rate limit, one offer every fourteen minutes, forever, and volume detection never sees them.

But evading a rate limit means running a schedule, and a schedule has a rhythm. People trade in ragged bursts and then sleep; schedulers don't. So regularity and endurance are scored alongside volume, over a rolling window of retained history rather than a single scan. One order every fourteen minutes never fills one page of activity, but across a day it is unmistakable.

Signals

A score needs at least one primary signal, meaning bot mechanics with no ordinary explanation, before it can cross the threshold. Corroborating signals describe patterns a hard-shopping collector also produces; they can support a primary signal but never convict alone.

Exact thresholds are tunable per collection and deliberately not published. Naming them would tell an operator precisely how slowly to run, which is what makes plain rate limits easy to beat.

Guards against false positives

• Offers are scored by instrument. A collection or trait offer covers every matching token at once, so repetition is spray. An item offer names one token, so it's judged on repetition against the same token or on machine scale, never on a short burst across several. Bidding on a few different pieces is shopping.
• A bulk “cancel all” is one click that emits many events at the same instant. Simultaneous cancellations collapse into a single unit of activity, and cancel signals require the cancels to be spread over distinct minutes.
• Every score is explainable: named signals with plain-English detail, visible before anything happens.

How freezing works

A frozen account cannot send or receive tokens of your collection. It is enforced by the token contract on every transfer, so it follows the wallet to every marketplace, aggregator and private transfer. It is not a marketplace ban.

There is one case where waiting does not work, and it is not a rare one. A trading bot that always keeps stock never reaches a zero balance, so the guard that protects collectors shields it forever. Such wallets sit in your findings like any other, with what they hold shown beside them. You can still freeze one from its row: the dashboard checks the balance first and asks you to confirm, because its tokens stay locked until you unfreeze it, which is the cost of the choice and why it is yours.

The rule is enforced in both directions. Every cycle also checks the wallets that are already frozen, and any that turns out to hold tokens is unfrozen and returned to the watchlist, where it is frozen again once it sells out. That matters after a misconfiguration: a wallet frozen while the ruleset was not enforcing anything could have kept buying, and turning enforcement on would otherwise strand everything it had bought.

Freezing is also idempotent: the current frozen set is read before every action, and accounts already in the requested state are skipped without sending a transaction. Unfreezing parks a wallet rather than returning it to the auto-freeze queue, so a deliberate unfreeze is never undone by the next tick.

If we get it wrong

Detection is a judgement about behaviour, and judgements can be wrong. A collector who bulk-lists an inventory, cuts a price four times in ten minutes, or raises a bid after being outbid can look like a machine from the outside. When that happens, this is what you have.

• Read the case first. Click the wallet. You get every signal with the numbers it was measured on, and the wallet's own recent orders from OpenSea: how many collections it traded, how many different tokens and traits, whether it kept returning to the same one, whether a relisted token moved in price. A collector shopping across projects and a bot working one order book do not look alike once the numbers are in front of you.
• Unfreeze is immediate. One row or a whole selection, in a single transaction. The confirmation lists exactly which wallets it will release before it sends anything.
• A released wallet is never re-frozen automatically. Releasing it is a decision, and the system does not overrule it on the next pass. It stays on the dashboard, and only you can freeze it again.
• Nothing is stranded, and it is checked both ways. A wallet holding your tokens is not frozen. If one ends up frozen while holding anyway, every pass finds it and releases it.
• Tell us. A wrong freeze is a bug in the scoring, not bad luck. Open a ticket with the address: several rules have been rewritten off the back of exactly one wallet that should never have been flagged.

Security model

You are pointing automation at your collection's admin rights, so the system is built assuming you don't trust it.

• Your keys stay yours. Every step is signed in your own browser wallet. Nothing is transmitted, held or requested.
• You own the Safe. Its signers are your wallets. We are not among them and cannot add ourselves.
• The freezer key is encrypted with AES-256-GCM, keyed by a secret held in the environment rather than the database. A database dump alone cannot spend it; the environment variable alone cannot either.
• Not a promise, an on-chain constraint. The Roles module rejects any transaction outside its scope. A full compromise of our server yields a freeze button and nothing more.
• Revoke in one action. Disable the module from your Safe and the automation stops immediately, with no cooperation from us.
• Take the key. The dashboard exports the freezer wallet's private key to any Safe owner who signs for it. Nothing is held hostage.

Hardening: raise your Safe to 2-of-2

Setup runs at threshold 1 so the wizard can execute with a single signature. Once freezing is confirmed working, raise it. With two signers, taking your collection requires compromising both wallets.

It costs you nothing operationally. Bot freezing keeps running unchanged, because the freezer acts through the Zodiac module and Safe modules execute without collecting owner signatures. That is exactly why the freeze permission was granted through a module rather than to an owner.

What does need both signatures afterwards: changing your validator policy, writing to your collection contract, and adding or removing signers, which are the actions you'd want two people on. Do those from app.safe.global, since collecting a second signature isn't built into this app yet.

Changing collection settings on OpenSea

OpenSea decides who may edit a collection by reading the contract's owner. After setup that owner is your Safe, so your personal wallet no longer has edit rights on its own. This catches most people out the first time they try to change a banner.

Do this once and routine edits stop involving the Safe: connect the Safe, then add your everyday wallet as a collaborator. Collaborators can edit the banner, logo, description, category and links. Two things stay owner only, so they always need the Safe: creating new items, and changing creator earnings.

Connecting the Safe to OpenSea

A Safe is a contract rather than a keypair, so it signs through EIP-1271 instead of producing an ordinary wallet signature. OpenSea supports this. It is the same mechanism a Safe already uses to approve listings.

1. On OpenSea choose Connect wallet, find WalletConnect, and click the copy icon to copy the pairing code. Copy the text rather than scanning the QR code.
2. Open your Safe at app.safe.global on the same network as the collection, and click the WalletConnect button in the header. A dropdown opens with a Paste button that reads the code from your clipboard, so allow clipboard access if the browser asks.
3. Approve the connection. The dapp's icon then appears in the Safe header, which is how you know the session is live.
4. OpenSea will ask for a signature to sign in. Confirm it in the Safe. At threshold 1 it completes straight away.
5. Go to OpenSea Studio, pick your collection, Collection details, Add collaborator, enter your everyday wallet address or ENS name, then Publish changes.

If the sign-in gives you trouble

Two things account for most failures. Check the Safe is on the same network as the collection before pairing, because a chain mismatch breaks the session quietly. And check whether the signature request is sitting in your Safe's queue waiting for confirmation, since the browser tab does not always surface it.

If OpenSea refuses the Safe login altogether, you can transfer collection ownership back to your own wallet, add the collaborator while signed in normally, then transfer ownership to the Safe again. Bear in mind that freezing stops working while the Safe is not the owner, because the validator requires the caller to be the collection's owner, so keep that window short.

Setting it on-chain instead

If your contract exposes a setContractURI function, the collaborator list and the collection artwork can be set from the contract itself under ERC-7572, with no OpenSea sign-in at all. The metadata JSON accepts name, description, image, banner_image, featured_image, external_link and collaborators. Check for the function on your collection's Contract page, which routes the call through the Safe for you.

ERC-7572 also asks the contract to emit ContractURIUpdated() whenever contractURI() changes. That event is the signal marketplaces watch to re-read the metadata, so a contract that updates the URI without emitting it can leave OpenSea showing the old values indefinitely.

Troubleshooting

FAQ