Quickstart

Start with the AI builder to turn an idea into a collection, or follow the CLI and TypeScript steps below for direct integration.

AI Agent Path#

Connect the BitBadges MCP builder using Set Up Your AI, then ask:

Hey Claude, create me a 5 ATOM / month subscription.

Your agent gathers the collection details, builds the transaction, checks it, and gives you a browser link to review and sign. Your First Collection walks through this as the first creation flow, including payment terms, 30-day periods, and renewal authorization.

Already have a different idea? Ask for an NFT collection, a payment request, or a backed smart token. Builder skills cover the available starting points. To call this flow from your own application, see Programmatic Agent.

CLI Path#

The following steps install bb, configure an API key, fetch a collection, and prepare your first transaction.

1. Install the CLI#

curl -fsSL https://install.bitbadges.io | sh

The installer detects your OS and architecture and installs two things:

1. bitbadgeschaind, the chain binary, into /usr/local/bin/ with the bb symlink. bb is the entry point for everything on this site.
2. bitbadges-cli, the SDK CLI, through bun or npm (whichever is on your path). It is reachable as bb <command>.

Installer options:

curl -fsSL https://install.bitbadges.io | sh -s -- --version v35              # a specific release
curl -fsSL https://install.bitbadges.io | sh -s -- --install-dir ~/.local/bin  # custom directory
curl -fsSL https://install.bitbadges.io | sh -s -- --no-sudo                   # never use sudo

The --testnet flag installs the testnet binary. Testnet is offline, so use the mainnet default. See Testnet.

SDK CLI only (API access, review tools, docs, no chain binary):

npm install -g bitbadges   # or: bun install -g bitbadges
bitbadges-cli --help       # every `bb <command>` on this site also works as `bitbadges-cli <command>`

Chain binary only, from source (Go 1.24+), or from GitHub Releases:

git clone https://github.com/BitBadges/bitbadgeschain.git
cd bitbadgeschain
make build-mainnet-linux/amd64   # or your platform

Verify:

bb version   # chain binary
bb doctor    # SDK CLI health and API connectivity

2. Set an API Key#

Get a key from the developer portal, then:

bb settings set apiKey "$BITBADGES_API_KEY"   # key from https://bitbadges.io/developer

BITBADGES_API_KEY in the environment also works. Config lives in ~/.bitbadges/config.json. See CLI for every settings key, environment variable, and the resolution order.

3. First Query#

bb api tokens get-collection 1

bb api exposes every BitBadges API route as bb api <group> <route>. bb api --help lists the groups. bb dev docs prints these docs in the terminal.

4. First Transaction#

Build a message, then hand it to your browser wallet to sign. Set SENDER to the BitBadges address controlled by that wallet and RECIPIENT to the intended destination before running the commands. The sender needs at least 1 BADGE for this send plus BADGE for transaction fees. These examples target mainnet and move real funds.

bb build send --from "${SENDER:?Set SENDER to your wallet address}" --to "${RECIPIENT:?Set RECIPIENT to the destination address}" --amount 1 --denom BADGE --mainnet \
  | bb deploy - --browser --expected-address "$SENDER" --mainnet

bb build <type> prints ready-to-sign JSON. bb deploy --browser opens the sign page on bitbadges.io and waits for your wallet (Keplr, MetaMask, and others). Two useful steps in between:

bb build send --from "${SENDER:?Set SENDER to your wallet address}" --to "${RECIPIENT:?Set RECIPIENT to the destination address}" --amount 1 --denom BADGE --mainnet > tx.json
bb check tx.json      # validate and review the transaction
bb simulate tx.json --mainnet   # expected gas and balance changes, nothing broadcast
bb preview tx.json    # shareable bitbadges.io preview URL; add --open to jump to review and sign
bb deploy tx.json --browser --expected-address "$SENDER" --mainnet

For a BitBadges token transfer instead of a bank send, use bb build transfer --yes --collection-id 1 --from "${SENDER:?Set SENDER to your wallet address}" --to "${RECIPIENT:?Set RECIPIENT to the destination address}" --token-ids 1 --amount 1. Builders exist for vaults, subscriptions, bounties, auctions, smart tokens, listings, and more. See Build and Deploy.

TypeScript Path#

npm install bitbadges

Read a collection with BitBadgesAPI. No wallet is needed.

import { BitBadgesAPI, BigIntify } from 'bitbadges';

const api = new BitBadgesAPI({
  convertFunction: BigIntify,
  apiKey: process.env.BITBADGES_API_KEY // get one at bitbadges.io/developer
});

const { collection, metadata } = await api.getCollection('1');
console.log(collection.collectionId, metadata.name);

Sign and broadcast with BitBadgesSigningClient. Server-side, create the adapter from a mnemonic.

import { BitBadgesSigningClient, GenericEvmAdapter, MsgTransferTokens, NETWORK_CONFIGS } from 'bitbadges';

// 1. Adapter from a mnemonic (server-side only)
const adapter = await GenericEvmAdapter.fromMnemonic(
  process.env.MNEMONIC!,
  NETWORK_CONFIGS['mainnet'].evmRpcUrl
);

// 2. Signing client (mainnet is the default network)
const client = new BitBadgesSigningClient({ adapter, network: 'mainnet' });

// 3. Broadcast
const result = await client.signAndBroadcast([
  new MsgTransferTokens({
    creator: client.address,
    collectionId: '1',
    transfers: [
      {
        from: client.address,
        toAddresses: ['bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue'],
        balances: [
          {
            amount: '1',
            tokenIds: [{ start: '1', end: '1' }],
            ownershipTimes: [{ start: '1', end: '18446744073709551615' }] // forever
          }
        ],
        prioritizedApprovals: [],
        onlyCheckPrioritizedCollectionApprovals: false,
        onlyCheckPrioritizedIncomingApprovals: false,
        onlyCheckPrioritizedOutgoingApprovals: false
      }
    ]
  })
]);

if (result.success) console.log('TX Hash:', result.txHash);
else console.error('Failed:', result.error);

In the browser, replace step 1 with a wallet adapter: GenericCosmosAdapter.fromKeplr('bitbadges-1') for Keplr, or GenericEvmAdapter.fromBrowserWallet({ expectedChainId: NETWORK_CONFIGS['mainnet'].evmChainId }) for MetaMask and other EVM wallets. The same user gets a different address on each path, so pick one per app. The React and Next.js quickstart walks through install, connect, query, and sign in under 10 minutes.

No-Code Path#

The Create tab and the developer portal create tokens, claims, and address lists with no integration. Most setup and management happens there. Explore the claim tester and the creation forms first; the interface answers many questions faster than prose.

Networks#

Testnet (bitbadges-2, EVM 50025) is offline. The SDK throws on network: 'testnet'. Mainnet runs as a chaosnet; use low-value assets for experimentation and fund the signer for gas. See Testnet and Network.

Starting with v35, transactions require fees of at least 10ubadge per unit of gas. Fund the signing account with BADGE before broadcasting. With the updated CLI, burner --fee 0 means automatic fee estimation; it does not produce a zero-fee transaction. If you need BADGE, use the faucet when available or ask in the BitBadges Discord.

Resources for AI-Assisted Development#

Next Steps#

• Create a Collection
• Token Standard concepts
• BitBadges API
• CLI