Bolt Protocol

Bolt Protocol unlocks seamless Bitcoin utility across the Stacks ecosystem. By enabling users to pay fees directly in sBTC, Bolt removes the friction of dual-token systems and brings pure-Bitcoin flow to smart contracts, games, and dApps. No STX required. No extra steps. Just Bitcoin — fast, efficient, and secure.

Power your app with Bolt. Build for the Bitcoin era.

Website: https://boltproto.org/

Executive Summary

Bolt Protocol makes Bitcoin work effortlessly on Stacks by letting you pay fees and transfer funds using only sBTC—like using cash directly instead of converting currencies first. This solves key issues like needing extra tokens for fees and waiting for confirmations. We've launched with core features, including a smart contract on mainnet, API for integrations, and a demo wallet. It's designed for developers to build apps easily and for users to enjoy instant, secure transactions. Future plans include more token support and community governance. For quick starts, check the integration guides or demo video.

Glossary

To make this documentation accessible, here's a quick guide to key terms:

sBTC: A token that represents Bitcoin on the Stacks blockchain, like a digital wrapper allowing Bitcoin to be used in smart contracts without leaving the Bitcoin ecosystem.
STX: The native token of the Stacks blockchain, typically used for transaction fees (like gas on Ethereum).
Stacks: A blockchain layer that builds on Bitcoin for smart contracts and apps, enabling programmable features while securing with Bitcoin.
dApp: Decentralized application—a web app that runs on blockchain, like a banking app but without a central authority.
Smart Contract: Self-executing code on the blockchain that automates agreements, like a vending machine that dispenses items once payment is made.
SIP-10: A standard for fungible tokens on Stacks, similar to ERC-20 on Ethereum.
Non-Custodial: Users keep full control of their funds and keys; no third party can access them without permission.
Operator: A coordinator that handles transaction processing securely, like a trusted relay in a network.
MicroSTX: A small unit of STX (1 STX = 1,000,000 microSTX), used for precise fee calculations.

If you're new to blockchain, think of Bolt Protocol as a bridge: it connects Bitcoin's security with Stacks' smart features, making everything feel as simple as sending an email.

Overview

Bolt Protocol solves two critical pain points for Stacks users:

Pay transaction fees with sBTC: Users no longer need to hold STX to pay for transactions. All fees can be paid directly in sBTC—like using your main currency without exchanging it first.
Instant transfers: Transactions between Bolt wallets are confirmed instantly, avoiding the typical Stacks blockchain confirmation times—similar to instant messaging versus waiting for postal mail.

Note: Bolt Protocol currently supports only sBTC. Support for other SIP-10 tokens will be added in future releases.

We offer a Bolt Wallet implementation on our website for users to use:

Bolt Wallet: https://boltproto.org/wallet

Note: This is a Bolt Wallet implementation (dApp) to transfer sBTC between wallets (instant transfers and Stacks transfer). To pay transaction fees in other dApps using sBTC, you'll need a wallet that integrates with Bolt Protocol like "Wallet Extension".

Wallet Extension Github Repository

Note: The current version of this extension is just a proof of concept for the Bolt Protocol integration, allowing you to pay transaction fees with sBTC on the Stacks Blockchain.

How Bolt Protocol Works

The architecture shows how Bolt Protocol serves as a layer between dApps, wallets, and the blockchain:

dApps connect directly to Bolt Protocol through the API or via wallet integrations.
Wallets can integrate with Bolt to provide sBTC fee payment capabilities.
The Operator handles three core functions:
- Standard sBTC transfers.
- Instant sBTC transfers between Bolt wallets.
- sBTC transaction fee payment for any contract.
Smart Contract provides the secure foundation for all operations.

This design allows users to interact with any Stacks dApp while paying fees in sBTC instead of STX, creating a seamless Bitcoin-native experience.

User Stories

To illustrate real-world use:

As a user new to Stacks: I can deposit sBTC into my Bolt Wallet and send it instantly to a friend without worrying about STX fees—like Venmo but on Bitcoin.
As a dApp developer: I can integrate Bolt so my game's players pay entry fees in sBTC, making onboarding easier and boosting adoption.
As a wallet provider: I add Bolt support to let users interact with any Stacks contract using only sBTC, reducing support tickets about token confusion.

Demo Video

Watch our demonstration video that showcases how Bolt Protocol enables seamless Bitcoin transactions on the Stacks blockchain:

How It Works

The Bolt Wallet lets you connect any Stacks wallet and experience the benefits of the protocol:

Deposit: Transfer your sBTC to your Bolt Wallet.
Transfer: Send sBTC between Bolt Wallets instantly.
Withdraw: Move your tokens back to your Stacks wallet.

All operations within the dApp require only sBTC—no STX is needed for transaction fees.

Integration Overview

Bolt Protocol enables two main integration paths for developers and wallets:

1. Native sBTC Transfers (Bolt Contract Functions)

Use Bolt Protocol's smart contract to transfer sBTC between wallets, with fees paid in sBTC and enable instant transfers.

See Native sBTC Transfer Guide for example usage.

2. Enable Users to Pay Transaction Fees with sBTC for Any Contract

Integrate Bolt Protocol into your wallet to allow users to pay transaction fees with sBTC (instead of STX) for any contract call on the Stacks blockchain. This enables a seamless experience where users never need STX for gas, even when interacting with third-party contracts. Users must deposit sBTC into their Fee Fund to use this feature.

See How to Enable Users to Pay Transaction Fees with sBTC in Your Wallet on Stacks for integration steps.

Integration Details

For Wallets

Wallets can integrate Bolt Protocol to:

Allow users to pay transaction fees with sBTC instead of STX.
Enable instant sBTC transfers between Bolt wallets.

Refer to the guides above for implementation details. Template for integration code:

// Example: Wallet Integration Snippet
async function payWithSBTC(tx) {
  const feeInSBTC = await calculateSBTCFee(tx);
  // Submit to Bolt API
  return await boltAPI.submitTransaction(tx, feeInSBTC);
}

For dApps

dApps can support Bolt Protocol directly, enabling users to pay fees in sBTC even if their wallet does not natively support Bolt. This reduces onboarding friction and simplifies UX for users who only hold sBTC.

Example: dApp Integration Snippet

// Calculate and display sBTC fee for a transaction
async function displayFeeInSBTC(tx) {
  const feeInMicroSTX = await estimateFee(tx);
  const feeRate = await getSBTCFeeRate();
  const feeInSBTC = feeInMicroSTX / feeRate;
  console.log(`Fee: ${feeInSBTC} sBTC`);
}

Key Features

Instant Transfers: Near real-time confirmed transactions.
Trustless Verification: Users can independently verify operator-processed transactions on Stacks.
No Separate Gas Token: Pay fees in sBTC, no need for STX.
Non-Custodial: Funds cannot move without the user’s signature.
Smart Contract: Enforces rules and enables fast verification and on-chain persistence.
Operator Model: Coordinates finalization of transactions on Stacks.
No Channel Required: No payment channels required.

Main functions of the Smart Contract (v2)

Contract address on Mainnet:

SP3QZNX3CGT6V7PE1PBK17FCRK1TP1AT02ZHQCMVJ.boltproto-sbtc-v2

Contract address on Testnet:

ST3QZNX3CGT6V7PE1PBK17FCRK1TP1AT02W1N0YJF.boltproto-sbtc-rc-2-0-0

Contract Functions: Native sBTC Transfers

These functions are sponsored by the Bolt Protocol operator, allowing users to pay fees in sBTC instead of STX. All sponsored functions must be submitted through the Bolt API.

See example implementation: cookbook/transfer-stacks-to-stacks.md

Transfer Function Matrix:

From \ To	Bolt Wallet	Stacks Wallet
Bolt Wallet	transfer-bolt-to-bolt	transfer-bolt-to-stacks
Stacks Wallet	transfer-stacks-to-bolt	transfer-stacks-to-stacks

All sponsored functions share the same parameter structure:

;; Parameters for all sponsored functions:
;;   amount: uint                   The transfer amount.
;;   recipient: principal           The destination wallet.
;;   memo: (optional (buff 34))     Optional memo.
;;   fee: uint                      Fee amount in sBTC (min 10 satoshis)
(function-name 
    (amount uint)
    (recipient principal)
    (memo (optional (buff 34)))
    (fee uint))

Function descriptions:

transfer-bolt-to-bolt: Transfer between Bolt Protocol wallets
transfer-bolt-to-stacks: Transfer from Bolt Protocol to Stacks wallet
transfer-stacks-to-bolt: Deposit from Stacks wallet to Bolt Protocol
transfer-stacks-to-stacks: Direct transfer between Stacks wallets

Enable Users to Pay Transaction Fees with sBTC for Any Contract

Bolt Protocol enables wallets to let users pay transaction fees in sBTC for contract calls to any Stacks smart contract, not just Bolt’s. Users must deposit sBTC into their Fee Fund to use this feature.

See: guides/pay-fee-with-sbtc.md

Bolt API (v1)

API Endpoints:

Mainnet: https://boltproto.org/api/v1
Testnet: https://test.boltproto.org/api/v1

Get Wallet Balance

GET /api/v1/wallet/:address/:token/balance

Example: GET https://boltproto.org/api/v1/wallet/ST3QZNX3CGT6V7PE1PBK17FCRK1TP1AT02W1N0YJF/sbtc-token/balance

Response:

{
  "address": "<address>",
  "balance": "1000000"
}

Get Transaction History

GET /api/v1/wallet/:address/:token/transactions

Example: GET https://boltproto.org/api/v1/wallet/ST3QZNX3CGT6V7PE1PBK17FCRK1TP1AT02W1N0YJF/sbtc-token/transactions

Response:

{
  "items": [
    {
      "txId": "faac8c81f79a7740341861dc689b03809145c3756450881018c8fa4859fe8495",
      "token": "sbtc-token",
      "amount": "1000000",
      "fee": "10",
      "sender": "ST3QZNX3CGT6V7PE1PBK17FCRK1TP1AT02W1N0YJF",
      "recipient": "ST3QZNX3CGT6V7PE1PBK17FCRK1TP1AT02W1N0YJF",
      "functionName": "transfer-bolt-to-stacks",
      "timestamp": {}
    }
  ],
  "totalItems": 1,
  "totalPages": 1,
  "currentPage": 1
}

Fee Calculation in sBTC

Get the estimated fee in microSTX for your contract call.
Fetch the current fee rate: GET https://boltproto.org/api/v1/transaction/sbtc-token/fee-rate Example response: {"feeRate": 200}
Calculate: sBTC fee (sats) = estimated fee in microSTX / feeRate

Example: 4,000 microSTX / 200 = 20 sats

Submit Transaction

POST /api/v1/transaction/sbtc-token

Request Body:

{ "serializedTx": "<serializedTx>" }

Response:

{ "txid": "5bed517eb7b58082d39df49240b75f1246584cd56a1b1af69c64295b86334291" }

Roadmap

✅ Phase 1: MVP & Core Infrastructure

Implement Bolt Protocol smart contracts on Stacks
Enable sBTC as gas (pay fees in sBTC, not STX)
Release Bolt Wallet demo with instant sBTC transfers
Open-source reference integrations for developers

⚙️ Phase 2: Developer Ecosystem & Wallet Integrations

Launch Portal (docs, showcase, access points)
Track usage metrics
Launch demo apps: Block Constellation — first 100% sBTC game
Add support for wallet integrations (Boom, Xverse, Leather...) (in progress)
Community outreach to align with Stacks app developers

🌐 Phase 3: Ecosystem Expansion & Incentivization

Launch Bolt DAO for governance and upgrades
Enable staking & rewards
Onboard partner apps: DeFi, marketplaces, tools
Launch incentive program for developers (grants, rewards)
Gamified ecosystem incentives (e.g. XP for transactions)
Promote Bolt + Stacks as a Lightning Alternative for Bitcoin scaling
Run hackathons and workshops for new use cases

🌍 Phase 4: Multi-Token Support

Expand Bolt Protocol to support other tokens (e.g. USDh, stablecoins)

Contact Us

X (Twitter): https://x.com/boltprotobtc

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
bolt-protocol-contracts		bolt-protocol-contracts
bolt-protocol-ui-demo		bolt-protocol-ui-demo
cookbook		cookbook
guides		guides
LICENSE		LICENSE
README.md		README.md
bolt-protocol-diagram.jpg		bolt-protocol-diagram.jpg

License

ronoel/bolt-protocol

Folders and files

Latest commit

History

Repository files navigation

Bolt Protocol

Table of Contents

Executive Summary

Glossary

Overview

How Bolt Protocol Works

User Stories

Demo Video

How It Works

Integration Overview

1. Native sBTC Transfers (Bolt Contract Functions)

2. Enable Users to Pay Transaction Fees with sBTC for Any Contract

Integration Details

For Wallets

For dApps

Example: dApp Integration Snippet

Key Features

Main functions of the Smart Contract (v2)

Contract Functions: Native sBTC Transfers

Enable Users to Pay Transaction Fees with sBTC for Any Contract

Bolt API (v1)

Get Wallet Balance

Get Transaction History

Fee Calculation in sBTC

Submit Transaction

Roadmap

✅ Phase 1: MVP & Core Infrastructure

⚙️ Phase 2: Developer Ecosystem & Wallet Integrations

🌐 Phase 3: Ecosystem Expansion & Incentivization

🌍 Phase 4: Multi-Token Support

Contact Us

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages