I am the author of bitcoinaddress.js library and I am wondering what's the best content for Bitcoin QR codes.

What Bitcoin QR codes should contain (for mobile wallet apps and other barcode scanners):

  • Only Bitcoin address (this is only one I have seen wild myself)

  • Bitcoin URI scheme link (BIP 21) with payment amount, transaction note, etc.

Currently I implemented address only, as I don't know how well-spread BIP 21 support is among the mobile phones and mobile wallets. If anyone can give me some answers and pointers to the prior research regarding the matter I'd be grateful.

4 Answers 4


I'm working on a Bitcoin project, and what I've seen are:

  • Just the Bitcoin address
  • A url parameter-like scheme with the format "bitcoin:{plus the bitcoin address}" (no brackets used)
  • A more elaborate url parameter that includes the amount, like "bitcoin:{bitcoin addr}?amount={the amount}

Coinbase uses the last scheme and it is fully recognized by the BlockChain iPhone app, enabling you to request a certain amount of Bitcoin directed to a specific address.

Coinbase uses the (deprecated) Google chart apis and the full querystring they use to build a QR code looks like this:

<img width="300" height="300" alt="Chart?cht=qr&amp;chl=bitcoin%3a1k1yfezde2c37pwdevjnin1yc2qbtly6bk%3famount%3d0" src="https://chart.googleapis.com/chart?cht=qr&amp;chl=bitcoin%3A1K1yfEZde2C37pWDevjnin1yc2qBtLy6bk%3Famount%3D0.01&amp;choe=UTF-8&amp;chs=300x300">

If you run that src url through a url decoder, you'll find that it requests 0.01 BTC to the address 1K1yfEZde2C37pWDevjnin1yc2qBtLy6bk.

When you're building a QR code, you don't need to url-encode the data. Coinbase is only doing so because they have to request the QR code from Google through a url addressing scheme.

I build my QR codes on my own server and display them as images on a web page, and I just use non-encoded data.

  • My project internally uses qrcode.js which can built QR codes on the client-side and claims compatibility down to IE6. Check it out, I highly recommend. Commented Feb 5, 2014 at 8:05
  • 1
    Also the eloborate URL parameter is called "Bitcoin URI Scheme" and can be found under proposal BIP 0021. Commented Feb 5, 2014 at 8:06
  • @Mikko, thanks for the pointer to BIP21. I reviewed that after I posted this response and it helped me understand what I was seeing.
    – ChrisW
    Commented Feb 5, 2014 at 18:22
  • BIP0021 does state that "Characters must be URI encoded properly."
    – alexg
    Commented Apr 30, 2017 at 9:37
  • "Properly" means according to RFC 3986 section 2; in particular tools.ietf.org/html/rfc3986#section-2.4 . Don't just percent-encode characters willy-nilly. Percent-encoding delimiter characters that are meant as delimiters is incorrect. Commented Mar 22, 2021 at 14:07

I'm the founder of CryptoCoinJS and use the library for my own software. This is probably obvious, when scanning QR codes, check for both. When generating QR codes, for backup I'd just do the address and for payment requests, I'd use the URI scheme.


I've met the Coinpunk developer last month at a meeting and he was discussing about how hard it was for him to create an entirely HTML5-based bitcoin QR code generator, that would work also on iOS devices. Apparently he was successful.

I'd therefore suggest to look into his project which is open-source: https://github.com/kyledrake/coinpunk

  • qrcode.js used in my project internally is open source and works (see Github page for continuous integration status). I'll check Coinpunk too. Commented Feb 5, 2014 at 8:04

I'm adding more info on the matter.

This is a format proposed in Chapter2 of Bitcoinbook (How Bitcoin Works)


Components of the URL

A bitcoin address: "1GdK9UzpHBzqzX2A9JFP3Di4weBwqgmoQA"
The payment amount: "0.015"
A label for the recipient address: "Bob's Cafe"
A description for the payment: "Purchase at Bob's Cafe"

And I believe it's pretty much the same as BIP21. Thanks for referencing it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.