Installation

Bitcoin4J is published to Maven Central as org.twostack:bitcoin4j. It is compiled for Java 11, so any JDK from 11 upwards will run it. The examples on these pages are tested on JDK 26.

Adding the dependency

Gradle (Kotlin DSL)

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.twostack:bitcoin4j:1.8.0")
}

Gradle (Groovy)

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.twostack:bitcoin4j:1.8.0'
}

Maven

<dependencies>
  <dependency>
    <groupId>org.twostack</groupId>
    <artifactId>bitcoin4j</artifactId>
    <version>1.8.0</version>
  </dependency>
</dependencies>

What comes along with it

Bitcoin4J brings in a few libraries of its own:

Dependency	Used for
Bouncy Castle (bcprov-jdk15to18)	Elliptic-curve cryptography, RIPEMD-160
Guava (30.0-android)	Hex encoding (Utils.HEX), preconditions, collections
SLF4J API	Logging
at.favre.lib:bytes	Byte-array helpers

Bouncy Castle and Guava are API dependencies. Some of the library’s public signatures use their types, which means they end up on your compile classpath too. If your project already uses a newer Guava, Gradle and Maven will settle on one version for both. Bitcoin4J only uses the long-stable parts of Guava, so this is rarely a problem.

Do note that SLF4J needs a binding before it prints anything. Without one it prints a one-time warning and discards the log output, which is harmless. Add org.slf4j:slf4j-simple (or your logging framework’s binding) if you want to see the logs.

Checking that it loads

Creating a key is a quick way to exercise both the cryptography provider and the encoding code.

// Generating a Private Key exercises both the cryptography provider and the encoding code.
PrivateKey privateKey = new PrivateKey();
String wif = privateKey.toWIF();   // a new mainnet key, starting with K or L

This gives us a new mainnet Private Key in WIF form, starting with K or L. You will get a different key every time you run it. The keys page explains what a WIF is.

Testing against a local build. To use a build of Bitcoin4J that is not on Maven Central yet, run ./gradlew publishToMavenLocal in a checkout of the library and add mavenLocal() before mavenCentral() in your repositories block. The example project behind these pages does the same.

Finding your way around the packages

The classes we use most live in a handful of packages:

Package	What is in it
org.twostack.bitcoin4j	PrivateKey, PublicKey, Address, Coin, ECKey, Utils, Sha256Hash
org.twostack.bitcoin4j.params	NetworkType, NetworkAddressType
org.twostack.bitcoin4j.address	LegacyAddress, Base58
org.twostack.bitcoin4j.crypto	HD keys (DeterministicKey, HDKeyDerivation), MnemonicCode
org.twostack.bitcoin4j.transaction	Transaction, TransactionBuilder, TransactionSigner, the lock and unlock builders
org.twostack.bitcoin4j.script	Script, ScriptBuilder, Interpreter, ScriptOpCodes, Script templates
org.twostack.bitcoin4j.block	Block