Lombard SDK V3
Last updated
Last updated
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.
The Lombard's SDK package provides a set of functions that allow interacting with the Lombard protocol and its features.
The SDK depends on the following packages:
axios
viem@2.23
bignumber.js@9
bitcoinjs-lib@6.1.5
@bitcoin-js/tiny-secp256k1-asmjs@2.2.3
You may install them by running the following command:
To install the SDK package, please run:
All functions are documented with JSDoc comments. You can use your IDE's autocomplete feature to see the available methods and their parameters.
You can read more about LBTC here: https://docs.lombard.finance/lbtc-liquid-bitcoin/introduction-to-lbtc
If you'd wish to stake your BTC and get LBTC follow the below steps:
1.1 Get the current minting fee.
1.2. Sign the network fee signature.
1.3. Store the signature to the Lombard's systems.
It is recommended to verify that the signature has been stored. Please use getNetworkFeeSignature
.
isDelayed
is a flag determining whether the execution of auto-claimer using the stored signature is delayed due to the higher gas costs.
1.4. Get or generate the BTC deposit address.
1.5. Deposit BTC to the address.
Now you can deposit your BTC to the generated in the previous step BTC address.
The funds will be claimed automatically by Lombard's claimer and transferred to
the account (address
).
1.6. Check the status of your deposit.
If you'd like to check the status of your deposit use getDepositsByAddress
function.
Every entry in the result of the above function may consist of the following properties:
txid
- the BTC transaction id,
index
- the index of the actual deposit transaction,
blockHeight
blockTime
value
- the amount of BTC deposited,
address
- the destination address,
chainId
- the destination chain id,
isClaimer
- a flag determining whether the deposit has been already claimed,
claimedTxId
- the corresponding claim transaction that transfer funds to the destination address,
rawPayload
- the payload of the transaction (can be use to claim the funds manually),
signature
- the signature used (can be used to claim the funds manually),
isRestricted
- a flag determining whether the transaction has been marked as suspicious/restricted,
payload
- the payload (corresponding to the Bascule drawbridge security),
sessionId
notarizationStatus
- the notarization status of the deposit (pending, submitted, approved or failed),
sessionState
- the state of the session (pending, completed, expired)
In case when a user deposited BTC to the BTC deposit address but the transaction has not been claimed automatically (due to expired signature or any other issue), you may want to claim LBTC manually as in the example below:
The successful execution of the above will result with the transaction id.
You can read more about the DeFi vaults here: https://docs.lombard.finance/lbtc-liquid-bitcoin/defi-vaults/lombard-defi-vault
If you'd wish to stake and bake your BTC follow the steps below.
3.1. See what's the current stake and bake fee.
To check the current stake and bake fee you may use the following function:
The fee amount will be deducted from the claimed LBTC automatically.
3.2. Sign the stake and bake signature.
3.3. Store the signature to the Lombard's systems.
It is recommended to verify if the signature has been stored.
3.4. Get or generate the BTC deposit address.
3.5. Deposit BTC to the address.
Now you can deposit your BTC to the BTC deposit address from above. The funds will be automatically claimed and deposited to the DeFi vault.
3.6. Check the status of you deposit
3.7. Check the amount of shares acquired.
The above code results with:
balance
- The amount of LBTCv shares owned by the account,
exchangeRate
- The current LBTCv to LBTC exchange rate,
balanceLbtc
- The value of the owned shares is LBTC.
Every LBTC is redeemable back to BTC, you can do that programmatically by following the steps:
4.1. Unstake LBTC.
4.2. Check the status of your unstakes.
If you'd like to get the list of all unstaked made by an address, use this:
Every entry in the result of the above may consist of:
txHash
- The unstake transaction hash,
chainId
,
blockHeight
,
unstakeDate
,
fromAddress
- The EVM source address,
toAddress
- The BTC destination address of the funds,
amount
- The amount unstaked,
payoutTxHash
- The BTC transaction hash,
payoutTxIndex
- The index of the actual payout transfer,
sanctioned
- A flag indicating whether the unstake transaction has been sanctioned and flagged as suspicious.
If a user already has LBTC depositing to the DeFi vault can be done via the deposit
function.
5.1. Making a deposit to the DeFi vault.
5.2. Checking the deposit history.
The above function returns an array of deposit data made by the specified user. Each entry contains:
txHash
- the transaction hash,
blockNumber
- the transaction's block number,
chainId
- the chain id,
amount
- the deposited amount,
shareAmount
- the amount of shares received,
token
- the deposit token.
5.3. Checking the user's DeFi vault balance.
In order to check the user's balance of the vault tokens, use this:
The above function returns the:
balance
- balance of LBTCv,
exchangeRate
- the current exchange rate between LBTCv and LBTC,
balanceLbtc
- the value of LBTCv represented in LBTC.
6.1. Requesting a withdrawal from the DeFi vault
Requesting a withdrawal from the DeFi vault can be done via:
6.2. Checking the withdrawal history (tracking the withdrawal request)
In order to check the whole history or to track the particular withdrawal please use the following function:
The result of the above is an object with broken down withdrawals by their state:
Each of the arrays from above consist of:
token
- the withdrawal token (LBTC),
shareAmount
- the amount of shares withdrawn,
amount
- the amount of funds withdrawn,
minPrice
- the min price of a share,
deadline
- the expiration timestamp,
timestamp
- the request timestamp,
txHash
- the withdraw request transaction hash,
blockNumber
- the request block number,
fulfilledTimestamp
- the fulfilment timestamp,
fulfilledTxHash
- the funds transfer transaction hash,
fulfilledBlockNumber
- the fulfilment block number.
6.3. Cancelling the withdrawal
If you wish to cancel you open withdrawal request use this:
If you'd like to check the amount of LUX points earned by an address then simply run the following function:
The function returns the object of shape:
9.1. Checking reward balances.
The data returned by the above function contains:
address
- the address of the reward earner (claimer),
availableBalance
- the available balance of the reward token (ready to be withdrawn),
lockedBalance
- the locked balance (in processing),
pendingBalance
- the pending balance to be credited,
rewardToken
- the reward token,
timestamp
- the timestamp.
9.2. Claiming rewards.
The function will ask a user to sign a message that consists of the amount, destination address and also a withdrawal fee and after obtaining this signature it will request a reward withdrawal from the pool to the provided destination address.
The function returns the RewardWithdrawal
object.
9.3. Checking the reward withdrawal fee.
9.4. Getting the withdrawal history (checking withdrawal status).
The function returns an array of:
amount
- the withdrawn (claimed) amount of rewards token,
rewardToken
- the reward token,
fee
- the applied withdrawal fee,
to
- the destination address,
signature
- the signature used,
status
- the withdrawal status,
estimatedTimeSent
- the estimated time when the funds are sent,
timestamp
- the timestamp.