Sending Bitcoin with Ruby

Super simplified version! WAOW

Ace Subido
Aug 9, 2019 · 8 min read

“Hmm, okay so we want to send BTC programmatically? It shouldn’t be that hard, let me read some docs and look at libraries”


One of the basic things you’d want to achieve in building on top of the Bitcoin ecosystem is to send Bitcoin. With, that I’ve written down some things that I’ve learned along the way in the most simplified way I can think of.

Here’s a step by step guide in sending Bitcoin with ruby by leveraging bitcoind’s JSON RPC endpoint.

You’ll need to have:

  • bitcoind running with -rpcallowip , configured with rpcusername and rpcpassword and more importantly -testnet. This will act as your ‘hot wallet’.

What if someone gets access to my private keys? What if someone brute forces the username/password of my bitcoind’s JSON RPC endpoint? etc.

Security is another topic worth another post (limit the surface of attack, pod/vm-level restrictions, network-level restraints, multiple bitcoind’s, not keeping large amounts of bitcoin in your hot wallet, etc.) but for now, let’s send some bitcoins 😄

Concept (simplified)

A transaction in the Bitcoin network is made of in’s and out’s.

  • Inputs are where you get your BTC from. These are past transactions with addresses you can control.


You have 5BTC in your wallet, it’s split up in 4 different addresses. yeah, I mean, I’m actually saying addresses, but it’s actually “unspent transaction outputs” ❓🙄❓🙄❓ Stick with me for now and I’ll point this out later.

  • 1addr has 2 BTC

You want to send 0.01BTC to someone named Person A, you’d need to use some of your BTC in those 4 address. Let’s say we want to use 3addr, and Person A gave you their address: 1some1. Your transaction would look like this:

  • Inputs 3addr = 0.5BTC

This isn’t complete though, so what happens to the 0.49BTC? Well you’d need to send it back to yourself of course! Otherwise it’ll all go to the miners. Best to generate a new address and put it there. Lets call that new address as 5addr. Now our transaction looks like this:

  • Inputs 3addr = 0.5BTC

What about those transaction fees? How do I set them?

The transaction fee is the difference between the sum of your inputs and sum of your output amounts. Let’s say the transaction fees would be 0.000178BTC

So the final transaction would look like:

  • Inputs 3addr = 0.5BTC

If you still didn’t get it, it’s okay! If you understand concepts better when you’re writing the code and tests, then it’ll probably click as you go along 😃

Getting the fees

First we’ll want to set what type of fees are “fast”, so that we can use the right number when creating the transaction. We can stuff this code inside some simple service class.

module Bitcoinzzz
class GetFees

AVE_TX_BYTES = 250.0
client =<your creds here>)
# whats the fee for 3 blocks?
response = client.request("estimatesmartfee", 3)
if response["errors"].any?
# ... do something

# estimatesmartfee is a bitcoind JSON RPC call
# it returns the optimal fee per kB (1000 bytes), given the
# number of blocks you want your transaction to confirm
# we only want the fee for 250bytes (average tx size).
# you can also compute for tx size if you want to.
fee = response["feerate"].to_d * (AVE_TX_SIZE / 1000.0)

Sending bitcoin with the fees

Can’t we just use sendtoaddress? (sendtoaddress is a bitcoind JSON RPC call)

Yes you can! That’s definitely the easiest way to do this, but if you want more control on fees, outputs being spent; splitting up what sendtoaddress does would be one step to that direction (a.k.a. small refactors using the Ship of Theseus method.), and we get to learn along the way too!

So here’s the steps to mimic sendtoaddress similarly

Getting your unspent money (What can I use for my inputs?)

To build the transaction you’ll need to get “spendable outputs”. To simplify the explanation, this is where the BTC will come from, a list of unspent addresses in the bitcoind wallet.

# listunspent is another bitcoind JSON RPC call, it lists all the 
# previous txs/addresses that you contains your
unspent = client.request("listunspent")
#=> [
"address": "1addr",
"amount": 2.0,
"confirmations": 1000,
"desc": "some_text",
"redeemScript": "some_redeem_script",
"safe": true,
"scriptPubKey": "some_script_pubkey",
"solvable": true,
"spendable": true,
"txid": "the_remote_txid",
"vout": 0
"address": "2addr",
"amount": 1.5,
"confirmations": 1000,
"desc": "some_text",
"redeemScript": "some_redeem_script",
"safe": true,
"scriptPubKey": "some_script_pubkey",
"solvable": true,
"spendable": true,
"txid": "the_remote_txid",
"vout": 0

Remember earlier I said this?

yeah, I mean, I’m actually saying addresses, but it’s actually “unspent transaction outputs” ❓🙄❓🙄❓ Stick with me for now and I’ll point this out later.

Sometimes you will see here 2 items with the same address but different vout values. It means that the address was used multiple times. So what this list really represents are unspent transaction outputs (UTXO) . These are previous transactions where the outputs are addresses that your bitcoind ‘hot wallet’ controls a.k.a. someone sending your hot wallet some BTC, or “change amounts” from previous transactions you made (more on that later)

Filter what you’ll use (What can I use for my inputs?)

Presented with this list, just grab what’s “spendable”. It means that this transaction can be used by bitcoind for sending (underneath, all that means is that the bitcoind has the keys to use that address).

# what you want your recipient to actually receive
receivable_amount = 0.01
# sample fee from Bitcoinzzz::GetFees.()
fee = 0.000178
# filter all spendable
spendable = do |output|
output if output["spendable"]

If you’re sending 0.01BTC + 0.000178BTC, you won’t need all the “spendable outputs”, so just get the right amount of outputs.

total_usable = 0# total amount you'll spend: 0.01 + 0.000178
sending_amount = receivable_amount + fee
# just get the right amount of outputs
usable = do |output|
if total_usable < sending_amount
total_usable += output["amount"]
# based on the unspent example, 'usable' array will only contain the 1addr hash by now. You're only sending 0.01BTC + 0.000178BTC anyway. 1addr contains 2BTC

Get a change address (Where will I send it? My outputs?)

Remember what I said earlier about outputs?

You’ll need to send the difference back to yourself. More on that later.

Of course you only want to send 0.01BTC + 0.000178BTC (fees). Right now, you have 0.5BTC worth of (ins) that funds your transaction! You’ll want to send the rest back to your own wallet. This is called a change address, you can get one using bitcoind’s JSON RPC again.

receiving_address = "SOME_ADDRESS_HERE"# getrawchangeaddress is another bitcoind JSON RPC call that gives 
# you a new address where you can send change to
change_address = client.request(
"bech32", # bech32 adoption would be very nice, lower tx size.
# Lets compute what we'll send back to yourself and what we'll send
# to the change_address
# total_usable = 2BTC from 1addr
# sending_amount = 0.01BTC + 0.000178 (fees)
change_amount = total_usable - sending_amount

Build the transaction hash (Putting my outputs and inputs together)

Once you’ve determined where you’ll get the money from (inputs), and where it’ll go (outputs). Let’s prepare a json object for createrawtransaction

ins = do |output|
"txid" => output["txid"],
"vout" => output["vout"],
outs = [
{ destination_address => receivable_amount },
{ change_address => change_amount },
#=> [
{ "1some1" => 0.01 },
{ "change_address" => 1.98922 },
tx_to_submit = { ins: ins, outs: outs }# createrawtransaction builds your transaction ready for signing.
# the result will be a hex-encoded string
raw_tx = client.request(
0, # locktime
true, # replaceable

Sign the transaction

After getting the hex-encoded transaction via createrawtransaction, sign it.

# signrawtransactionwithwallet is a bitcoind JSON RPC call that will 
# sign your transaction with the keys for those addresses
resp = client.request(
if resp["errors"].present?
raise StandardError, "Error with signing transaction - #{resp}"
signed_tx = resp["hex"]

Send the transaction

You can now send the signed transaction to the local bitcoind node and to the network!

# you can check the tx_id returned in a blockchain explorer like 
# or
tx_id = client.request("sendrawtransaction", signed_tx)

Testing Sending Bitcoin

Yey! Let’s grab our handy-dandy vcr: { record: :once } Here’s a simple test for all that work we just did.

require "rails_helper"# Put all of the things that we did in some decoupled class so that it's easy to test. Here it assumes we can just write an integration test for a Bitcoinzzz::Send class that does everything we talked aboutmodule Bitcoinzzz
RSpec.describe Send do
let(:fee) { Bitcoinzzz::GetFees.() }
let(:client) do<test_net_credentials>)
let(:address) { client.request("getnewaddress") }
"sends BTC",
vcr: {
record: :once,
match_requests_on: %i[body uri method],
) do
current_balance = client.request("getbalance")
result_tx_id = described_class.(
tx_fee_in_btc: fee,
destination_address: address,
receivable_amount: 0.002,
after_send_balance = client.request("getbalance") # expect the balance differences to be for the tx_fee since we
# sent it back to our self
expected_diff = current_balance - after_send_balance
expect(expected_diff.round(7).to_d).to eq fee
expect(result_tx_id).not_to be_nil
expect(result_tx_id).to be_a String
remote_tx = client.request(
true, # verbose, gets you json instead of a hex string

# parse that remote_tx and do your expectations

Next steps

There you go! You can now send Bitcoin with Ruby. Although, what if this service class gets called a lot? And at the same time?

  • You can probably use something like sidekiq-unique-jobs and line all the withdrawal requests in a worker queue so that you won’t have race conditions.

There are more ways but you can definitely make this a safe service class to use via defensive programming.

Another next-level implementation for this is to not rely on bitcoind’s wallet for getting the unspent outputs, building and signing the transaction hashes. This allows you to feed multiple inputs coming from a cold wallet, and multi-sig keys from different signers.

You can use lower-level libraries such as bitcoin-ruby to achieve this, but you’ll have to keep track of your addresses, keys, transactions on your own a.k.a. implementing/complementing bitcoind’s wallet capabilities.

Hopefully this guide has eased you into how to work with Bitcoin and bitcoind.


Transforming money services with cryptocurrencies