tokens

Token Operations (BSV21)

Send, list, deploy, and mint BSV21 tokens with @1sat/actions. CLI group is bsv21 (was tokens).

Actions

Action	Description
listBsv21	List BSV21 token UTXOs
getBsv21Balances	Aggregated balances by token ID
sendBsv21	Send by value (tokenId + amounts + destinations)
buyBsv21	Buy marketplace OrdLock listing
deployBsv21Mint	Fixed-supply deploy+mint
deployBsv21Auth	Mintable deploy+auth
mintBsv21	Spend auth to mint / re-issue / end

Fungible API stays value-based (not spend-by-id). Basket UTXOs still carry id: internally. Self destinations must be basketed/tagged.

Balances

import { getBsv21Balances, createContext } from '@1sat/actions'

const ctx = createContext(wallet, { services })
const balances = await getBsv21Balances.execute(ctx, {})

for (const token of balances) {
  const displayAmt = Number(BigInt(token.amt)) / 10 ** token.dec
  console.log(`${token.sym ?? token.id}: ${displayAmt}`)
}

List UTXOs

import { listBsv21 } from '@1sat/actions'

const outputs = await listBsv21.execute(ctx, { limit: 100 })
// tags: bsv21:{tokenId}, amt:{amount}, dec:{decimals}, id:…

Send

import { sendBsv21 } from '@1sat/actions'

const result = await sendBsv21.execute(ctx, {
  tokenId: 'abc123...def456_0',
  recipients: [
    { amount: '1000000', destination: { counterparty: '02abc...' } },
    { amount: '500000', destination: { address: '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa' } },
  ],
})

Amounts are raw units (respect dec). Overlay validation requires services.

Buy listing

import { buyBsv21 } from '@1sat/actions'

await buyBsv21.execute(ctx, {
  tokenId: 'abc123...def456_0',
  outpoint: 'txid_vout',
  amount: '1000000',
  marketplaceAddress: '1Market...', // optional
  marketplaceRate: 0.02,
})

External UTXO: BEEF from services/overlay.

Deploy fixed supply

import { deployBsv21Mint } from '@1sat/actions'

const result = await deployBsv21Mint.execute(ctx, {
  symbol: 'MYTOKEN',
  amount: '2100000000000000',
  decimals: 8,
  icon: 'iconTxid_0',
})
// result.tokenId

Deploy mintable + mint

import { deployBsv21Auth, mintBsv21 } from '@1sat/actions'

const dep = await deployBsv21Auth.execute(ctx, { symbol: 'MINTABLE', decimals: 8 })

await mintBsv21.execute(ctx, {
  tokenId: dep.tokenId!,
  mint: { amount: '1000000', destination: { address: recipient } },
})

Requirements

bun add @1sat/actions @1sat/wallet @1sat/templates @bsv/sdk