Docs — Role Key

Start here

What Role Key does.

Role Key is a Discord bot that checks which NFTs your members hold and gives them the matching roles. Members never connect a wallet, sign a message or approve a token. They prove a wallet is theirs with a one-time self-send or a code on a public profile, and Role Key reads the rest from the chain.

You set everything up once on the dashboard (roles, tiers, rule, channels) and send a verify panel to your server. Members just press Verify on the panel; nobody types a command. Role Key then re-checks holdings automatically (every 10 minutes on Pro and Network, every hour on the free plan) to keep roles right.

Demo · Verify panel to roles · 0:20Muted · loops

In short

No wallet prompt, no signature, no approval. Only the wallet owner can move funds out of a wallet, so a self-send of an exact amount is the proof.

Six steps · all on the dashboard

Quick start.

Everything is set up on the rolekey.xyz dashboard. Apart from inviting the bot, there’s nothing to configure inside Discord, and members never run a command.

01
Invite the bot
Add Role Key from the Add to Discord button. It asks for four permissions only: Manage Roles, View Channels, Send Messages and Embed Links.
02
Log in on the dashboard
Open rolekey.xyz/dashboard and log in with Discord. Pick your server from the list.
03
Pick roles, tiers and the rule
Add the collection’s contract and chain, then map thresholds to roles, for example Holder at 1+ and Whale at 10+. Choose Stack or Highest only for tiers (see Role rules).
04
Pick a verify channel
Choose where the panel goes. The dashboard checks that Role Key can view the channel, send messages and embed links there, and that its role sits above the roles it gives. If something’s missing, it tells you exactly what to fix.
05
Send the panel
Press Send panel. Role Key posts the verify panel with a Verify button in that channel.
06
Pick an updates channel
Required. Role Key posts important product updates there, such as new features or changes that affect your setup.

That’s it. Members press Verify on the panel, pick a method, and get their roles once the proof is seen.

In your verify channel · Verify panel

# posted by Role Key when you press Send panel
Verify your Lil Mutants
Holder   1+     Whale   10+

[ Verify ]   [ My roles ]

# members press Verify. no commands to type

No wallet connect · no signature

Verification methods.

Each method proves a member controls a wallet without that wallet ever touching a website. Members pick the one they prefer. Admins can turn a method off for their server.

Self-send

Cost: Gas only
Needs: Wallet app
Chains: All five

Each request gets its own exact amount, like 0.000437 ETH. The member sends that amount from the wallet to the same wallet, in their own wallet app. The funds never leave; only gas is spent. When Role Key sees that exact transfer on-chain, the wallet is linked.

STEP 01RequestMember presses Verify on the panel and picks Self-send.

STEP 02Exact amountRole Key issues a unique amount for this request.

STEP 03Send to selfWallet A → Wallet A, same chain, in the wallet app.

STEP 04LinkedTransfer is seen on-chain. Roles are applied.

Example request · Self-send

# unique to this request: send exactly this amount
amount   0.000437 ETH
from     0x7a3f…c91e   # your wallet
to       0x7a3f…c91e   # the same wallet
chain    Ethereum

Profile code

Cost: Free*
Needs: A public profile
On-chain: Nothing*

Role Key gives the member a one-time code. They place it on a public profile tied to the wallet, such as a marketplace profile bio (OpenSea) or an ENS text record on the name that points to the wallet, then press Check in Discord. Once verified, the code can be removed.

STEP 01Get a codeMember presses Verify, picks a profile code and gets a one-time code.

STEP 02Place itPaste it into the marketplace bio or an ENS text record.

STEP 03CheckPress Check in Discord. Role Key reads the public profile.

* A marketplace bio is free and off-chain. Updating an ENS text record is an on-chain update and costs gas once.

Collections · thresholds · tiers

Role rules.

A rule says: hold this much of this collection, get this role. Add several thresholds to make tiers, then choose how tiers are given:

Stack: members get every tier role up to their highest. 12 tokens gets Holder and Whale.
Highest only: members get just their top tier. 12 tokens gets Whale only.

RoleConditionThreshold

HolderAny token from the collection≥ 1

WhaleTen or more tokens≥ 10

GenesisHolds a token in the ID range#1–100

Multiple chains add up

Link a collection’s contracts across chains and Role Key counts them as one balance. A member with 4 tokens on Ethereum and 6 on Base meets a ≥ 10 rule.

Linked collection · Example

collection  Lil Mutants
  ethereum  0x…   # 4 held
  base      0x…   # 6 held
total       10   # → Holder, Whale

Roles stay accurate

Rechecks & role removal.

Role Key re-checks every verified wallet automatically: every 10 minutes on Pro and Network and every hour on the free plan. Nobody has to press anything again.

Removal: a role comes off only after two failed checks in a row, so a quick transfer between wallets doesn’t cost anyone their role.
Re-adding: when a member holds again, the role comes back on the next check.
Tiers: moving between tiers follows your Stack or Highest-only setting.

Fail-safe

If a chain read fails, nothing is removed. Role Key waits for a clean read before taking any role away, so an RPC outage never strips your holders.

Five networks · two standards

Chains & token standards.

ERC-721 and ERC-1155 are supported on every network below.

Network	Type	Native	ERC-721	ERC-1155
Ethereum	Layer 1	`ETH`	✓ ERC-721	✓ ERC-1155
Base	Layer 2	`ETH`	✓ ERC-721	✓ ERC-1155
ApeChain	Layer 3	`APE`	✓ ERC-721	✓ ERC-1155
Robinhood Chain	Layer 2	`ETH`	✓ ERC-721	✓ ERC-1155
HyperEVM	Hyperliquid L1	`HYPE`	✓ ERC-721	✓ ERC-1155

Four permissions · one rule about order

Bot permissions & role order.

Role Key needs exactly four permissions. It doesn’t need Administrator and doesn’t read message history.

Required permissions · 4 total

✓ Manage Roles     # give and remove holder roles
✓ View Channels    # see your verify channel
✓ Send Messages    # post the verify panel
✓ Embed Links      # show verify cards

Role order

Discord only lets a bot assign roles that sit below its own. Drag the Role Key role above every role in your rules.

Adminyours

Role Keymust be here

Whaleassigned

Holderassigned

Genesisassigned

@everyone

Connect Discord · pick a server

Dashboard.

The dashboard is where you set everything up: roles, tiers and the rule, the verify channel, the panel and the updates channel. Log in with Discord and Role Key asks for two scopes only:

OAuth scopes · Discord

identify   # your Discord ID, username and avatar
guilds     # the list of servers you’re in

It then lists servers where you’re an admin and Role Key is installed. If a server is missing, check that you’re an admin there and that the bot has been added.

For your members

Member FAQ.

Q01

Do I have to connect my wallet?

No. Role Key never asks for a wallet connection, a message signature or a token approval.

Q02

Do I need to type a command?

No. Press Verify on the panel in the verify channel and follow the steps. Everything happens through buttons.

Q03

Does self-send cost me anything?

Only gas. You send the amount from your wallet to the same wallet, so it never leaves.

Q04

Why is the amount so specific?

Each request gets its own exact amount, like 0.000437 ETH. That makes your transfer unique, so Role Key can tell it’s yours.

Q05

Do I verify again in every server?

No. Once a wallet is linked, it counts in every server that uses Role Key. Each server applies its own rules.

Q06

What if I sell?

Role Key re-checks automatically, every 10 minutes on Pro and Network servers and every hour on the free plan. If your wallet no longer qualifies on two checks in a row, the role comes off. Buy back in and it returns on the next check.

Q07

Is my wallet address public?

Wallet addresses and on-chain activity are public by nature, including the self-send transaction. See the Privacy Policy for what Role Key stores.

Fix it fast

Troubleshooting.

T01

Verification passed, but the role wasn’t assigned

Role order / permissions

Move the Role Key role above the role it should assign (Server Settings → Roles).
Confirm the bot still has Manage Roles.
Check the rule points at the right role in the dashboard.

T02

My self-send wasn’t detected

Amount / chain / confirmations

Wrong amount: send the exact amount from your request, not a rounded one. Some wallets round; type all decimals.
Wrong chain: send on the chain shown in your request.
From and to: both must be the wallet you’re verifying.
Confirmations: wait for the transaction to confirm, then check again.

T03

My profile code wasn’t found

Placement

Make sure the profile is public and belongs to the wallet you’re verifying.
Paste the full code with no extra characters, save, then press Check.
For ENS, the text record must be on the name that points to your wallet.

T04

The verify panel didn’t post

Channel permissions

Open the server in the dashboard and pick the verify channel again. It lists any missing permission (View Channel, Send Messages, Embed Links) and how to fix it. Then press Send panel.

T05

A server is missing from my dashboard

Admin + bot

The dashboard only lists servers where you’re an admin and Role Key is installed. Add the bot, or ask the owner for admin.

T06

A role came off unexpectedly

Recheck

The wallet didn’t meet the rule on two checks in a row (10 minutes apart on Pro and Network, an hour apart on the free plan), for example after a transfer. If it holds again, the role returns on the next check. Role Key never removes roles on a failed chain read.

Still stuck? Contact support.

Role Key docs.