bb build

bb build <type> turns a few flags into a complete, ready-to-sign transaction message. Use it when a template fits; pipe the result into bb check, bb preview, or bb deploy.

For invoice substandards, use bb build payment-request-v2 --list-examples, --example <type>, and --schema to discover editable terms. The agent workflow covers exact JSON roundtrips and metadata precedence; Invoices and Payment Links documents the resulting approvals and tracking. bb pay-requests build-v2 is an alias; the older bb pay-requests build continues to build legacy requests.

Example#

bb build vault --backing-coin USDC \
  --name "Demo Vault" --symbol vUSDC \
  --image ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/vault.png --description "USDC-backed vault" \
  --daily-withdraw-limit 1000 --explain

# build, then review and sign in the browser
bb build vault --backing-coin USDC --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json | bb preview - --open

# build and broadcast with a connected wallet
bb build vault --backing-coin USDC --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json \
  --manager bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --browser

The first command prints the message inside the envelope (485 lines for a vault; the head, with --creator bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d, is):

{
  "ok": true,
  "data": {
    "typeUrl": "/tokenization.MsgCreateCollection",
    "value": {
      "creator": "bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d",
      "validTokenIds": [
        {
          "start": "1",
          "end": "1"
        }
      ],
      "collectionPermissions": {
        "canDeleteCollection": [
          {
            "permanentlyForbiddenTimes": [
              {
                "start": "1",
                "end": "18446744073709551615"
              }
            ]
          }
        ],
        "canArchiveCollection": [
          {
            "permanentlyForbiddenTimes": [
              {
                "start": "1",
                "end": "18446744073709551615"
              }
            ]
          }
        ]
      }
    }
  }
}

{
  "ok": true,
  "data": {
    "typeUrl": "/tokenization.MsgCreateCollection",
    "value": {
      "creator": "bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d",
      "validTokenIds": [
        {
          "start": "1",
          "end": "1"
        }
      ],
      "collectionPermissions": {
        "canDeleteCollection": [
          {
            "permanentlyPermittedTimes": [],
            "permanentlyForbiddenTimes": [
              {
                "start": "1",
                "end": "18446744073709551615"
              }
            ]
          }
        ],
        "canArchiveCollection": [
          {
            "permanentlyPermittedTimes": [],
            "permanentlyForbiddenTimes": [
              {
                "start": "1",
                "end": "18446744073709551615"
              }
            ]
          }
        ]
      }
    }
  }
}

The walkthrough that explains the output is in Create a Collection. This page is the flag reference.

Subcommands#

The subcommand list comes from bitbadgesjs-sdk/src/cli/commands/build.ts. Collection builders emit MsgCreateCollection for a new collection (they assemble it as MsgUniversalUpdateCollection and narrow it at the emit boundary). Approval builders emit MsgSetOutgoingApproval or MsgSetIncomingApproval.

Ten standards groups expose the same builder as bb <standard> build (for example bb auctions build is bb build auction). Same flags, same output. nfts and dynamic-stores have no build alias.

Shared Flags#

Every subcommand accepts these. --help renders them under Metadata, Output, Network, Builder, and Deploy headings after the per-command flags.

--json-only still works as a deprecated alias for --quiet.

Metadata Modes#

Every metadata-bearing builder accepts exactly one of two modes per entity:

1. --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json when you already host the JSON.
2. --name + --image + --description. The CLI serializes them into the on-chain customData field. The BitBadges API, SDK, and site parse customData on read and show it as the resolved metadata, so no IPFS account is needed.

Approvals are text-only: --name + --description, no image. The CLI errors if neither mode is complete; there are no placeholder defaults. On-chain shape: Collections.

For payment-request-v2 --json, --uri replaces inline metadata from the JSON. Supplying any inline metadata flag removes the JSON's uri and merges the supplied inline fields with any remaining inline fields in the JSON; the resulting name, image, and description must be complete. Combining --uri with inline metadata flags is rejected. Other JSON builder handlers take metadata from the JSON rather than merging these flags into it.

Denoms and Amounts#

--denom style flags accept a symbol (BADGE, USDC, ATOM, OSMO) or a canonical denom (ubadge, ibc/E1116484B327AEE59CDC3DA73D319834781A13DB2A7DFC1F38A30CD45ABF58B8). Amounts are display units when the denom is a symbol and base units when it is a raw denom. --base-units forces base units. USDC resolves to the canonical Injective-routed denom; USDC.n is the legacy denom. See Supported Denoms.

Durations accept daily, monthly, annually, shorthand such as 30d, 24h, 5m, or ms-since-epoch.

JSON Input#

bb build vault --backing-coin USDC --json '{"backingCoin":"USDC","uri":"ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json"}'
bb build vault --backing-coin USDC --json ./params.json
echo '{"backingCoin":"USDC","uri":"ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json"}' | bb build vault --backing-coin USDC --json -

JSON uses the matching SDK builder's parameter names. Required CLI flags still apply, even when the JSON includes the corresponding field. In the vault examples, --backing-coin satisfies CLI parsing while backingCoin in the JSON supplies the builder value. Keep builder parameters and metadata in the JSON; do not assume command-line flags override them. The V2 payment metadata exception is described above.

Collection Builders#

vault#

bb build vault --backing-coin USDC --symbol vUSDC --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json \
  --daily-withdraw-limit 1000 --require-2fa 84 --emergency-recovery bb1zc268nctj8xwslgw7q22cahs6k4y048agr6fvf

smart-token#

bb build smart-token --backing-coin USDC --symbol sUSDC --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json \
  --tradable --ai-agent-vault

Vault collections are Smart Tokens with the cosmosCoinBackedPath invariant. bb build smart-account was the old name.

subscription#

bb build subscription --interval monthly --price 10 --denom USDC \
  --recipient bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --tiers 3 --transferable \
  --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json

There is no bb build recurring-payment. A subscriber's recurring approval derives from the live collection; use bb subscriptions subscribe or bb subscriptions enable-renewal.

bounty#

bb build bounty --amount 500 --denom USDC --verifier bb1zc268nctj8xwslgw7q22cahs6k4y048agr6fvf \
  --recipient bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue --submitter bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d \
  --expiration 30d --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json

payment-request#

bb build payment-request --amount 10 --denom USDC \
  --payer bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --recipient bb18cad7xxsk3drvwdxeasc3wqn2plftpzq2tsrsr --expiration 30d \
  --name "Service charge" --image ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/invoice.png \
  --context "Agent requests payment for the September report under the approved budget of 100 USDC per month."

The inverse of bounty: no escrow up front. The payer approves and pays from their own wallet in one action.

crowdfund#

bb build crowdfund --goal 10000 --denom USDC --crowdfunder bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --deadline 30d \
  --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json

auction#

bb build auction --bid-deadline 7d --accept-window 7d --seller bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d \
  --name "Rare Item" --description "Limited edition" --image ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/1.png

product-catalog#

bb build product-catalog --store-address bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d \
  --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json \
  --products '[{"name":"Widget","price":25,"denom":"USDC","maxSupply":100},{"name":"Pass","price":5,"denom":"USDC","burn":true}]'

Product fields: name (required), price (display units, required), denom (required), storeAddress (optional recipient override; BitBadges or EVM account), maxSupply (omit or 0 for unlimited), burn (true burns on purchase), uri, image, description. One token ID per product; each product becomes a "Purchase" approval. The builder freezes products, prices, recipients, stock limits and metadata at creation; publish a new catalog for different terms.

prediction-market#

bb build prediction-market --verifier bb1zc268nctj8xwslgw7q22cahs6k4y048agr6fvf --denom USDC \
  --name "Will testnet return by 2027?" --description "Resolves YES if the BitBadges testnet is back online before 2027-01-01." \
  --image ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/market.png

credit-token#

bb build credit-token --payment-denom USDC --recipient bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d \
  --symbol CREDIT --tokens-per-unit 100 --uri ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/collection.json

custom-2fa#

bb build custom-2fa --creator bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --name "Demo 2FA Token" \
  --image ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/2fa.png --description "Short-lived 2FA token" --burnable

Issue tokens afterwards with bb custom-2fa mint. The lifetime is encoded at mint time, so a raw mint without that command produces tokens that never expire. See Standards.

address-list#

bb build address-list --name "Allowlist" --description "Approved addresses" \
  --image ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi/list.png

Emits MsgCreateAddressLists. Takes the shared metadata flags only.

Approval Builders#

intent#

bb build intent --address bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --collection-id 81 \
  --pay-denom USDC --pay-amount 100 --receive-denom BADGE --receive-amount 500 --expiration 30d

Identical output to bb intents create.

listing#

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

Identical output to bb nfts list.

bid#

bb build bid --address bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue --collection-id 1 --token-ids 4 --price 40 --denom USDC --expiration 7d
bb build bid --address bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue --collection-id 1 --price 40 --denom USDC          # collection-wide

Identical output to bb nfts bid.

pm-sell-intent and pm-buy-intent#

bb build pm-sell-intent --address bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --collection-id 12 --token yes --amount 10 --price 50 --denom USDC
bb build pm-buy-intent  --address bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue --collection-id 12 --token no  --amount 10 --price 50 --denom USDC

Coin and Token Transfers#

send#

bb build send --from bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --to bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue --amount 1.5 --denom BADGE
bb build send --from bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --to bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue --amount 1500000000 --denom ubadge --base-units

Use send for fee top-ups or returning dust. For BitBadges token transfers use transfer.

transfer#

bb build transfer                                                        # interactive walkthrough
bb build transfer --collection-id 1 --from bb1p0rrel3365scadq5k9pv0x0zp9j22js6dnw70d --to bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue --amount 5
bb build transfer --yes --collection-id 1 --from Mint --to bb1py4mfpg6uf59qkyzg0nmau322c5873eeysp5ue      # non-interactive

Needs an API key. The walkthrough fetches the collection, the sender's outgoing approvals, and the recipient's incoming approvals, then renders a numbered list grouped by level (collection, outgoing, incoming) with predetermined, payment, must-own, and backed tags. It 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 a pick has predeterminedBalances, whether to set precalculateBalancesFromApproval and an optional scalingMultiplier.
4. If not precalculated, the per-recipient amount and tokenIds.

If a picked approval needs a coin payment or prerequisite ownership, a "Heads up" line lists those conditions before the emit.

The output flows through the same pipeline as the collection builders, so --simulate, --explain, and --browser behave the same. --burner refuses transfers (it is create-only).

Behavior#

• Output is one envelope on stdout with the message in data and validation, review, simulate, and resolved-metadata reports in meta. The human-readable auto-review prints on stderr; --quiet silences it.
• bb deploy and bb preview unwrap the envelope when reading stdin or a file.
• Sign and broadcast with Deploy, the Signing Client, or the site's review flow through bb preview --open.

Related#

• Create a Collection
• Analyze
• Deploy
• Standards