The OG alternative to Ballsdex!
That is right, one of the oldest Ballsdex-like bots in existence, created in December 2022 as a legitimate Ballsdex alternative, has returned.
Join our cause at the NDS headquarters!
To install dependencies:
bun installTo build the bot:
bun run buildTo run on dev:
bun run devTo start:
bun run start# Linux
rm -rf dist/ && bun run build
# Windows
Remove-Item dist/ -Recurse -Force
bun run buildThis will recreate the dist directory, up to date with the src directory.
In order to check for any errors and warnings on the codebase, run:
bun run typecheckNationdex uses an embedded PGlite (WASM Postgres) instance via @nationdex/db. No external database container or DATABASE_URL is required. And most importantly, no more Docker!
Nationdex serves an HTTP API through @nationdex/api. The routes are ForgeScript files in src/api_routes/v1/GET (read) and src/api_routes/v1/POST (write). It listens on API_PORT (default 2222), so the examples below use http://localhost:2222.
GET routes return JSON and need no token, except /v1/search_db, which needs one with the inspect.read capability (see below). Query values go in the URL (?id=...).
| Route | Query | Returns |
|---|---|---|
GET /v1/stats |
none | collectibles_caught_global, collectibles_count, registered_users, registered_guilds |
GET /v1/config |
none | The bot config (bot, urls, paths, maintainers, prefix, logChannel, accent) |
GET /v1/collectibles/data |
optional id |
The whole catalog, or just that nation. Unknown id gives 404 and {"error": "Collectible Not Found"} |
GET /v1/user |
id (Discord user ID, required) |
collectiblesData (inventory), auctionData, settings. A player's privacy settings are honoured: a private inventory or profile comes back as {"private": true} unless the request carries a token with inspect.read. Unknown user gives 404 and {"error": "User Not Found"} |
GET /v1/users/:id/auction |
none | The user's auction stats (total, sold, earnings, onSale). A private profile returns {"private": true} unless the request carries a token with inspect.read. Unknown user gives 404 and {"error": "User Not Found"} |
GET /v1/guilds/:id |
none | A server's spawn configuration (guild, status, config_channel, weight, timestamp). Unknown or unjoined guild gives 404 and {"error": "Guild Not Found"} |
GET /v1/cards |
none | The card backgrounds as an array of id, name, file, url and nationsCount (how many nations use it). url is the path of the image, for example /v1/cards/democracy/image |
GET /v1/cards/:id/image |
id from GET /v1/cards |
The card background PNG itself (image/png, cached for an hour), ready for an <img> tag. Unknown id gives 404 and {"error": "Card Not Found"} |
GET /v1/commands/data |
none | The prefix command definitions (src/config/commands.ts) |
GET /v1/slash/data |
none | The slash command definitions (src/config/slash.ts) |
GET /v1/search_db/:variable |
optional id. Needs a token with inspect.read (401 without a token, 403 without the capability) |
The raw database records of a variable, for example /v1/search_db/spawnConfig or /v1/search_db/userCollectibles?id=123. Each record has identifier, name, id, type, value (a JSON string) and guild_id |
curl http://localhost:2222/v1/stats
curl "http://localhost:2222/v1/collectibles/data?id=31"
curl "http://localhost:2222/v1/user?id=525421785001361408"search_db returns raw records (balances, staff grants, the audit log), which is why it needs a token. Send it the same way as for the POST routes below. Keep the API port behind a reverse proxy with HTTPS so tokens are not sent in clear text.
POST routes edit users, nations, cards and the bot settings. Every call needs a token and a JSON body.
- A staff member with a role (see
/access grant) runs/access tokenin the main server. The token is shown once. Up to 3 tokens per person,/access tokenrevokeremoves them. - Send it as
Authorization: Bearer ndx_...withContent-Type: application/json. - The token only identifies you. Each route checks your current capability, so removing someone's role cuts their API access at once.
| Capability | Routes | Default roles |
|---|---|---|
nations.edit |
/v1/nations* (except /card) |
curator |
cards.edit |
/v1/nations/:id/card, /v1/categories*, /v1/cards* |
curator |
users.edit |
/v1/users/:id/* |
support |
guilds.edit |
/v1/guilds/:id/* |
support, moderator |
config.edit |
/v1/config* |
owner only |
inspect.read |
GET /v1/search_db/*, the full GET /v1/user view |
developer |
curl -X POST http://localhost:2222/v1/users/525421785001361408/balance \
-H "Authorization: Bearer ndx_<your token>" \
-H "Content-Type: application/json" \
-d '{"mode": "add", "amount": 500}'Every answer has the same shape, and ok is true only for status 200:
{ "ok": true, "status": 200, "statusText": "OK", "value": { } }
{ "ok": false, "status": 400, "statusText": "Bad Request", "error": "A nation named Atlantis already exists." }| Status | Meaning |
|---|---|
200 |
Done. value may carry a result |
400 |
The input was rejected. error says why and nothing was changed |
401 |
Missing, malformed or revoked token |
403 |
The token's owner does not hold the capability this route needs |
404 |
users routes only: no such Discord user |
413 |
Body too large (64 KB, or 15 MB for the background upload) |
500 |
Unexpected error, nothing was changed |
503 |
The application emojis could not be checked with Discord. Try again in a moment |
Successful calls are written to /access audit as api:<route>. Request bodies are never logged.
| Route | Body keys |
|---|---|
POST /v1/nations |
name text, 1-80 chars, must be unique. class an existing category. emoji_id the name or ID of an existing application emoji, up to 64 chars (400 if it does not exist, 503 if Discord cannot be asked right now; emojis uploaded after startup are found). attack whole number, 0 or more. health whole number, 0 or more. rarity / weight positive number, float or int (spawn weight, default 10). Optional short_name, regime, economy, capacity_name, capacity_description, credits, translations, catch_names / catching_names, global_caught, price, sell_price. wild_card and collection_card are artwork file names that must already exist (see /art below). Answers { "value": { "id": "112" } }. A new nation cannot spawn or be given to players until it has artwork |
POST /v1/nations/:id |
Send any or all fields to change. name (1-80), short_name (up to 48, empty or null clears it), class (existing category, moves category and updates counters), emoji_id (up to 64, skips Discord re-verification if unchanged), credits (up to 120), attack, health (0 or more), rarity / weight (positive number, float or int like 0.8, updates both and recounts owner inventories), regime (background name in assets/cards, .png extension optional), economy (icon filename in assets/icons), price, sell_price (0 or more), global_caught (0 or more), capacity_name (up to 64), capacity_description (up to 600), catch_names and catching_names (array or comma separated text, lowercased, at least one, kept in sync, no clash with other nations), translations (same, empty clears it), wild_card and collection_card (existing artwork filename in assets/spawn_art or assets/window_art, skips check if unchanged). If an id field is present in the payload, it is automatically ignored. At least one valid field is required |
POST /v1/nations/:id/category |
class an existing category. Moves the nation and fixes every counter |
POST /v1/nations/:id/delete |
cascade true also deletes every catch of the nation and recounts the owners. Without it, the call fails while catches exist. Always refused while an auction holds the nation |
POST /v1/nations/:id/art |
Needs cards.edit. kind spawn (the wild artwork shown when it spawns) or window (the collection artwork). data the image, base64 encoded, PNG, JPEG or WebP, up to 10 MB. name the file name without extension (letters, numbers, -, _, up to 60); it is generated from the nation when left out. Answers { "value": { "file": "Atlantis.png" } }. A nation needs spawn artwork to spawn and both kinds before it can be given to a player |
POST /v1/nations/:id/card |
regime card background (file name in assets/cards without .png), economy icon (file name in assets/icons with its extension). Send either or both |
| Route | Body keys |
|---|---|
POST /v1/categories |
name 2-20 chars: lowercase letters, numbers, - or _, starting with a letter. total, total_caught, classes and collectibles are reserved |
POST /v1/categories/:name/delete |
none. Fails while a nation uses the category, and for the last category |
POST /v1/cards/backgrounds |
name 1-40 chars, no ., / or \. data (or image) the PNG, base64 encoded, exactly 1428x2000 pixels, up to 10 MB. Fails if the name already exists |
POST /v1/cards/backgrounds/:name/replace |
Needs cards.edit. data (or image) the new PNG, base64 encoded, exactly 1428x2000 pixels, up to 10 MB. Overwrites the file assets/cards/<name>.png, so every nation and special that uses the background shows the new image at once. 404 when the background does not exist |
POST /v1/cards/backgrounds/:name/delete |
none. Fails while a nation or a special uses it |
POST /v1/cards/:name/edit |
Edits an existing card background or special variant. :name is the card ID or special name. Fields: name (new identifier, 1-40 chars; renames card background file on disk, updates catalog nations using this regime, and updates special entries), image or data (base64 encoded PNG, 1428x2000 pixels, up to 10 MB; replaces card image on disk), optional special properties: emoji, rarity / chance, catch_phrase, credits, display_name, card (background name). At least one valid field is required |
POST /v1/cards/add/regime |
Creates a new regime card background. name 1-40 chars, no ., / or \. image or data base64 encoded PNG, exactly 1428x2000 pixels, up to 10 MB. Fails if the card already exists. Answers { "value": { "id": "name", "file": "name.png" } } |
POST /v1/cards/add/special |
Creates a new special card variant. name 1-40 chars, no ., / or \. Optional image or data (base64 encoded PNG, 1428x2000 pixels, up to 10 MB to upload a new card background image), card (card background name in assets/cards, defaults to name; if no image is uploaded, the background file must already exist), emoji (string/emoji), rarity / chance (number, spawn chance), catch_phrase (text), credits (text), display_name (custom name). Fails if the special already exists. Answers { "value": { "id": "name", "card": "cardName", "file": "cardName.png" } } |
:id is a Discord user ID that must exist.
| Route | Body keys |
|---|---|
POST /v1/users/:id/balance |
mode set, add or remove. amount whole number, up to 12 digits. The result stays between 0 and 999999999999 |
POST /v1/users/:id/settings |
key inventory_privacy or profile_privacy (value public or private), or accept_gifts (value true or false). value one of those values |
POST /v1/users/:id/settings/reset |
none. Back to the defaults |
POST /v1/users/:id/stats |
key catches_total, battles_won, trades_completed or gifts_sent. value whole number, up to 9 digits |
POST /v1/users/:id/auction |
Updates auction stats. Can send direct fields (total, sold, earnings whole numbers up to 12 digits, and/or onSale array of auction IDs), or send key (total, sold, earnings, onSale) and value with optional mode (set, add or remove) |
POST /v1/users/:id/nations/give |
nation a catalog ID. count 1-25 (default 1) |
POST /v1/users/:id/nations/remove |
catch the 7-character catch ID. Fails if the user does not hold it (catches in an active auction are not in their inventory) |
POST /v1/users/:id/nations/edit |
Edits nation instance(s) held by the user. Specify target via catch (7-character ID), catches (array of IDs), or nation (catalog ID to edit all instances of that nation). Editable fields: attack, health (0-999999999), attack_type, health_type (buffed or nerfed), special (variant name, or empty/none to clear), card or regime (background file in assets/cards), nation (new catalog ID to reassign the catch, updates inventory class counts and catalog statistics), timestamp, caught_in (ms). At least one field to change is required |
:id is a Discord guild (server) ID where the bot is a member.
| Route | Body keys |
|---|---|
POST /v1/guilds/:id/edit |
Configures server spawn settings. channel (or config_channel, spawn_channel) Discord channel ID where collectibles spawn (send empty string or null to clear and spawn in the most active channel). status (or enabled) enabled or disabled (boolean true or false also accepted). Optional weight whole number accumulator. At least one field is required |
root is config (the bot config) or keywords (the words the bot uses, such as currency.plural). path is a dotted path like urls.server. Text values are up to 300 chars. Keywords become Discord command and option names, so they must be 1-32 lowercase letters, numbers, - or _. Texts built at startup, like command descriptions, change after a restart.
| Route | Body keys |
|---|---|
POST /v1/config |
root, path of an existing value, value. Checked by path: accent is #rrggbb, prefix is 1-5 chars without spaces, maintainers.* are full http(s) profile links (the key is the name shown in /about, underscores show as spaces; add one with parent maintainers), logChannel is a channel ID or empty, paths.* are relative and cannot contain .., urls.* and *.profile / *.repo must be http(s) URLs, bot.name is 1-32 chars, api.allowedOrigins is a list of origins (see below). Keywords follow the rule above |
POST /v1/config/add |
root, parent the group to add to (empty for the top level), key letters, numbers and _ (up to 32, starting with a letter), value |
POST /v1/config/delete |
root, path of a custom value. Built-in values cannot be deleted |
POST /v1/config/reset |
root, path of a built-in value, back to its default |
Keys in bold are required.
The API sends no CORS headers: browsers on another origin cannot call it. Call it from a server, from curl, or through the admin panel, which is served by the bot itself and talks to the API on the same machine.
Made with great honor and dedication by those who worked for Nationdex.
| Developers | Roles |
|---|---|
| Ariel Aram | Founding Father |
| Aditya | Frontend Developer |
| Ayansh | Backend Developer |
| Staff | Roles |
|---|---|
| Mr. Lore | Staff Member |
| BloxyBlitz | Staff & Code Reviewer |
| HiboMan | Staff & Code Reviewer |
| AhmedTheWarrior | Staff Member |
And Nationdex as a whole was only possible at some point thanks to the help from the following people.
| Honourable Mentions | Roles |
|---|---|
| Luka22r | Former BDFD & Python Head-Dev |
| MetroKitten | Former Developer & Ex-Manager |
| Tape | Former BDFD & FS Developer |
| Econome | Former FS & DJS Developer |
| Gasvo | Former BDFD Expert Developer |
| Emtyapple | Former BDFD Mid-Range Dev |
| Emperor Scorpion | Leader of Scorpceltic Empire |
| Hariri | Original Idealist |
| UG | Former Server Shareholder |
Project Nationdex 2026, our gratitude to everyone who made it possible, our response to everyone who fought for a better community. Wishes, are eternal, and hope, is not lost.
