🔗 go-whatsonchain

The unofficial Go SDK for the whatsonchain.com API supporting both BSV and BTC blockchains.

`CI / CD`		`Quality`
`Security`		`Community`

`Project Navigation`

🚀 `Installation`	💡 `Usage`
📚 `Documentation`	🧪 `Examples & Tests`
⚡ `Benchmarks`	🛠️ `Code Standards`
🤖 `AI Usage`	🤝 `Contributing`
👥 `Maintainers`	⚖️ `License`

📦 Installation

go-whatsonchain requires a supported release of Go.

go get github.com/mrz1836/go-whatsonchain

💡 Usage

Quick Start

package main

import (
	"context"
	"log"

	"github.com/mrz1836/go-whatsonchain"
)

func main() {
	// Create a client with default options (BSV mainnet)
	client, err := whatsonchain.NewClient(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	log.Println("client loaded", client.UserAgent())
	log.Println("Chain:", client.Chain(), "Network:", client.Network())
}

Configuration Options

The library uses functional options for clean and flexible configuration:

package main

import (
	"context"
	"log"
	"time"

	"github.com/mrz1836/go-whatsonchain"
)

func main() {
	// Create a client with custom options
	client, err := whatsonchain.NewClient(
		context.Background(),
		whatsonchain.WithChain(whatsonchain.ChainBSV),
		whatsonchain.WithNetwork(whatsonchain.NetworkMain),
		whatsonchain.WithAPIKey("your-secret-key"),
		whatsonchain.WithUserAgent("my-app/1.0"),
		whatsonchain.WithRateLimit(10),
		whatsonchain.WithRequestTimeout(60*time.Second),
		whatsonchain.WithRequestRetryCount(3),
	)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("client loaded with custom options")
}

Available Options

WithChain(chain) - Set blockchain (ChainBSV or ChainBTC)
WithNetwork(network) - Set network (NetworkMain, NetworkTest, NetworkStn)
WithAPIKey(key) - Set API key for authenticated requests
WithUserAgent(agent) - Set custom user agent
WithRateLimit(limit) - Set rate limit per second
WithHTTPClient(client) - Use custom HTTP client
WithRequestTimeout(timeout) - Set request timeout
WithRequestRetryCount(count) - Set retry count for failed requests
WithBackoff(initial, max, factor, jitter) - Configure exponential backoff
WithDialer(keepAlive, timeout) - Configure dialer settings
WithTransport(idle, tls, expect, maxIdle) - Configure transport settings

Multi-Chain Support

BSV Client

package main

import (
	"context"
	"log"

	"github.com/mrz1836/go-whatsonchain"
)

func main() {
	// Create BSV client
	client, err := whatsonchain.NewClient(
		context.Background(),
		whatsonchain.WithChain(whatsonchain.ChainBSV),
		whatsonchain.WithNetwork(whatsonchain.NetworkMain),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Use BSV-specific methods
	opReturnData, err := client.GetOpReturnData(context.Background(), "your-tx-hash")
	if err != nil {
		log.Fatal(err)
	}
	log.Println("OP_RETURN data:", opReturnData)

	// Use shared methods (work for both BSV and BTC)
	chainInfo, err := client.GetChainInfo(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("BSV Chain Info: %+v", chainInfo)
}

BTC Client

package main

import (
	"context"
	"log"

	"github.com/mrz1836/go-whatsonchain"
)

func main() {
	// Create BTC client
	client, err := whatsonchain.NewClient(
		context.Background(),
		whatsonchain.WithChain(whatsonchain.ChainBTC),
		whatsonchain.WithNetwork(whatsonchain.NetworkMain),
	)
	if err != nil {
		log.Fatal(err)
	}

	// Use BTC-specific methods
	blockStats, err := client.GetBlockStats(context.Background(), 700000)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("Block Stats: %+v", blockStats)

	// Get miner statistics
	minerStats, err := client.GetMinerBlocksStats(context.Background(), 7) // last 7 days
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("Miner Stats: %+v", minerStats)

	// Use shared methods (work for both BSV and BTC)
	chainInfo, err := client.GetChainInfo(context.Background())
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("BTC Chain Info: %+v", chainInfo)
}

📚 Documentation

View the generated documentation

Features

Multi-blockchain support - Seamless switching between BSV and BTC blockchains with a single client
Production-ready HTTP client - Built-in exponential backoff with configurable retry logic and crypto-secure jitter to handle transient failures gracefully
Intelligent rate limiting - Per-second request throttling with automatic sleep intervals to stay within API quotas
Zero external dependencies - Pure Go implementation with no production dependencies (testify only for testing)
Comprehensive API coverage - 135+ endpoints (71 BSV, 64 BTC) fully implemented and tested
Flexible configuration - Functional options pattern for clean, type-safe client initialization
Enterprise-grade transport - Fine-grained control over timeouts, keep-alives, connection pooling, and TLS handshake settings
Network flexibility - Switch between mainnet, testnet, and STN per client or per request

Heads up! go-whatsonchain is intentionally light on dependencies. The only external package it uses is the excellent testify suite—and that's just for our tests. You can drop this library into your projects without dragging along extra baggage.

Supported API Coverage

Coverage Summary: 153 endpoints (84 BSV + 69 BTC) from the whatsonchain.com API

Quick Navigation: BSV API • BTC API • WebSockets

BSV API (84 endpoints)

✅ Health (1 endpoint)

Get Health Status - /woc

✅ Chain Info (4 endpoints)

Get Blockchain Info - /chain/info
Get Circulating Supply - /circulatingsupply
Get Chain Tips - /chain/tips
Get Peer Info - /peer/info

✅ Block (7 endpoints)

Get Block by Hash - /block/hash/{hash}
Get Block by Height - /block/height/{height}
Get Block Pages - /block/hash/{hash}/page/{page}
Get Block Headers - /block/headers
Get Header by Hash or Height - /block/{hash}/header
Get Header Bytes File Links - /block/headers/resources
Get Latest Header Bytes - /block/headers/latest

✅ Transaction (13 endpoints)

✅ Mempool (2 endpoints)

Get Mempool Info - /mempool/info
Get Mempool Transactions - /mempool/raw

✅ (Un)Spent Transaction Outputs (14 endpoints)

✅ Address (13 endpoints)

✅ Script (10 endpoints)

✅ Exchange Rate (2 endpoints)

Get Current Exchange Rate - /exchangerate
Get Historical Exchange Rate - /exchangerate/historical

✅ Search (1 endpoint)

Get Explorer Links - /search/links (POST)

✅ On-Chain Data (1 endpoint)

Get OP_RETURN Data - /tx/{hash}/opreturn

✅ Stats (6 endpoints)

Get Block Stats by Height - /block/height/{height}/stats
Get Block Stats by Hash - /block/hash/{hash}/stats
Get Miner Block Stats - /miner/blocks/stats
Get Miner Minimum Fee Rate Stats - /miner/fees
Get Miner Summary Stats - /miner/summary/stats
Get Tag Count by Height - /block/tagcount/height/{height}/stats

✅ Tokens (13 endpoints)

1Sat Ordinals (7 endpoints)

Get Token by Origin - /token/1satordinals/{origin}/origin
Get Token by Outpoint - /token/1satordinals/{outpoint}
Get Token Content - /token/1satordinals/{outpoint}/content
Get Token Latest Transfer - /token/1satordinals/{outpoint}/latest
Get Token Transfer History - /token/1satordinals/{outpoint}/history
Get Tokens by TxID - /token/1satordinals/tx/{txid}
Get 1Sat Ordinals Stats - /tokens/1satordinals

STAS v0 (6 endpoints)

Get All STAS Tokens - /tokens
Get STAS Token by ID - /token/{contractId}/{symbol}
Get Token UTXOs for Address - /address/{address}/tokens/unspent
Get Address Token Balance - /address/{address}/tokens
Get Token Transactions - /token/{contractId}/{symbol}/tx
Get STAS Stats - /tokens/stas

BTC API (69 endpoints)

✅ Health (1 endpoint)

Get Health Status - /woc

✅ Chain Info (4 endpoints)

Get Blockchain Info - /chain/info
Get Circulating Supply - /circulatingsupply
Get Chain Tips - /chain/tips
Get Peer Info - /peer/info

✅ Block (7 endpoints)

Get Block by Hash - /block/hash/{hash}
Get Block by Height - /block/height/{height}
Get Block Pages - /block/hash/{hash}/page/{page}
Get Block Headers - /block/headers
Get Header by Hash or Height - /block/{hash}/header
Get Header Bytes File Links - /block/headers/resources
Get Latest Header Bytes - /block/headers/latest

✅ Transaction (9 endpoints)

Get Transaction by Hash - /tx/hash/{hash}
Bulk Transaction Details - /txs (POST)
Bulk Transaction Status - /txs/status (POST)
Get Transaction as Binary - /tx/{hash}/bin
Get Raw Transaction Data - /tx/{hash}/hex
Bulk Raw Transaction Data - /txs/hex (POST)
Get Raw Transaction Output - /tx/{hash}/out/{index}/hex
Bulk Raw Transaction Output Data - /txs/vouts/hex (POST)
Decode Transaction - /tx/decode (POST)

✅ Mempool (2 endpoints)

Get Mempool Info - /mempool/info
Get Mempool Transactions - /mempool/raw

✅ (Un)Spent Transaction Outputs (14 endpoints)

✅ Address (12 endpoints)

✅ Script (10 endpoints)

✅ Exchange Rate (2 endpoints)

Get Current Exchange Rate - /exchangerate
Get Historical Exchange Rate - /exchangerate/historical

✅ Search (1 endpoint)

Get Explorer Links - /search/links (POST)

✅ Stats (6 endpoints)

Get Block Stats by Height - /block/height/{height}/stats
Get Block Stats by Hash - /block/hash/{hash}/stats
Get Miner Block Stats - /miner/blocks/stats
Get Miner Minimum Fee Rate Stats - /miner/fees
Get Miner Summary Stats - /miner/summary/stats
Get Tag Count by Height - /block/tagcount/height/{height}/stats

WebSockets (ComingSoon™)

⚠️ Deprecated Endpoints

The following methods are maintained for backward compatibility but should not be used in new code. They will be removed in a future major version.

Deprecated Method	Replacement
`AddressBalance`	`AddressConfirmedBalance` + `AddressUnconfirmedBalance`
`AddressHistory`	`AddressConfirmedHistory` + `AddressUnconfirmedHistory`
`BulkBalance`	`BulkAddressConfirmedBalance` + `BulkAddressUnconfirmedBalance`
`BulkUnspentTransactions`	`BulkAddressConfirmedUTXOs` + `BulkAddressUnconfirmedUTXOs`
`BulkUnspentTransactionsProcessor`	Direct UTXO methods
`GetScriptHistory`	`GetScriptConfirmedHistory` + `GetScriptUnconfirmedHistory`
`BulkScriptUnspentTransactions`	`BulkScriptConfirmedUTXOs` + `BulkScriptUnconfirmedUTXOs`
`GetMerkleProof`	`GetMerkleProofTSC`
`BulkBroadcastTx`	`BroadcastTx`

These deprecated endpoints are not included in the active endpoint count above.

Development Setup (Getting Started)

Install MAGE-X build tool for development:

# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:install

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=master

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any managed tools. It is the recommended way to keep your development environment and CI in sync with the latest versions.

🧪 Examples & Tests

All unit tests and fuzz tests run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench time=2s

Performance Results

Benchmarks run on Apple M1 Max using Go's built-in benchmark tool with 2-second intervals.

Operation	Time (ns/op)	Memory (B/op)	Allocations (allocs/op)
Client Operations
Client Creation (Minimal)	275	1,048	9
Client Creation (Fully Configured)	287	1,048	9
Build URL (Simple)	158	144	4
Build URL (With Args)	194	168	5
Get Chain Config	2.1	0	0
Set Chain Config	2.1	0	0
Address Operations
Get Address Info	2,748	2,697	25
Get Address Balance	2,209	2,393	24
Get Address History	3,605	3,097	32
Get Address UTXOs	5,668	3,705	36
Get Confirmed Balance	2,391	2,337	22
Get Unconfirmed Balance	2,683	2,337	22
Transaction Operations
Get Transaction by Hash	8,117	6,035	43
Bulk Transaction Details (1 tx)	15,536	14,135	69
Bulk Transaction Details (20 txs)	17,489	16,815	69
Broadcast Transaction	2,071	2,753	26
Decode Transaction	9,294	6,835	54
Get Merkle Proof	5,679	3,826	40
Get Spent Output	4,431	3,233	31
Block Operations
Get Block by Hash	11,271	6,307	48
Get Block by Height	8,691	5,963	47
Get Block Pages	3,104	2,833	30
Get Header by Hash	10,296	6,435	49
Get Latest Header Bytes	2,109	3,905	21
Chain Info Operations
Get Chain Info	3,442	2,881	24
Get Chain Tips	2,546	2,497	27
Get Circulating Supply	1,514	1,993	17
Get Exchange Rate	2,569	2,433	26
Get Historical Exchange Rate	3,916	3,089	36
Get Peer Info	6,467	3,641	33
Get Mempool Info	3,068	2,633	27
Get Mempool Transactions	2,648	2,593	32

Notes:

All times are in nanoseconds per operation
Memory is bytes allocated per operation
Benchmarks use mock HTTP responses for consistent, reproducible results

To reproduce these benchmarks:

magex bench time=2s

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.

👥 Maintainers


MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 484 Commits
.github		.github
.vscode		.vscode
examples		examples
.cursorrules		.cursorrules
.devcontainer.json		.devcontainer.json
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitpod.yml		.gitpod.yml
.golangci.json		.golangci.json
.goreleaser.yml		.goreleaser.yml
LICENSE		LICENSE
README.md		README.md
addresses.go		addresses.go
addresses_benchmark_test.go		addresses_benchmark_test.go
addresses_test.go		addresses_test.go
blocks.go		blocks.go
blocks_benchmark_test.go		blocks_benchmark_test.go
blocks_test.go		blocks_test.go
bsv_specific.go		bsv_specific.go
bsv_specific_test.go		bsv_specific_test.go
btc_specific.go		btc_specific.go
btc_specific_test.go		btc_specific_test.go
chain_info.go		chain_info.go
chain_info_benchmark_test.go		chain_info_benchmark_test.go
chain_info_test.go		chain_info_test.go
chain_support_test.go		chain_support_test.go
chunk.go		chunk.go
client.go		client.go
client_benchmark_test.go		client_benchmark_test.go
client_test.go		client_test.go
codecov.yml		codecov.yml
definitions.go		definitions.go
errors.go		errors.go
errors_test.go		errors_test.go
exchange_rates.go		exchange_rates.go
exchange_rates_test.go		exchange_rates_test.go
fuzz_test.go		fuzz_test.go
go.mod		go.mod
go.sum		go.sum
health.go		health.go
health_test.go		health_test.go
http_client.go		http_client.go
http_client_test.go		http_client_test.go
interface.go		interface.go
interface_test.go		interface_test.go
mempool.go		mempool.go
mempool_test.go		mempool_test.go
request_helpers.go		request_helpers.go
request_helpers_test.go		request_helpers_test.go
scripts.go		scripts.go
scripts_test.go		scripts_test.go
search.go		search.go
search_test.go		search_test.go
stats.go		stats.go
stats_test.go		stats_test.go
tokens.go		tokens.go
tokens_test.go		tokens_test.go
transactions.go		transactions.go
transactions_benchmark_test.go		transactions_benchmark_test.go
transactions_test.go		transactions_test.go
url_builder.go		url_builder.go
whatsonchain.go		whatsonchain.go
whatsonchain_test.go		whatsonchain_test.go

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

🔗 go-whatsonchain

Project Navigation

📦 Installation

💡 Usage

Quick Start

Configuration Options

Available Options

Multi-Chain Support

BSV Client

BTC Client

📚 Documentation

Features

BSV API (84 endpoints)

✅ Health (1 endpoint)

✅ Chain Info (4 endpoints)

✅ Block (7 endpoints)

✅ Transaction (13 endpoints)

✅ Mempool (2 endpoints)

✅ (Un)Spent Transaction Outputs (14 endpoints)

✅ Address (13 endpoints)

✅ Script (10 endpoints)

✅ Exchange Rate (2 endpoints)

✅ Search (1 endpoint)

✅ On-Chain Data (1 endpoint)

✅ Stats (6 endpoints)

✅ Tokens (13 endpoints)

1Sat Ordinals (7 endpoints)

STAS v0 (6 endpoints)

BTC API (69 endpoints)

✅ Health (1 endpoint)

✅ Chain Info (4 endpoints)

✅ Block (7 endpoints)

✅ Transaction (9 endpoints)

✅ Mempool (2 endpoints)

✅ (Un)Spent Transaction Outputs (14 endpoints)

✅ Address (12 endpoints)

✅ Script (10 endpoints)

✅ Exchange Rate (2 endpoints)

✅ Search (1 endpoint)

✅ Stats (6 endpoints)

WebSockets (ComingSoon™)

⚠️ Deprecated Endpoints

🧪 Examples & Tests

⚡ Benchmarks

Performance Results

🛠️ Code Standards

🤖 AI Usage & Assistant Guidelines

👥 Maintainers

🤝 Contributing

How can I help?

📝 License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 60

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`Project Navigation`

Packages