sBTC token operations on Stacks L2 — check balances, transfer sBTC, get deposit info, check peg statistics, deposit BTC to receive sBTC, and track deposit status. Transfer and deposit operations require an unlocked wallet.
Provides sBTC (wrapped Bitcoin on Stacks L2) operations. sBTC uses 8 decimals — the same as Bitcoin. Transfer and deposit operations require an unlocked wallet (use bun run wallet/wallet.ts unlock first). Balance and info queries work without a wallet.
bun run sbtc/sbtc.ts <subcommand> [options]
Get the sBTC balance for a Stacks address.
bun run sbtc/sbtc.ts get-balance [--address <addr>]
Options:
--address (optional) — Stacks address to check (uses active wallet if omitted)Output:
{
"address": "SP2...",
"network": "mainnet",
"balance": {
"sats": "100000",
"btc": "0.001 sBTC"
}
}
Transfer sBTC to a recipient. Requires an unlocked wallet.
sBTC uses 8 decimals. Specify --amount in satoshis (1 sBTC = 100,000,000 satoshis).
bun run sbtc/sbtc.ts transfer --recipient <addr> --amount <sats> [--memo <text>] [--fee low|medium|high|<microStx>] [--sponsored]
Options:
--recipient (required) — Stacks address to send to--amount (required) — Amount in satoshis (e.g., "100000" for 0.001 sBTC)--memo (optional) — Memo message to include--fee (optional) — Fee preset (low|medium|high) or micro-STX amount; auto-estimated if omitted--sponsored (flag) — Use fee sponsorship if availableOutput:
{
"success": true,
"txid": "abc123...",
"from": "SP2...",
"recipient": "SP3...",
"amount": "0 sBTC",
"amountSats": "100000",
"network": "mainnet",
"explorerUrl": "https://explorer.hiro.so/txid/abc123...?chain=mainnet"
}
Get information about how to deposit BTC to receive sBTC. If a wallet with Taproot keys is unlocked, returns a personalized deposit address. Otherwise returns general instructions.
bun run sbtc/sbtc.ts get-deposit-info
Output (with unlocked wallet):
{
"network": "mainnet",
"depositAddress": "bc1p...",
"maxSignerFee": "80000 satoshis",
"reclaimLockTime": "950 blocks",
"stacksAddress": "SP2...",
"instructions": [...]
}
Output (without wallet):
{
"network": "mainnet",
"depositAddress": "bc1p...",
"minDeposit": "...",
"maxDeposit": "...",
"instructions": [...]
}
Get sBTC peg information including total supply and peg ratio.
bun run sbtc/sbtc.ts get-peg-info
Output:
{
"network": "mainnet",
"totalSupply": {
"sats": "1000000000",
"btc": "10 sBTC"
},
"pegRatio": "1.000000"
}
Deposit BTC to receive sBTC on Stacks L2. Builds, signs, and broadcasts a Bitcoin transaction to the sBTC deposit address. After Bitcoin confirmation, sBTC tokens are minted to your Stacks address. Requires an unlocked wallet with Bitcoin and Taproot keys.
By default only uses cardinal UTXOs (safe to spend — no inscriptions).
bun run sbtc/sbtc.ts deposit --amount <sats> [--fee-rate fast|medium|slow|<number>] [--max-signer-fee <sats>] [--reclaim-lock-time <blocks>] [--include-ordinals]
Options:
--amount (required) — Amount to deposit in satoshis (1 BTC = 100,000,000 satoshis)--fee-rate (optional) — fast (~10 min), medium (~30 min), slow (~1 hr), or number in sat/vB (default: medium)--max-signer-fee (optional) — Max fee the sBTC system can charge in satoshis (default: 80000)--reclaim-lock-time (optional) — Blocks until reclaim becomes available if deposit fails (default: 950)--include-ordinals (flag) — Include ordinal UTXOs (WARNING: may destroy valuable inscriptions!)Output:
{
"success": true,
"txid": "btcTxid123...",
"explorerUrl": "https://mempool.space/tx/btcTxid123...",
"deposit": {
"amount": "0.001 BTC",
"amountSats": 100000,
"recipient": "SP2...",
"bitcoinAddress": "bc1q...",
"taprootAddress": "bc1p...",
"maxSignerFee": "80000 sats",
"reclaimLockTime": "950 blocks",
"feeRate": "5 sat/vB"
},
"network": "mainnet",
"note": "sBTC tokens will be minted to your Stacks address after Bitcoin transaction confirms."
}
Check the status of an sBTC deposit transaction via the Emily API.
bun run sbtc/sbtc.ts deposit-status --txid <btcTxid> [--vout <index>]
Options:
--txid (required) — Bitcoin transaction ID of the deposit--vout (optional) — Output index of the deposit (default: 0)Output:
{
"txid": "btcTxid123...",
"vout": 0,
"status": "pending",
"explorerUrl": "https://mempool.space/tx/btcTxid123...",
"network": "mainnet"
}
deposit command uses Bitcoin L1 — ensure you have BTC in your wallet's Bitcoin address