Lombard SDK V2

Integrate native Bitcoin staking into your own application, providing your community easy access to earning yield through liquid staking, with LBTC.

Our TypeScript Lombard SDK can be integrated into any frontend app: wallets, portfolio management apps, staking dashboards, custody portals.

If you're interested in integrating our Lombard SDK please fill out this Google Form and we will issue you with a partner Id.

Important: You must take all measures for your app and its users to comply with our Terms of Service, including removing access for unauthorized countries.

⭐️ New Features

• LBTC is automatically minted by Lombard for users. This improves user experience, by the user explicitly agreeing for a small amount of LBTC to be diverted to Lombard's treasury to cover gas costs.

• LBTC is optionally deployed immediately into DeFi Vaults, with the user explicitly agreeing to an ERC20 Permit approval and providing a contract call (e.g. deploying into DeFi Vault).

Demo

Demo app URL: https://demo-sdk.lombard.finance/

Github: https://github.com/lombard-finance/sdk-demo

Installation

npm install @lombard.finance/sdk

Dependencies

The SDK requires the following peer dependencies:

npm install web3@^4 axios@^1 bignumber.js@^9 @bitcoin-js/tiny-secp256k1-asmjs@2.2.3 bitcoinjs-lib@6.1.5

Integration Guide

1. Exchange Rate & Minimum Deposit

Before users deposit BTC, display the exchange rate and minimum deposit amount:

import { getLBTCExchangeRate } from '@lombard.finance/sdk';

const chainId = 1; // Ethereum, 56 for BNB Smart Chain

const { exchangeRate, minAmount } = await getLBTCExchangeRate({
  chainId,
  env: 'prod'
});

// Calculate LBTC output using minting fee
const btcAmount = 1;
const lbtcOutput = btcAmount * exchangeRate;

const mintingFee = await getLBTCMintingFee({ chainId });
const finalAmount = lbtcOutput - mintingFee.toNumber()

Important: Deposits below minAmount will not be processed. Each individual deposit must exceed this threshold.

2. Select Output

Either:

• 2.a. Users stake their BTC and get LBTC: Users must sign a Network Fee authorization

• 2.b. Users stake their BTC directly into a DeFi Vault: Users must sign an ERC-20 Permit

2.a. Stake BTC, get LBTC

Users must authorize Lombard Protocol to deduct a small LBTC fee to contribute towards minting costs. Depending on the destination chain, this may be zero, but must still be signed.

import { 
  getLBTCMintingFee, 
  signNetworkFee, 
  storeNetworkFeeSignature 
} from '@lombard.finance/sdk';

// 1. Get current minting fee
const fee = await getLBTCMintingFee({ chainId });
const feeSatoshis = toSatoshi(fee.toString()).toString();

// 2. Sign fee authorization (valid for 24 hours)
const expiryUnix = Math.floor(Date.now() / 1000) + 86400;

// This function calls for a user signature either with EIP-712 if a fee exists, or as a simple text message if fee is zero
const { signature, signatureData } = await signNetworkFee({
  address: '0x...', 
  provider: window.ethereum,
  chainId,
  fee: feeSatoshis,
  expiry: expiryUnix,
  env: 'prod'
}); 

// Also store signature and typedData locally to use
// when generating btc deposit address in step 2

// 3. Store signature with Lombard
await storeNetworkFeeSignature({
  signature,
  signatureData,
  address: '0x...',
  env: 'prod'
});

Note: You can verify if a user has a valid fee authorization using getNetworkFeeSignature to prevent re-signing.

2.b. Stake BTC into a DeFi Vault

Enable automatic deployment of minted LBTC into DeFi operations. The authorization must be completed before the BTC deposit.

The authorization allows a vault contract to move LBTC tokens on behalf of the user when they are minted. Each chain has a list of supported vaults that can be retrieved using getStakeAndBakeVaults.

import { 
  signStakeAndBake, 
  getStakeAndBakeVaults,
  getLBTCExchangeRate,
  getStakeAndBakeFee,
  getNetworkFeeSignature,
  toSatoshi 
} from '@lombard.finance/sdk';

// Get available vaults for the chain
const vaults = getStakeAndBakeVaults(chainId);
const selectedVault = vaults[0]; // e.g., select Veda/Lombard DeFi Vault

const stakeAndBakeFee = await getStakeAndBakeFee({
  chainId,
  vaultAddress: selectedVault.address,
});

const fee = fromSatoshi(stakeAndBakeFee) // 0.000001

// Calculate approval amount
const approvalValue = btcAmount * exchangeRate;

const expectedLBTC = approvalValue - fee; // The LBTC amount that the user will receive

const permitExpiryTime = Math.floor(Date.now() / 1000) + 7200; // 2 hours later

// Sign authorization
const { signature, signatureData } = await signStakeAndBake({
  provider: window.ethereum,
  address: '0x...',
  chainId,
  value: toSatoshi(approvalValue.toString()).toString(),
  expiry: permitExpiryTime,
  vaultKey: selectedVault.key
});

await storeStakeAndBakeSignature({ signature, signatureData, env: 'prod' });

Each vault has the following properties:

interface IStakeAndBakeVault {
  key: string;    // Unique identifier for the vault
  name: string;   // Display name (e.g., "Veda / Lombard DeFi Vault")
  address: string // Contract address of the vault
}

3. BTC Deposit Address Generation

Each deposit address is uniquely linked to:

• Destination chain (where LBTC will be minted)

• User's wallet address

• Your partner ID

First, check for an existing address:

import { getDepositBtcAddress } from '@lombard.finance/sdk';

const existingAddress = await getDepositBtcAddress({
  address: '0x...',
  chainId,
  partnerId: 'YOUR_PARTNER_ID',
});

if (existingAddress) {
  // Use existing address
  return existingAddress;
}

If no address exists, generate a new one:

// For Ethereum: Use network fee signature
const btcAddress = await generateDepositBtcAddress({
  address: '0x...',
  chainId,
  signature, // Returned from 2.a. or 2.b. above
  signatureData, // Returned from 2.a. or 2.b. above
  partnerId: 'YOUR_PARTNER_ID',
  referrerCode: 'OPTIONAL_REFERRAL_CODE',
  env: 'prod'
});

4. Checking for deposits

Finally you can use getDepositsByAddress to fetch and display the deposit history for a specified address.Comment

import { getDepositsByAddress } from '@lombard.finance/sdk';
...
const deposits = await getDepositsByAddress({
  address: '0x...', // LBTC address
  env: 'prod', // 'prod' | 'testnet' | 'stage'
}); // Returns IDeposit[]