API Documentation

Lightning Network Payments

WARNING: This feature is experimental!

Blocktap supports a pay-per-request system using micropayments on the Bitcoin Lightning Network.

Using the Lightning Network to make requests to Blocktap consists of a three step process:

  1. Call the Blocktap invoice API (this generates an invoice and a one-time-use API key)
  2. Pay the invoice via the Lightning Network
  3. Use the one-time-use API key to retrieve the results

Lightning Network Channel

To ensure fast payments, we recommend creating a channel with our Lightning Network node:


Important Notes

  • This feature is experimental.
  • The pay-per-request API key is a one-time-use key. After your request to the GraphQL endoint has been made, the key will no longer be valid.
  • You must send the exact same request body to the /graphql endpoint that was used to generate the invoice with the /api/invoice endpoint. Failure to do so will result in a error.
  • You cannot reuse your API key, even with the same query. In the future, the results will be cached for a small period of time so that you can retry your request if your connection is interrupted.
  • Only simple validation of the query is performed when the invoice is generated. We cannot guarantee that your query will execute correctly or return data. For example, using an exchange or asset symbol that is not in the system will return no data. In the future we will add a refund capability for queries that do not execute correctly.

Step 1: Invoice API

The first step is retrieving a lightning network invoice and one-time-use API key from the invoice endpoint.

POST /api/invoice
Content-Type: application/json


The body of the POST request should be Content-Type: application/json. The JSON body can have the following properties similar to sending GraphQL requests:

Name Type Mandatory Description
query string true The GraphQL syntax query to be execute. Can contain multple queries, but only one will execute.
operation string false Used to select which query in query should execute. Can be omitted if there is only one query.
variables object false Object mapping to variables used in the query.

An example payload is:

  "query": "query market(@exchangeSymbol: String! baseSymbol:\"BTC\" quoteSymbol:\"USD\") { marketSymbol }",
  "operation": "market",
  "variables": {
    "exchangeSymbol": "Binance"


The response will will be Content-Type: application/json and have the following properties:

Name Type Description
price number Price of the invoice in USD
value number Invoice size in millisatoshi (0.00000000001 BTC)
paymentRequest string Lightning Network invoice
apikey string Blocktap one-time-use API key that can be used after the invoice is paid

An example response is:

  "price": 0.0000369897648072,
  "value": 1000,
  "paymentRequest": "lntb10n1pwqtz6wpp5gq7za4fhw247yupn3gfh37fn4v29fss9hctt2t4d3u9pmhehrdrsdqavfkx7cmtw3shqgr5da4k2m3qxy6r2cqzysxq2w5dr7auveh4dsd00eje57ck76805s69eeukfglyl6j7p986fj5fjmyvqaxxrn9vs0r3p9l0phesre3ht3estnz3prrn9l6sjwsqsqr6sfa3",
  "apikey": "20208e84c648179822d968eedf102b5d44ce49da04ef3d63c83ec22834ed3b0b"


JavaScript Example

let query = `
query market {
  market(exchangeSymbol: "Binance", baseSymbol: "LTC", quoteSymbol: "BTC") {
    ticker {

fetch('https://api.blocktap.io/api/invoice', {
  method: 'POST',
  header: {
    'Content-Type': 'application/json',
  body: JSON.stringify({ query }),
  .then(res => res.json())

Node.js Example

let https = require('https');

let query = `
query market {
  market(exchangeSymbol: "Binance", baseSymbol: "LTC", quoteSymbol: "BTC") {
    ticker {

let payload = JSON.stringify({ query });

let req = https.request(
    host: 'api.blocktap.io',
    method: 'POST',
    path: '/api/invoice',
    header: {
      'Content-Type': 'application/json',
      'Content-Length': Buffer.byteLength(query),
  res => {
    let buffers = [];
    res.on('data', data => buffers.push(data));
    res.on('end', () => {
      let result = Buffer.concat(buffers);


cURL Example

curl \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{ "query": "{ exchange (exchangeSymbol:\"binance\") { country } }" }' \

Step 3: GraphQL API

Using a pay-per-request API key is similar to a normal API key. Refer to the connecting page for more information about attaching the API key to a request.

GraphiQL Interface

You can view an example of the Lightning Network in action when using the Pay-Per-Request mode in the GraphiQL interface.

When you first execute a query, the interface will prompt you to continue by paying a Lightning Network invoice.

Lightning Network Invoice

Once you have paid the invoice, the Paid button will execute the Blocktap query using your paid one-time-use API key.