L402 API Demonstration

Step-by-step guide to navigating the L402 paywall for secure data transactions

This walkthrough will guide you through the operations of the L402 protocol. By manually completing the steps of an L402 request and payments, you will learn about the different steps of the process and what is going on behind the scenes. Happy exploring!

Prerequisites

• An active internet connection.
• A Lightning-enabled Bitcoin wallet that shows you the preimage of a payment.
• Some familiarity with command line scripting.

Make a Request to the API

We first send a data request to the Random Number API. This is an L402 API, so we will get a 402 Request for Payment error. This '402 Payment Required' error includes a 'macaroon' and a 'lightning invoice' in the authorization header.

1$ curl -v -k https://rnd.ln.sulu.sh/randomnumber

The macaroon serves as our key to access the desired information from the API. It functions as a digital token, informing the API about the permissions granted upon paying the invoice.

It encapsulates the access it grants and can be constrained by including path restrictions and additional limitations within its string representation. As long as the macaroon remains valid and hasn't expired, it can be used to access the paid services. However, the macaroon is only valid if the lightning invoice that accompanies it is paid. We attach proof-of-payment in the form of a preimage.

Pay using your invoice

Pay the lightning invoice using a digital wallet that reveals the preimage as proof once the lightning invoice has been paid.

Assemble L402 token

Now we put together the L402 token using the 'macaroon' and the 'preimage' in the following format:

L402 macaroon:preimage

The L402 token, that includes both the macaroon and the preimage (proof of payment), is all we need to authenticate our access to the API.

Receive your data

Make an authorized request with the assembled L402 in the header to the Random Number API and receive the purchased data.

1$ curl -v -k -H "Authorization: L402 macaroon:preimage" https://rnd.ln.sulu.sh/randomnumber

Do you want to try this out?

If you wan to learn how you can integrate L402 API into your next web app, check out our Github repo.