Skip to content
Switch branches/tags
Go to file


Failed to load latest commit information.
Latest commit message
Commit time

Build Status Gitter java-bigchaindb-driver

Official Java and Android Driver for BigchainDB

Please note: This driver is compatible with Android API 23 and later.


BigchainDB Server BigchainDB Java Driver
2.x 1.x



The build system supports both Maven and Gradle.

Maven Users

In your pom.xml file, add bigchaindb-driver as a dependency:



mvn clean install

Gradle Users

In your build.gradle file, add bigchaindb-driver as a dependency:

dependencies {
    implementation 'com.bigchaindb.bigchaindb-driver:1.2'


./gradlew install


A sample of an end-to-end CREATE and TRANSFER operation is available in the gist

Set Up Your Configuration

Single-Node Setup

	.addToken("header1", <header1_value>)
	.addToken("header2", <header2_value>).setup();

Multi-Node Setup (More Robust and Reliable)

Note - multi-node setup is only available in version 1.2 and later

Assumption - The following setup assumes that all nodes are all connected within same BigchainDB network.

	//define connections
    Map<String, Object> conn1Config = new HashMap<String, Object>(), 
                 conn2Config = new HashMap<String, Object>();
    //define headers for connections
    Map<String, String> headers1 = new HashMap<String, String>();
    Map<String, String> headers2 = new HashMap<String, String>();
    //config header for connection 1
    headers1.put("app_id", "<your-app-id>");
    headers1.put("app_key", "<your-app-key>");
    //config header for connection 2
    headers2.put("app_id", "<your-app-id>");
    headers2.put("app_key", "<your-app-key>");
    //config connection 1
    conn1Config.put("baseUrl", "");
    conn1Config.put("headers", headers1);
    Connection conn1 = new Connection(conn1Config);
    //config connection 2
    conn2Config.put("baseUrl", "");
    conn2Config.put("headers", headers2);
    Connection conn2 = new Connection(conn2Config);
    //add connections
    List<Connection> connections = new ArrayList<Connection>();
    //...You can add as many nodes as you want
    .setTimeout(60000) //override default timeout of 20000 milliseconds

Example: Prepare Keys, Assets and Metadata

// prepare your keys
net.i2p.crypto.eddsa.KeyPairGenerator edDsaKpg = new net.i2p.crypto.eddsa.KeyPairGenerator();
KeyPair keyPair = edDsaKpg.generateKeyPair();

// New asset
Map<String, String> assetData = new TreeMap<String, String>() {{
    put("city", "Berlin, DE");
    put("temperature", "22");
    put("datetime", new Date().toString());

// New metadata
MetaData metaData = new MetaData();
metaData.setMetaData("what", "My first BigchainDB transaction");

Example: Create an Asset

Performing a CREATE transaction in BigchainDB allocates or issues a digital asset.

// Set up, sign, and send your transaction
Transaction createTransaction = BigchainDbTransactionBuilder
	.addAssets(assetData, TreeMap.class)
	.buildAndSign((EdDSAPublicKey) keyPair.getPublic(), (EdDSAPrivateKey) keyPair.getPrivate())

Example: Transfer an Asset

Performing a TRANSFER transaction in BigchainDB changes an asset's ownership (or, more accurately, authorized signers):

// Generate a new keypair to TRANSFER the asset to
KeyPair targetKeypair = edDsaKpg.generateKeyPair();

// Describe the output you are fulfilling on the previous transaction
final FulFill spendFrom = new FulFill();

// Change the metadata if you want
MetaData transferMetadata = new MetaData();
metaData.setMetaData("what2", "My first BigchainDB transaction");

// the asset's ID is equal to the ID of the transaction that created it
String assetId = createTransaction.getId();

// By default, the 'amount' of a created digital asset == "1". So we spend "1" in our TRANSFER.
String amount = "1";

// Use the previous transaction's asset and TRANSFER it
Transaction transferTransaction = BigchainDbTransactionBuilder

	// source keypair is used in the input, because the current owner is "spending" the output to transfer it
	.addInput(null, spendFrom, (EdDSAPublicKey) keyPair.getPublic())

	// after this transaction, the target 'owns' the asset, so, the new output includes the target's public key
	.addOutput(output, (EdDSAPublicKey) targetKeypair.getPublic())

	// reference the asset by ID when doing a transfer
	.addAssets(assetId, String.class)

	// the source key signs the transaction to authorize the transfer
	.buildAndSign((EdDSAPublicKey) keyPair.getPublic(), (EdDSAPrivateKey) keyPair.getPrivate())

Example: Setup Config with WebSocket Listener

public class MyCustomMonitor implements MessageHandler {
	public void handleMessage(String message) {
		ValidTransaction validTransaction = JsonUtils.fromJson(message, ValidTransaction.class);

// config
	.addToken("app_id", "2bbaf3ff")
	.addToken("app_key", "c929b708177dcc8b9d58180082029b8d")
	.webSocketMonitor(new MyCustomMonitor())

More Examples

Example: Create a Transaction (without signing and without sending)

// Set up your transaction but only build it
Transaction transaction = BigchainDbTransactionBuilder
	.addAssets(assetData, TreeMap.class)
	.buildOnly((EdDSAPublicKey) keyPair.getPublic());

Example: Create and Sign Transaction (without sending it to the ledger)

//    Set up your transaction
Transaction transaction = BigchainDbTransactionBuilder
	.addAssets(assetData, TreeMap.class)
	.buildAndSignOnly((EdDSAPublicKey) keyPair.getPublic(), (EdDSAPrivateKey) keyPair.getPrivate());

API Wrappers


Send a Transaction

TransactionsApi.sendTransaction(Transaction transaction) throws IOException

Send a Transaction with Callback

TransactionsApi.sendTransaction(Transaction transaction, final GenericCallback callback) 

Get Transaction given a Transaction Id

Transaction TransactionsApi.getTransactionById(String id) throws IOException

Get Transaction given an Asset Id

Transactions TransactionsApi.getTransactionsByAssetId(String assetId, Operations operation)


Get Outputs given a public key

Outputs getOutputs(String publicKey) throws IOException

Get Spent Outputs given a public key

Outputs getSpentOutputs(String publicKey) throws IOException

Get Unspent Outputs given a public key

Outputs getUnspentOutputs(String publicKey) throws IOException


Get Assets given search key

Assets getAssets(String searchKey) throws IOException

Get Assets given search key and limit

Assets getAssetsWithLimit(String searchKey, String limit) throws IOException


Get Blocks given block id

Block getBlock(String blockId) throws IOException

Get Blocks given transaction id

List<String> getBlocksByTransactionId(String transactionId) throws IOException


Get MetaData given search key

MetaDatas getMetaData(String searchKey) throws IOException

Get MetaData given search key and limit

MetaDatas getMetaDataWithLimit(String searchKey, String limit) throws IOException


Gets the the local validators set of a given node

Validators getValidators() throws IOException

BigchainDB Documentation


Inspired by

The BigchainDB team and others including:

  • @bodia
  • @alvin-reyes
  • @agwego
  • @nf-PostQuantum
  • @Rokko11
  • @tzclucian
  • @kremalicious
  • @avanaur
  • @GerardoGa
  • @bakaoh
  • @innoprenuer

Release Process

To execute a release build with Maven, define performRelease to enable GPG signing:

mvn clean package install -DperformRelease



Exception: src/main/java/com/bigchaindb/util/ has a different license; see the comments at the top of that file for more information.