This add-on is operated by Chain Inc.

The Bitcoin API for Developers


Last Updated: 07 May 2015

The Chain add-on is currently in beta.

Table of Contents

Chain is an add-on that makes it easy for your application to interact with Bitcoin.

With simple API calls you can get address balances, identify unspent outputs, and send transactions to the network – all without managing any complicated Bitcoin infrastructure.

Chain is accessible via an API and has a supported Ruby client library.

Provisioning the add-on

Chain can be attached to a Heroku application via the CLI:

A list of all plans available can be found here.

$ heroku addons:create chain
-----> Adding chain to sharp-mountain-4005... done, v18 (free)

Once Chain has been added a CHAIN_URL will be set in that app’s environment. This new environment variable can be confirmed using the heroku config:get command.

$ heroku config:get CHAIN_URL

After installing Chain, the application should be configured to fully integrate with the add-on.

Local setup

Environment setup

After provisioning the add-on, it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export CHAIN_URL=value.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the CHAIN_URL values retrieved from heroku config to .env.

$ heroku config -s | grep CHAIN_URL >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Using with Ruby/Rails

Ruby on Rails applications will need to add the following entry into their Gemfile specifying the Chain client library.

gem 'chain-ruby'

Update application dependencies with bundler.

$ bundle install

Then you can access the Chain API anywhere in your code:


Ruby Gem Methods


Chain.get_address_transactions(address, limit: limit)





For more examples, visit

Migrating between plans

Application owners should carefully manage the migration timing to ensure proper application function during the migration process.

Use the heroku addons:upgrade command to migrate to a new plan.

$ heroku addons:upgrade chain:newplan
-----> Upgrading chain:newplan to sharp-mountain-4005... done, v18 ($49/mo)
       Your plan has been updated to: chain:newplan

Removing the add-on

Chain can be removed via the CLI.

This will destroy all associated data and cannot be undone!

$ heroku addons:destroy chain
-----> Removing chain from sharp-mountain-4005... done, v20 (free)


All Chain support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at or