bitcoincore-rpc

The bitcoincore-rpc crate provides a Rust client library for interacting with the Bitcoin Core daemon's JSON-RPC API.

Note that the data types used in the interface are provided by a separate crate, bitcoincore-rpc-json, which contains the JSON-enabled data types required for the RPC calls.

The rust-bitcoincore-rpc package compiles into two distinct crates:

1. bitcoincore-rpc: Provides the RPC client implementation that exposes Bitcoin Core JSON-RPC APIs as native Rust functions.
2. bitcoincore-rpc-json: Contains the Rust data structures representing the JSON responses from the Bitcoin Core JSON-RPC APIs. bitcoincore-rpc depends on this crate.

The Auth enum defines how the client authenticates with the Bitcoin Core RPC server. You can use one of three methods:

1. Auth::None: No authentication.
2. Auth::UserPass(username, password): Standard HTTP Basic authentication.
3. Auth::CookieFile(path): Uses a Bitcoin Core .cookie file to extract credentials. The client reads the first line of the file and splits it by the first colon to obtain the username and password.

use rust_bitcoincore_rpc::Auth;
use std::path::PathBuf;

// Using username and password
let auth = Auth::UserPass("myuser".to_string(), "mypass".to_string());

// Using a cookie file
let auth = Auth::CookieFile(PathBuf::from("/path/to/.bitcoin/.cookie"));

Workflow for constructing and signing transactions:

1. Construct: Use create_raw_transaction(utxos, outs, locktime?, replaceable?) to create a new transaction from inputs and outputs.
2. Fund: Use fund_raw_transaction(tx, options?, is_witness?) to automatically select UTXOs and calculate fees.
3. Sign:
   • sign_raw_transaction_with_wallet(tx, utxos?, sighash_type?): Signs using the wallet's private keys.
   • sign_raw_transaction_with_key(tx, privkeys, prevtxs?, sighash_type?): Signs using provided private keys.
4. PSBT: Alternatively, use create_psbt(inputs, outputs, locktime?, replaceable?) to create a Partially Signed Bitcoin Transaction.

To interact with a Bitcoin Core JSON-RPC server, create a new Client instance using Client::new. You must provide the server URL and an Auth object (e.g., Auth::None or Auth::CookieFile).

use bitcoincore_rpc::Client;
use bitcoincore_rpc::Auth;

let client = Client::new("http://localhost/", Auth::None).unwrap();

This repository is archived as of 2025-11-25 and is no longer maintained.

• For a blocking API, users are recommended to switch to corepc-client.
• For an async RPC client, users should refer to the rust-bitcoin discussion thread.

To use the client, connect to a Bitcoin Core node via its JSON-RPC interface. This example assumes the node is running on localhost:8332 with password authentication enabled.

You will need to use Client::new with an Auth::UserPass credential and call methods provided by the RpcApi trait.

extern crate bitcoincore_rpc;

use bitcoincore_rpc::{Auth, Client, RpcApi};

fn main() {

    let rpc = Client::new("http://localhost:8332",
                          Auth::UserPass("<FILL RPC USERNAME>".to_string(),
                                         "<FILL RPC PASSWORD>".to_string())).unwrap();
    let best_block_hash = rpc.get_best_block_hash().unwrap();
    println!("best block hash: {}", best_block_hash);
}

Supported Bitcoin Core Versions

The following versions are officially supported and automatically tested:

• 0.18.0
• 0.18.1
• 0.19.0.1
• 0.19.1
• 0.20.0
• 0.20.1
• 0.21.0

Minimum Supported Rust Version (MSRV)

This library requires Rust 1.56.1 or higher.