Lombard
  • Unlocking Bitcoin's Potential
    • Introducing Lombard & LBTC
      • Our Value Proposition
      • The State of Bitcoin
      • Lombard's Mission & Vision
  • Lombard's Partners
    • Babylon's Bitcoin Staking
    • Lombard's Security Consortium
  • Bitcoin Staking Partners
  • LBTC: Liquid Bitcoin
    • Introduction to LBTC
    • DeFi Vaults
      • Lombard DeFi Vault
        • LBTC/LBTCv
      • Bitcoin Bera Vault
      • Sentora DeFi Vault
    • Lux & Luminary Program
      • Referral Program
      • Nov. '24 The Golden Bull
      • Dec. '24 Flash Event
    • Staking Yield Distribution
    • Supported Blockchains
    • User Guides
      • Staking BTC & Minting LBTC
      • Unstaking LBTC
      • Lombard DeFi Vault: Depositing & Withdrawing
      • Claiming BABY
      • LBTC Bridging to Sui
  • Technical Documentation
    • Smart Contracts
    • Protocol Fees
    • Protocol Architecture
      • Lombard Ledger (Consortium)
      • CubeSigner: Key Management
      • Bascule Drawbridge
      • LBTC Design
      • Babylon Staking
      • PMM Module
      • Trustless Relayer
    • Oracles
    • Audits & Bug Bounties
    • Sanctions & Risk Monitoring
    • Transaction Tracing
  • Frequently Asked Questions
    • FAQs
      • BABY FAQs
  • Developers
    • Lombard SDK V3
    • SDK FAQ
    • Lombard SDK V2 (deprecated)
  • Quick Links
    • Lombard Website
    • Lombard X (Twitter)
    • Lombard Dune Dashboard
    • Lombard Dune PoR
    • Lombard Discord Server
  • Legals
    • Terms of Service
    • Privacy Policy
    • UK Residents
Powered by GitBook
On this page
  • ⭐️ New Features
  • Demo
  • Installation
  • Integration Guide
  • 1. Exchange Rate & Minimum Deposit
  • 2. Select Output
  • 2.a. Stake BTC, get LBTC
  • 2.b. Stake BTC into a DeFi Vault
  • 3. BTC Deposit Address Generation
  • 4. Checking for deposits
  1. Developers

Lombard SDK V2 (deprecated)

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

PreviousSDK FAQNextTerms of Service

Last updated 3 months ago

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 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 , 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 approval and providing a contract call (e.g. ).

Demo

Demo app URL:

Github:

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[]

Google Form
ERC20 Permit
deploying into DeFi Vault
https://demo-sdk.lombard.finance/
https://github.com/lombard-finance/sdk-demo
Terms of Service