🤖AI Agents & Bots

This section is for developers building AI agents, bots, and automated systems that interact with the BitBadges blockchain. Whether you're building an autonomous minting agent, a gating bot, or an AI-powered claim system, you'll find everything you need here.

5-Minute Quickstart

npm install bitbadgesjs-sdk

import { BitBadgesSigningClient, GenericEvmAdapter, MsgTransferTokens, NETWORK_CONFIGS } from 'bitbadgesjs-sdk';

// 1. Create adapter from mnemonic (server-side)
const adapter = await GenericEvmAdapter.fromMnemonic(
  'your twelve word mnemonic phrase here ...',
  NETWORK_CONFIGS['testnet'].evmRpcUrl
);

// 2. Create signing client (testnet)
const client = new BitBadgesSigningClient({
  adapter,
  network: 'testnet'
});

// 3. Get testnet tokens
await fetch('https://api.bitbadges.io/testnet/api/v0/faucet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ address: client.address })
});

// 4. Broadcast your first transaction
const result = await client.signAndBroadcast([
  MsgTransferTokens.create({
    creator: client.address,
    collectionId: '1',
    transfers: [/* ... */]
  })
]);

console.log('TX Hash:', result.txHash);

Integration Paths

Path	Best For	Install
MCP Builder Tools	AI assistants (Claude, Cursor, etc.)	npm i -g bitbadges-builder-mcp
SDK Signing Client	Full-featured bots, server-side agents	npm i bitbadgesjs-sdk
Direct HTTP	Lightweight scripts, any language	REST calls to api.bitbadges.io
Agent Spending Authorization	Set daily caps, time windows, and revocation	guide

MCP Quick Setup

# Claude Code (one command)
claude mcp add bitbadges-builder -- npx -y bitbadges-builder-mcp

# Or install globally
npm install -g bitbadges-builder-mcp

See the full MCP Builder Tools Reference for all 50+ tools (including session-based per-field builders), configuration for Claude Desktop / Cursor, and workflow guides.

Network Configuration

Network	API URL	Node LCD	Cosmos Chain ID	EVM Chain ID	EVM RPC
Mainnet	https://api.bitbadges.io	https://lcd.bitbadges.io	bitbadges-1	50024	https://evm-rpc.bitbadges.io
Testnet	https://api.bitbadges.io/testnet	https://lcd-testnet.bitbadges.io	bitbadges-2	50025	https://evm-rpc-testnet.bitbadges.io
Local	http://localhost:3001	http://localhost:1317	bitbadges-1	90123	http://localhost:8545

Additional endpoints (testnet):

• RPC: https://rpc-testnet.bitbadges.io

• EVM RPC: https://evm-rpc-testnet.bitbadges.io

• WebSocket: wss://rpc-testnet.bitbadges.io/websocket

Section Contents

Page	Description
Testnet Faucet API	Get free testnet BADGE tokens for your bot
MCP Builder Tools Reference	All 50+ MCP tools for AI assistants
WebSocket Events	Subscribe to real-time blockchain events
Bot Examples	Copy-paste examples for common bot patterns
E2E: AI Agent with USDC Vault	Full tutorial: wallet setup, vault rules, withdraw/deposit

BB-402: Token-Gated API Access

BB-402 lets any server gate API access behind on-chain token ownership using the standard HTTP 402 status code. Unlike x402 (Coinbase) which only supports per-request USDC payments, BB-402 uses token ownership as a universal primitive -- a soulbound token costing X USDC is a verifiable on-chain receipt (equivalent to x402), but the same protocol also handles subscriptions, tiered access, reputation, blocklists, and compound conditions with $and/$or logic.

Agent --> Server:  GET /api/data
Server --> Agent:  402 { ownershipRequirements, message }
Agent --> Server:  GET /api/data + X-BB-Proof: { address, chain, message, signature }
Server --> Agent:  200 OK (or 403)

See the full BB-402 guide and quickstart in the Token Standard section, or the complete specification.

Further Reading

• Signing Client Reference - Full signing client documentation

• API Getting Started - REST API reference

• Testnet Mode - Testnet environment details

• BitBadges AI Quickstarter - GitHub template repo

• SDK AI Agent Guide - SDK-specific AI guide