# Builder Tools Reference The [BitBadges Builder](https://github.com/bitbadges/bitbadgesjs/tree/main/packages/bitbadgesjs-sdk/src/builder) provides 50+ tools for AI assistants to build, audit, and validate BitBadges transactions. It works with Claude Desktop, Claude Code, Cursor, and any MCP-compatible client. > **Building from your own code (Node/TypeScript)?** Use the [Programmatic Agent](/for-developers/ai-agents/programmatic-agent.md) — same tools + system prompt + validation loop, BYO Anthropic key, no MCP client required. One-liner: `new BitBadgesBuilderAgent({ anthropicKey }).build('…')`. > For terminal-based workflows without an MCP client, use the [BitBadges CLI](/for-developers/cli.md) — it provides 104+ API routes, review/audit tools, and built-in docs from the command line. See [CLI for AI Agents](/for-developers/cli/for-ai-agents.md). ## Installation ```bash # Install globally npm install -g bitbadges # Or run directly (no install) npx -p bitbadges bitbadges-builder ``` ### Claude Desktop Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "bitbadges-builder": { "command": "npx", "args": ["-y", "-p", "bitbadges", "bitbadges-builder"], "env": { "BITBADGES_API_KEY": "your-api-key", "BITBADGES_MNEMONIC": "your mnemonic phrase" } } } } ``` ### Claude Code After running the standard chain + CLI install (`curl -fsSL https://install.bitbadges.io | sh`), the manual MCP add is: ```bash claude mcp add bitbadges-builder -- npx -y -p bitbadges bitbadges-builder ``` Optionally, install the [Claude Code plugin](/for-developers/ai-agents/claude-code-plugin.md) on top — it auto-wires the same MCP and adds 8 workflow skills plus `/bitbadges:setup` and `/bitbadges:status` slash commands: ``` /plugin marketplace add BitBadges/bitbadges-plugin /plugin install bitbadges ``` The plugin is a convenience layer; the CLI install is what actually powers it. ### Cursor Add to `.cursor/mcp.json`: ```json { "mcpServers": { "bitbadges-builder": { "command": "npx", "args": ["-y", "-p", "bitbadges", "bitbadges-builder"], "env": { "BITBADGES_API_KEY": "your-api-key" } } } } ``` ### Environment Variables | Variable | Required | Description | | ----------------------- | --------------------- | ----------------------------------------------------------------------- | | `BITBADGES_API_KEY` | For queries/broadcast | Your BitBadges API key ([get one here](https://bitbadges.io/developer)) | | `BITBADGES_MNEMONIC` | For signing | Mnemonic for server-side signing (testnet recommended) | | `BITBADGES_PRIVATE_KEY` | For signing | Alternative: hex private key | ## Tools by Category ### Session-Based Per-Field Builders (Recommended) The recommended way to build collections. Each tool sets one field on a session-scoped transaction, allowing incremental construction with full control. All tools can be called in parallel within the same round. | Tool | Description | | ---------------------------- | ------------------------------------------------------------------------------- | | `set_standards` | Set the collection's protocol standards (e.g., "Subscription", "Smart Token") | | `set_valid_token_ids` | Set which token IDs exist in the collection | | `set_default_balances` | Set default balance configuration and user-level auto-approve flags | | `set_permissions` | Set collection permissions (use presets like "locked-approvals" or custom) | | `set_invariants` | Set collection-level invariants (e.g., noCustomOwnershipTimes, maxSupplyPerId) | | `set_manager` | Set the collection manager address | | `set_collection_metadata` | Set collection-level metadata (name, description, image) | | `set_token_metadata` | Set per-token metadata URIs | | `set_custom_data` | Set custom data on the collection | | `add_approval` | Add a collection approval with approvalCriteria | | `remove_approval` | Remove a collection approval by approvalId | | `set_approval_metadata` | Set metadata for a specific approval | | `add_alias_path` | Add an alias path (for ICS20-backed smart tokens) | | `remove_alias_path` | Remove an alias path | | `add_cosmos_wrapper_path` | Add a Cosmos wrapper path | | `remove_cosmos_wrapper_path` | Remove a Cosmos wrapper path | | `set_is_archived` | Set whether the collection is archived | | `set_mint_escrow_coins` | Fund the mint escrow address at creation (for quest rewards, payment overrides) | | `add_transfer` | Append a MsgTransferTokens to the transaction (for auto-minting at creation) | | `remove_transfer` | Remove a transfer message from the transaction | | `get_transaction` | Return the current session transaction as JSON | ### Helper Builders Standalone tools for building specific non-collection resources. | Tool | Description | | --------------------- | -------------------------------------------------------------------------------------------------- | | `build_claim` | Build claim JSON for the API (code-gated, password-gated, whitelist-gated, open) | | `build_address_list` | Build an on-chain address list collection | | `build_transfer` | Build a MsgTransferTokens by auto-querying the collection and constructing the correct transaction | | `build_dynamic_store` | Build transaction JSON for dynamic store operations (create, update, delete, set values) | > **Note:** For building collections, use the session-based per-field tools above. They provide full control, support parallel calls, and are the recommended approach for all collection types. ### Audit & Analysis | Tool | Description | | -------------------- | ------------------------------------------------------------------------------------------------- | | `review_collection` | Unified review: audit, standards compliance, and UX findings in one call with audience filtering | | `explain_collection` | Human-readable collection report with Q\&A mode (user/developer/auditor audiences) | | `analyze_collection` | Structured analysis of transferability, approvals, permissions, and how to obtain/transfer tokens | ### Simulation & Validation | Tool | Description | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `simulate_transaction` | Dry-run a transaction without broadcasting. Returns `parsedEvents` (coin, badge, and IBC transfers) and `netChanges` (per-address balance diffs) | | `validate_transaction` | Validate a transaction is well-formed before broadcasting | ### Queries | Tool | Description | | --------------------- | ---------------------------------------------------------------------------------------- | | `query_collection` | Fetch collection details from the BitBadges API | | `query_balance` | Check token balance for an address | | `query_dynamic_store` | Query on-chain dynamic store data (get store details, check address values, list values) | | `verify_ownership` | Verify if an address meets ownership requirements | | `search` | Search collections, accounts, and tokens | | `search_plugins` | Search for off-chain claim plugins or fetch specific plugins by ID | | `lookup_token_info` | Look up token metadata and info | ### Component Generators Helper tools that generate specific pieces of a collection (approvals, permissions, addresses) without managing session state. | Tool | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | `generate_approval` | Generate approval structures by pattern (public-mint, manager-mint, smart-token-backing, subscription, etc.) | | `generate_permissions` | Generate permission presets (fully-immutable, manager-controlled, locked-approvals) | | `generate_backing_address` | Compute the deterministic IBC backing address for a given denom | | `generate_alias_path` | Generate alias path config for token display on DEX | | `generate_wrapper_address` | Compute the deterministic wrapper address for a custom denom | | `generate_unique_id` | Generate collision-free IDs for approvals (prefix + random hash) | ### Utilities | Tool | Description | | ----------------------- | ------------------------------------------------------------------------------------------------ | | `validate_address` | Validate a BitBadges address | | `convert_address` | Convert between address formats (ETH, Cosmos, etc.) | | `get_current_timestamp` | Get the current timestamp (for time-based configs) | | `diagnose_error` | Diagnose BitBadges transaction errors and get suggested fixes | | `search_knowledge_base` | Search across all BitBadges knowledge — docs, learnings, recipes, error patterns, critical rules | ### Instructions & Docs | Tool | Description | | ------------------------ | ----------------------------------------------------------------------------------------------------- | | `get_skill_instructions` | Get detailed build instructions for specific skills (smart-token, fungible-token, subscription, etc.) | | `fetch_docs` | Fetch documentation pages | ## Workflows ### Session-Based Build (Recommended) The per-field tools build up a collection incrementally in a session. This is the recommended approach — it gives full control and supports parallel tool calls. ``` set_standards + set_valid_token_ids + set_invariants + add_approval + set_permissions + set_default_balances + set_collection_metadata + set_token_metadata → (optional) add_transfer (for auto-mint at creation) → validate_transaction + review_collection + simulate_transaction (in parallel) → fix errors with remove_approval + re-add (max 3 attempts) → get_transaction (final JSON) ``` **Step-by-step:** 1. **Build** — Call per-field tools in parallel to define the collection: standards, token IDs, invariants, approvals, permissions, metadata, balances. 2. **Auto-Mint** (optional) — If the user wants tokens minted to specific addresses at creation, call `add_transfer` to append a `MsgTransferTokens` alongside the collection creation. 3. **Verify** — Call `validate_transaction`, `review_collection`, and `simulate_transaction` in parallel. Fix any errors with targeted `remove_approval` + re-add. 4. **Export** — Call `get_transaction` to get the final transaction JSON for signing. ### Query & Verification (No Signing) ``` query_collection → verify_ownership → (take action based on result) ``` > **Note:** The builder does not handle signing or broadcasting. Transaction signing must be done externally using the BitBadges SDK, a wallet, or the BitBadges frontend. ## Auto-Mint at Creation The `add_transfer` tool lets you mint tokens to specific addresses at the same time as collection creation. This produces a transaction with two messages: `MsgUniversalUpdateCollection` + `MsgTransferTokens`. **When to use:** "Mint 100 tokens to myself", "distribute tokens to team members", "auto-mint at creation". **How it works:** 1. Build the collection normally with a mint approval (e.g., `add_approval` with `fromListId: "Mint"`, `initiatedByListId: `) 2. Call `add_transfer` with the recipient addresses, balances, and `prioritizedApprovals` referencing the mint approval 3. Verify and export as normal — the transaction will contain both messages Maximum 4 transfer messages per transaction. ## Skills (Guided Workflows) The builder includes skill instructions accessible via `get_skill_instructions`. These guide AI agents through building specific collection types. For full instructions and examples for each skill, see the [**Builder Skills reference**](/token-standard/skills.md). Common features like ownership requirements, codes, and passwords are built into the approval system directly and can be composed with any skill. ## Related Tools | Tool | Install | Description | | ----------------- | ------------------------------------------------------------------------- | ------------------------------------------------ | | **BitBadges SDK** | `npm i bitbadges` | TypeScript SDK for direct blockchain interaction | | **GitBook MCP** | [docs.bitbadges.io/\~gitbook/mcp](https://docs.bitbadges.io/~gitbook/mcp) | Search BitBadges documentation | | **BitBadges API** | [api.bitbadges.io](https://api.bitbadges.io) | REST API for queries and data | ## Builder Resources The builder also exposes embedded documentation as resources: | Resource URI | Name | Description | | ---------------------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | `bitbadges://tokens/registry` | Token Registry | IBC denoms, symbols, decimals, and pre-generated backing addresses | | `bitbadges://rules/critical` | Critical Rules | Critical rules that must be followed when building transactions | | `bitbadges://skills/all` | Skill Instructions | Instructions for all builder skills | | `bitbadges://docs/concepts` | Core Concepts | Core BitBadges concepts: transferability, approvals, permissions, balances, and address lists | | `bitbadges://docs/examples` | Full Examples | Complete transaction JSON examples for NFT collections, fungible tokens, and Smart Tokens | | `bitbadges://recipes/all` | Code Recipes & Decision Matrices | Code snippets and decision matrices for common operations | | `bitbadges://learnings/all` | Learnings & Gotchas | Known gotchas, tips, and discoveries from building with BitBadges | | `bitbadges://errors/patterns` | Error Patterns | Common error messages mapped to diagnoses and fixes | | `bitbadges://docs/frontend` | Reference Frontend Patterns | Patterns from the BitBadges reference frontend (Next.js + Ant Design) | | `bitbadges://workflows/all` | Workflow Chains | Step-by-step tool chains for common multi-step operations | | `bitbadges://schema/token-builder` | Token Builder Schema | Annotated schema for per-field session builders: design axes, field reference, approval patterns, and validation checklist | Access these via your MCP client's resource reading capabilities. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bitbadges.io/for-developers/ai-agents/builder-tools.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.