Lightning Swap Connect (LSC) URI

Lightning Swap Connect (LSC) is OpenReceive’s short, server-only format for configuring an authenticated swap API endpoint. One URI replaces a provider’s HTTPS base URL, API key, and API secret.

Example

lightning+swapconnect://swap.example/v1?key=example-key&secret=example-secret

The example resolves to:

LSC does not replace NWC. NWC connects OpenReceive to the receive-only Lightning wallet. LSC connects OpenReceive to an optional service that accepts another asset and swaps it into a Lightning invoice.

URI syntax

An LSC v0.1 URI has this form:

lightning+swapconnect://host[/path]?key=KEY&secret=SECRET

The components are:

The URI must not contain user information or a fragment. Each required query parameter must appear exactly once. Unknown parameters are rejected, so a typo cannot silently change your configuration.

LSC v0.1 defines one swap-provider API contract. OpenReceive assumes every configured provider implements it. That is why the URI has no field for choosing or negotiating a contract.

Query names and values use standard URI percent-encoding. Build URIs with a URL library instead of joining strings. The OpenReceive Node package exports formatLscUri() for this.

Endpoint mapping

The custom scheme always maps to HTTPS:

lightning+swapconnect://HOST[:PORT]/PATH
                         │
                         └── https://HOST[:PORT]/PATH/

You cannot express plain HTTP. The parsed base path always ends with a slash. OpenReceive builds a provider identifier from the lower-case hostname, the optional port, and the path, replacing unsupported characters with -. Two configured URIs may not produce the same identifier.

Environment variables

You configure swap providers with LSC_URI_PRIMARY and, optionally, LSC_URI_BACKUP. While the primary answers, OpenReceive uses only the primary. It uses the backup only when the primary is down. See Environment variables.

The BTCPay Server plugin reads no environment variables. You paste the primary and backup codes into Store → OpenReceive, and the plugin keeps them in its per-store settings (BTCPay quickstart). The same primary-then-backup rule applies.

Security requirements

An LSC URI is a bearer credential. Anyone who has it can use whatever permissions and budget the provider gave that key.

• Keep LSC URIs on the server. Keep them out of browser bundles, logs, exception messages, screenshots, analytics, shell history, and committed files.
• Store the complete URI as one secret. Do not split it into public and secret parts.
• Give each application its own provider key with the smallest permissions and budget available.
• Rotate the key and secret if the URI is exposed.
• Redact the whole value. Redacting only secret still exposes the API key and the provider’s identity.
• Do not put an LSC URI in a link, QR code, or browser address bar. Credentials in a URI can leak through browser history, telemetry, referrers, clipboard managers, and process inspection.

NWC deliberately defines a connection URI for a client and a wallet service that use cryptographic keys. LSC just packages ordinary HTTPS API credentials. It adds no end-to-end encryption beyond TLS, and it defines no provider authorization handshake.