# Smart Tokens and existing vaults

`Smart Token` represents a token backed by an existing chain coin. Deposit and withdrawal use the coin-backed path and reserved backing address. This page covers the shipping Smart Token and `Vault` builders; it does not include the paused Agent Vault standard.

## Configuration and variants

| Builder | Options | Behavior |
| --- | --- | --- |
| `bb build smart-token` | `--backing-coin`, optional `--symbol` | Creates a backed token with deposit and withdrawal approvals |
| Same builder | `--tradable` | Adds the `Liquidity Pools` capability for pool trading |
| Same builder | `--allow-forceful-transfers` | Explicitly permits forceful post-mint transfer capability; default disables it |
| `bb build vault` | `--backing-coin`, optional `--symbol` | Creates the existing `Smart Token` + `Vault` variant with frozen collection permissions |
| Vault | `--daily-withdraw-limit` | Caps withdrawal amounts per initiating address in daily reset intervals |
| Vault | `--require-2fa <collection-id>` | Requires current ownership of token ID 1 in the specified collection for withdrawal |
| Vault | `--emergency-recovery <address>` | Adds a recovery-address-authorized forceful migration approval |

```bash
bb build smart-token --backing-coin USDC --symbol vUSDC \
  --creator "$CREATOR" --uri "$METADATA_URI"
bb build vault --backing-coin USDC --daily-withdraw-limit 100 \
  --creator "$CREATOR" --uri "$METADATA_URI"
bb smart-tokens show "$COLLECTION_ID"
bb smart-tokens status "$COLLECTION_ID"
```

A daily limit uses backing-coin display units at construction and is converted to base units. It is per initiator, not a global reserve limit or necessarily a holder limit. The generated schedule starts at the next UTC midnight and repeats every 86,400,000 milliseconds. Before that first reset, the initial tracker interval applies. Separate approvals have separate counters even if their tracker labels match.

The existing `--ai-agent-vault` Smart Token flag is only a discovery tag. It does not add agent delegation, spending policies, or the paused Agent Vault behavior. Emergency recovery is a substantive trust decision: the designated address can move holders' tokens. It is not merely a contact field.

## Lifecycle and state

`bb smart-tokens list`, `show`, and `status` expose recognized collections. Use `bb smart-tokens deposit <collection-id> --creator <address> --amount <n>` or `bb smart-tokens withdraw <collection-id> --creator <address> --amount <n>`. Both interpret amounts as display units by default and accept `--base-units` for raw integers. There is no separate `bb vaults` action group. Generic Smart Token actions are applicable only when their validator accepts the actual vault configuration; extra withdrawal gates may require matching proof or authorization inputs.

Depositing locks backing coins and obtains the backed token. Withdrawing returns tokens through the backing path and releases backing coins, subject to the approval and user authorization checks. These are not invoice payments: inspect reserve state, token balances, and the backing invariant rather than a payment completion tracker.

The vault deposit and withdrawal approvals use backed-minting authorization, not forceful overrides of the reserved backing address. The vault disables pool creation and freezes permissions. Existing aliases/wrapper denominations must satisfy chain naming and uniqueness rules; a display symbol is not proof that a new denomination is available.

Review [Smart Token primitives](https://docs.bitbadges.io/agents/skills/smart-token), [coin wrapper paths](https://docs.bitbadges.io/token-standard/ibc/cosmos-coin-wrapper-paths), [invariants](https://docs.bitbadges.io/token-standard/approval-criteria/invariants), [ownership gates](https://docs.bitbadges.io/token-standard/approval-criteria/token-ownership), and [liquidity pools](https://docs.bitbadges.io/standards/markets). Validate the actual backing path and approval shape before treating a tagged collection as redeemable.

## Smart Token JSON

Save the following input as `smart-token.json`, replace the demo addresses and metadata, then build it with the CLI command below. `backingCoin` resolves a supported backing denomination. `symbol` configures the wrapper display path. `tradable` adds the pool capability; it does not create a funded pool. The forceful-transfer flag controls the invariant, not a particular delegated payment permission.

<!-- sdk-example: buildSmartToken -->
```json
{
  "backingCoin": "BADGE",
  "symbol": "vBADGE",
  "tradable": true,
  "allowForcefulPostMintTransfers": false,
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build smart-token --json smart-token.json \
  --backing-coin "$(jq -r '.backingCoin' smart-token.json)" \
  --creator "$CREATOR" --output-file smart-token-proposal.json
```

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildSmartToken`.

## Vault JSON

Save the following input as `vault.json`, replace the demo addresses and metadata, then build it with the CLI command below. `dailyWithdrawLimit` is a display-unit number per initiating address per reset interval; zero means unlimited. Optional `require2fa` is a collection ID string and `emergencyRecovery` is an address. Those fields add authorization paths and must be reviewed explicitly.

<!-- sdk-example: buildVault -->
```json
{
  "backingCoin": "BADGE",
  "symbol": "vBADGE",
  "dailyWithdrawLimit": 100,
  "uri": "https://example.com/metadata.json"
}
```

```bash
bb build vault --json vault.json \
  --backing-coin "$(jq -r '.backingCoin' vault.json)" \
  --creator "$CREATOR" --output-file vault-proposal.json
```

The repeated required flags are read from the same JSON file because CLI argument validation runs before loading JSON. Review the resulting proposal using the [CLI lifecycle](https://docs.bitbadges.io/standards/lifecycle). SDK reference: `buildVault`.

## IBC Token Factory

The frontend's `IBC Token Factory` template creates a token with a Cosmos coin wrapper path. It is distinct from the Smart Token's existing-coin backing invariant. A wrapper converts collection token balances into a corresponding chain coin denomination; it does not by itself make the asset backed by USDC or another external reserve.

The `/mint/ibc-token` form uses token ID 1, mint and wrapper approvals, a one-to-one conversion path, `allowSpecialWrapping: true`, and no manager. Its wrapper path defines denomination metadata and conversion balances. Use generic collection/session tools and the [wrapper path reference](https://docs.bitbadges.io/token-standard/ibc/cosmos-coin-wrapper-paths) for SDK construction; the CLI has no `bb build ibc-token` command.

The following **field fragment** identifies the capability; it is not the complete collection. The required approvals and `cosmosCoinWrapperPaths` configuration must also be present and validated.

```json
{
  "standards": ["IBC Token Factory"],
  "validTokenIds": [{ "start": "1", "end": "1" }],
  "invariants": { "allowSpecialWrapping": true }
}
```

Inspect both the original collection balance and the wrapped coin balance when reconciling conversions. A symbol is not a denomination identifier, and denomination paths must satisfy chain naming/uniqueness requirements. An IBC-compatible representation is not evidence that a cross-chain transfer or remote-chain registration has completed.