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


---

# 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/cli/build-commands.md?ask=<question>
```

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.