How to add a QR code to your website - or anywhere! Bitcoin donation button example

QR codes. Yes, those little rascals you’ve seen around before. Let’s create one to serve as a Bitcoin donation button for your website.

Ever seen something like this guy?

In this little tutorial we’ll create the QR code image file via command line and add a donation button along with the QR code to a website. You’ll learn two things:

  • Creating QR codes with any content and size straight from our beloved command line
  • Some bitcoin related query string syntax to open a wallet when scanning a QR code

Alright then, let’s get right to it.


Get yourself qrencode from Kentaro Fukuchi (link). For the sake of simplicity, I got myself a local copy via brew install qrencode on my MacBook. You don’t know brew? Shame on you, get this essential piece of package managing software for your mac right here. It’s fantastic, don’t think twice.

Don’t want to run it on a mac? Good news: pretty much any distro that doesn’t smell already should ship it. Try sudo apt-get install qrencode (Debian, Ubuntu) or sudo yum install qrencode (RHEL, CentOS).

You’re a Windows user? Try compiling qrencode using cygwin, or use some other GUI QR generator - sorry, out of scope here.

Creating the QR code

Finally, you have qrencode installed. Assuming you have a terminal open already, type:

qrencode -o helloworld.png -s 3 -m 0 'Yeay! It works, hello world!'

This will create our image file, helloworld.png, with 3 pixels per block (-s 3) and no margin pixels (-m 0) and the content Yeay! It works, hello world!. Yep, that’s the image from the preface section.

Go ahead, grab a phone and scan the code. All it will display is whatever you set to be the content. This opens endless possibilities. You can include links, raw data, or just a ton of characters (by default ~ 2950 @ 8 bits/char, see here).

qrencode comes with a nice man page, you should check it out for more fine tuning options (man qrencode).

TO include a URL in you QR code, just set the content to a URL. Like this:

qrencode -o url-qr-example.png -s 3 -m 0 ''

Resulting in this:

Scanning this would usually open a browser, depending on the default behavior of your scanner app.

Well this was fun. Let’s create a QR code that’s a tad bit more useful in the next section.

Creating a bitcoin donation button

Ok, we now know how to quickly create a QR code. But how can we open someone’s wallet (pun intended) when they scan the code? Simple.

Query string shenanigans

We set the content to a specially formatted standard query string, like this one:


But slowly. What does this query string contain?

  • bitcoin:: This precedes your wallet’s public address, specifying the protocol to use when evaluating the QR content. It’s agreed upon that bitcoin: opens / is handled by the user’s default wallet application (both on desktop and mobile).
  • 3Qdb9iCMfzppCw4nME1Fst7Dsk7DmyuT4j: This is my wallet’s public bitcoin address. Replace it with your own (you can skip this step, but that would mean more money for me ;)…)
  • ?!: You might’ve guessed it. This is a reference that you want this transaction to be known by. The ? is the delimiter for the query string’s attributes that follow, in this case, just label. %20 is just a URI encoded space character, so that the message reads says thanks!.

You could also add amount in the string to specify a preset amount for the transaction. Only the first parameter in the query string after your public bitcoin address is delimited with a ?. All subsequent parameters are delimited by an ampersand (&param). In case of amount, this would look like this: &amount=20.

Some param that is used and implemented less frequently is message. Analogous to the amount example from above, you could put it in with &message=donation. In my experiments, this breaks some wallet clients as they don’t handle this extra param and hiccup.

More params are discussed RFC-like on bitcoins gihub pages, like this one.

Putting it all together

Now that we know how to create QR codes and how to craft nifty query strings with bitcoin addresses, nothing is holding us back any longer. Type:

qrencode -o bitcoin-qr-example.png -s 3 -m 0 'bitcoin:3Qdb9iCMfzppCw4nME1Fst7Dsk7DmyuT4j?!'

You’ll get this:

Once you scanned the code, the scanner will open your default wallet application, asking for the amount to donate (or to transfer, more generally speaking).

Alright, we have the perfect QR code now. All that’s left is to insert it into our website or print it somewhere else. For the website case, just adding the image inside an anchor tag (<a></a>) would already do the trick. As you can see, below every article I added a little bitcoin logo along the QR code we just created, inside said anchor tag.


And here it is, just add something like this anywhere you’d like your donation button to appear. People can then either click or scan it, depending on which device their wallet resides. And for anyone who wants to read it off manually, you can have the public bitcoin address visible in plain sight:

<a href="bitcoin:3Qdb9iCMfzppCw4nME1Fst7Dsk7DmyuT4j?!">
    <img src="img/bitcoin_logo.png">
    <img src="img/bitcoin_qr.png">

Results in something you see below the articles on this blog. Neat.

Closing thoughts

That wasn’t too hard, was it? I hope you liked this little tutorial. If you have any questions, please leave a comment.

In case you’d like to show your appreciation with some cold hard cash, go ahead, the public address in the logo above (and below this article) is live and awaiting any gracious donations :).

Written on July 17, 2016