First Ledger NFT
CreateChecking whether you are signed in

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 /setup create 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 take send 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

Anyone

Sends 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

Anyone

Lists your linked wallets, each linking to its page on First Ledger.

/refresh

Anyone

Reloads 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

Anyone

Lists this server’s holder roles and what each needs, ticking the ones you have.

/floor

Anyone

Posts 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

Anyone

Posts a collection’s stats: floor, best offer, listed, holders, volume, sales, royalty and whether it is verified.

collectionrequired
The collection.

/nft

Anyone

Posts an NFT’s card: image, owner, rarity rank, price if listed, royalty, flags and traits.

idrequired
The NFT’s NFTokenID, 64 characters long.

/portfolio

Anyone

Shows your NFTs across your linked wallets, grouped by collection.

/alerts add

Anyone

Turns 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.

kindrequired
offer_received offers on your NFTs, suspicious_offer a warning when an offer looks like a scam, collection_sale sales in a collection, or listing_below listings 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

Anyone

Turns an alert off.

kindrequired
offer_received offers on your NFTs, suspicious_offer a warning when an offer looks like a scam, collection_sale sales in a collection, or listing_below listings under a price.
collection
Needed for sales and listing alerts.

/alerts list

Anyone

Lists your alerts.

/privacy allow

Anyone

Lets a partner app look up your linked wallets.

partnerrequired
The partner app’s name.

/privacy revoke

Anyone

Stops sharing with a partner app.

partnerrequired
The partner app’s name.

/privacy status

Anyone

Lists the partner apps you share with.

/unlink

Anyone

Removes your link, and the roles the bot gave you, in every server you share with it.

/help

Anyone

Shows whether you are linked, and a short guide to these commands.

Setting up

/setup

Manage Server

Posts 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 Server

Checks 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 Server

Tracks 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 Server

Stops tracking a collection.

collectionrequired
The collection.

/admin collection list

Manage Server

Lists the collections this server tracks.

Holder roles

/admin role set

Manage Server

Gives 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.
trait
Type:Value, such as Background: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 Server

Gives 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.
kindrequired
xrp, token for a token issued on the XRP Ledger, mpt for a multi-purpose token, or lp for 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 as RLUSD.
issuance-id
For mpt: the 48-character issuance id.
pool
For lp: the AMM pool’s account address.

/admin role set-json

Manage Server

Gives 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 Server

Deletes 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 Server

Lists every role rule in words, and whether it is on.

Feeds and server tools

/admin feed add

Manage Server

Posts 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_expired and uri_modified. Defaults to sale.
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.
layout
full or compact.

/admin feed layout

Manage Server

Switches a feed between the full and compact layout.

channelrequired
The channel.
layoutrequired
full or compact.

/admin feed remove

Manage Server

Deletes a channel’s feed.

channelrequired
The channel.

/admin feed list

Manage Server

Lists your feeds, what each posts, and whether it is on.

/admin stat add

Manage Server

Creates 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.

kindrequired
floor, holders, volume for the day’s volume, listed, or role for 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 Server

Stops updating a stat channel. The channel itself stays.

channelrequired
The channel.

/admin snapshot take

Manage Server

Sends 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 Server

Lists recent snapshots.

/admin audit

Manage Server

Shows the last 25 role and rule changes, and why each happened.

user
Only this member’s changes.

/admin reconcile

Manage Server

Re-checks every linked member now. The changes appear in /admin audit.

Allowlists, polls, raffles and events

/allowlist create

Manage Server

Posts 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 Server

Closes an allowlist now.

namerequired
Its name, up to 60 characters, different from the server’s other allowlists.

/allowlist export

Manage Server

Sends 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 Server

Lists the server’s allowlists, with their entries and when they close.

/poll create

Manage Server

Posts 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).
weighting
member one vote or entry each, or nft one 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 Server

Closes a poll now and posts the results.

idrequired
The id in the post’s footer.

/raffle create

Manage Server

Posts 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).
weighting
member one vote or entry each, or nft one 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 Server

Closes 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 Server

Posts 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 as 2026-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 Server

Cancels an event and updates its post.

idrequired
The id in the post’s footer.

/event attendees

Manage Server

Lists 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.

  • holds with collection, min and an optional max: holds that many NFTs from the collection.
  • holds_trait with collection, traits (1 to 12, each written Type:Value) and min: holds that many NFTs with any of the traits.
  • holds_any_verified with min: holds that many NFTs from verified collections, whichever they are.
  • holds_non_transferable with collection and min: holds that many of the collection’s soulbound NFTs, the ones that can’t be sold.
  • held_for with collection, days (1 to 3,650) and min: has held that many for at least that many days.
  • rarity_rank with collection and max_rank: holds an NFT ranked that rare or rarer.
  • listed_ratio with collection and max, a fraction from zero to one: has listed no more than that share of their NFTs. False for someone holding none.
  • top_holders with collection and n (1 to 1,000): is one of the collection’s top holders.
  • is_creator with collection: one of their wallets created or issued the collection.
  • royalty_compliant with collection: every NFT they hold from it was minted or bought in a sale that paid the royalty.
  • xrp_balance with min: holds at least that much XRP.
  • token_balance with issuer, currency (a code such as RLUSD, or its 40-character hex form) and min: holds at least that much of the token.
  • mpt_balance with issuance_id (48 hex characters) and min: holds at least that much of the multi-purpose token.
  • amm_lp_balance with amm_account and min: holds at least that many of the pool’s liquidity tokens.
  • wallet_in with addresses (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.

The Discord bot · First Ledger NFT