L402
Charge for an API request with a Lightning payment using your Phoenixd node and phoenixd-l402-sdk. Your backend sets the price, verifies the payment and serves the result. Payments go to your node.
Set up your paid endpoint
- Create a Phoenixd node and save its connection URL and limited-access password. For a Nodana-hosted node, copy the URL from its details in the dashboard.
- Install the SDK in your Node.js backend and generate an application signing secret. Follow the SDK setup and handler example.
- Choose a price as a positive integer string in satoshis, such as
amount: "100"for 100 sats. - Add a database operation that records each payment once before you deliver the paid result.
When a client requests the endpoint without a valid credential, return the SDK's HTTP 402 challenge. An L402-capable client pays the invoice and retries the same request with its payment credential. The SDK verifies the proof; your backend records the purchase and delivers the result.
Record the purchase before delivery
For one request per payment, use a unique payment-hash insert in your database. Only the first insert should succeed, including when two retries arrive together. The SDK example calls this application function db.recordPaymentOnce; implement it using your database.
If a payment has already been recorded, check the purchase's delivery status before asking the customer to pay again. Keep enough purchase information to recover when a request fails after recording payment. A database failure should stop delivery and return a service error.
You can also grant access to a purchased resource using your own entitlement records. Keep your normal sign-in and permission checks, and set Cache-Control: no-store on paid responses.
Set payment and credential expiry
Set these options on L402.create:
| Option | Purpose | Default |
|---|---|---|
invoiceExpirySeconds | Time allowed to pay the invoice | 300 seconds |
challengeExpirySeconds | Time allowed to present the credential | 300 seconds |
network | Expected Lightning network | mainnet |
Credential expiry is capped to the invoice expiry. Paying does not extend the deadline. Your purchase records determine any access you grant after initial verification.
Test and troubleshoot
Call your endpoint with curl -i https://api.example.com/premium. Expect HTTP 402 with a WWW-Authenticate: L402 header. Use an L402-capable client to pay and retry, then check that the purchase is recorded and the result is delivered once.
- The node rejects your connection: check its complete URL, availability and limited-access Phoenixd password. See API authentication.
- Invoice creation fails: check the node's status and expected network. Handle
L402Errorwith codeinvalid_invoiceas a service error. - A paid retry is rejected: check the deadline, current price, signing secret and that the retry uses the same URL, method and body.
- A payment is already recorded: look up the original purchase and recover its delivery before requesting another payment.
Use HTTPS for remote node and API connections. Keep node passwords, signing secrets and payment credentials out of browser code and logs.