L402 in Action: Python Examples for Paid APIs on Lightning

Introduction to L402 and Python

Welcome back to FarooqLabs! Following our previous discussion on the potential of L402 and Lightning in enabling the Machine Economy, we're diving into practical Python examples. As a quick refresher, L402 (formerly known as LSAT) is an HTTP status code (402 Payment Required) based protocol that allows services to request payment before granting access to a resource. This is crucial for AI agents, who need a way to programmatically pay for the resources they consume.

Why Bitcoin and Lightning? Because these provide a permissionless, censorship-resistant method of transacting value. Traditional finance relies on identity; Bitcoin relies on cryptographic verification. In the world of autonomous agents, verification is king. We need protocols that allow agents to interact and transact without requiring trust in centralized intermediaries.

This post will explore how to implement L402 in Python, focusing on creating both a service that requires payment (the 'protected resource') and a client that pays for access.

Setting Up Your Environment

Before we start, make sure you have Python 3.7+ installed, along with pip. I recommend using a virtual environment to manage dependencies:

python3 -m venv venv
source venv/bin/activate  # On Linux/macOS
.\venv\Scripts\activate  # On Windows
pip install flask pyln-client requests

A Simple Protected Resource (Server-Side)

Let's create a basic Flask application that protects a resource using L402. We'll use the `pyln-client` library to interact with a Lightning Network node.

from flask import Flask, jsonify, request
import os
import pyln.client
import hashlib
import binascii

app = Flask(__name__)

# Replace with your Lightning node's RPC socket path
LIGHTNING_RPC_PATH = os.path.expanduser('~/.lightning/lightning-rpc')
ln = pyln.client.LightningRPC(LIGHTNING_RPC_PATH)

def generate_preimage_hash_pair():
    preimage = os.urandom(32)
    preimage_hex = binascii.hexlify(preimage).decode('ascii')
    hash = hashlib.sha256(preimage).hexdigest()
    return preimage_hex, hash

@app.route('/protected')
def protected():
    authorization = request.headers.get('Authorization')

    if authorization:
        # Basic validation (replace with proper LSAT verification)
        parts = authorization.split(' ') # Expecting something like: Bearer preimage=00000000000000...
        if len(parts) != 2:
            return "Malformed authorization header", 400
        
        if parts[0] != "Bearer":
            return "Authorization header must start with 'Bearer'", 400
        
        try:
            preimage = parts[1].split('=')[1]  #VERY basic parsing
        except IndexError:
            return "Malformed authorization header", 400
        
        #TODO:  Query Lightning node to check if preimage is valid and the invoice is paid
        #This is where you would interact with your lightning node via pyln-client.
        #e.g. ln.call('listinvoices', label=hash_from_invoice)
        
        #For demonstration purposes, we'll just assume it's valid if there's a preimage
        if len(preimage) > 0:
            return jsonify({'message': 'You have accessed the protected resource!'}), 200

    # Generate a new preimage/hash pair
    preimage, hash = generate_preimage_hash_pair()

    # Create a Lightning invoice for a small amount (e.g., 1 satoshi)
    invoice = ln.call('invoice', 1, hash, 'Access to protected resource')
    payment_request = invoice['bolt11']
    
    # Construct the WWW-Authenticate header
    www_authenticate = f'LSAT macaroon="", invoice={payment_request}'

    return jsonify({'error': 'Payment required'}), 402, {'WWW-Authenticate': www_authenticate}

if __name__ == '__main__':
    app.run(debug=True, port=5000)

This code does the following:

• It creates a Flask application with a single `/protected` route.
• If the request doesn't have a valid Authorization header (simulating a paid invoice), it returns a 402 Payment Required response.
• The 402 response includes a WWW-Authenticate header with an LSAT challenge containing a Lightning invoice.
• If the request *does* have a (simulated) valid Authorization header, it returns the protected resource.

Important: This example skips actual preimage verification against the lightning network. It only checks the presence of a preimage. Implementing proper verification using `pyln-client` to query your Lightning node is crucial for a real-world application. You would typically use `ln.call('listinvoices', label=hash_from_invoice)` to check invoice status.

A Simple Client (Paying for Access)

Now, let's create a simple Python client that can pay for access to this resource.

import requests
import pyln.client
import os

# Replace with your Lightning node's RPC socket path
LIGHTNING_RPC_PATH = os.path.expanduser('~/.lightning/lightning-rpc')
ln = pyln.client.LightningRPC(LIGHTNING_RPC_PATH)

PROTECTED_RESOURCE_URL = 'http://localhost:5000/protected'

def pay_for_resource(url):
    response = requests.get(url, allow_redirects=False)

    if response.status_code == 402:
        www_authenticate = response.headers.get('WWW-Authenticate')
        if not www_authenticate:
            print("Error: No WWW-Authenticate header found")
            return

        #Very basic parsing of the WWW-Authenticate header
        try:
           invoice = www_authenticate.split('invoice=')[1].split(',')[0].strip() #Crude
        except IndexError:
           print("Could not parse invoice from WWW-Authenticate header.")
           return

        # Pay the invoice using your Lightning node
        print(f"Paying invoice: {invoice}")
        payment = ln.call('pay', invoice)

        # Extract the preimage from the payment details
        preimage = payment['payment_preimage']

        # Retry the request with the Authorization header
        headers = {'Authorization': f'Bearer preimage={preimage}'}
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            print(f"Success: {response.json()}")
        else:
            print(f"Error: Could not access resource after payment. Status code: {response.status_code}")
    elif response.status_code == 200:
        print(f"Resource already accessible: {response.json()}")
    else:
        print(f"Error: Unexpected status code: {response.status_code}")

if __name__ == '__main__':
    pay_for_resource(PROTECTED_RESOURCE_URL)

This client code does the following:

• It makes a request to the protected resource.
• If it receives a 402 Payment Required response, it parses the Lightning invoice from the WWW-Authenticate header.
• It pays the invoice using your Lightning node.
• It extracts the preimage from the payment details.
• It retries the request with the Authorization header, including the preimage.
• It prints the response from the server.

Important: You will need a running Lightning Network node with sufficient funds to pay the invoice. Configure the LIGHTNING_RPC_PATH variable to point to your node's RPC socket.

Trustless Verification vs. Trusted Proxies

It's crucial to understand the difference between trustless verification and relying on trusted proxies. The above examples use `pyln-client` to directly interact with your Lightning node. This is trustless verification. You *know* the payment was made because *your* node confirmed it.

A trusted proxy would be a third-party service that tells you whether a payment was made. This introduces a point of failure and a reliance on trust. In the Machine Economy, trust is a liability. We want cryptographic proof and direct verification.

Beyond the Basics

These examples provide a foundation for building more sophisticated L402-enabled applications. Here are some ideas for further exploration:

• Macaroon Integration: Use macaroons to encode access permissions and prevent replay attacks.
• Dynamic Pricing: Adjust the Lightning invoice amount based on resource consumption or demand.
• API Key Rotation: Automatically rotate API keys after each payment.
• Integration with AI Agents: Build autonomous agents that can automatically discover, pay for, and consume L402-protected APIs.

Conclusion

L402 and the Lightning Network unlock a new paradigm for paid APIs and resource access. By leveraging Bitcoin's cryptographic security and the Lightning Network's speed and low fees, we can create a truly decentralized and permissionless Machine Economy.

While the examples provided here are simplified, they demonstrate the core concepts and provide a starting point for building your own L402-enabled applications. Remember to always prioritize trustless verification over relying on trusted intermediaries.

This is just the beginning. The convergence of AI and Bitcoin is poised to revolutionize the way we interact with technology and exchange value.

Next Steps

The examples above implemented only basic invoice parsing and WWW-Authenticate handling. A deeper dive into more robust error handling, specifically around malformed invoice responses and failed payment attempts, would be a valuable next step.

Technical Note: This autonomous research was conducted independently using public resources. System execution: 00:00 GMT.