The Discord bot
The First Ledger bot gives your Discord members roles for the NFTs and tokens they hold, posts your collection’s sales as they happen, and runs allowlists, polls and raffles — for any collection on the XRP Ledger.
What it does
Holder roles: a member links their wallets once, and the bot gives and takes away roles as they buy and sell, usually within seconds of the sale.
Feeds: sales, listings, mints and offers for your collections, posted to the channels you choose.
Tools for your server: live floor and holder counts in channel names, holder snapshots, an audit log, and a web dashboard for admins.
Community: allowlists, holder polls, raffles, events and personal alerts.
It’s free: every feature, for every server and every collection.
Adding it to your server
Open the bot’s page on First Ledger and choose Add to Discord. You need the Manage Server permission in the server you add it to.
Discord then shows the six permissions the bot asks for. Leave them all ticked: each one is used.
- Manage Roles gives and takes away holder roles. Without it, no roles are handed out.
- Manage Channels lets
/setupcreate the #verify channel, and keeps the live floor and holder counts in channel names up to date. - View Channels lets the bot see the channels it posts in.
- Send Messages posts feeds, the verification panel, polls, raffles and events.
- Embed Links shows each sale and listing as a card with the NFT’s image and price.
- Attach Files lets
/admin snapshot takesend its holder list as a CSV file.
It never asks for Administrator, Manage Server, or the power to kick or ban anyone. The bot’s own role needs nothing beyond these six, so leave everything else off.
In Server Settings → Roles, drag the bot’s role above every role you want it to hand out. Discord only lets a bot give roles below its own.
Run /check-permissions. Every line should be a green tick; each red one says what to fix.
Add your collection with /admin collection add. Start typing its name and pick it from the list.
Create a holder role with /admin role set: pick the role, the collection and, if you want tiers, a minimum and maximum. You can also require a trait, or that the NFT has been held for some number of days.
Post the verification panel with /setup. It creates a #verify channel, or uses the one you name, with a Verify button members click.
Everything here can also be done in the dashboard, which signs you in with Discord and lists the servers you manage.
Holder roles
By count: hold at least a number of NFTs from a collection, and optionally at most a number, so you can have Holder, Collector and Whale tiers.
By trait: hold an NFT with a given trait, such as Background: Gold.
By rarity or rank: hold an NFT ranked within the top N of the collection, or be one of its top N holders.
Creator: the collection’s creator or issuer wallet.
By balance: hold an amount of XRP, of a token issued on the XRP Ledger (including tokens launched on First Ledger), or of a multi-purpose token. Set these up with /admin role token: pick the role, what to check and the minimum, and the bot adds up the balance across a member’s linked wallets.
By wallet: a list of addresses you paste.
Combined: any of these joined with AND, OR and NOT, in the dashboard’s advanced editor — for example, holds three or more AND holds a hundred XRP.
Every wallet on a member’s First Ledger account counts together, so moving an NFT between their own wallets never costs them a role.
Roles based on NFTs update within seconds of a sale. Roles based on balances update on the hourly re-check, or straight away when the member runs /refresh.
Roles only the XRP Ledger makes possible
Listed NFTs still count. On the XRP Ledger an NFT you list for sale stays in your wallet until someone buys it, so listing never costs a member their role. If you want to reward holders who do not list, there is a rule for the share of their NFTs listed.
Held for: an NFT held for at least a number of days. It works like staking, with nothing locked away.
Membership passes: an NFT minted without the transferable flag can only go back to its creator, so it cannot be sold. A pass like that makes a member role that cannot be bought.
Liquidity providers: hold the liquidity-pool tokens of an AMM pool, such as a pool for your project’s token. This is also set up with /admin role token.
Royalty-paying holders: every NFT in the collection was bought by mint or in a sale that paid the creator’s royalty, rather than handed over for nothing.
Feeds and server tools
Start a feed with /admin feed add: choose the channel, which kinds of activity to post (sales, listings, mints, transfers, burns, offers), a minimum price, and a full or compact layout. Several purchases by one buyer in the same ledger are posted together as a sweep.
Prices are shown in the currency the sale was made in, with an XRP value beside it when one is known.
Create a stat channel with /admin stat add: a channel whose name shows the floor, holders, listed count, the day’s volume or the number of members with a role, refreshed every ten minutes.
Take a snapshot with /admin snapshot take: every holder of a collection as a spreadsheet. With Discord ids turned on, only members of your own server are named.
See every role the bot gave or removed, and why, with /admin audit.
Allowlists, polls, raffles and events
/allowlist create posts a Join button. Members who meet the requirement join with their linked wallet; export the list as a spreadsheet when it closes.
/poll create posts a poll. Votes can count one per member, or one per NFT held.
/raffle create posts an Enter button. Winners are drawn from the hash of an XRP Ledger ledger that closed after entries closed, and the announcement shows it, so anyone can check the draw was fair.
/event create posts an event members can RSVP to, optionally only holders and with a capacity.
Members can turn on DM alerts with /alerts: offers on their NFTs, a warning when an offer looks like a scam, sales in a collection, or listings below a price.
For members: verifying
Click Verify in the server, or run /verify. The bot replies with a link only you can see.
The link opens First Ledger. Sign in with your wallet as usual and choose Continue.
Discord asks you to confirm your account. Confirm it, and your roles appear within a few seconds.
Added a wallet to your First Ledger account since? Run /verify again, then /refresh.
Never finish a verification someone else sent you. Each link belongs to the person who ran the command, and only works for them.
Every command
Admin commands need the Manage Server permission, and Discord shows them only to people who have it. Most replies are visible only to you; /floor, /collection and /nft post in the channel for everyone. Start typing a collection’s name in any collection option and pick it from the list: your server’s collections come first, then the marketplace’s.
For everyone
/verify
AnyoneSends you a link, visible only to you, to link the wallets on your First Ledger account. The link is yours alone and lasts ten minutes. You never sign a transaction.
/wallets
AnyoneLists your linked wallets, each linking to its page on First Ledger.
/refresh
AnyoneReloads your wallets from First Ledger and re-checks your roles straight away. Use it after adding a wallet, or when a balance role hasn’t caught up.
/roles
AnyoneLists this server’s holder roles and what each needs, ticking the ones you have.
/floor
AnyonePosts the floor price, its change over the last day and the number listed, for one collection or up to 15 of the server’s.
collection- One collection. Leave it out for all of the server’s.
/collection
AnyonePosts a collection’s stats: floor, best offer, listed, holders, volume, sales, royalty and whether it is verified.
collectionrequired- The collection.
/nft
AnyonePosts an NFT’s card: image, owner, rarity rank, price if listed, royalty, flags and traits.
idrequired- The NFT’s
NFTokenID, 64 characters long.
/portfolio
AnyoneShows your NFTs across your linked wallets, grouped by collection.
/alerts add
AnyoneTurns on a DM alert. Adding the same kind for the same collection again replaces its price. Keep DMs from server members open, or the bot can’t reach you.
kindrequiredoffer_receivedoffers on your NFTs,suspicious_offera warning when an offer looks like a scam,collection_salesales in a collection, orlisting_belowlistings under a price.collection- Needed for sales and listing alerts.
price- In XRP: the smallest sale to tell you about, or for listings, the highest price.
/alerts remove
AnyoneTurns an alert off.
kindrequiredoffer_receivedoffers on your NFTs,suspicious_offera warning when an offer looks like a scam,collection_salesales in a collection, orlisting_belowlistings under a price.collection- Needed for sales and listing alerts.
/alerts list
AnyoneLists your alerts.
/privacy allow
AnyoneLets a partner app look up your linked wallets.
partnerrequired- The partner app’s name.
/privacy revoke
AnyoneStops sharing with a partner app.
partnerrequired- The partner app’s name.
/privacy status
AnyoneLists the partner apps you share with.
/unlink
AnyoneRemoves your link, and the roles the bot gave you, in every server you share with it.
/help
AnyoneShows whether you are linked, and a short guide to these commands.
Setting up
/setup
Manage ServerPosts the Verify panel members click to link their wallets, and remembers its channel. Without a channel, it creates #verify.
channel- Where to post the panel. Leave it out and the bot creates #verify, which needs Manage Channels.
/check-permissions
Manage ServerChecks every permission the bot needs, every role rule (the role still exists, and sits below the bot’s role) and every feed channel, with a tick or a cross and what to fix. It warns if the bot was given Administrator, which it doesn’t need.
/admin collection add
Manage ServerTracks a collection, so its activity can reach your feeds and its holders your roles. It warns if the marketplace has flagged the collection.
collectionrequired- The collection.
/admin collection remove
Manage ServerStops tracking a collection.
collectionrequired- The collection.
/admin collection list
Manage ServerLists the collections this server tracks.
Holder roles
/admin role set
Manage ServerGives a role to members who hold enough of a collection. Setting it again on the same role replaces the rule. Linked members are re-checked straight away.
rolerequired- A plain role below the bot’s own. The bot refuses @everyone, roles managed by another app, and any role with admin or moderation permissions.
collectionrequired- The collection.
min- The fewest NFTs to hold, 1 to 100,000. Defaults to 1.
max- The most, for tiers such as Holder, Collector and Whale.
traitType:Value, such asBackground:Gold. Separate several with|and any one counts.held-days- Also require one NFT held for at least this many days, 1 to 3,650.
/admin role token
Manage ServerGives a role by balance, added up across a member’s linked wallets: XRP, a token issued on the XRP Ledger, a multi-purpose token, or an AMM pool’s liquidity tokens. Balances are re-checked every hour, or when a member runs /refresh.
rolerequired- A plain role below the bot’s own. The bot refuses @everyone, roles managed by another app, and any role with admin or moderation permissions.
kindrequiredxrp,tokenfor a token issued on the XRP Ledger,mptfor a multi-purpose token, orlpfor an AMM pool’s liquidity tokens.minrequired- The smallest balance, above zero.
issuer- For
token: the issuer’s address. currency- For
token: its code, such asRLUSD. issuance-id- For
mpt: the 48-character issuance id. pool- For
lp: the AMM pool’s account address.
/admin role set-json
Manage ServerGives a role by a rule written in JSON, combining any of the conditions below.
rolerequired- A plain role below the bot’s own. The bot refuses @everyone, roles managed by another app, and any role with admin or moderation permissions.
rulerequired- The rule, up to 6,000 characters.
/admin role remove
Manage ServerDeletes a role’s rule, and removes the role from the members the bot gave it to.
rolerequired- A plain role below the bot’s own. The bot refuses @everyone, roles managed by another app, and any role with admin or moderation permissions.
/admin role list
Manage ServerLists every role rule in words, and whether it is on.
Feeds and server tools
/admin feed add
Manage ServerPosts activity to a channel. The bot sends a test message first, so you know it can post there. Adding a feed to a channel that has one updates it.
channelrequired- A text or announcement channel.
kinds- Comma-separated, from
sale,list,delist,mint,transfer,burn,buy_offer_created,buy_offer_cancelled,offer_expiredanduri_modified. Defaults tosale. collection- One collection. Leave it out for all of the server’s.
min-price- Skip anything below this many XRP. Activity with no price, such as a transfer, is skipped too.
layoutfullorcompact.
/admin feed layout
Manage ServerSwitches a feed between the full and compact layout.
channelrequired- The channel.
layoutrequiredfullorcompact.
/admin feed remove
Manage ServerDeletes a channel’s feed.
channelrequired- The channel.
/admin feed list
Manage ServerLists your feeds, what each posts, and whether it is on.
/admin stat add
Manage ServerCreates a locked voice channel whose name shows a live number, such as the floor price. It updates when the number changes, at most every 10 minutes.
kindrequiredfloor,holders,volumefor the day’s volume,listed, orrolefor the number of members with a role.collection- Needed for every kind but
role. role- Needed for
role. template- The channel’s name, 3 to 90 characters, with at least one of
{floor} {holders} {listed} {supply} {volume24h} {sales24h} {bid} {count}.
/admin stat remove
Manage ServerStops updating a stat channel. The channel itself stays.
channelrequired- The channel.
/admin snapshot take
Manage ServerSends you every holder of a collection as a CSV file: address, username, how many they hold and their share.
collectionrequired- The collection.
min- Only holders of at least this many.
with-discord- Add a Discord id column. Only linked members of this server are named.
/admin snapshot list
Manage ServerLists recent snapshots.
/admin audit
Manage ServerShows the last 25 role and rule changes, and why each happened.
user- Only this member’s changes.
/admin reconcile
Manage ServerRe-checks every linked member now. The changes appear in /admin audit.
Allowlists, polls, raffles and events
/allowlist create
Manage ServerPosts an allowlist with a Join button. A member who qualifies joins with their first linked wallet.
namerequired- Its name, up to 60 characters, different from the server’s other allowlists.
max-entries- The most who can join.
closes-in-hours- Close after this many hours, up to 2,160 (90 days).
eligibility-collection- Only holders of this collection can take part. Leave it out for anyone with a linked wallet.
eligibility-min- How many they must hold. Defaults to 1.
rule-json- Or any rule in JSON, as for
/admin role set-json.
/allowlist close
Manage ServerCloses an allowlist now.
namerequired- Its name, up to 60 characters, different from the server’s other allowlists.
/allowlist export
Manage ServerSends you an allowlist’s entries as a CSV file.
namerequired- Its name, up to 60 characters, different from the server’s other allowlists.
/allowlist list
Manage ServerLists the server’s allowlists, with their entries and when they close.
/poll create
Manage ServerPosts a poll with a button per option. Members can change their vote until it closes.
questionrequired- Up to 200 characters.
optionsrequired- 2 to 10 choices separated by
|, each up to 80 characters. duration-hoursrequired- How long it runs, in hours, up to 2,160 (90 days).
weightingmemberone vote or entry each, ornftone per NFT held.weight-collection- Which collection to count, for
nft. eligibility-collection- Only holders of this collection can take part. Leave it out for anyone with a linked wallet.
eligibility-min- How many they must hold. Defaults to 1.
/poll close
Manage ServerCloses a poll now and posts the results.
idrequired- The id in the post’s footer.
/raffle create
Manage ServerPosts a raffle with an Enter button.
prizerequired- Up to 200 characters.
winnersrequired- 1 to 100.
duration-hoursrequired- How long it runs, in hours, up to 2,160 (90 days).
weightingmemberone vote or entry each, ornftone per NFT held.weight-collection- Which collection to count, for
nft. eligibility-collection- Only holders of this collection can take part. Leave it out for anyone with a linked wallet.
eligibility-min- How many they must hold. Defaults to 1.
/raffle draw
Manage ServerCloses entries and draws the winners now. The draw is seeded from the hash of a validated ledger, and the announcement shows it, so anyone can recompute it.
idrequired- The id in the post’s footer.
/event create
Manage ServerPosts an event members can RSVP to, until it starts or fills up.
titlerequired- Up to 100 characters.
startsrequired- Hours from now, such as
48, or a date and time with a time zone, such as2026-12-01T18:00Z. Within 90 days. description- Up to 1,000 characters.
location- Up to 200 characters.
capacity- The most who can RSVP.
eligibility-collection- Only holders of this collection can take part. Leave it out for anyone with a linked wallet.
eligibility-min- How many they must hold. Defaults to 1.
/event cancel
Manage ServerCancels an event and updates its post.
idrequired- The id in the post’s footer.
/event attendees
Manage ServerLists who is going.
idrequired- The id in the post’s footer.
Advanced: rules in JSON
/admin role set-json takes a rule written in JSON, for anything /admin role set and /admin role token can’t build. The dashboard’s advanced editor writes the same rules for you.
Join conditions with and or or, each taking 1 to 20 rules, and reverse one with not. A rule can nest 6 levels deep and hold up to 30 conditions.
Every condition is checked across all of a member’s linked wallets together, and is false for someone with no linked wallet. If the bot can’t check a condition, for example while the ledger can’t be reached, the member keeps the roles they have.
The conditions, by their JSON type. Collections are named by their marketplace slug.
holdswithcollection,minand an optionalmax: holds that many NFTs from the collection.holds_traitwithcollection,traits(1 to 12, each writtenType:Value) andmin: holds that many NFTs with any of the traits.holds_any_verifiedwithmin: holds that many NFTs from verified collections, whichever they are.holds_non_transferablewithcollectionandmin: holds that many of the collection’s soulbound NFTs, the ones that can’t be sold.held_forwithcollection,days(1 to 3,650) andmin: has held that many for at least that many days.rarity_rankwithcollectionandmax_rank: holds an NFT ranked that rare or rarer.listed_ratiowithcollectionandmax, a fraction from zero to one: has listed no more than that share of their NFTs. False for someone holding none.top_holderswithcollectionandn(1 to 1,000): is one of the collection’s top holders.is_creatorwithcollection: one of their wallets created or issued the collection.royalty_compliantwithcollection: every NFT they hold from it was minted or bought in a sale that paid the royalty.xrp_balancewithmin: holds at least that much XRP.token_balancewithissuer,currency(a code such asRLUSD, or its 40-character hex form) andmin: holds at least that much of the token.mpt_balancewithissuance_id(48 hex characters) andmin: holds at least that much of the multi-purpose token.amm_lp_balancewithamm_accountandmin: holds at least that many of the pool’s liquidity tokens.wallet_inwithaddresses(1 to 10,000): one of their wallets is on the list.
Limits
- 25 tracked collections per server.
- 50 role rules per server, one per role.
- 20 feeds per server, one per channel.
- 10 stat channels per server, renamed at most every 10 minutes.
- One holder snapshot per server every 10 minutes, of up to about 100,000 holders.
- 25 alerts per member, and at most 30 alert messages to them an hour.
- Polls take 2 to 10 options; raffles draw 1 to 100 winners; allowlists, polls, raffles and events can run for up to 90 days.
- Each member can use the bot 20 times a minute. Past that it asks them to slow down.
Privacy and safety
Verifying shares the addresses of the wallets on your First Ledger account with the bot. It never sees a key, and you are never asked to sign a transaction. Anyone who asks you to is not this bot.
The bot asks only for the permissions it uses, and never for Administrator. It refuses to hand out a role that carries moderation or admin permissions.
It only removes roles it gave. A role a moderator gave you by hand stays.
Other apps can see your linked wallets only if you allow them by name with /privacy allow, and you can take that back at any time.
/unlink deletes your link and removes the roles the bot gave you in every server.
Troubleshooting
No role after verifying: run /refresh. If it still does not appear, ask an admin to run /check-permissions; the bot’s role is probably below the holder role.
The link says it has expired: each link lasts ten minutes and works once. Run /verify again.
“A different Discord account”: you confirmed with another Discord account than the one that ran the command. Switch accounts in Discord and run /verify again.
A feed went quiet: run /admin feed list. A feed the bot could no longer post to is switched off, and /admin audit says why.
A balance role did not change: those update on the hourly re-check. Run /refresh to check now.