API documentation

Base URL: https://lightning-swap.com · Authenticated methods under /api/v2

Getting started

1. Create an account and open the API tokens page.
2. Generate a key. Copy the Lightning Swap Connect URI (or the API key and API secret it carries) from the API tokens page.
3. Sign every authenticated POST with HMAC-SHA256 over the exact JSON body string.
4. Create orders with type=fixed, direction=to, toCcy=BTCLN, and a BOLT11 in toAddress.
5. Poll /order until DONE, EXPIRED, or EMERGENCY. On emergency, call /emergency with choice=REFUND.

Lightning Swap Connect (LSC) URI

Lightning Swap Connect is OpenReceive's compact, server-only format for configuring an authenticated swap API endpoint. One URI replaces a provider's HTTPS base URL, API key, and API secret. The API tokens page shows a ready-made LSC URI for every key you create — copy it and hand it to your integration as a single secret.

lightning+swapconnect://lightning-swap.com?key=<API key>&secret=<API secret>

That URI resolves to:

The base URL is the root; authenticated methods still live under /api/v2 — see Authentication. LSC carries no extra privileges: it is the same key and secret in one string.

LSC is not an NWC replacement. NWC connects OpenReceive to the receive-only Lightning wallet. LSC connects OpenReceive to an optional service — such as Lightning Swap — that accepts another asset and swaps it into a Lightning invoice.

URI syntax

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

• The URI must not contain user information or a fragment.
• Each required query parameter must appear exactly once.
• Unknown parameters are rejected, so a misspelling cannot silently change configuration.
• Query names and values use standard URI percent-encoding. Producers should use a URL implementation rather than concatenating strings; the OpenReceive Node package exports formatLscUri() for this.

LSC v0.1 defines one swap-provider API contract. Every configured provider is assumed to implement that contract, so the URI has no selector or negotiation field.

Endpoint mapping

The custom scheme always maps to HTTPS:

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

Plain HTTP cannot be expressed. The parsed base path always has a trailing slash. A provider identifier is derived from the lower-case hostname, optional port, and path by replacing unsupported characters with -. Two configured URIs may not derive the same identifier.

Environment variables

Swap providers are configured with LSC_URI_PRIMARY and optional LSC_URI_BACKUP. While the primary answers, OpenReceive uses only the primary; the backup is consulted only when the primary is down.

Security requirements

• Keep LSC URIs on the server and 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 fragments.
• Give each application a separate provider key with the smallest available permissions and budget.
• Rotate the key and secret if the URI is exposed — revoke it on the API tokens page and create a new one.
• Redact the complete value. Redacting only secret still exposes the API key and provider identity.
• Do not place an LSC URI in a link, QR code, or browser address bar. URI credentials can leak through history, telemetry, referrers, clipboard managers, and process inspection.

NWC intentionally defines a connection URI for a client and wallet service with cryptographic keys. LSC packages conventional HTTPS API credentials; it does not add end-to-end encryption beyond TLS and does not define a provider authorization handshake.

Authentication

Authenticated requests send JSON (UTF-8) with these headers:

Sign the exact bytes of the request body. For empty-body calls such as /ccies, POST the literal string {} and sign that — do not sign an empty string.

cURL — sign and call

BODY='{"type":"fixed","fromCcy":"SOL","toCcy":"BTCLN","direction":"to","amount":"0.00004243"}'
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')

curl -sS https://lightning-swap.com/api/v2/price \
  -H "Content-Type: application/json; charset=UTF-8" \
  -H "X-API-KEY: $API_KEY" \
  -H "X-API-SIGN: $SIGN" \
  -d "$BODY"

Python — sign and call

import hashlib, hmac, json, urllib.request

def ls_post(path, payload, api_key, api_secret):
    body = json.dumps(payload, separators=(",", ":"))
    sign = hmac.new(api_secret.encode(), body.encode(), hashlib.sha256).hexdigest()
    req = urllib.request.Request(
        f"https://lightning-swap.com{path}",
        data=body.encode(),
        headers={
            "Content-Type": "application/json; charset=UTF-8",
            "X-API-KEY": api_key,
            "X-API-SIGN": sign,
        },
        method="POST",
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)

# Empty-body catalog call — body must be "{}"
print(ls_post("/api/v2/ccies", {}, API_KEY, API_SECRET))

Canonical JSON matters for the signature: whatever string you hash must be identical to the bytes on the wire. Prefer a compact encoder (no insignificant whitespace) and reuse that string for both signing and the POST body.

Request limits

Weight budget: 900 units per UTC minute per API token.

• Exceeding the minute budget returns code: 429 — Rate limit exceeded.
• When used weight in the current minute reaches 150, further /create calls are blocked (Create rate limit gate reached).

Response envelope

Every JSON method returns:

{
  "code": 0,
  "msg": "OK",
  "data": { }
}

For /price, FixedFloat-style validation often still returns code: 0 with data.errors[] populated (e.g. LIMIT_MIN, OFFLINE_FROM). Treat a non-empty errors array as “do not create”.

Typical integration flow

1. GET /rates/fixed.xml — cache indicative rates and min/max (optional; no auth).
2. POST /api/v2/ccies — confirm pay-in codes and recv/send.
3. POST /api/v2/price — quote direction=to for a Lightning amount (or from for a deposit amount).
4. POST /api/v2/create — binding order; store data.id + data.token; show from.address / from.amount to the payer.
5. POST /api/v2/order — poll until terminal.
6. If status=EMERGENCY, POST /api/v2/emergency with choice=REFUND and a refund address on the deposit network; poll until DONE with back.tx.id.

/create is authoritative. XML rates and /price are for UX and limits — the deposit amount on the create response is what the payer must send.

<rates>
  <item>
    <from>SOL</from>
    <to>BTCLN</to>
    <in>1</in>
    <out>0.00117230</out>
    <amount>0.00320351</amount>
    <tofee>0.00000700 BTCLN</tofee>
    <minamount>0.02500000 SOL</minamount>
    <maxamount>1.35281076 SOL</maxamount>
  </item>
  …
</rates>

{
  "code": 0,
  "msg": "OK",
  "data": [
    {
      "code": "SOL",
      "coin": "SOL",
      "network": "SOL",
      "name": "Solana",
      "recv": 1,
      "send": 0,
      "tag": null,
      "contract": null,
      "priority": 0,
      "logo": "https://lightning-swap.com/assets/images/coins/svg/sol.svg",
      "color": "#a364fc"
    },
    {
      "code": "USDTTRC",
      "coin": "USDT",
      "network": "TRX",
      "name": "Tether (TRC20)",
      "recv": 1,
      "send": 0,
      "tag": null,
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "priority": 4,
      "logo": "https://lightning-swap.com/assets/images/coins/svg/usdttrc.svg",
      "color": "#53ae94"
    },
    {
      "code": "BTCLN",
      "coin": "BTC",
      "network": "LN",
      "name": "Bitcoin (Lightning)",
      "recv": 0,
      "send": 1,
      "tag": null,
      "contract": null,
      "priority": 0,
      "logo": "https://lightning-swap.com/assets/images/coins/svg/btcln.svg",
      "color": "#9157ff"
    }
  ]
}

// Request
{
  "type": "fixed",
  "fromCcy": "SOL",
  "toCcy": "BTCLN",
  "direction": "to",
  "amount": "0.00004243"
}

// Response
{
  "code": 0,
  "msg": "OK",
  "data": {
    "from": {
      "code": "SOL",
      "network": "SOL",
      "coin": "SOL",
      "amount": 0.03815503,
      "rate": 0.00116446,
      "precision": 8,
      "min": 0.025,
      "max": 0.91611682,
      "usd": 2.9,
      "btc": 0.00004488
    },
    "to": {
      "code": "BTCLN",
      "network": "LN",
      "coin": "BTC",
      "amount": 0.00004243,
      "rate": 858.76715387,
      "precision": 8,
      "min": 0.00002711,
      "max": 0.00106478,
      "usd": 2.74
    },
    "errors": []
  }
}

// Request
{
  "type": "fixed",
  "fromCcy": "SOL",
  "toCcy": "BTCLN",
  "direction": "to",
  "amount": "0.00004243",
  "toAddress": "lnbc42430n1p49elex…cplvlg2n"
}

// Response (trimmed)
{
  "code": 0,
  "msg": "OK",
  "data": {
    "id": "QBSPEO",
    "type": "fixed",
    "email": "",
    "status": "NEW",
    "time": {
      "reg": 1784479529,
      "start": null,
      "finish": null,
      "update": 1784479529,
      "expiration": 1784480129,
      "left": 600
    },
    "from": {
      "code": "SOL",
      "coin": "SOL",
      "network": "SOL",
      "name": "Solana",
      "alias": "solana",
      "amount": "0.03815503",
      "address": "DTJnkqp4Uxx4ccpzLqSnaRtoescQRgpm1s5Pra3LesXF",
      "tag": "",
      "tagName": null,
      "tx": {
        "id": null,
        "amount": null,
        "fee": null,
        "ccyfee": null,
        "timeReg": null,
        "timeBlock": null,
        "confirmations": null
      },
      "addressAlt": null,
      "reqConfirmations": 1,
      "maxConfirmations": 16
    },
    "to": {
      "code": "BTCLN",
      "coin": "BTC",
      "network": "LN",
      "name": "Bitcoin (Lightning)",
      "alias": "lightning",
      "amount": "0.00004243",
      "address": "lnbc42430n1p49elex…cplvlg2n",
      "tag": "",
      "tagName": null,
      "tx": { "id": null, "amount": null, "fee": null, "ccyfee": null,
              "timeReg": null, "timeBlock": null, "confirmations": null }
    },
    "back": {
      "code": "",
      "amount": null,
      "address": "",
      "tx": { "id": null, "amount": null, "fee": null, "ccyfee": null,
              "timeReg": null, "timeBlock": null, "confirmations": null }
    },
    "emergency": { "status": [], "choice": "NONE", "repeat": "0" },
    "token": "ls7c2edffd2acd0be11bb1b6983975d7dc8d2945400a5b012b"
  }
}

// Request
{ "id": "QBSPEO", "token": "ls7c2edffd2acd0be11bb1b6983975d7dc8d2945400a5b012b" }

// Response data (highlights)
{
  "id": "QBSPEO",
  "status": "DONE",
  "time": {
    "reg": 1784479529,
    "start": 1784479622,
    "finish": 1784479625,
    "update": 1784479625,
    "expiration": 1784480129,
    "left": 502
  },
  "from": {
    "code": "SOL",
    "amount": "0.03815503",
    "address": "DTJnkqp4Uxx4ccpzLqSnaRtoescQRgpm1s5Pra3LesXF",
    "tx": {
      "id": "5jFuRUiLFRK3LFdghA6BVx5KkT5b58uhSWqDqmu5wJrwngKNoq8by7i7DPi55Vuwq8GyNk7yBdctM2K4oBNnHdP8",
      "amount": "0.03815503",
      "fee": "0.00000635",
      "ccyfee": "SOL",
      "timeReg": 1784479622,
      "timeBlock": 1784479622,
      "confirmations": "12"
    },
    "reqConfirmations": 1,
    "maxConfirmations": 16
  },
  "to": {
    "code": "BTCLN",
    "amount": "0.00004243",
    "tx": {
      "id": "dd57894b0f721cfa593857f69efd10ce920f0a7710f7deb73782004d19664ac1",
      "amount": "0.00004243",
      "fee": "0.00000011",
      "ccyfee": "BTC",
      "timeReg": 1784479625,
      "timeBlock": 1784479625,
      "confirmations": "1"
    }
  },
  "emergency": { "status": [], "choice": "NONE", "repeat": "0" },
  "token": "ls7c2edffd2acd0be11bb1b6983975d7dc8d2945400a5b012b"
}

// Request (classic underpay → refund)
{
  "id": "WJ3IYG",
  "token": "ls2e2ac023d09704e467cbbf3d620ea54f5a315c04582770eb",
  "choice": "REFUND",
  "address": "BfMe1deFYJwaSeD9XoN1X8xw1PtcYjginrbvkQjS9w9U"
}

// Response
{ "code": 0, "msg": "", "data": true }

Order statuses

Emergency reasons (data.emergency.status[])

emergency.choice: NONE until the client calls /emergency, then REFUND. EXCHANGE is never set by Lightning Swap.

Currency codes

Public codes match FixedFloat naming so pair strings port cleanly.

HTTP / code mapping

Worked example — happy path (SOL → BTCLN)

Captured from a full Lightning Swap exercise (sol_sol_lightningswap_exercise.json). Sequence: rates → ccies → price → create → poll → DONE.

1. Quote direction=to for 0.00004243 BTC → pay-in 0.03815503 SOL.
2. Create with matching BOLT11; receive deposit address DTJnkqp4…, order QBSPEO.
3. Payer sends exact from.amount.
4. Poll until DONE: deposit tx on from.tx, Lightning payment id on to.tx.

# Minimal create + poll loop (bash)
BODY=$(jq -nc --arg inv "$BOLT11" \
  '{type:"fixed",fromCcy:"SOL",toCcy:"BTCLN",direction:"to",amount:"0.00004243",toAddress:$inv}')
SIGN=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $2}')
CREATE=$(curl -sS https://lightning-swap.com/api/v2/create \
  -H "Content-Type: application/json; charset=UTF-8" \
  -H "X-API-KEY: $API_KEY" -H "X-API-SIGN: $SIGN" -d "$BODY")
ID=$(jq -r .data.id <<<"$CREATE")
TOKEN=$(jq -r .data.token <<<"$CREATE")
# … instruct payer to send .data.from.amount to .data.from.address …
# then poll /api/v2/order with {"id","token"} until status is DONE / EMERGENCY / EXPIRED

Worked example — classic underpay → refund

From stress_underpay_classic_sol_sol_lightningswap.json: order created for 0.038088 SOL → 0.00004265 BTC; payer sent only 0.031544 SOL → EMERGENCY with LESS → /emergency REFUND → DONE with refund tx on back.tx.

1. Order enters emergency after underpay

{
  "code": 0,
  "msg": "OK",
  "data": {
    "id": "WJ3IYG",
    "type": "fixed",
    "status": "EMERGENCY",
    "from": {
      "code": "SOL",
      "amount": "0.038088",
      "address": "7V3hvrvkZWdeFPAkDa2Z4im5FYfp1ajPpKgg5rTDWz8e",
      "tx": {
        "id": "25vM5nq7yixAszcsW3NJj4JBcFqNcP4mmXBfVpUGHTNWn8LSZX5zcEjJPpatXq7HHyUVZ9tQ4Yz4pyPaCVgwEPfH",
        "amount": "0.031544",
        "fee": "0.00000635",
        "ccyfee": "SOL",
        "confirmations": "4"
      }
    },
    "to": {
      "code": "BTCLN",
      "amount": "0.00004265",
      "tx": { "id": null, "amount": null }
    },
    "back": {
      "code": "SOL",
      "amount": "0.031544000",
      "address": "",
      "tx": { "id": null }
    },
    "emergency": {
      "status": ["LESS"],
      "choice": "NONE",
      "repeat": "0"
    },
    "token": "ls2e2ac023d09704e467cbbf3d620ea54f5a315c04582770eb"
  }
}

2. Submit refund

{
  "id": "WJ3IYG",
  "token": "ls2e2ac023d09704e467cbbf3d620ea54f5a315c04582770eb",
  "choice": "REFUND",
  "address": "BfMe1deFYJwaSeD9XoN1X8xw1PtcYjginrbvkQjS9w9U"
}
→ { "code": 0, "msg": "", "data": true }

3. Terminal state after refund broadcast

{
  "status": "DONE",
  "from": {
    "tx": {
      "id": "25vM5nq7yixAszcsW3NJj4JBcFqNcP4mmXBfVpUGHTNWn8LSZX5zcEjJPpatXq7HHyUVZ9tQ4Yz4pyPaCVgwEPfH",
      "amount": "0.031544"
    }
  },
  "to": { "tx": { "id": null } },
  "back": {
    "code": "SOL",
    "amount": "0.031539000",
    "address": "BfMe1deFYJwaSeD9XoN1X8xw1PtcYjginrbvkQjS9w9U",
    "tx": {
      "id": "LFdgqWhtpugZbCeQjm876Quva5bYKvtoHSsotZjPh7SrpgnEkf6mR2kjCxGmdCUvfsQdjBknd1VGxpUj4j3FWad",
      "amount": "0.031539000",
      "fee": "0.000005",
      "ccyfee": "SOL"
    }
  },
  "emergency": {
    "status": ["LESS"],
    "choice": "REFUND",
    "repeat": "0"
  }
}

Note back.amount matches the credited deposit (full refund). Native SOL/ETH still lose on-chain gas. to.tx stays empty because the Lightning invoice was never paid.

Not supported (FixedFloat surfaces we omit)

Compared to the full FixedFloat API, Lightning Swap does not implement: