API and remote mode

Step 01

Check API health

Start your local or Docker backend first.

curl http://localhost:3001/health

For an interactive request interface, open http://localhost:3001/swagger-ui/. The schema is at /api-docs/openapi.json.

Step 02

Decode through HTTP

Replace the placeholder with the complete plain BOLT11 string. The optional network query accepts mainnet, testnet, signet, or regtest.

curl "http://localhost:3001/api/v1/invoices/decode/PASTE_COMPLETE_INVOICE_HERE?expected_network=regtest"

The invoice is a URL path segment; URL-encode input when constructing requests programmatically. Responses use millisatoshis for amounts and Unix seconds for timestamps, and include a validation object.

Step 03

Use the terminal with the API

After building the CLI, launch remote mode:

./target/release/bolt11-decoder --api-url http://localhost:3001

Or decode directly:

./target/release/bolt11-decoder --api-url http://localhost:3001 decode 'PASTE_COMPLETE_INVOICE_HERE'

You can also configure LIGHTNING_API_URL. Remote mode requires the API to be reachable. The CLI validates locally first and attaches its local validation report to the remote result; QR images are always read locally.

Step 04

Read API errors

• 400: Invalid input or unsupported expected network.
• 404: Unknown route; check the base URL and service on that port.
• 414: Invoice exceeds the input limit.
• 422: A decoded value cannot be represented safely.