Go to file
bumi c50a982090 Require lnrpc >= 0.7.1 2019-10-27 17:46:03 +01:00
bin Hello World! 2018-10-28 12:37:29 +01:00
lib/rack Require lnrpc >= 0.7.1 2019-10-27 17:46:03 +01:00
spec Hello World! 2018-10-28 12:37:29 +01:00
.gitignore Hello World! 2018-10-28 12:37:29 +01:00
.rspec Hello World! 2018-10-28 12:37:29 +01:00
.travis.yml Hello World! 2018-10-28 12:37:29 +01:00
Gemfile Hello World! 2018-10-28 12:37:29 +01:00
LICENSE.txt Hello World! 2018-10-28 12:37:29 +01:00
README.md Update README.md 2018-11-22 11:16:51 +00:00
Rakefile Hello World! 2018-10-28 12:37:29 +01:00
rack-lightning.gemspec Require lnrpc >= 0.7.1 2019-10-27 17:46:03 +01:00


Rack::Lightning - micropayments for your rack app

Rack middleware for requesting Bitcoin Lightning payments for HTTP request.

Status: alpha - proof of concept

How does it work?

  1. On the first request a Lightning invoice is created and th 402 Payment Required HTTP status code is returend with a application/vnd.lightning.bolt11 content type header and a Lightning invoice as a body.
  2. Once the client has paid the invoice it does a second request providing the proof of payment / the preimage of the Lightning payment in a X-Preimage header. The middleware checks the if the invoice was paid and continues with the rack app stack

Have a look at the Faraday HTTP client middleware to automatically handle the payment of the requested invoice.


The middleware uses the gRPC service provided by the Lightning Network Daemon(lnd). A running node with is required which is used to generate and validate invoices.

Details about lnd can be found on their github page


Add this line to your application's Gemfile:

gem 'rack-lightning'


Simply add the Rack::Lightning middleware:

require "rack/lightning"

Example = Rack::Builder.new {
  use Rack::Lightning, { price: 100 } 
  run Proc.new { |env| ['200', {'Content-Type' => 'text/html'}, ['get rack\'d']] }


The middleware accepts the following configuration options:

  • price: the price in satoshi (default: 100)
  • address: the address of the lnd gRPC service( default: localhost:10009)
  • credentials_path: path to the tls.cert (default: ~/.lnd/tls.cert)
  • macaroon_path: path to the macaroon path (default: ~/.lnd/data/chain/bitcoin/testnet/admin.macaroon)
  • credentials: instead of configuring a credentials_path you can pass the content of the tls.cert directly
  • macaroon: instead of configuring a macaroon_path you can pass the hex content of the macaroon directly

How to pass credentials or macaroon data from a variable like a environment varibale?

The tls.cert and the macaroon config can be loaded from a variable:

ENV['LND_CREDENTIALS'] = "the content of your tls.cert file"
ENV['LND_MACAROON'] = "the hex encoded content of your macaroon file"
# you can get the macaroon content like this: xxd -p -c2000 admin.macaroon
# or ::File.read(::File.expand_path("/path/to/admin.macaroon")).each_byte.map { |b| b.to_s(16).rjust(2,'0') }.join

Example = Rack::Builder.new {
  use Rack::Lightning, { macaroon: ENV['LND_MACAROON'], credentials: ENV['LND_CREDENTIALS'] } 
  run Proc.new { |env| ['200', {'Content-Type' => 'text/html'}, ['get rack\'d']] }

What is the Lightning Network?

The Lightning Network allows to send real near-instant microtransactions with extremely low fees. It is a second layer on top of the Bitcoin network (and other crypto currencies). Thanks to this properties it can be used to monetize APIs.

Similar projects


Bug reports and pull requests are welcome on GitHub at https://github.com/bumi/rack-lightning.


The gem is available as open source under the terms of the MIT License.