Bitbadges Builder

BitBadges Collection Builder

Build BitBadges collections using the bitbadges-builder-mcp server tools.

Quick Reference

Available Tools

Supported Token Symbols

Example Workflows

1. USDC Stablecoin with Spend Limit

User: "Create a 1:1 backed USDC stablecoin with 100 USDC/day spend limit"

1. Call `lookup_token_info` with query "USDC"
   → Get IBC denom, decimals, backing address

2. Call `build_smart_token` with:
   - ibcDenom: "USDC"
   - creatorAddress: [user's address]
   - name: "Wrapped USDC"
   - symbol: "wUSDC"
   - dailyWithdrawLimit: "100000000" (100 USDC in 6 decimals)

3. Call `validate_transaction` to verify

4. Return JSON for user to broadcast

2. Simple NFT Collection

User: "Create an NFT collection of 1000 items at 5 BADGE each"

1. Call `build_nft_collection` with:
   - creatorAddress: [user's address]
   - name: "My NFT Collection"
   - totalSupply: "1000"
   - mintPrice: "5000000000" (5 BADGE in 9 decimals)
   - mintPriceDenom: "ubadge"
   - tradable: true

2. Call `validate_transaction` to verify

3. Return JSON for user to broadcast

3. Fungible Token with Liquidity Pool

User: "Create a swappable token called MYTOKEN"

1. Call `build_fungible_token` with:
   - creatorAddress: [user's address]
   - name: "My Token"
   - symbol: "MYTOKEN"
   - swappable: true
   - decimals: "9"

2. Call `validate_transaction` to verify

3. Return JSON for user to broadcast

Critical Rules

Number Format

• ALL numbers must be strings: "1" not 1
• UintRange: { "start": "1", "end": "18446744073709551615" }
• Forever time: "18446744073709551615"

List IDs (Only These Allowed)

• "All" - Any address
• "Mint" - Mint address
• "!Mint" - Except Mint
• "bb1..." - Specific address
• "!bb1..." - Except address
• "!Mint:bb1..." - Smart Token unbacking format

Smart Token Rules

• THREE approvals required: backing + transferable + unbacking
• NO fromListId: "Mint" approvals
• allowBackedMinting: true required
• mustPrioritize: true required
• overridesFromOutgoingApprovals: true for backing addresses (recommended — backing addresses auto-set their approvals, so it works either way)
• overridesFromOutgoingApprovals: false for unbacking (sender is a regular user)

Mint Approval Rules

• MUST have overridesFromOutgoingApprovals: true
• Only for fromListId: "Mint"

Token Metadata

• MUST include tokenIds field

Decimals Reference

When converting user amounts to base units:

• USDC: 6 decimals → 100 USDC = "100000000"
• ATOM: 6 decimals → 100 ATOM = "100000000"
• OSMO: 6 decimals → 100 OSMO = "100000000"
• BADGE: 9 decimals → 5 BADGE = "5000000000"

Troubleshooting

If validation fails, common issues:

1. Numbers not strings → Use "1" not 1
2. Missing tokenIds → Add to tokenMetadata entries
3. Invalid list ID → Use only reserved IDs
4. Missing override → Add overridesFromOutgoingApprovals: true for Mint

Output Format

Always return:

1. Summary of what was created
2. Complete transaction JSON in code block
3. Instructions for broadcasting

{
  "messages": [
    {
      "typeUrl": "/tokenization.MsgUniversalUpdateCollection",
      "value": { ... }
    }
  ]
}