← Orb

Build an app for Orb

An Orb app (some people say “bot”) is a program you write that lives in the communities that chose to install it. It posts, reads, answers commands members type, joins voice and drives the room’s player — through one HTTP API, with its own token. It is not a person: no wallet, no session, no signing key.

Two gates open every call

Scopes — yours

What the app is written to do: read messages, post, join voice, drive the player, check a member’s anchored proof.

Role — the community’s

What an admin accepted when they installed it: a role of its own with exactly the rights those scopes need, optionally in a few channels only.

An app can do only what both allow. You cannot give yourself a right in someone else’s community, and an admin cannot make an app do what it never asked for.

messages:readmessages:writevoicemusicpassport

Five minutes to a working bot

  1. In a community you manage, open Settings → Apps → Register an application. Name it, pick its scopes. The token is shown once: copy it into ORB_BOT_TOKEN.
  2. Install it in the same panel. Orb creates the app’s role with exactly the rights it needs.
  3. Call the API with the token:
export ORB_URL=https://your-orb.example
export ORB_BOT_TOKEN=orbbot_...

# Who am I, and where was I accepted?
curl -s "$ORB_URL/api/bot/v1/app" -H "authorization: Bearer $ORB_BOT_TOKEN"

# Say hello in a channel the app can use
curl -s "$ORB_URL/api/bot/v1/messages" -X POST \
  -H "authorization: Bearer $ORB_BOT_TOKEN" -H "content-type: application/json" \
  -d '{"channel":"CHANNEL_ID","content":"Hello from my first Orb bot"}'

Then listen. With the SDK (Node 18+, no dependencies) a bot that answers a command is this long:

import { OrbBot } from './orb-bot/index.mjs';

const bot = new OrbBot();            // reads ORB_BOT_TOKEN and ORB_URL

await bot.commands.sync([{ name: 'ping', description: 'Is the bot alive?' }]);
await bot.run({ commands: { ping: ctx => ctx.reply('pong') } });

Full guideAPI reference (OpenAPI)JavaScript SDKSDK readmeRunnable examplesThe registry on Monad

Commands, the API and this guide are in English; what your app says to members is up to you.

The Orb Bot Registry (Monad testnet)

Optional, and nothing needs it to run a bot. You can put your app on a public registry from your own wallet: its name, what it asks for, a hash of its manifest and an optional price. A community that installs a priced app pays once, in the test token: 95% goes straight to you and 5% to Orb, both fixed in the contract and shown before anyone signs. The contract cannot pause, upgrade or take back an app. Testnet only: ORB here has no value.

Contract
0x4dc0f7105D872273492f8Ac486e78e7A28Ed3d54
Fee on a paid install
5%
Apps registered
0
Fees waiting for Orb
0 ORB

Apps people have listed

Nothing is listed yet. Yours can be the first: choose “Anyone, in the directory” when you register it.