> For the complete documentation index, see [llms.txt](https://docs.bitbadges.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitbadges.io/for-developers/cli/build-commands.md).

# 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`](/for-developers/cli/deploy-commands.md). 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](/for-developers/cli/sign-bridge.md#build--browser).

> **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](/token-standard/learn/collection-setup-fields.md#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.

```bash
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.

```bash
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.

```bash
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.**

```bash
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](/token-standard/skills/payment-request.md).

### `build crowdfund`

Create a crowdfunding collection with a funding goal and deadline.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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.

```bash
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).

```bash
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`](/for-developers/cli/standards-commands.md) (a `MsgSetOutgoingApproval`) — either command works.

```bash
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`](/for-developers/cli/standards-commands.md) 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.

```bash
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`.

```bash
# 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.

```bash
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.

```bash
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.

```bash
# 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.

```bash
# 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](/for-developers/create-and-broadcast-txs/signing-client.md), the [BitBadges frontend](https://bitbadges.io), or the chain binary.