diff --git a/README.md b/README.md
index 7e0de0e..8cd9f30 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,26 @@
-# Rack::Lightning
+# Rack::Lightning - micropayments for your rack app
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/rack/lightning`. To experiment with that code, run `bin/console` for an interactive prompt.
+[Rack middleware](https://rack.github.io/) for requesting Bitcoin [Lightning payments](http://lightning.network/) per request.
 
-TODO: Delete this and the text above, and describe your gem
+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` 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](https://github.com/bumi/faraday_ln_paywall) to automatically handle the 
+payment of the requested invoice.
+
+## Requirements
+
+The middleware uses the gRPC service provided by the [Lightning Network Daemon(lnd)](https://github.com/lightningnetwork/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](https://github.com/lightningnetwork/lnd/)
 
 ## Installation
 
@@ -12,27 +30,43 @@ Add this line to your application's Gemfile:
 gem 'rack-lightning'
 ```
 
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install rack-lightning
-
 ## Usage
 
-TODO: Write usage instructions here
+Simply add the `Rack::Lightning` middleware:
 
-## Development
+```ruby
+require "rack/lightning"
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Example = Rack::Builder.new {
+  use Rack::Lightning, { price: 100 } 
+  run Proc.new { |env| ['200', {'Content-Type' => 'text/html'}, ['get rack\'d']] }
+}.to_app
+```
+
+## Configuration 
+
+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)
+
+## What is the Lightning Network?
+
+The [Lightning Network](https://en.wikipedia.org/wiki/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
+
+* [philippgille/ln-paywall](https://github.com/philippgille/ln-paywall) - middleware for Go frameworks. looks great and very well designed!
+* [ElementsProject/paypercall](https://github.com/ElementsProject/paypercall) - express.js middelware for node.js applications
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/rack-lightning.
+Bug reports and pull requests are welcome on GitHub at https://github.com/bumi/rack-lightning.
 
 ## License
 
diff --git a/lib/rack/lightning.rb b/lib/rack/lightning.rb
index 666908b..63a4893 100644
--- a/lib/rack/lightning.rb
+++ b/lib/rack/lightning.rb
@@ -8,7 +8,7 @@ module Rack
 
     def initialize(app, options={})
       @app = app
-      @invoice_storage = {}
+      @invoice_storage = {} # TODO: don't store this in memory!
       @options = options
       @price = @options[:price] || 100
       @options[:address] ||= 'localhost:10009'