Skip to content

mrz1836/go-whatsonchain

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

386 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
 
 
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
 
 
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
 
 

Repository files navigation

🔗 go-whatsonchain

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

CI / CD Quality & Security Docs & Meta Community
Latest Release
Build Status
CodeQL
Last commit 		Go Report Card
Code Coverage
OpenSSF Scorecard
Security policy 		Go version
Go docs
AGENTS.md rules
MAGE-X Supported
Dependabot 		go-whatsonchain API docs
Contributors
Sponsor
Donate Bitcoin

🗂️ Table of Contents


📦 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: 135 total endpoints (71 BSV + 64 BTC) from the whatsonchain.com API

Quick Navigation: BSV API • BTC API • WebSockets

BSV API (71 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 (6 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 (64 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 (6 endpoints)

✅ Exchange Rate (2 endpoints)

✅ Search (1 endpoint)

✅ Stats (6 endpoints)

WebSockets (ComingSoon™)

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

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by configuration files: .env.base (default configuration) and optionally .env.custom (project-specific overrides) – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

  • .env.base – Default configuration that works for most Go projects
  • .env.custom – Optional project-specific overrides

This magical file controls everything from:

  • 🚀 Go version matrix (test on multiple versions or just one)
  • 🏃 Runner selection (Ubuntu or macOS, your wallet decides)
  • 🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
  • 🛡️ Security tool versions (gitleaks, nancy, govulncheck)
  • 🤖 Auto-merge behaviors (how aggressive should the bots be?)
  • 🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just add ENABLE_CODE_COVERAGE=false to your .env.custom to override the default in .env.base and push. No YAML archaeology required!


Workflow Name Description
auto-merge-on-approval.yml Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml Automatically merges Dependabot PRs that meet all requirements.
fortress.yml Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml Runs OpenSSF Scorecard to assess supply chain security.
stale.yml Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml Keeps GitHub labels in sync with the declarative manifest at .github/labels.yml.
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 Compliance

This project documents expectations for AI assistants using a few dedicated files:

  • AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
  • CLAUDE.md — quick checklist for the Claude agent.
  • .cursorrules — machine-readable subset of the policies for Cursor and similar tools.
  • sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.


👥 Maintainers

MrZ
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! 🚀

Stars


📝 License

License

About

🔗 Unofficial Golang SDK for the WhatsOnChain API

docs.whatsonchain.com/

Topics

go api golang bitcoin bsv woc gomod gomodule whatsonchain whatsonchain-api

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

14 stars

Watchers

3 watching

Forks

5 forks
Report repository

Releases 54

Release v1.0.0 Latest
Sep 30, 2025
+ 53 releases

Sponsor this project

  •  
Learn more about GitHub Sponsors

Packages

No packages published

Contributors 4

  •  
  •  
  •  
  •  

Languages