Tutorial Series: Onboard an API to Sparkwall


Apr 9, 2024

Sparkwall Beta is Live

Sparkwall, our flagship fully managed L402 infrastructure offering, has just entered public beta! Monetizing APIs has never been easier. With the click of a button, you can turn any API into a fully monetized product thanks to the power of the Lightning Network. From Pay-per-use, to dynamic pricing, instant settlement of funds, and micro-transaction support, harness the power of L402 to charge your customers for API access.

You can try all of this now thanks to our open Sparkwall beta. On this tutorial, we will learn how to onboard a simple API to Sparkwall from scratch. We will learn many of the concepts along the way, but if you are not familiar with the L402 protocol, the foundation of our API monetization technology, we recommend that you first take a look at our documentation.

If you prefer, you can follow along the tutorial with this video:


Before we get right to it, make sure you have the following ready:

  • A Lightning Labs LND lightning node (we will be using a Voltage node).

  • A Sparkwall account.

Once you are ready with these, we can get started!


We will be monetizing a simple free API called cat-fact. It is a simple API that returns a collection of facts about cats everytime the /facts endpoint is called:

[ { "status": { "verified": true, "sentCount": 1 }, "_id": "58e00b5f0aac31001185ed24", "user": "58e007480aac31001185ecef", "text": "When asked if her husband had any hobbies, Mary Todd Lincoln is said to have replied \"cats.\"", "__v": 0, "source": "user", "updatedAt": "2020-08-23T20:20:01.611Z", "type": "cat", "createdAt": "2018-02-19T21:20:03.434Z", "deleted": false, "used": false }, { "status": { "verified": true, "feedback": "", "sentCount": 1 }, "_id": "5887e1d85c873e0011036889", "user": "5a9ac18c7478810ea6c06381", "text": "Cats make about 100 different sounds. Dogs make only about 10.", "__v": 0, "source": "user", "updatedAt": "2020-09-03T16:39:39.578Z", "type": "cat", "createdAt": "2018-01-15T21:20:00.003Z", "deleted": false, "used": true }]

This API is being run free-of-charge, but the maintainers would like to charge a small per-call price for the API to support the project. They are just asking for 0.0002$ per call! Thanks to the Lightning Network and L402, this is now possible for every open source project out there looking for funding. Let's onboard it to Sparkwall!

Step 1: Creating a Wallet

Before onboarding the API, we need to create a wallet to receive funds we charge users for access to the API. You will do this once or twice on Sparkwall, since you can reuse a single wallet for all your APIs.

A wallet is just an abstraction to receive funds over the ligthning network. It can be a Lightning node that you host, a lightning wallet such as Alby, or a more complex setup. We are working hard to integrate as many wallets as possible to our platform, so if you have any specific request do not hesitate to get in touch with us (and join our Discord ;). For the purpose of this tutorial, we will use a Voltage node.

Navigate to the Wallets menu on the left-hand side bar to open the Wallets Dashboard:

From here we can click on register a new wallet to open up the wallet registration dialog:

We need 4 key pieces of data:

  • Our Node Public Key

  • An Invoicing Macaroon

  • Our node's TLS Certificate

  • Our node's API address

We can get all these from Voltage's dashboard. The node public key can be found in the Home dashboard. The invoicing macaroon can be found under Manage Access > Macaroon Bakery. The TLS certificate can also be found under Manage Access > Apps > Alby (and other apps as well). Once you have all the necessary details, click on Register to create a new wallet.

Once we have a wallet we are ready to onboard our API!

Step 2: Registering an API

Next we will onboard our API details. For this navigate to the API dashhoard on the left-hand sidebar menu. The following menu will appear:

Click on Register New API to start.

Now we must register our API details. For cat-fact, these are:

  • API Name: cat-fact (or any of your choosing)

  • Category: Choose an appropriate one

  • Description: Random facts about cats :)

  • Backend Protocol: The HTTP protocol to connect to your API backend. Can be either HTTP or HTTPS. In our case it is HTTPS.

  • Sparkwall Hostname: This is a key part of the configuration. Sparkwall will generate a new hostname for your API, that will be L402 monetized. The hostname will end with .ln.sulu.sh This is the hostname your consumers will use to access the API and pay for it. This hostname will become the public hostname of your API.

  • TLS Certificate: If your backend requires a TLS certificate for access (recommended), you can add it here. For cat-fact, no TLS certificate is required.

  • Healthcheck URL: A URL to check the health of your API. If the API has no specific /health path, any path of the API that returns a status 200 when the API is healthy can be used here. For cat-fact, we can use the /facts endpoint: https://cat-fact.herokuapp.com/facts.

Once all this information is set, we are ready to register our API!

Step 3: Package Creation

The last step to publish our monetized API is to create a package. A package specifies how we will monetize our API service: how much we are charging for access, are we charging per-call or for a set amount of time, are we charging differently for each endpoint… All of these settings are in the package creation state.

Go over to the Packages tab next to the newly created API to create a package. You can choose any name for your package, just pick something that will help you remember what the package is about:

Once you have set all the parameters, we are ready to create the package!

Step 4: Click Publish

As soon as you create a package, the Publish button should appear on the top right corner of the API dashboard. Go ahead and SMASH IT. Your L402 API will be live in no time.

To test it, make an API request to the Sparkwall hostname we have just created. It will look something like https://cat-fact.ln.sulu.sh/facts . Try access that URL on the browser, if everything went well you should now get a Payment Required error on your browser window. You are now required to pay a small fee to access the API!

If you inspect the response headers, you will find a WWW-Authenticate header with the L402 payment request. Go ahead and pay that lightning invoice, construct an L402 token as specified in our documentation, and gain access to a bunch of fun cat facts!

Wrap up

Through this tutorial we have learnt how we can easily monetize an API with L402 thanks to Sulu's Sparkwall platform. Sparkwall is still in beta, and we are looking for feedback. So go ahead, sign up to Sparkwall, play around and help bring forward the future of API and internet monetization.