L402 API Catalog › Bitcoin & Lightning Data

Invoice Decode L402 API

Decode any BOLT11 Lightning invoice into structured data.

30 sats per call, paid over the Lightning Network. No API key and no signup: the first request answers 402 Payment Required with a Lightning invoice, and repeating the request with the proof of payment returns your data.

l402_invoice_decode 30 sats

Parameters

invoice BOLT11 string

Call it with curl

The first call answers 402 with a Lightning invoice in the WWW-Authenticate header. Pay it from any Lightning wallet, then repeat the call with the L402 token and preimage.

cURL

curl -X POST https://lightningfaucet.com/api/ \
  -H "Content-Type: application/json" \
  -H "Authorization: L402 $MACAROON:$PREIMAGE" \
  -d '{"action":"l402_invoice_decode","invoice":"lnbc..."}'

What comes back

A successful call returns JSON, with the delivered content merged over the standard L402 receipt fields. Example values, not live data.

JSON

{
    "success": true,
    "http_code": 200,
    "service": "invoice_decode",
    "timestamp": 1789139045,
    "paid_sats": 30,
    "amount_sats": 1000,
    "description": "Coffee",
    "payment_hash": "9b1d4f0c3a7e5b28d6410f9c2e8a7b35d0c94e16f8a2b7d3c5e091a4f6b8d2c70",
    "destination": "03a5c7e9142b8d6f0a3c5e7911d4b6f8a2c40e6d8b1f3a5c7e9012b4d6f8a1c3e5b",
    "expiry": 3600,
    "is_expired": false
}

Call it from an AI agent

With lightning-wallet-mcp the payment is handled for you. From the CLI:

Terminal

lw pay-api "https://lightningfaucet.com/api/l402/invoice_decode?invoice=lnbc..."

In Claude Code, Cursor or any MCP host, ask the agent to call pay_l402_api with that URL. The fee is 1% of the price, rounded down, so calls under 100 sats carry no platform fee.

Questions

How much does the Invoice Decode API cost?
Each call costs 30 sats, paid as a Lightning invoice at request time. There is no subscription, no minimum and no monthly bill: you are charged for the calls you make.

Do I need an API key or an account?
No. Payment is the authentication. The first request answers 402 Payment Required with a Lightning invoice; settling it returns a preimage that authenticates the retry.

What does Invoice Decode return?
A JSON object carrying amount_sats, description, payment_hash, destination, expiry and is_expired. See the example response above for the exact shape.

Related endpoints

Lightning Stats 200 sats Price Oracle 200 sats LNURL Metadata 30 sats Node Info 30 sats Fee Estimate 50 sats Ask a Human 500 sats

All Bitcoin & Lightning Data endpoints · How L402 authentication works · List your own API on the gateway