Tokens

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

The model

A fungible holding is a set of one-satoshi tips, each carrying an integer amount in base units. The wallet keeps them in storage basket bsv21, and a balance is the sum of the tips it holds for one token id.

Concept	Value
Token id	The deploy output’s outpoint, normalized as `<txid>_<vout>`
Tip	A one-satoshi output carrying an amount of that token
Amount	An integer in base units, as a string — apply `dec` only for display

The fungible-token path is BSV-21 with BRC-162 binary value locks. It provides the scaling model for token balances and transfers; there is no separate 1Sat fungible-token product surface. Token calls always prompt, and token view is a separate grant from item view.

Read balances

Basket	Required tag
`p bsv21 all`	none
`p bsv21 id`	`bsv21:<tokenId>`

const tokens = await wallet.listOutputs({
  basket: 'p bsv21 all',
  includeCustomInstructions: true,
  limit: 50,
  offset: 0
});

const robot = await wallet.listOutputs({
  basket: 'p bsv21 id',
  tags: [`bsv21:${tokenId}`],
  tagQueryMode: 'all',
  includeCustomInstructions: true,
  limit: 20
});

Sum the tips yourself; there is no per-token balance method. A third-party grant is an allowlist of token ids, so asking for all later never widens it — the user must approve each new token. listOutputs({ basket: 'bsv21' }) returns 400 USE_PBSV21_SCOPE.

Token vocabulary

Tag	Meaning
`bsv21`	Protocol marker
`bsv21:<tokenId>`	Token id, the preferred form
`amt:<integer>`	Face value of this tip in base units
`op:<op>`	`deploy+mint`, `deploy+auth`, `mint`, `auth`, `transfer`, or `burn`
`sym:<symbol>`	Ticker, lowercased, up to 32 characters
`dec:<0-18>`	Display decimals
`icon:<outpoint>`	Icon inscription output
`issuer:<pubkey>`	Compressed issuer public key
`cosign:<pubkey>`	Cosigner gate
`id:<key>`	Wallet-assigned row key — not the token id

`customInstructions`

A JSON mirror of the protocol operation, which the wallet uses to index and display the tip:

{
  "p": "bsv-20",
  "op": "transfer",
  "id": "<tokenId>",
  "amt": "2500",
  "sym": "ROBOT",
  "dec": 2,
  "issuer": "<pubkey>",
  "icon": "<outpoint>"
}

p must be bsv-20 for the mirror to parse. amt is required for any balance-bearing operation, dec may be 0–18, and maxSupply is accepted as local remittance metadata only — it is not part of the on-chain BRC-162 output. Authority-only operations (deploy+auth, auth) carry no holdings and are not counted as balance. Symbol and decimals are display metadata carried by the deploy and the remittance. They are not a consensus rule, so never trust a ticker as a unique identifier — the token id is the identity.

Mint a token

An identity-backed mint is a createAction with an output in basket bsv21 whose operation is deploy+mint, deploy+auth, or mint:

const { txid } = await wallet.createAction({
  description: 'Deploy and mint ROBOT',
  labels: ['bsv21', 'handcash-mint-token'],
  outputs: [
    {
      lockingScript: bsv21DeployMintScript, // BRC-162 binary value lock
      satoshis: 1,
      outputDescription: 'ROBOT deploy and mint',
      basket: 'bsv21',
      tags: ['bsv21', 'op:deploy+mint', 'sym:ROBOT', 'amt:1000000', 'dec:2'],
      customInstructions: JSON.stringify({
        p: 'bsv-20',
        op: 'deploy+mint',
        sym: 'ROBOT',
        amt: '1000000',
        dec: '2'
      })
    }
  ]
});

When the user approves, HandCash recognizes the mint as identity-backed and enriches it:

It writes the wallet’s identity key into the issuer: tag and customInstructions.
It appends a Sigma signature to the deploy locking script when the action’s first input is an output the wallet can attest to. Wallets that later see that signature show the token as issuer-attested.
It reuses an existing icon for the same issuer and symbol when you did not supply one.

The wallet does not build the script from your tags. A deploy with an amount of zero is an authority lock and is refused on the value path, and a mint that spends existing tips without inputBEEF fails rather than proceeding blind. The prompt is titled Mint token and shows the symbol, the supply, and that Pay and auto-pay do not cover it.

Transfer tokens

const { txid } = await wallet.createAction({
  description: 'Send 25 ROBOT',
  labels: ['bsv21', 'send-token'],
  inputBEEF: tokenInputBeef,
  inputs: selectedTips.map((tip) => ({
    outpoint: tip.outpoint,
    inputDescription: 'ROBOT tip',
    unlockingScript: tip.unlockingScript
  })),
  outputs: [
    {
      lockingScript: recipientTransferScript,
      satoshis: 1,
      outputDescription: 'ROBOT transfer'
      // No sender basket: this tip belongs to the recipient.
    },
    {
      lockingScript: changeTransferScript,
      satoshis: 1,
      outputDescription: 'ROBOT change',
      basket: 'bsv21',
      tags: ['bsv21', `bsv21:${tokenId}`, 'amt:7500', 'sym:ROBOT', 'dec:2'],
      customInstructions: JSON.stringify({
        p: 'bsv-20',
        op: 'transfer',
        id: tokenId,
        amt: '7500',
        dec: 2
      })
    }
  ]
});

Invariants the wallet enforces, and your app must respect:

Conservation per token id — base units out never exceed base units in. Never round.
Change is mandatory when the selected tips exceed the amount you are sending. Dropping it destroys value.
Every tip is one satoshi.
The payee output carries no sender basket; only your change output goes back into bsv21.
Parent bodies must be provable. Supply inputBEEF covering the spent tips, or verification fails closed.
Cosigned tips do not spend with a plain unlock, and covenant-locked tips are refused outright.

Failures are named rather than silent: insufficient units, a zero-amount authority spend, an invalid recipient, missing source transactions, conservation mismatches, and BRC-176 prove failed all surface as errors instead of a downgraded transaction.

Burn tokens

A burn destroys base units: it spends tips, emits no payee token output, and optionally returns change to the holder. The satoshis behind the burned tips are recovered to the wallet. Burn amounts must be positive integers.

Receive tokens

const { accepted } = await wallet.internalizeAction({
  tx: atomicBeef,
  description: 'Receive 25 ROBOT',
  labels: ['bsv21', 'receive-token'],
  outputs: [
    {
      outputIndex: 2,
      protocol: 'basket insertion',
      insertionRemittance: {
        basket: 'bsv21',
        tags: ['bsv21', `bsv21:${tokenId}`, 'amt:2500', 'sym:ROBOT', 'dec:2'],
        customInstructions: JSON.stringify({
          p: 'bsv-20',
          op: 'transfer',
          id: tokenId,
          amt: '2500',
          sym: 'ROBOT',
          dec: 2
        })
      }
    }
  ]
});

The named output must be one satoshi, must pay the wallet, and must decode as a BRC-162 value lock matching the same token id and amount. Anything else is refused with a named reason such as an ambiguous token output or no token tip paying this wallet.

Verification

Token provenance is a BRC-176 walk: from a tip back to a fixed-supply deploy, checking that inputs cover outputs for that token id in every transaction along the way. It fails closed on a missing parent body, an over-transfer, a cycle, or an authority output. What that means for your app:

A tip the wallet produced on a send carries a proven subject BEEF.
Listing a holding does not prove it. Treat issuerAttested as an attestation that a signature matches the claimed issuer’s address, not as a full supply audit.
A token with no symbol is displayed by a truncated token id, so ship a sym: tag if you want a readable name.

Release a tip

await wallet.relinquishOutput({
  basket: 'p bsv21 all',
  output: tokenOutpoint
});

This drops local tracking only — it does not spend or destroy the output — and prompts as Release token.

Not available to apps

Attempt	Result
`listOutputs({ basket: 'bsv21' })`	`400 USE_PBSV21_SCOPE`
`getTokenIcon`	HandCash hosts only, `403 MARKET_ORIGIN_DENIED`
Auto-pay covering a token mint, send, or release	Always prompts
Cosigned token sends through the wallet’s own path	Not wired yet
Treating a row `id:` tag as the token id	Wrong key; use `bsv21:<tokenId>`

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 balances

Token vocabulary

Tags

`customInstructions`

Mint a token

Transfer tokens

Burn tokens

Receive tokens

Verification

Release a tip

Not available to apps

Next steps

​The model

​Read balances

​Token vocabulary

​Tags

​customInstructions

​Mint a token

​Transfer tokens

​Burn tokens

​Receive tokens

​Verification

​Release a tip

​Not available to apps

​Next steps

The model

Read balances

Token vocabulary

Tags

`customInstructions`

Mint a token

Transfer tokens

Burn tokens

Receive tokens

Verification

Release a tip

Not available to apps

Next steps