Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


npm release MIT license Pull Requests Welcome IRC

Charge for HTTP APIs on a pay-per-call basis with Bitcoin and Lightning.

Want to require a payment when users take some programmatic action, such as sending an SMS or running imaging processing? That's what paypercall is for.

Available as an express middleware (where a node.js app makes charges directly) or as a reverse proxy (where a reverse proxy requires payment before providing access to an app).

Powered by ⚡ Lightning Charge.


$ npm install paypercall

Server Setup

As a middleware

paypercall can be used as an express middleware to charge payments directly in your node.js apps. Below is an example app that charges 0.1 USD to send SMS messages:


const pay = require('paypercall')({ chargeUrl: ..., chargeToken: ... })
    , twi = require('twilio')(twilioSid, twilioToken)
    , app = require('express')()

app.use(require('body-parser').urlencoded())'/sms', pay(0.1, 'USD'), (req, res, next) =>
  twi.messages.create({ from: 'paypercall', to:, body: req.body.message })
    .then(msg => res.send({ success: true, sid: msg.sid }))

app.listen(4000, _ => console.log('HTTP server running on localhost:4000'))

See ifpaytt for a more full-fledged application using paypercall as a middleware.

As a reverse proxy

Alternatively, you can develop your HTTP server with no payments awareness and use paypercall as a reverse proxy to handle payments. Below is an example using a python app:

from flask import Flask, request
from import Client as Twilio

app = Flask(__name__)
twi = Twilio(twilioSid, twilioToken)

@app.route("/sms", methods=['POST'])
def sms():
  msg = twi.messages.create(from='paypercall', to=request.form['to'], body=request.form['message'])
  return { 'success': True, 'sid': msg.sid }

Run the python app and the paypercall proxy:

$ flask run
* Running on http://localhost:4001/

$ paypercall --charge-token mySecretToken --upstream-url http://localhost:4001 \
             --port 4000 --rates-yaml '{ POST /sms: 0.1 USD }'
HTTP reverse proxy running on http://localhost:4000, proxying to http://localhost:4001

You will now have the python app running on port 4001 (providing API calls free of charge) and the paypercall reverse proxy running on port 4000 (charging on a per-call basis).

Paying for API calls

Users can access paypercall-enabled API endpoints in three steps:

  1. Send an empty request (no body) to the paypercall-enabled endpoint to get the BOLT11 payment request and the X-Token header:

    $ curl -i -X POST http://localhost:4000/sms
    HTTP/1.1 402 Payment Required
    Content-Type: application/vnd.lightning.bolt11
    X-Token: lmbdmJeoSQ0ZCB5egtnph.af1eupleFBVuhN2vrbRuDLTlsnnUPYRzDWdL5HtWykY
  2. Make the payment:

    $ lightning-cli pay lnbcrt8925560p1pdfh7n2pp54g5avyupe70l988h30u0hy8agpj2z7qsveu7ejhys97j98rgez0...
  3. Send the request again, this time with the request body and with the X-Token header echoed back:

    $ curl -i -X POST http://localhost:4000/sms \
      -H 'X-Token: lmbdmJeoSQ0ZCB5egtnph.af1eupleFBVuhN2vrbRuDLTlsnnUPYRzDWdL5HtWykY' \
      -t to=+972-789456123 \
      -d message='I got lightning working and all I got was this sms!'
    HTTP/1.1 200 OK
    Content-Type: application/json



const pay = require('paypercall')(options)

Returns a new payment middleware factory. options can contain the following fields:

  • chargeUrl: Lightning Charge server URL (optional, defaults to http://localhost:9112)
  • chargeToken: Lightning Charge access token (required)
  • dbPath: Path to sqlite database (optional, defaults to ./paypercall.db)
  • currency: Default currency if none is specified (optional, defaults to BTC)
  • secret: Secret key used for HMAC tokens (optional, generated based on chargeToken by default)
  • invoiceExp: How long should invoices be payable for (optional, defaults to 1 hour)
  • accessExp: How long should paid access tokens remain valid for (optional, defaults to 1 hour)
const payware = pay(amount[, currency])

Returns an express middleware that requires a payment of amount units of currency (or the default currency if none provided) before letting requests pass through.

Can be used as following:

const pay = require('paypercall')({ chargeToken: 'myToken', currency: 'EUR' })
    , app = require('express')

// charge requests to a specific route'/sms', pay(0.15), (req, res) => { /* send SMS */ })

// charge all requests to /paid-apis/*
app.use('/paid-apis', pay(0.25))

// dynamic pricing (should only be based on the method and path)'/ocr/:type', (req, res, next) => {
  pay(getPriceForType(req.params.type))(req, res, (err) => {
    if (err) return next(err)
    // payment succesfull, run OCR
    // (the paid invoice is accessible at `req.invoice`)

Reverse proxy

$ paypercall --help

  Charge for HTTP APIs on a pay-per-call basis with Bitcoin and Lightning

    $ paypercall [options]

    -c, --charge-url <url>      lightning charge server url [default: http://localhost:9112]
    -t, --charge-token <token>  lightning charge access token [required]

    -u, --upstream-url <url>    the upstream server to reverse proxy [required]
    -r, --rates-path <path>     path to YAML file mapping from endpoints to rates [default: ./rates.yaml]
    -y, --rates-yaml <yaml>     YAML string to use instead of reading from {rates-path}
    -x, --currency <name>       default rate currency if none is specified [default: BTC]
    -d, --db-path <path>        path to store sqlite database [default: ./payperclick.db]

    --invoice-expiry <sec>      how long should invoices be payable for [default: 1 hour]
    --access-expiry <sec>       how long should paid access tokens remain valid for [default: 1 hour]
    --token-secret <secret>     secret key used for HMAC tokens [default: generated based on {charge-token}]

    -p, --port <port>           http server port [default: 4000]
    -i, --host <host>           http server listen address [default:]
    -e, --node-env <env>        nodejs environment mode [default: production]
    -h, --help                  output usage information
    -v, --version               output version number

    $ payperclick -t myAccessToken -u \
                  -y '{ POST /sms: 0.0001 BTC, PUT /page/:id: 0.0002 BTC }'