Use the Go SDK
Use go-sdk to build keys, scripts, transactions and proofs for the BSV blockchain in Go, from a signed P2PKHPay to Public Key Hash, the standard script that locks coins to an address transaction up to a BRC-100BSV Request for Comments 100, the standard interface between apps and wallets wallet interface and overlay servicesBuilt from topic managers, which decide what is admitted, and lookup services, which query what was admitted.. The docs and examples live in the Go repositories, and this page links them.
What the SDK includes
The module is github.com/bsv-blockchain/go-sdk. Each area below is a package under that path:
| Area | Packages |
|---|---|
| Keys and cryptography | primitives/ec, primitives/aesgcm, compat/bip32, compat/bip39, compat/ecies, message |
| Script and templates | script, transaction/template/p2pkh |
| Transactions and fees | transaction |
| Proofs | spv, with BEEFBackground Evaluation Extended Format (BRC-62), a transaction sent with its proofs support in transaction |
| Broadcasting and chain tracking | transaction/broadcaster, transaction/chaintracker |
| Wallet interface | wallet, with the BRC-100 interface and ProtoWallet |
| Authentication | auth |
| Overlay services, identity and storage | overlay, registry, identity, kvstore, storage |
Get started
Add the SDK to a Go module, then run a first program that signs a transaction and prints it, without touching the network.
Create a module and add the SDK
This page was written against go-sdk v1.7.3, which needs Go 1.26 or newer. In a new folder, create a module and add the SDK:
go mod init example.com/bsv-go
go get github.com/bsv-blockchain/go-sdkThe last line of the output names the version that was added:
go: creating new go.mod: module example.com/bsv-go
go: added github.com/bsv-blockchain/go-sdk v1.7.3Create main.go
Create main.go in the module folder. The program builds and signs a transaction on your computer, with a key, a locking scriptThe part of a transaction output that sets the condition to spend it, an input, an output and a signature. It makes no network call and spends no coins.
The program generates a private key on each run and never saves it. Keep a private key that holds real funds out of your source code and out of version control.
package main
import (
"fmt"
"log"
ec "github.com/bsv-blockchain/go-sdk/primitives/ec"
"github.com/bsv-blockchain/go-sdk/script"
"github.com/bsv-blockchain/go-sdk/transaction"
"github.com/bsv-blockchain/go-sdk/transaction/template/p2pkh"
)
func main() {
priv, err := ec.NewPrivateKey()
if err != nil {
log.Fatal(err)
}
address, err := script.NewAddressFromPublicKey(priv.PubKey(), false)
if err != nil {
log.Fatal(err)
}
lockingScript, err := p2pkh.Lock(address)
if err != nil {
log.Fatal(err)
}
unlocker, err := p2pkh.Unlock(priv, nil)
if err != nil {
log.Fatal(err)
}
tx := transaction.NewTransaction()
err = tx.AddInputFrom(
"0000000000000000000000000000000000000000000000000000000000000000",
0,
lockingScript.String(),
10000,
unlocker,
)
if err != nil {
log.Fatal(err)
}
if err := tx.PayToAddress(address.AddressString, 9000); err != nil {
log.Fatal(err)
}
if err := tx.Sign(); err != nil {
log.Fatal(err)
}
fmt.Println("Transaction ID:", tx.TxID())
fmt.Println("Raw hex:", tx.Hex())
}Run the program
In the module folder, run go mod tidy once, so Go records the packages the code imports. Without it, go run stops with a missing go.sum entry error. Then run the program:
go mod tidy
go run .The program prints the transaction ID and the signed transaction in hex. Both change on every run, because the key is new each time:
Transaction ID: 764d9d730e316b6eeb0d12c221f189d2f1a88a51d94c37c8b0b94da579b01e92
Raw hex: 0100000001000000000000000000000000000000000000000000000000000000000000000000000000...These parts of main.go need a closer look:
NewAddressFromPublicKey(priv.PubKey(), false)derives a testnet address from the public key.truegives a Mainnet address.AddInputFromdescribes the output the input spends: its transaction ID, its index, its locking script as a hex string and its value in satoshisThe smallest unit of BitcoinSV (BSV). 100,000,000 satoshis make 1 BSV.. Here the output exists only in the program, so the transaction ID is a placeholder of zeros. To spend a real output, use the values of one of your own UTXOsUnspent transaction output.p2pkh.Unlock(priv, nil)gives the input a signing template, andtx.Sign()signs every input that has one.PayToAddressadds an output of 9,000 satoshis. The 1,000 satoshis left between the input and the output are the fee.
A broadcast transaction cannot be undone, and the broadcaster examples in the repository send to Mainnet. Test on testnet before you use Mainnet.
To send a transaction, use a broadcaster from the transaction/broadcaster package. The transaction in main.go cannot be broadcast, because it spends an output that exists only in the program. The WhatsOnChain broadcaster takes a Network field, and broadcaster.WOCTestnet selects testnet. For the broadcaster BSV Association runs, see Broadcast transactions with BSV Broadcaster.
Find the docs and examples
The docs and examples live in the Go repositories, next to the code.
Docs and repositories
Start from these repositories and docs:
- go-sdk, with its README and releases.
- go-sdk docs, with
concepts,examplesandlow-levelfolders. - API reference on pkg.go.dev, generated from the code.
- go-wallet-toolbox, with its docs, for building BRC-100 wallets in Go.
- go-overlay-services, the overlay services engine in Go.
- go-402-pay, server middleware and client helpers for BSV micropayments over HTTP 402.
- go-bsv-middleware, middleware for authentication and micropayments, with examples.
- go-uhrp-storage-server, a file storage server addressed by content hash.
- go-private-backup-cache, an append-only cache for encrypted wallet backups.
Examples you can run
Each of these folders in docs/examples holds a small program for one task:
| Task | Example folder |
|---|---|
| Build and sign a P2PKH transaction | create_simple_tx |
Put data in a transaction with OP_RETURN | create_tx_with_op_return |
| Derive a child key with BRC-42BSV Key Derivation Scheme | derive_child |
| Generate an HD key | generate_hd_key |
| Encrypt a message for one recipient | ecies_single |
| Verify a BEEF structure | verify_beef |
Related articles
To learn more about the SDKs on the BSV blockchain, review these articles: