Skip to main content
The mainnet developer preview supports two end-to-end flows: exchanging BTC for an asset and paying a Lightning invoice. Asset exchange selects a market from the solver registry. Lightning send uses one pinned solver, reached with an addressed RFQ over Nostr. The solver card publishes the current limits and fee for each swap.
Every funded swap moves real bitcoin. Use small amounts and implement the cancellation or refund path before funding a swap. InMemoryWalletRepository, InMemoryContractRepository, and InMemoryAssetSwapRepository keep state only for the life of the process. Applications that may restart need persistent repositories supported by their runtime.

Setup

Install the SDK, Intents client, and the Nostr transport peer dependency:
Fund enough BTC to cover more than one test. An unresolved swap holds its funds in the contract until its cancellation or refund path becomes available, so a wallet funded for exactly one swap may be unable to start another.

Pay a Lightning Invoice

Lightning send is exact-out: payment.fundAmount is the quote’s from_amount, and the invoice amount is its to_amount. Recovery is not automatic. If the solver does not pay the invoice, the wallet must return after refund_locktime and submit a refund.
The @arkade-os/swap/nostr transport uses nostr-tools to send the addressed RFQ over the relays in the solver card. Addressed RFQs use Nostr kind 24859 during the preview. requestLightningSend requests a quote, derives the expected contract locally with the SDK-supplied covenant co-signer, rejects an address mismatch, and checks invoice expiry and refund headroom. Funding payment.fundAmount accepts the quote. The solver observes the funded contract through Arkade, pays the invoice, learns the preimage, and claims the swap. The solver can complete this sequence without the application remaining online. The card currently accepts Lightning sends from 500 to 50,000 sats and sets fee_bps: 30. A 10,000-sat invoice locks 10,031 sats, with the difference between from_amount and to_amount representing the fee.

Exchange BTC for an Asset

Asset exchange selects a compatible market, calculates a quote from the solver card’s feed and fee, and funds the swap. An unfilled swap has no automatic expiry. Keep cancellation available until the application confirms a fill or cancellation.
An asset exchange settles both sides through Arkade. One transaction enforces the swap and binds the asset movement. Record offer.offerHex and the funding txid in the SDK asset-swap repository as soon as wallet.send returns. cancelOffer and restoreAssetSwaps use both values to identify the deposit. cancelOffer submits the cancellation without a solver signature. Keep that action available because the deposited funds remain locked until the swap is filled or cancelled.

Lightning Receive

No solver currently serves Lightning receive. The solver card sets max_base_amount: "0" for lightning:BTC → arkade:BTC, so it refuses requests for that route. requestLightningReceive requests a hold invoice and seals the claim preimage. The configured claim key determines who can open the packet, publish the preimage, and complete the claim. Implement the receive and claim flow when a compatible solver becomes available.

Preview Availability

Lightning send uses a pinned solver during the preview. The quote, funding, settlement, and recovery sequence follows the shared protocol lifecycle, while the APIs and provisional wire details may still change. Build against the pinned card now and add broader solver selection as compatible implementations become available.

Lightning Solver Card

The Lightning preview solver is not listed in the registry. Its signed card publishes the connection details and current terms. Pin its relay and solver key in nostrRfqTransport.
min_quote_amount and max_quote_amount define the Lightning amount accepted when paying an invoice. The max_base_amount of "0" closes the lightning:BTC → arkade:BTC receive route on this deployment.The card is signed, and sig covers the connection data it advertises. Pinning the card makes this solver and its advertised connection data part of the application’s trust boundary. Load the latest signed card before deployment because its limits, fee, relay, and key may change.

Integrate Lightning

Request, fund, claim, and recover Lightning swaps.

Exchange Assets

Integrate asset discovery, exchange, and cancellation.

Implementation Status

Check solver, client, and route readiness.

Trust and Limitations

Review settlement guarantees, external dependencies, and recovery conditions.