Lombard SDK V2 (Pre-Release)

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.

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/[email protected] [email protected]

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 { exchangeRate, minAmount } = await getLBTCExchangeRate({
  chainId: 1,
  env: 'prod'
});

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

// For Ethereum
const mintingFee = await getLBTCMintingFee({ chainId: 1 });
const finalAmount = lbtcOutput - mintingFee.toNumber()

// Non Ethereum chains
const finalAmount = lbtcOutput;

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

When a user has entered a valid BTC amount and confirm by pressing a "Stake" button, proceed to the next step.

2. Network Fee Authorization

If mintingFeeis greater than zero (true on Ethereum), users must authorize Lombard to deduct a small LBTC fee to cover minting costs. This step is not required for chains where Lombard Protocol covers the fees.

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

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

// 2. Sign fee authorization (valid for 24 hours)
const expiryUnix = Math.floor(Date.now() / 1000) + 86400;
const { signature, typedData } = await signNetworkFee({
  address: '0x...', 
  provider: window.ethereum,
  chainId: 1,
  fee: feeSatoshis,
  expiry: expiryUnix,
  env: 'prod'
});

// Also store signature and typedData locally to use
// when generating the btc deposit address

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

Note: You can verify if a user has a valid fee authorization using getNetworkFeeSignature.

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: 1,
  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 using signNetworkFee
const { signature, typedData } = await signNetworkFee({...})

const btcAddress = await generateDepositBtcAddress({
  address: '0x...',
  chainId: 1,
  signature, // Returned from signNetworkFee above
  eip712Data: typedData, // Returned from signNetworkFee above
  partnerId: 'YOUR_PARTNER_ID',
  referrerCode: 'OPTIONAL_REFERRAL_CODE',
  env: 'prod'
});

// For other chains: Use simple address confirmation
import { signLbtcDestionationAddr } from '@lombard.finance/sdk';

const addressSignature = await signLbtcDestionationAddr({
  account: '0x...',
  chainId: 8453, // Base
  provider: window.ethereum
});

const btcAddress = await generateDepositBtcAddress({
  address: '0x...',
  chainId: 8453,
  signature: addressSignature,
  partnerId: 'YOUR_PARTNER_ID',
  env: 'prod'
});

You may now prompt the user to deposit to this address.

4. Checking for deposits

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

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