REST

Use REST for standard HTTP integrations with the LND node behind a Node-backed deployment.

Setup reminder

Before calling LND, collect the node host, the current REST endpoint and port, a least-privilege macaroon, and the TLS behavior required by the client.

Use Configuration for the complete connection checklist. Do not copy an endpoint, port, certificate override, or dashboard path from historical documentation without verifying the current node.

Authentication

Encode the macaroon as a hex string and send it in the Grpc-Metadata-Macaroon request header.

Store the macaroon as a secret. Separate read-only monitoring credentials from credentials that can create invoices, send funds, change channels, or administer the node.

Do not log request headers, macaroon values, private keys, recovery material, or complete error objects that can expose credentials.

Request and response encoding

Send JSON requests with the content type required by the LND REST endpoint.

LND REST represents some byte fields differently from the underlying gRPC API. When a byte field appears in a path or query parameter, follow the endpoint’s REST mapping. Some values require URL-safe base64 instead of raw hex or standard base64.

Treat identifiers, hashes, payment data, and serialized messages as typed values. Validate their expected encoding before constructing a URL.

First request

Start with a read-only node-information or health request.

Verify the node identity and Bitcoin network in the response before implementing payment, channel, or wallet operations. Confirm that authentication failures, TLS failures, and unexpected response codes are handled without exposing secrets.

Client behavior

Use explicit connection and request timeouts. Retry only operations that are safe to repeat, use bounded exponential backoff, and preserve application-level idempotency for payment workflows.

Reuse connections where the client library supports it. Apply response-size limits and parse structured errors before deciding whether to retry, fail, or escalate.

Do not disable TLS verification in production. Isolate any development-only override and remove it before deployment.

Monitoring patterns

Use REST for periodic node information, wallet balances, channel state, fee reports, and other operational reads when streaming is not required.

Track request latency, response status, authentication failure rate, TLS failures, timeout rate, and the age of the last successful read.

A successful HTTP response does not replace reconciliation. Compare direct node activity with Payments and treasury records when the same node backs a Payments integration.

Write operations

Before enabling write calls, document who can create invoices, send funds, open or close channels, change fees, or administer the node.

Use the narrowest credential and smallest tested workflow. Verify the result with an independent read and capture an audit record that does not contain secrets.

Continue

• Configuration for endpoint, macaroon, and TLS setup.
• GRPC for generated clients and streaming calls.
• Node Security and Macaroons for access controls.
• Resources for official LND API, repository/proto, and installation references.