L402

How to use it as an API

Understanding L402: Pay-Per-Use APIs with Bitcoin 💡

L402 is a "Bitcoin Standard" for APIs. It lets different applications "talk" to each other securely. Instead of usernames, passwords, and credit card details, it uses a clever combination of:

  • Macaroons: These are like special, tamper-proof digital "tickets" or "tokens" that grant access.
  • Lightning Network: This allows for instant, low-fee Bitcoin payments.

Together, they create a secure and private way to access paid services. You only pay for what you use.Learn More

Choose a service to get started:

How to Use Our L402 Services: A Step-by-Step Guide ⚙️

Using an L402-protected service involves a simple two-step process: first, you request access and get a "bill" (invoice), and second, you pay the bill and present your "proof of payment" (preimage) to use the service.

Step 1: Request Access & Get Your "Ticket" and "Invoice"

  1. Make Your First Request: Send your initial API request to the desired service endpoint.
  2. Receive a 402 Payment Required Response: This is normal! The response header will contain:
    • A Macaroon (your access "ticket").
    • An Invoice (a Lightning Network payment request).
    www-authenticate: L402 macaroon="<YOUR_UNIQUE_MACAROON>", invoice="<LIGHTNING_INVOICE_STRING>"

Step 2: Pay the Invoice & Use the Service

  1. Pay the Lightning Invoice: Use any Lightning-compatible wallet.
  2. Get the Preimage: After payment, your wallet provides a preimage (your "proof of payment").
  3. Make Your Second Request (with Payment Proof): Send the exact same request as in Step 1 tohttps://sats4ai.com/api/l402/image. This time, include the `Authorization` header:
    Authorization: L402 <YOUR_UNIQUE_MACAROON>:<YOUR_PREIMAGE>

❗ Important Notes:

  • Identical Requests: The body/data of your first and second requests must be exactly the same.
  • Not a Stream (Currently): Our L402 services do not currently support streaming responses.

Using the L402 Image Generation API

You can generate images by sending a POST request to our L402-protected image generation endpoint. Follow the steps below, which include example `curl` commands.

API Endpoint: https://sats4ai.com/api/l402/image

Step 1: Initial Request (to get Macaroon and Invoice)

First, make a request to the API with your desired image parameters. This initial request will not generate the image yet; instead, it will return a 402 Payment Required status along with the L402 headers (a macaroon and a Lightning invoice).

Example `curl` command:

curl -X POST https://sats4ai.com/api/l402/image \
-H "Content-Type: application/json" \
-d '{
  "input": {
    "prompt": "A futuristic cityscape at sunset, neon lights reflecting on wet streets",
    "width": 1024,
    "height": 1024
  },
  "model": "Best"
}' \
-i

Explanation of the command:

  • -X POST: Specifies an HTTP POST request.
  • https://sats4ai.com/api/l402/image: The target API URL.
  • -H "Content-Type: application/json": Indicates the request body is JSON.
  • -d '{...}': The JSON data payload with your image preferences.
  • -i: Tells `curl` to include HTTP response headers in the output (so you can see the www-authenticate header).

Expected Response Headers:

You will receive an HTTP/1.1 402 Payment Required response. Look for the www-authenticate header:

www-authenticate: L402 macaroon="<YOUR_MACAROON_STRING_HERE>", invoice="<YOUR_LIGHTNING_INVOICE_HERE>"
  • <YOUR_MACAROON_STRING_HERE>: This is your unique access token (the "ticket").
  • <YOUR_LIGHTNING_INVOICE_HERE>: This is the Lightning Network invoice you need to pay.

Step 2: Pay the Lightning Invoice

Copy the <YOUR_LIGHTNING_INVOICE_HERE> string and pay it using any Lightning-enabled Bitcoin wallet. Upon successful payment, your wallet will provide you with a preimage. The preimage is your cryptographic proof of payment.

Step 3: Final Request (to get the Image)

Once you have the macaroon (from Step 1) and the preimage (from Step 2), make the exact same POST request again. This time, include an Authorization header.

Important: The JSON data payload (-d '{...}') in this second request must be identical to the one sent in Step 1.

Example `curl` command:

curl -X POST https://sats4ai.com/api/l402/image \
-H "Content-Type: application/json" \
-H "Authorization: L402 <YOUR_MACAROON_STRING_HERE>:<YOUR_PREIMAGE_HERE>" \
-d '{
  "input": {
    "prompt": "A futuristic cityscape at sunset, neon lights reflecting on wet streets",
    "width": 1024,
    "height": 1024
  },
  "model": "Best"
}'

Explanation of changes:

  • Replace <YOUR_MACAROON_STRING_HERE> with the actual macaroon from Step 1.
  • Replace <YOUR_PREIMAGE_HERE> with the actual preimage from Step 2.
  • The -H "Authorization: L402 <macaroon>:<preimage>" header is added.

Expected Successful Response:

If the L402 authentication is valid, the API will process your request and return the generated image as a base64 encoded string:

data:image/jpeg;base64,... (long base64 string representing the image)

You can then decode this base64 string to get your image file.

Request Body Parameters

Here's a breakdown of the JSON object you send in your POST request body:

model: string

Specifies the quality of the image generation model.

Accepted Values: "Standard", "Better", "Best"

Example: "Best"

input: object

Contains the specific parameters for the image generation.

prompt: string

The text prompt describing the image you want to generate.

Example: "A futuristic cityscape at sunset, neon lights reflecting on wet streets"

width: integer

The width of the generated image. The value must be a multiple of 32 (if it's not, it will be rounded to the nearest multiple of 32).

Minimum: 256Maximum: 1440

Example: 1024

height: integer

The height of the generated image. The value must be a multiple of 32 (if it's not, it will be rounded to the nearest multiple of 32).

Minimum: 256Maximum: 1440

Example: 1024