NodeFlow SDK is a React library that enables seamless asset bridging between EVM chains and the Bitcoin Lightning Network.
npm install astra-modal-testbash
yarn add @lnfi-network/nodeflow-sdk
or
npm install @lnfi-network/nodeflow-sdk
`
> Peer dependencies (wagmi, viem, @reown/appkit, etc.) will be installed automatically.
Configuration
| Item | Value | Description |
| :--- | :--- | :--- |
| Project ID | Get from WalletConnect | Required for wallet connection |
| Dev API URL | | Development/Testnet |
| Prod API URL | (Contact support) | Production |
---
Quick Start
`jsx
import {
NodeFlowProvider,
NodeFlowModal,
nodeFlowSend,
nodeFlowReceive,
useNodeFlowPairs // Hook to get available asset pairs
} from '@lnfi-network/nodeflow-sdk';
function App() {
return (
apiUrl=""
>
);
}
function MyBridgeUI() {
// Get available trading pairs dynamically - no hardcoded asset IDs needed!
const { pairs, defaultAssetId, isReady } = useNodeFlowPairs();
if (!isReady) return Loading...;
return (
{/ Lightning → EVM: Get tokens by paying LN invoice /}
{/ EVM → Lightning: Pay LN invoice with tokens /}
);
}
`
---
How It Works
$3
User pays a Lightning invoice to receive EVM tokens.
`
┌─────────────────────────────────────────────────────────────────────────────┐
│ Lightning → EVM (nodeFlowSend) │
└─────────────────────────────────────────────────────────────────────────────┘
User SDK LSP Node
│ │ │
│ nodeFlowSend({ │ │
│ assetId, amount │ │
│ }) │ │
├─────────────────────────────►│ │
│ │ │
│ │ Request Quote & Invoice │
│ ├──────────────────────────────►│
│ │ ◄── { invoice } │
│ │ │
│ Show Invoice QR │ │
◄──────────────────────────────│ │
│ │ │
│ User pays via LN wallet │ │
├──────────────────────────────┼──────────────────────────────►│
│ │ │
│ │ LSP releases tokens on-chain │
│ │ ◄──────────────────────────────
│ │ │
│ ✅ Tokens received! │ │
◄──────────────────────────────│ │
`
$3
User pays a Lightning invoice using their EVM tokens.
`
┌─────────────────────────────────────────────────────────────────────────────┐
│ EVM → Lightning (nodeFlowReceive) │
└─────────────────────────────────────────────────────────────────────────────┘
User SDK LSP Node
│ │ │
│ nodeFlowReceive({ │ │
│ assetId, invoice │ │
│ }) │ │
├─────────────────────────────►│ │
│ │ │
│ Show quote & confirm │ │
◄──────────────────────────────│ │
│ │ │
│ Approve & Deposit tokens │ │
├─────────────────────────────►│ │
│ │ │
│ │ Lock tokens in contract │
│ ├──────────────────────────────►│
│ │ │
│ │ LSP pays LN invoice │
│ │ ◄──────────────────────────────
│ │ │
│ ✅ Invoice paid! │ │
◄──────────────────────────────│ │
`
---
API Reference
$3
####
Main provider component. Wrap your app with this.
| Prop | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| projectId | string | ✅ | WalletConnect Project ID |
| apiUrl | string | ✅ | NodeFlow API URL |
| themeMode | 'dark' \| 'light' | - | Theme mode (default: 'dark') |
| customNetworks | Network[] | - | Custom network configuration |
####
Modal component for transaction UI. Add once inside the provider.
---
$3
#### nodeFlowSend(options)
Lightning → EVM: Get tokens by paying a Lightning invoice.
| Option | Type | Description |
| :--- | :--- | :--- |
| assetId | string | Asset ID (get from useNodeFlowPairs) |
| amount | number | Amount in satoshis |
| onProgress | (step, data) => void | Progress callback |
| onSuccess | (result) => void | Success callback |
| onError | (error) => void | Error callback |
Progress steps: 'init' → 'signature' → 'deposit' → 'pending' → 'complete'
`javascript
const result = await nodeFlowSend({
assetId: defaultAssetId,
amount: 1000,
onProgress: (step) => console.log('Step:', step),
onSuccess: (result) => console.log('Success:', result),
});
`
#### nodeFlowReceive(options)
EVM → Lightning: Pay a Lightning invoice using tokens.
| Option | Type | Description |
| :--- | :--- | :--- |
| assetId | string | Asset ID (get from useNodeFlowPairs) |
| invoice | string | Lightning invoice to pay |
| onProgress | (step, data) => void | Progress callback |
| onSuccess | (result) => void | Success callback |
| onError | (error) => void | Error callback |
Progress steps: 'init' → 'approve' → 'deposit' → 'complete'
`javascript
const result = await nodeFlowReceive({
assetId: defaultAssetId,
invoice: 'lnbc...',
onSuccess: (result) => console.log('Paid:', result),
});
`
---
$3
#### useNodeFlowPairs()
Get available trading pairs for the current chain.
`javascript
const {
pairs, // All available pairs
defaultAssetId, // First pair's asset ID
currentPair, // Currently selected pair
setCurrentPair, // Set current pair
isReady // Whether pairs are loaded
} = useNodeFlowPairs();
`
#### useNodeFlowState()
Get SDK configuration state.
`javascript
const {
supportedChainIds, // Supported chain IDs from backend
isConfigReady, // Config loaded
apiUrl, // Current API URL
targetNetwork // Current network
} = useNodeFlowState();
`
---
Using NodeFlowConfig (Existing Wagmi Setup)
If you already have Wagmi configured in your app, use NodeFlowConfig instead:
`jsx
import { NodeFlowConfig, NodeFlowModal } from '@lnfi-network/nodeflow-sdk';
// Inside your existing WagmiProvider
``