Tokens

Beta — BRC wallet only. Desktop / Mobile over BRC-100.

The model

HandCash tokens are Bitcoin Native Tokens (BNT), the open mode of the BRC-255 draft. The holder’s signature alone moves an output, and the recipient checks every hop back to the deploy, so no indexer or issuer is trusted.

Concept	Value
Asset id	40 hex characters, fixed at deploy
Kind	`token` (fungible) or `item` (a supply-1 deploy)
Amount	A whole number of base units, as a string — apply `dec` only for display
Filing	Tokens in `bntft`, items in `bntnft`; rows are tagged `bntft:<assetId>` or `bntnft:<assetId>`

The wallet builds, signs, and checks every BNT transaction itself. Apps ask for it with the four methods below and never write, spend, or relinquish a BNT output directly.

BSV-21 / BRC-162 tokens are not supported. Requests that name the bsv21 basket, carry bsv21 tags, or contain a BRC-162 lock return 400 ASSET_PROTOCOL_RETIRED, and p bsv21 … baskets return 400 UNSUPPORTED_P_BASKET.

Read holdings

listBntAssets returns every open asset this wallet holds, with its balance and supply policy:

const { assets } = await wallet.listBntAssets();
// [{ assetId, kind, mode, sym, name, dec, issuers, balance, outputs, authority, deploy, imageUrl, supply }]

To list the outputs behind a holding, use a token view basket. Token view is its own grant, separate from item view; a denied prompt returns 403 TOKEN_VIEW_DENIED.

Basket	Required tag
`p bntft all`	none
`p bntft token`	`bntft:<assetId>`
`p bntft id`	`id:<key>`

const rows = await wallet.listOutputs({
  basket: 'p bntft token',
  tags: [`bntft:${assetId}`],
  include: 'entire transactions'
});

BNT items are read through the item grant with p bntnft … and the same scopes as p 1sat … — see Collectables.

Issue

const { assetId, txid } = await wallet.issueBntAsset({
  kind: 'token',
  sym: 'ROBOT',
  supply: '1000000',
  dec: 2
});

A token needs sym; an item needs name, has a supply of exactly 1, and may carry content and a collection (the asset id of a token whose authority you hold). The supply policy is fixed at deploy:

Policy	Arguments	Minting
Fixed	no `auth`, `max`, or `size`	refused with `fixed-supply`
Open	`auth: true`	any amount
Capped	`max` (units, supply included) and/or `size` (collection members)	up to the cap, then `over-cap`
Open mint	`openMint: { count, amount }` on a token	anyone, `amount` units at a time, `count` times

Only open mode is issued today; mode other than 'open' is refused.

Mint

await wallet.mintBntAsset({ assetId, amount: '5000' });

For an open-mint token you do not issue, pass deploy (txid_vout) when this wallet has never seen the asset, or tip (any mint, txid.vout); the wallet follows its spends to the newest mint.

Send

await wallet.transferBntAsset({
  assetId,
  recipient: recipientIdentityKey,
  amount: '7500'
});

The recipient is an identity key. The wallet delivers the transfer and its proof to the recipient’s bnt message box, and the recipient’s wallet checks it before filing. There is no internalizeAction step for the receiving app.

Prompts and errors

Issue, mint, and send each show the user an approval prompt. A refusal before anything is staged returns 400 BNT_<REASON>, for example BNT_BAD_ASSET_ARGS, BNT_FIXED_SUPPLY, BNT_OVER_CAP, or BNT_UNSUPPORTED_MODE.

Attempt	Result
`createAction` spending a BNT output	`400 BNT_WALLET_ONLY` — use `transferBntAsset`
`listOutputs({ basket: 'bntft' })`	`400 USE_TOKEN_SCOPE`
`p bntft token` without a `bntft:` tag	`400 MISSING_TOKEN_SCOPE_TAG`
Writing into `bntft` or `bntnft`	Refused; only the wallet files BNT outputs
Countersigned (`iptft` / `iptnft`) transfers	Not supported yet

Get Started

BRC wallet (Beta)

v3 / Getting Started

v3 / Connect

v3 / Payments

v3 / Items

v3 / Business Wallet

v2 / Item Operations

v2 / Collection Management

v2 / Friends

API / Payment Requests

Wallet API / Whitelabel Services

The model

Read holdings

Issue

Mint

Send

Prompts and errors

Next steps

​The model

​Read holdings

​Issue

​Mint

​Send

​Prompts and errors

​Next steps

The model

Read holdings

Issue

Mint

Send

Prompts and errors

Next steps