Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🤖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.

Install

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

This installs the chain binary and SDK CLI. For CLI-based agent workflows (query, review, transact — no TypeScript needed), see CLI for AI Agents.

5-Minute Quickstart (TypeScript)

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

// 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);

Metadata: No Hosting Required

The CLI builders and templates accept --name, --image, and --description (or --name + --description for approvals — no image) and serialize them into the on-chain customData field. The indexer, SDK, and frontend parse customData on read and surface the result as the resolved metadata, so an agent can ship a working collection without an IPFS pin or Pinata account. Pass --uri <pre-hosted-uri> instead if you would rather host the JSON yourself; URI takes priority when both are populated. See Collection Configuration › Inline metadata via customData for the on-chain shape.

--image should be a URL, not bytes. Inline customData lives on-chain — you pay gas per byte and blocks have a hard size cap. Pre-host images on IPFS (or any URL host) and pass the URL to --image. Inline customData is for the metadata wrapper (name, description, link to image), not the image itself. See Cost considerations.

Want zero hosting AND an image? The SDK ships a deterministic SVG placeholder-art generator (import { generatePlaceholderArt } from 'bitbadges') that produces 1-8 KB data:image/svg+xml;base64,... URIs you can drop into --image. Same seed always produces the same art. Trade-off: the SVG bytes still live on-chain — a 1-8 KB SVG costs an extra ~10-80k gas per write versus a hosted-URL image. Cheap convenience for placeholder-y looks; not the right call for image-heavy or high-frequency-update collections. See Optional: deterministic SVG placeholder art.

Integration Paths

The chain binary + CLI install is the canonical entrypoint for everything below — install it first, then layer whichever harness-specific convenience you want on top.

Path
Best For
Install

CLI & Chain Binary (start here)

Terminal agents, shell scripts, any language

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

BitBadges Builder Tools (MCP)

Cursor, Claude Desktop, other MCP clients

npm i -g bitbadges — guide

Claude Code Plugin

Claude Code users — auto-wired MCP + 8 workflow skills (built on top of the CLI)

/plugin marketplace add BitBadges/bitbadges-plugin then /plugin install bitbadges — guide

SDK Signing Client

Full-featured TypeScript bots

npm i bitbadges

Direct HTTP

Lightweight scripts, any language

REST calls to api.bitbadges.io

Agent Spending Authorization

Set daily caps, time windows, and revocation

guide

Quick Setup

See the full 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

Builder Tools Reference

All 50+ builder 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.

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

Further Reading

PreviousCLI for AI AgentsNextClaude Code Plugin

Last updated