Lightning

Code for the arkade:BTC → lightning:BTC and lightning:BTC → arkade:BTC routes. For the model underneath, see Markets and Execution and the protocol reference.

Setup

pnpm add @arkade-os/sdk @arkade-os/swap

Prerequisites:

an initialized Arkade IWallet — Create Your Wallet;
an Arkade server URL — developer resources lists the networks.

Create the transport, and catch SwapRefusal where you request quotes:

import { nostrRfqTransport } from "@arkade-os/swap/nostr";

// The developer-preview solver
const relays = ["wss://nostr.arkade.sh"];
const solverPubkey =
  "66422c952f8dcb96e4d0c3f049cd1e265b8461b916d9913c65c2494b64b4e3ce";

const transport = nostrRfqTransport({ relays, solverPubkey });

Requests are sealed so only that solver reads them. SwapRefusal is that solver declining instead of quoting — amount outside its bounds, route off, no inventory — and it carries the reason; nothing is committed, so show the reason or re-request. Check quote.pair matches the pair you asked for — no transport does this for you.

Pay an Invoice

Decode the BOLT11 locally, then request a quote:

import { requestLightningSend, type InvoiceFacts } from "@arkade-os/swap";

const invoice: InvoiceFacts = {
  raw: bolt11,
  paymentHash: decoded.paymentHash,
  amountSats: decoded.amountSats,
  expiresAt: decoded.expiresAt,
};

const payment = await requestLightningSend(
  wallet,
  arkadeServerUrl,
  transport,
  { invoice },
);

if (payment.quote.pair !== "arkade:BTC->lightning:BTC") {
  throw new Error("quote pair mismatch");
}

requestLightningSend rejects expired invoices, unsafe refund windows, and a quoted address that differs from the contract it derives locally. This corridor is exact-out: quote.to_amount is the invoice amount and quote.from_amount is what the lockup must carry — the spread is the fee. requestLightningSend registers the lockup with your wallet’s contract manager and derives the swap secrets from the wallet seed — the covenant is watched, survives restart, and your app stores nothing. Fund it:

const fundingTxid = await wallet.send({
  address: payment.address,
  // number, and NOT the invoice amount — the spread is the fee
  amount: payment.quote.from_amount,
});

Funding accepts the quote; it does not prove the invoice was paid.

Refund a Stalled Send

If the solver never pays, the lockup is yours to reclaim once refund_locktime passes — nothing does this automatically:

import { refundIfUnresolved, senderIdentityForRfqSecrets } from "@arkade-os/swap";

const outcome = await refundIfUnresolved(
  transport,
  wallet.arkProvider,
  wallet.indexerProvider,
  {
    rfqId: payment.rfqId,
    script: payment.script,
    sender: await senderIdentityForRfqSecrets(wallet, payment.secrets),
    // Optional on the quote type (absent for arkade↔arkade); always present
    // on corridor quotes like this one.
    refundLocktime: payment.quote.refund_locktime!,
  },
);

Switch on the four RefundOutcome variants: resolved, refunded, nothing_to_refund, and needs_recovery — the last is returned, not retried, and needs the wallet’s VTXO recovery before a refund can be pushed.

Receive a Payment

Claim while your wallet is online. Offline claiming through a daemon is not available yet, and an unclaimed receive stalls both sides until the timeouts fire.

Not available in the developer preview. The preview solver does not serve lightning:BTC → arkade:BTC yet. The API below is the released surface, ready when a solver serves the corridor.

requestLightningReceive derives the preimage and payout key from the wallet seed, seals the claim packet, and verifies the lockup it derives locally. The solver mints a hold invoice on the payment hash and never sees the preimage until you claim.

import { requestLightningReceive, type InvoiceFacts } from "@arkade-os/swap";
import { secp256k1 } from "@noble/curves/secp256k1.js";

const receive = await requestLightningReceive(
  wallet,
  arkadeServerUrl,
  transport,
  {
    amount: amountSats,
    amountSide: "to", // amountSats is what you receive
    // Sealed recipient of the claim packet. This guide claims from the same
    // wallet, so nobody needs to read it — a throwaway key is correct. A
    // wallet claiming through covclaimd passes covclaimd's compressed key.
    covclaimdPubkey: secp256k1.getPublicKey(secp256k1.utils.randomSecretKey(), true),
    // Your BOLT11 decoder, applied to the solver's hold invoice — return
    // the same InvoiceFacts shape the send flow builds (raw, paymentHash,
    // amountSats, expiresAt).
    decodeInvoice,
  },
);

The lockup is registered with your wallet’s contract manager, as with a send — nothing to store before you pay. Paying the hold invoice (receive.invoice) is the acceptance — there is no accept message. The solver funds the Arkade lockup once it sees the payment held.

Claim It

Claiming reveals the preimage, which is what lets the solver settle the Lightning payment: the swap completes only when you claim. claimReceiveLockup waits for the solver’s funding, then pushes the claim:

import {
  claimReceiveLockup,
  preimageForRfqSecrets,
  senderIdentityForRfqSecrets,
} from "@arkade-os/swap";
import { ArkAddress } from "@arkade-os/sdk";

const { arkTxid } = await claimReceiveLockup(wallet.indexerProvider, wallet.arkProvider, {
  swapPkScript: receive.swapPkScript,
  script: receive.script,
  receiver: await senderIdentityForRfqSecrets(wallet, receive.secrets),
  preimage: await preimageForRfqSecrets(wallet, receive.secrets),
  destinationPkScript: ArkAddress.decode(receive.payoutAddress).pkScript,
  // The quote's to_amount — the claim refuses a short-funded lockup rather
  // than publish the preimage for less than the swap owes.
  expectedAmount: receive.quote.to_amount,
  vtxos: [], // required by the input type; the claim waits for funding itself
  // Unix seconds — refund_locktime is a Unix timestamp, not a block height.
  // Optional on the quote type; always present on corridor quotes.
  deadline: receive.quote.refund_locktime!,
});

Arkade Assets

Swap BTC against an Arkade Asset.

RFQ Protocol

Review quote, transport, settlement, and recovery requirements.

Understand Intents

Build with Intents

Earn Fees

Reference

Setup

Pay an Invoice

Refund a Stalled Send

Receive a Payment

Claim It

Arkade Assets

RFQ Protocol

​Setup

​Pay an Invoice

​Refund a Stalled Send

​Receive a Payment

​Claim It

Arkade Assets

RFQ Protocol

Setup

Pay an Invoice

Refund a Stalled Send

Receive a Payment

Claim It