# Use the Go SDK

> For the complete documentation index, see [llms.txt](https://bsvblockchain.com/docs/llms.txt).

go-sdk is the Go library for BSV blockchain apps: keys, scripts, transactions, proofs, a wallet interface and overlay services, with its docs and examples in the Go repositories.

import BlueTable from '/snippets/BlueTable.jsx';

Use `go-sdk` to build keys, scripts, transactions and proofs for the BSV blockchain in Go, from a signed P2PKH (Pay to Public Key Hash, the standard script that locks coins to an address) transaction up to a BRC-100 (BSV Request for Comments 100, the standard interface between apps and wallets) wallet interface and overlay services (Built 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:

<BlueTable>

| 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 BEEF (Background 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` |

</BlueTable>

## 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.

**1. 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:

```bash
go mod init example.com/bsv-go
go get github.com/bsv-blockchain/go-sdk
```

The last line of the output names the version that was added:

```text
go: creating new go.mod: module example.com/bsv-go
go: added github.com/bsv-blockchain/go-sdk v1.7.3
```

**2. Create main.go**

Create `main.go` in the module folder. The program builds and signs a transaction on your computer, with a key, a locking script (The 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.

```go main.go
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())
}
```

**3. 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:

```bash
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:

```text
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. `true` gives a Mainnet address.
- `AddInputFrom` describes the output the input spends: its transaction ID, its index, its locking script as a hex string and its value in satoshis (The 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 UTXOs (Unspent transaction output).
- `p2pkh.Unlock(priv, nil)` gives the input a signing template, and `tx.Sign()` signs every input that has one.
- `PayToAddress` adds 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](https://bsvblockchain.com/docs/guides/services/broadcasting/).

## 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](https://github.com/bsv-blockchain/go-sdk), with its README and [releases](https://github.com/bsv-blockchain/go-sdk/releases).
- [go-sdk docs](https://github.com/bsv-blockchain/go-sdk/tree/master/docs), with `concepts`, `examples` and `low-level` folders.
- [API reference](https://pkg.go.dev/github.com/bsv-blockchain/go-sdk) on pkg.go.dev, generated from the code.
- [go-wallet-toolbox](https://github.com/bsv-blockchain/go-wallet-toolbox), with its [docs](https://github.com/bsv-blockchain/go-wallet-toolbox/tree/main/docs), for building BRC-100 wallets in Go.
- [go-overlay-services](https://github.com/bsv-blockchain/go-overlay-services/tree/master/docs), the overlay services engine in Go.
- [go-402-pay](https://github.com/bsv-blockchain/go-402-pay), server middleware and client helpers for BSV micropayments over HTTP 402.
- [go-bsv-middleware](https://github.com/bsv-blockchain/go-bsv-middleware/tree/main/examples), middleware for authentication and micropayments, with examples.
- [go-uhrp-storage-server](https://github.com/bsv-blockchain/go-uhrp-storage-server/tree/main/docs), a file storage server addressed by content hash.
- [go-private-backup-cache](https://github.com/bsv-blockchain/go-private-backup-cache/tree/main/docs), an append-only cache for encrypted wallet backups.

### Examples you can run

Each of these folders in [`docs/examples`](https://github.com/bsv-blockchain/go-sdk/tree/master/docs/examples) holds a small program for one task:

<BlueTable>

| 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-42 (BSV 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` |

</BlueTable>

## Related articles

To learn more about the SDKs on the BSV blockchain, review these articles:

- [SDKs overview](https://bsvblockchain.com/docs/sdk/)
- [Use the Python SDK](https://bsvblockchain.com/docs/sdk/python/)
- [Use the TypeScript SDK](https://bsvblockchain.com/docs/sdk/typescript/)
- [How the BSV blockchain stack fits together](https://bsvblockchain.com/docs/concepts/architecture/)