BitBadges Quickstarter for AI Agents

A quickstarter template for AI agents to interact with the BitBadges blockchain. This project provides all the necessary setup, documentation, and tools to get started with BitBadges development.

Overview

BitBadges is an IBC-enabled blockchain built on the Cosmos SDK. This quickstarter includes:

• Proto definitions for blockchain interactions
• SDK setup and configuration
• Chain registry information
• Documentation context for AI agents
• Helper scripts for setup and updates

Prerequisites

• Bun (recommended) or Node.js
• Git

Quick Start

1. Clone this repository

   git clone <repository-url>
   cd bitbadges-quickstarter-ai

2. Install dependencies

   bun install

3. Set up environment variables

   cp .env.example .env
   # Edit .env with your configuration

4. Run the setup script

   bun run setup

   This will:

   • Download latest proto definitions from the SDK
   • Download SDK AI Agent Guide
   • Download Cosmos chain registry (BitBadges chain info)
   • Optionally download full documentation dump (if DOWNLOAD_FULL_DOCS=true in .env)

5. Update dependencies (when needed)

   bun run update

Configuration

Environment Variables

See .env.example for all required environment variables. Key variables include:

• BITBADGES_API_KEY - Your BitBadges API key
• NETWORK - Network to use: mainnet, testnet, or stagenet
• CHAIN_ID - Chain ID (default: bitbadges-1 for mainnet)

Network Configuration

The quickstarter supports multiple networks:

• Mainnet: bitbadges-1
• Testnet: bitbadges-2

API Endpoints

REST APIs

• Mainnet: https://api.bitbadges.io
• Testnet: https://api.bitbadges.io/testnet
• Stagenet: https://api.bitbadges.io/stagenet

On-Chain Endpoints

LCD (Light Client Daemon)

• Mainnet: https://lcd.bitbadges.io
• Testnet: https://lcd-testnet.bitbadges.io
• Port: 1317

RPC

• Mainnet: https://rpc.bitbadges.io
• Testnet: https://rpc-testnet.bitbadges.io
• Port: 26657

OpenAPI Specifications

For full OpenAPI/Swagger specifications (manual export required):

• Off-Chain API: https://bitbadges.stoplight.io/docs/bitbadges → Export (for BitBadges API endpoints)
• On-Chain API: https://lcd.bitbadges.io/ → Swagger UI (for Cosmos SDK LCD endpoints)

Note: The SDK and proto files already provide all necessary type definitions and interfaces. OpenAPI specs are optional for reference only.

Blockchain Information

• Chain ID (Mainnet): bitbadges-1
• Bech32 Prefix: bb
• Explorer: https://explorer.bitbadges.io

Documentation

⚠️ Critical: Token Standard Learning

Before proceeding with any BitBadges development, you MUST understand the Token Standard 100%. This is the foundation of everything in BitBadges.

Essential Reading (in order):

1. Token Standard Overview: Start with the main token standard documentation
2. Learn Section: _docs/bitbadges-docs/token-standard/learn/ (if full docs downloaded)
   • Manager / Permissions
   • Balances
   • Transferability / Approvals
   • Approval Criteria (all sub-sections)
   • Minting and Circulating Supply
   • Auto-Scan vs. Prioritized Approvals
   • And all other learn topics

Why this matters: The token standard defines how badges work, how transfers are approved, how balances are managed, and all core concepts. Without understanding this, you cannot effectively use the SDK or build on BitBadges.

For AI Agents

AI agents should have full context to our documentation. Choose your preferred method:

1. MCP (Model Context Protocol): https://docs.bitbadges.io/~gitbook/mcp
2. Documentation Site: https://docs.bitbadges.io
3. GitHub Repository: https://github.com/trevormil/bitbadges-docs
4. Full Repository (recommended): Downloaded to _docs/bitbadges-docs/ when DOWNLOAD_FULL_DOCS=true

The setup script will download relevant documentation to _docs/ for local reference.

SDK Documentation

• SDK AI Agent Guide: Located in _docs/SDK_AI_AGENT_GUIDE.md (downloaded during setup)
• Proto Definitions: Located in _docs/proto/ (downloaded during setup)
• Metadata Hosting Guide: Located in docs/METADATA_HOSTING.md (included in quickstarter)
• Full Documentation Repository: Located in _docs/bitbadges-docs/ (downloaded if DOWNLOAD_FULL_DOCS=true in .env)
• Token Standard Learn Section: _docs/bitbadges-docs/token-standard/learn/ ⚠️ REQUIRED READING

Metadata Hosting

Like NFTs and other blockchain smart contracts, BitBadges metadata content is hosted externally while URIs are stored on-chain.

Supported Metadata Types:

• Collection metadata (name, image, description)
• Badge/token metadata
• Approval metadata
• Backed paths and aliases

Hosting Options:

• IPFS (recommended): Decentralized, permanent, content-addressed
• Arweave: Pay once, store forever
• Centralized (S3, CDN): Fast but requires maintenance

See docs/METADATA_HOSTING.md for complete documentation on:

• Setting up IPFS hosting
• Uploading metadata with proper schemas
• Best practices for permanence and accessibility
• Implementation examples for collections, badges, and approvals

Note: Custom claims hosting (leaves, challenge details) is not covered. The guide focuses on standard metadata ({ name, image, description, ... }) that is stored externally.

SDK Usage

The bitbadgesjs-sdk provides:

• Helper functions for blockchain interactions
• Proto-generated TypeScript client
• API client utilities
• Chain registry information

Wallet Setup for Programmatic Transactions

For AI agents that need to sign transactions programmatically, you can create a wallet with a hardcoded mnemonic:

// scripts/create-agent-wallet.ts
import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';

async function createAgentWallet() {
    const wallet = await DirectSecp256k1HdWallet.generate(12, { prefix: 'bb' });
    const accounts = await wallet.getAccounts();
    console.log('Address:', accounts[0].address);
    console.log('Mnemonic:', wallet.mnemonic); // Store in .env!
    return { address: accounts[0].address, mnemonic: wallet.mnemonic };
}

Important: Store the mnemonic securely in your .env file (never commit it to git). You can then use the mnemonic to sign transactions:

// Using stored mnemonic
import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';

const wallet = await DirectSecp256k1HdWallet.fromMnemonic(
    process.env.AGENT_MNEMONIC!,
    { prefix: 'bb' }
);

Generate a wallet: Run bun run create-wallet to generate a new wallet and mnemonic.

Transaction Handling

For AI agents that need to create and broadcast transactions:

• Transaction Handling Guide: See docs/TRANSACTION_HANDLING.md for complete documentation on:
  • Generating TxContext for the SDK
  • Simulating transactions to estimate gas
  • Getting account number and sequence
  • Funding with gas denominations
  • Broadcasting transactions
  • Polling for confirmation (transactions are asynchronous)

Key Points:

• Always simulate before broadcasting
• Fetch fresh account info (account number and sequence) before each transaction
• Poll for confirmation - transactions must be included in a block
• Ensure sufficient gas balance before broadcasting

Example: Getting Coins Registry

See config/env.example.ts for a complete configuration example:

import {
    MAINNET_COINS_REGISTRY,
    TESTNET_COINS_REGISTRY,
} from 'bitbadgesjs-sdk';
import { config } from './config/env';

export const getCoinsRegistry = () => {
    return config.network === 'testnet'
        ? TESTNET_COINS_REGISTRY
        : MAINNET_COINS_REGISTRY;
};

Copy config/env.example.ts to config/env.ts and customize as needed.

IBC Support

BitBadges is IBC-enabled and follows typical Cosmos SDK interfaces, tooling, and documentation. For IBC connections, see the chain registry in _docs/chain-registry/bitbadges/_IBC.

ICS20 Denominations

For base ICS20 denominations supported, use the coins registry from the SDK (see example above).

Wallet Integration

Keplr is recommended for frontend wallet integration. The blockchain follows standard Cosmos SDK wallet interfaces.

Project Structure

.
├── _docs/                    # Documentation and reference files (gitignored)
│   ├── proto/               # Proto definitions
│   ├── chain-registry/      # Cosmos chain registry
│   └── SDK_AI_AGENT_GUIDE.md    # SDK AI Agent guide
├── docs/                    # Static documentation (tracked in git)
│   ├── METADATA_HOSTING.md  # Metadata hosting guide
│   └── TRANSACTION_HANDLING.md  # Transaction handling guide
├── config/                   # Configuration files
│   └── env.example.ts       # Example config using SDK
├── scripts/                  # Setup and utility scripts
│   ├── setup.ts             # Main setup script
│   ├── download-proto.ts    # Download proto definitions
│   ├── download-guide.ts    # Download AI Agent Guide
│   └── download-registry.ts # Download chain registry
├── .env.example             # Environment variable template
├── package.json             # Dependencies
├── tsconfig.json            # TypeScript configuration
└── README.md                # This file

Note: The _docs/ folder is gitignored as it contains downloaded files. Run bun run setup to populate it.

Scripts

• bun run setup - Initial setup (downloads all dependencies)
• bun run update - Update all downloaded resources to latest versions
• bun run download:proto - Download proto definitions only
• bun run download:guide - Download SDK AI Agent Guide only
• bun run download:registry - Download chain registry only
• bun run download:full-docs - Download full documentation dump only
• bun run create-wallet - Generate a new wallet mnemonic for programmatic transactions

Development

This project uses:

• Bun for package management and runtime
• TypeScript for type safety
• Script-based setup for easy updates

Resources

• BitBadges SDK: https://github.com/BitBadges/bitbadgesjs
• Cosmos Chain Registry: https://github.com/cosmos/chain-registry
• Cosmos SDK Documentation: https://docs.cosmos.network

Support

For issues and questions:

• Check the documentation at https://docs.bitbadges.io
• Review the SDK AI Agent Guide in _docs/SDK_AI_AGENT_GUIDE.md
• Consult the SDK repository: https://github.com/BitBadges/bitbadgesjs