---
name: bsv-tokens
description: "Design or implement tokens on BSV: reading a token balance from one basket, receiving a token into a basket with internalizeAction, showing what a token is, where it came from and whether it is real, issuing one, and stablecoins. Use when asked to 'show a token balance', 'display an NFT', 'receive a token', 'mint a token', 'issue a stablecoin', '1Sat Ordinals', 'BSV-21', 'STAS', or anything about tokens in a BSV product."
---

> Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

# Show, receive and issue BSV tokens

**Scope:** Tokens as outputs: access through a basket, the four things to show, receiving, issuing and stablecoins.

**Does NOT cover:**

- Writing arbitrary data on chain: see [bsv-on-chain-data](../bsv-on-chain-data/SKILL.md)
- Asking for wallet access generally: see [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md)

**Cross-references:** [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md), [bsv-on-chain-data](../bsv-on-chain-data/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

A token on BSV is a specific output the wallet holds, with a chain of ownership back to its issue, moved the way a payment is moved. No contract can move it, so there is no token approval to grant. The wallet keeps tokens in a basket, apart from spending money, so they cannot be spent as fees or swept into a payment, and an app asks for one basket rather than the whole wallet. The families in use are 1Sat Ordinals (BRC-159, BRC-160) with BSV-21 as its fungible side (BRC-161), and STAS, which puts more of the rules in the script.

## ALWAYS

- Treat the supply decision as final in the interface, because it is. A field labelled "Supply" with no warning is a trap. _([costs money](https://www.bitcoinsv.design/guide/rule/d20dfe7b12/))_
- Show provenance as a short human sentence before a trade or a transfer: "Issued by Example Studio, 3 owners since, unbroken." The full chain belongs behind that line, not in front of it. _([costs trust](https://www.bitcoinsv.design/guide/rule/3d6d023dfe/))_
- Resolve the real-or-fake question for the user rather than printing an ID and hoping. Match against issuers they already trust, and say plainly when you cannot. _([costs trust](https://www.bitcoinsv.design/guide/rule/032bc32a78/))_
- Say what is being written on chain, that it cannot be edited later, and what it costs. The cost is a fraction of a penny, which is worth saying out loud because people expect otherwise. _([costs trust](https://www.bitcoinsv.design/guide/rule/19b03c2390/))_
- Name the issuer wherever the balance appears, not only at acquisition. "120 GBP, issued by Example Trust" is the honest form. _([costs trust](https://www.bitcoinsv.design/guide/rule/df5ae6683e/))_
- Choose by what you need enforced on chain rather than by what is popular. A loyalty point and a regulated instrument are not the same design problem, and the stricter family exists for the second. _([rule](https://www.bitcoinsv.design/guide/rule/88096862ab/))_

## NEVER

- Ask for broad wallet access in order to read a token balance. Ask for the basket. An app that wants everything in order to show one number is the reason permission screens get ignored. _([costs trust](https://www.bitcoinsv.design/guide/rule/468c1a74fb/))_
- Show a token's picture at the size of a decision without the provenance beside it. The picture is the part that is trivial to fake. _([costs trust](https://www.bitcoinsv.design/guide/rule/3ad9441a9c/))_
- Draw a stablecoin balance in the same type as a BSV balance with no distinction. One is a bearer asset and the other is a claim on a company. _([costs trust](https://www.bitcoinsv.design/guide/rule/ab34f1e402/))_

## Patterns

_Design guidance in each pattern comes from the guide page it cites. Method names, arguments and code are implementation notes checked against `@bsv/sdk` 4.0.0._

### 1. Read a balance from one basket

**When:** The app shows the user's tokens.

**How:**

1. Ask for the basket your token lives in, not broad wallet access. An app that wants everything to show one number is why permission screens get ignored.
2. Call `listOutputs({ basket, include: 'locking scripts' })` and decode the token data from the locking scripts.

```ts
import { WalletClient } from "@bsv/sdk";

const wallet = new WalletClient("auto", "example.com");
const { outputs } = await wallet.listOutputs({
  basket: "example tickets",
  include: "locking scripts",
  includeTags: true,
});
```

_Source: [Holding tokens](https://www.bitcoinsv.design/guide/patterns/holding-tokens/)_

### 2. Show the four things

**When:** Anywhere a token is shown at the size of a decision: before a trade, a transfer or an acceptance.

**How:**

1. What it is: a name and an image, which prove nothing because both can be copied.
2. Where it came from, as a short sentence before the full chain: "Issued by Example Studio, 3 owners since, unbroken."
3. Whether it is the real one: match against issuers the user already trusts and say plainly when you cannot. Do not print a token ID and hope.
4. What can be done with it: transferable, sellable, redeemable, or none of those.

_Source: [Holding tokens](https://www.bitcoinsv.design/guide/patterns/holding-tokens/)_

### 3. Receive a token into its basket

**When:** Somebody sends the user a token.

**How:**

1. Call `internalizeAction` with `protocol: 'basket insertion'` and an `insertionRemittance` naming the `basket` (and any `tags`) the token belongs in, so it stays out of the spending pot.
2. Show it with its provenance line, not just its picture.

_Source: [Holding tokens](https://www.bitcoinsv.design/guide/patterns/holding-tokens/)_

### 4. Issue a token, or hold a stablecoin

**When:** A product mints tokens, or shows a balance an issuer promises to redeem.

**How:**

1. Say what is being written on chain, that it cannot be edited later, and what it costs: less than 1p, worth saying because people expect otherwise.
2. Treat the supply decision as final in the interface. A field labelled "Supply" with no warning is a trap.
3. For a stablecoin, name the issuer wherever the balance appears: "120 USD, issued by Example Trust". Never draw it in the same type as a BSV balance; one is a bearer asset, the other a claim on a company.

_Source: [Holding tokens](https://www.bitcoinsv.design/guide/patterns/holding-tokens/)_

## All the rules

`references/rules.md`: 9 rules from 1 page, 8 of them costly, most costly first.
Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json

## Implementation resources

- **[@bsv/brc100-ui-react-components](https://github.com/bsv-blockchain/brc100-ui-react-components)**: React components the reference wallets use for permission prompts: ProtocolPermissionHandler, SpendingAuthorizationHandler, BasketAccessHandler, CertificateAccessHandler, GroupPermissionHandler and AccessAtAGlance.
- **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk.
- **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app.
- **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number.

---

_Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._