Build Commands

The bb build command provides 17 builders that generate ready-to-sign transaction JSON. Each builder creates a complete collection or approval configuration from simple, human-readable parameters.

All build commands accept friendly inputs -- use coin symbols like USDC instead of raw IBC denominations, and duration shorthands like 30d instead of millisecond timestamps. The output is a fully-formed transaction message that can be signed and broadcast using the SDK, the BitBadges frontend, or the chain binary.

Tip — don't want to bring your own wallet? Pipe the output of any collection builder straight into deploy --burner. The CLI generates a throwaway signer, funds it from the faucet, broadcasts the create-collection tx, and hands ownership to the address you pass as --manager. No keys to set up.

Already have a wallet in your browser? Use --browser instead — the build runs, the resulting tx is handed to your connected Keplr / MetaMask via /sign, and the hash comes back to your terminal. Add --sign-only to skip the broadcast and get signed bytes back for your own submitter. See Sign Bridge.

No IPFS hosting needed. Every template accepts metadata in one of two modes per metadata-bearing entity: pass --uri <pre-hosted-uri> if you have already hosted the JSON yourself, or pass the per-entity field flags (--name, --image, --description) and the CLI serializes 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 there is no Pinata account to set up. Approvals are text-only — --name + --description, no image. The CLI throws a clear error if neither mode is fully satisfied; there are no defaults or placeholders. See Collection Configuration › Inline metadata via customData for the on-chain shape.

Common Flags

Every build command supports the following flags:

Flag	Description
--dry-run	Validate the output against standard compliance checks (results printed to stderr)
--explain	Print a human-readable explanation of the generated transaction (to stderr)
--creator <address>	Set the creator/sender address
--manager <address>	Set the collection manager address
--json <input>	Pass all parameters as JSON (inline, file path, or - for stdin). Overrides individual flags
--condensed	Output compact JSON with no whitespace
--output-file <path>	Write output to a file instead of stdout

Collection Builders

These commands generate MsgUniversalUpdateCollection transaction JSON for creating new collections.

build vault

Create an IBC-backed vault token with optional withdrawal limits, 2FA gating, and emergency recovery.

bb build vault --backing-coin USDC \
  --name "My Vault" \
  --symbol vUSDC \
  --daily-withdraw-limit 1000 \
  --explain

Flag	Required	Description
--backing-coin <symbol>	Yes	Backing coin symbol (USDC, BADGE, ATOM, OSMO)
--name <name>	No	Collection name (default: "Vault")
--symbol <symbol>	No	Display symbol (e.g., vUSDC)
--image <url>	No	Image URL
--description <text>	No	Description
--daily-withdraw-limit <n>	No	Max daily withdrawal in display units
--require-2fa <collectionId>	No	2FA collection ID for withdrawal gating
--emergency-recovery <address>	No	Recovery address for emergency migration

build subscription

Create a recurring subscription collection with configurable intervals, pricing, and optional multi-tier support.

bb build subscription --interval monthly \
  --price 10 --denom USDC --recipient bb1... \
  --tiers 3 --transferable

Flag	Required	Description
--interval <duration>	Yes	Interval: daily, monthly, annually, or shorthand (30d)
--price <amount>	No	Price per interval in display units
--denom <symbol>	No	Payment coin (USDC, BADGE)
--recipient <address>	No	Payout address
--payouts <json>	No	Multiple payouts: [{"recipient","amount","denom"}]
--tiers <n>	No	Number of tiers (default: 1)
--transferable	No	Allow post-mint transfers between users
--name <name>	No	Collection name (default: "Subscription")

build bounty

Create a bounty with escrowed funds, a verifier who approves completion, and a designated recipient.

bb build bounty --amount 500 --denom USDC \
  --verifier bb1... --recipient bb1... --expiration 30d

Flag	Required	Description
--amount <n>	Yes	Bounty amount in display units
--denom <symbol>	Yes	Coin (USDC, BADGE)
--verifier <address>	Yes	Verifier address
--recipient <address>	Yes	Recipient address
--expiration <duration>	No	Expiration duration (default: 30d)
--name <name>	No	Collection name (default: "Bounty")

build payment-request

Create an agent-initiated payment request — the inverse of bounty. The agent (or any address) creates a collection requesting payment from a targeted payer; the payer approves AND pays from their own wallet in a single action. No escrow up front.

bb build payment-request \
  --amount 10 --denom USDC \
  --payer bb1payer... --recipient bb1agent... \
  --expiration 30d --name "Service charge" \
  --context "Agent X is requesting payment for completed deliverable Y under approved budget envelope of \$100/month."

Flag	Required	Description
--amount <n>	Yes	Payment amount in display units
--denom <symbol>	Yes	Coin (USDC, BADGE)
--payer <address>	Yes	Payer address (the human approver)
--recipient <address>	Yes	Recipient address (agent / merchant)
--expiration <duration>	No	Expiration duration (default: 30d)
--name <name>	No	Collection name (default: "Payment Request")
--context <text>	No	Rationale shown to the payer at approval time (≥100 chars recommended)

See the full spec in skills/payment-request.

build crowdfund

Create a crowdfunding collection with a funding goal and deadline.

bb build crowdfund --goal 10000 --denom USDC \
  --crowdfunder bb1... --deadline 30d

Flag	Required	Description
--goal <n>	Yes	Funding goal in display units
--denom <symbol>	Yes	Coin (USDC, BADGE)
--crowdfunder <address>	Yes*	Who receives funds on success, and the party whose progress balance gates success/refund. *Falls back to --creator; the builder errors if neither is set (it can't build a payout-less crowdfund).
--deadline <duration>	No	Deadline duration (default: 30d)
--name <name>	No	Collection name (default: "Crowdfund")

build auction

Create an auction collection with configurable bidding and acceptance windows.

bb build auction --bid-deadline 7d --accept-window 7d \
  --name "Rare Item" --description "Limited edition collectible" \
  --seller bb1seller...

Flag	Required	Description
--bid-deadline <duration>	No	Bidding window (default: 7d)
--accept-window <duration>	No	Accept window after bidding ends (default: 7d)
--name <name>	No	Item name (default: "Auction")
--description <text>	No	Item description
--image <url>	No	Item image URL
--seller <address>	No	Seller address — only this address can accept the winning bid (defaults to --creator)

build product-catalog

Create a product catalog collection with multiple products, each having its own price and optional supply limit.

bb build product-catalog \
  --products '[{"name":"Widget","price":25,"denom":"USDC","maxSupply":100}]' \
  --store-address bb1...

Flag	Required	Description
--products <json>	Yes	Product array: [{"name","price","denom","maxSupply?","burn?"}]
--store-address <address>	Yes	Payment recipient address
--name <name>	No	Collection name (default: "Product Catalog")

build prediction-market

Create a binary prediction market (YES/NO outcome tokens) with a designated resolver.

bb build prediction-market --verifier bb1... \
  --denom USDC --name "Will X happen by 2027?"

Flag	Required	Description
--verifier <address>	Yes	Market resolver address
--denom <symbol>	No	Payment coin (default: USDC)
--name <name>	No	Market question (default: "Prediction Market")
--description <text>	No	Market details
--image <url>	No	Market image URL

build smart-account

Create an IBC-backed smart account with optional trading and AI agent vault support.

bb build smart-account --backing-coin USDC \
  --symbol sUSDC --tradable --ai-agent-vault

Flag	Required	Description
--backing-coin <symbol>	Yes	Backing coin (USDC, BADGE, ATOM, OSMO)
--symbol <symbol>	No	Display symbol
--image <url>	No	Token image URL
--tradable	No	Enable liquidity pool trading
--ai-agent-vault	No	Add AI Agent Vault standard tag

build credit-token

Create a credit or prepaid token where users pay to receive a configurable number of tokens.

bb build credit-token --payment-denom USDC \
  --recipient bb1... --symbol CREDIT --tokens-per-unit 100

Flag	Required	Description
--payment-denom <symbol>	Yes	Payment coin (USDC, BADGE)
--recipient <address>	Yes	Payment recipient
--symbol <symbol>	No	Token symbol (default: CREDIT)
--tokens-per-unit <n>	No	Tokens per 1 display unit of payment (default: 100)
--name <name>	No	Collection name (default: "Credit Token")

build custom-2fa

Create a custom 2FA token collection for use as a second authentication factor in other collections.

bb build custom-2fa --name "My 2FA Token" --image ipfs://... \
  --description "Short-lived 2FA token" --creator bb1manager... --burnable

Flag	Required	Description
--creator <address>	Yes	Manager address — only this address may mint 2FA tokens (mint is restricted to the manager; the builder errors if omitted)
--name <name>	Yes	Token name (with --image + --description, or pass --uri)
--image <url>	Yes*	Token image URL (*unless --uri is used)
--description <text>	Yes*	Description (*unless --uri is used)
--burnable	No	Allow burning
--transferable	No	Allow post-mint transfers between users

After creating the collection, issue tokens with bb custom-2fa mint. The token lifetime (default 5 minutes) is encoded at mint time, so this step is required for tokens to expire — broadcasting a raw mint without it produces tokens that never expire, silently breaking the 2FA guarantee.

bb custom-2fa mint <collection-id> --creator bb1manager... \
  --to bb1user...,bb1user2... [--expiration 10m] | bb deploy

Add --browser or --burner to broadcast inline instead of piping to bb deploy.

Flag	Required	Description
--creator <address>	Yes	Manager address — only the manager may mint 2FA tokens
--to <addresses>	Yes	Recipient bb1... address(es), comma-separated
--expiration <duration>	No	Token lifetime: 5m, 10m, … or ms-since-epoch (default: 5m). --expiry is a deprecated alias.

build address-list

Create an on-chain address list (not a token collection -- uses a separate message type).

bb build address-list --name "Allowlist" --description "Approved addresses"

Flag	Required	Description
--name <name>	Yes	List name
--image <url>	No	List image URL
--description <text>	No	Description

Approval Builders

These commands generate user-level approval messages for marketplace listings, bids, payments, and trading intents.

build intent

Create an OTC swap intent (user outgoing approval) on the Intent Exchange. Emits the identical shape to bb intents create (a MsgSetOutgoingApproval) — either command works.

bb build intent --address bb1... \
  --collection-id 5 \
  --pay-denom USDC --pay-amount 100 \
  --receive-denom BADGE --receive-amount 500 \
  --expiration 30d

Flag	Required	Description
--address <address>	Yes	Creator address
--collection-id <id>	Yes	Intent Exchange collection ID
--pay-denom <symbol>	Yes	What you send (USDC, BADGE)
--pay-amount <n>	Yes	Amount you send in display units
--receive-denom <symbol>	Yes	What you receive
--receive-amount <n>	Yes	Amount you receive in display units
--expiration <when>	No	Intent expiry: ms-since-epoch or duration (30d, 24h, monthly). Default: 30d, matches bb intents create. --expiry / --valid-until are deprecated aliases.

Recurring payments? There is no bb build recurring-payment — a subscriber's recurring approval must be derived from the live subscription collection, not built offline. Use bb subscriptions claim / bb subscriptions subscribe instead, which read the subscription's faucet approval and emit the correct user recurring approval.

build listing

Create a marketplace listing (user outgoing approval) to sell a token from a collection. Emits the identical shape to bb nfts list (a MsgSetOutgoingApproval). Orderbook listings are single-token — pass one token id; a true range errors.

bb build listing --address bb1... \
  --collection-id 7 --token-ids 4 \
  --price 50 --denom USDC --max-sales 1 --expiration 30d

Flag	Required	Description
--address <address>	Yes	Seller address
--collection-id <id>	Yes	Collection ID to list from
--token-ids <id>	Yes	Single token id to list (orderbook listings are single-token; a range errors)
--price <n>	Yes	Asking price in display units
--denom <symbol>	Yes	Price coin (USDC, BADGE)
--max-sales <n>	No	Maximum number of sales (default: 1)
--expiration <when>	No	Listing expiry: ms-since-epoch or duration (30d, 24h, monthly). Default: 30d.

build bid

Create a marketplace bid (user incoming approval) to buy a token from a collection. Emits the identical shape to bb nfts bid (a MsgSetIncomingApproval). Pass one token id for a single-token bid (a true range errors); omit --token-ids for a collection-wide bid — full parity with bb nfts bid.

# Single-token bid
bb build bid --address bb1... \
  --collection-id 7 --token-ids 4 \
  --price 40 --denom USDC --expiration 7d

# Collection-wide bid (any token in the collection)
bb build bid --address bb1... \
  --collection-id 7 \
  --price 40 --denom USDC

Flag	Required	Description
--address <address>	Yes	Bidder address
--collection-id <id>	Yes	Collection ID to bid on
--token-ids <id>	No	Single token id to bid on (a true range errors). Omit for a collection-wide bid.
--token-amount <n>	No	Number of tokens (default: 1)
--price <n>	Yes	Bid price in display units
--denom <symbol>	Yes	Price coin (USDC, BADGE)
--expiration <when>	No	Bid expiry: ms-since-epoch or duration (7d, 24h, monthly). Default: 7d.

build pm-sell-intent

Create a prediction market sell intent (user outgoing approval) to sell outcome tokens.

bb build pm-sell-intent --address bb1... \
  --collection-id 12 --token yes \
  --amount 10 --price 50 --denom USDC

Flag	Required	Description
--address <address>	Yes	Seller address
--collection-id <id>	Yes	Prediction market collection ID
--token <yes|no>	Yes	Which outcome token to sell
--amount <n>	Yes	Number of tokens to sell
--price <n>	Yes	Total payment amount in display units
--denom <symbol>	Yes	Payment coin (USDC, BADGE)
--expiration <when>	No	Intent expiry: ms-since-epoch or duration (24h, 7d, monthly). Default: 24h, matches bb prediction-markets buy/sell.

build pm-buy-intent

Create a prediction market buy intent (user incoming approval) to buy outcome tokens.

bb build pm-buy-intent --address bb1... \
  --collection-id 12 --token no \
  --amount 10 --price 50 --denom USDC

Flag	Required	Description
--address <address>	Yes	Buyer address
--collection-id <id>	Yes	Prediction market collection ID
--token <yes|no>	Yes	Which outcome token to buy
--amount <n>	Yes	Number of tokens to buy
--price <n>	Yes	Total payment amount in display units
--denom <symbol>	Yes	Payment coin (USDC, BADGE)
--expiration <when>	No	Intent expiry: ms-since-epoch or duration (24h, 7d, monthly). Default: 24h, matches bb prediction-markets buy/sell.

Transfer Builder

This command builds a MsgTransferTokens transaction for moving existing tokens between addresses. Unlike the collection builders, it runs as an interactive walkthrough by default — it fetches the collection, the sender's outgoing approvals, and the recipient's incoming approvals, then walks you through picking which approvals to prioritize, whether to use predetermined-balance precalculation, and the amount + token IDs to transfer. Every prompt has a flag short-circuit so the command can also run non-interactively in scripts.

build transfer

Build a MsgTransferTokens with guided approval discovery. Requires BITBADGES_API_KEY (env var or bb settings set apiKey ...) — the walkthrough fetches the collection and per-user approvals from the API.

# Interactive walkthrough — prompts for everything
bb build transfer

# Flag-driven (still prompts for the approval-selection step)
bb build transfer --collection-id 1 --from bb1abc... --to bb1xyz... --amount 5

# Fully non-interactive — picks no prioritized approvals (chain matches),
# no precalculation, default amount=1, default tokenIds=all valid
bb build transfer --yes --collection-id 1 --from bb1abc... --to bb1xyz...

The walkthrough renders a numbered list grouped by approval level (collection / outgoing / incoming) with tags for predetermined, payment, must-own, and backed, then asks:

1. Which approvals to set as prioritizedApprovals (comma-separated indices, blank to skip).

2. For each level with a pick, whether to set onlyCheckPrioritized<Level>Approvals: true.

3. If any picked approval has predeterminedBalances, whether to delegate balance computation via precalculateBalancesFromApproval (and an optional scalingMultiplier for consuming N predetermined steps in one tx).

4. If not precalculated, the per-recipient amount and the tokenIds to transfer.

If a picked approval requires a coin payment or prerequisite token ownership, the walkthrough prints a "Heads up" line listing those side conditions before the final emit.

Flag	Required	Description
--collection-id <id>	No	Collection ID (prompts if omitted)
--from <address>	No	Sender address (bb1.../0x.../"Mint" for minting); prompts if omitted
--to <address>	No	Recipient address (cannot be "Mint"); prompts if omitted
--amount <n>	No	Per-recipient amount when not precalculated (default: prompt; 1 with --yes)
--token-ids <spec>	No	Token IDs — 1-5, 1,3,5, or all (default: prompt; all with --yes)
--yes	No	Skip every prompt. Picks no prioritized approvals (chain matches), no precalc, default amount + tokenIds. For scripts/CI

The output MsgTransferTokens flows through the same emit() pipeline as the collection builders, so --simulate, --explain, --browser, and the auto-validate banner all behave identically. The --burner path is CREATE-only and will refuse a transfer with its standard error.

JSON Input Mode

All commands support --json for passing parameters as a JSON object. This is useful for scripting, piping from other tools, or when an AI agent generates the parameters programmatically.

# Inline JSON
bb build vault --json '{"backingCoin":"USDC","name":"My Vault"}'

# From a file
bb build vault --json ./params.json

# From stdin
echo '{"backingCoin":"USDC"}' | bb build vault --json -

Output

All build commands output transaction JSON to stdout. Use --dry-run and --explain to inspect the output before signing:

• --dry-run runs standard compliance checks and prints any violations to stderr

• --explain prints a human-readable summary of what the transaction does to stderr

The output JSON can be signed and broadcast using the BitBadges SDK signing client, the BitBadges frontend, or the chain binary.