About the Lombard SDK
What is the Lombard SDK?
Lombard SDK is a JavaScript/TypeScript package that lets you integrate Bitcoin functionality into your platform without operating Bitcoin infrastructure. Install it via npm, configure your environment, and you get access to Bitcoin staking, wrapping, yield strategies, and cross-chain routing—all backed by Lombard's production infrastructure.
Who is the Lombard SDK for?
The Lombard SDK is built for teams that ship great products:
→ DeFi protocols launching canonical BTC assets
→ Chains wanting native or whitelabeled Bitcoin
→ Fintechs offering Bitcoin yield to users
→ Exchanges & wallets adding BTC capabilities
→ Institutions integrating onchain Bitcoin strategies
Why should I integrate the Lombard SDK?
You can ship Bitcoin features in weeks instead of months without hiring a team to build and maintain custody, validators, cross-chain routing, and monitoring infrastructure. You get institutional-grade security, Proof-of-Reserve, and 24/7 operations—without the operational overhead.
How do I get started?
Install the SDK from npm, grab some testnet BTC and Sepolia ETH from faucets, connect a wallet provider (OKX for Bitcoin, MetaMask or similar for EVM), and use partnerId: 'test' in your config. That's it, you can start generating deposit addresses and testing flows immediately.
What if I want a more direct integration path?
If the SDK doesn't fit your architecture or you need deeper customization, contact us to discuss direct API access or custom integration patterns.
How long does integration take?
Most teams ship to production in 2-4 weeks. You'll spend a few days testing in the Playground, about a week configuring and validating your flows, then 1-2 weeks on production integration. If you're just adding BTC staking to an existing wallet, it can be faster.
Do I need to run my own Bitcoin infrastructure?
No. Lombard operates custody, validators, cross-chain routing, and monitoring. You handle the UX and business logic. You never touch Bitcoin private keys or signing operations.
About Bitcoin Connect
What is Bitcoin Connect?
Bitcoin Connect is Lombard's developer platform for building Bitcoin products. It is an evolving suite of developer tools including APIs and Oracles that can be freely accessed to integrate Lombard's assets and infrastructure on any chain, protocol or application.
How does the Lombard SDK fit into Bitcoin Connect?
The Lombard SDK is the first tool available within Bitcoin Connect. It's a deployment-ready toolkit for integrating Lombard's Bitcoin infrastructure directly into your application. Additional tools like APIs and other builder capabilities will be added to the platform over time.
Should I use Bitcoin Connect or build my own Bitcoin infrastructure?
Bitcoin Connect lets you ship Bitcoin products in weeks instead of quarters. Building in-house means hiring a team to build and maintain custody, validators, cross-chain routing, and monitoring infrastructure indefinitely. If your core business isn't Bitcoin infrastructure, Connect is the faster and more secure path.
What is a Partner ID and why do I need one?
A Partner ID lets your users skip CAPTCHA when generating deposit addresses, tracks all deposits to your organization for analytics, and makes you eligible for fee sharing and partner rewards. For testing, use 'test' as your Partner ID. For production, request one via the Partner Intake Form—usually issued same day.
Can I use the same Partner ID across multiple products?
You can, but it's better to request separate Partner IDs if you want independent attribution tracking for different products or integrations.
What's the flow for staking BTC to LBTC?
Create a stake action, prepare it with the amount and recipient address, authorize the signature (either a fee authorization for Ethereum or address confirmation for other chains), then generate a BTC deposit address. Give that address to your user, they send BTC to it, and LBTC gets minted to their destination address after confirmations.
How do BTC deposit addresses work?
Each combination of destination chain, recipient address, and Partner ID gets a unique Bitcoin address. These addresses never expire and can receive multiple deposits—you don't need to generate a new one each time. Each deposit is processed independently.
What's the difference between fee authorization and address confirmation?
If you're staking to Ethereum mainnet, users sign an EIP-712 message authorizing the network fee. For all other chains, they sign a simpler message confirming the destination chain ID. Both are required before generating the deposit address.
How long does it take for BTC to become LBTC?
After the user sends BTC to the deposit address, it takes several Bitcoin block confirmations before LBTC is minted on the destination chain. The exact timing depends on Bitcoin network conditions and the destination chain's settlement requirements. The SDK provides progress events so you can show confirmation status in your UI.
What can I build with the Lombard SDK?
The SDK lets you offer established Bitcoin assets to your users: LBTC (Bitcoin with native yield) and BTC.b (bridged Bitcoin) across all supported chains.
From there, you can build revenue-generating products including Bitcoin yield and staking flows, automated vault strategies, whitelabeled Bitcoin assets, and cross-chain settlement and routing. Users can stake BTC to receive LBTC, mint BTC.b, deploy directly into DeFi vaults like Veda or Silo in a single transaction, and handle unstaking or redemptions back to native BTC.
Which chains are supported?
Production chains include Ethereum, Arbitrum, Base, Avalanche, Solana, Sui, and Starknet. For testing, use Sepolia, Holesky, or Bitcoin Signet.
Can I deploy to DeFi protocols automatically?
Yes. The Lombard SDK supports direct deployment to Veda and Silo vaults. Instead of stake → receive LBTC → manually deploy, users can do it all in one step using stakeAndDeploy or depositAndDeploy actions.
Can I white-label Bitcoin assets?
Yes, but this requires coordination with Lombard. Email [email protected] to discuss white-labeled asset issuance backed by Lombard infrastructure.
How do SDK actions work?
Every action follows the same pattern: create it with your target configuration, prepare it with the specific parameters (amount, recipient), authorize any required signatures, then execute. Actions have predictable status states like IDLE, NEEDS_FEE_AUTHORIZATION, READY, CONFIRMING, COMPLETED. You can subscribe to events to track progress.
What's the difference between using the full SDK object and modular factories?
The full SDK object (createLombardSDK) gives you all capabilities in one place—good for exploring. Modular factories (btcStake, evmUnstake, etc.) let you import only what you need for better tree-shaking and smaller bundle sizes in production.
What happens if a user cancels or an operation fails?
If an error occurs, the action stays at the step where it failed—it doesn't reset. This means users can retry the same step without starting over. All SDK errors are LombardError instances with a code, message, and metadata so you can handle them appropriately in your UI.
How do I track operation progress?
Subscribe to events on the action object. You get StatusChange events when the action moves between states, Progress events with confirmation counts, Completed when it's done, and Error if something fails. This lets you update your UI in real-time as operations progress.
Which Bitcoin wallets are supported?
Currently OKX Wallet via the window.okxwallet.bitcoin provider. The wallet must support getAccounts, signMessage, and signPsbt methods.
Which EVM wallets work?
Any wallet that implements the EIP-1193 interface. MetaMask, WalletConnect, Coinbase Wallet, etc. If you're using Wagmi, you can pass in the wallet client directly.
What about Solana, Sui, or Starknet?
The SDK supports standard wallet adapters for each chain. For Solana use window.solana, for Sui use window.suiWallet, for Starknet use window.starknet. You configure all your providers once in the SDK config and it handles the rest.
Data & Tracking
How do I fetch a user's deposit history?
Call sdk.api.deposits(address) with their destination address. You get back an array of all deposits with amounts, transaction hashes, chains, notarization status, and claim status.
Can I check if a deposit address already exists?
Yes. Call sdk.api.depositAddress(recipient, chainId) and it returns the existing address or throws if none exists. This is useful for showing returning users their existing deposit address without generating a new one.
How do referrals work?
Pass a referralCode when calling prepare() on stake or deposit actions. The code gets attached to the deposit address at generation time and can't be changed afterward. You can check if an address has a referrer with sdk.referrals.lookupReferrer().
How do I get exchange rates for LBTC?
Call sdk.api.exchangeRatio() to get current ratios for all supported tokens. For LBTC you'll get tokenBTCRatio (how many LBTC per 1 BTC) and BTCTokenRatio (how many BTC per 1 LBTC).
What is the SDK Playground?
A live testing environment where you can configure flows, validate execution paths, simulate operations, and generate example SDK code without deploying anything to mainnet. It's the fastest way to understand how the SDK works before writing integration code.
How do I test on testnet?
Set env: Env.testnet in your config and use partnerId: 'test'. Get testnet BTC from a Signet faucet and Sepolia ETH from a Sepolia faucet. Everything works the same as production but with test tokens.
Operations & Security
Who handles custody and security?
Lombard operates all custody infrastructure, validator coordination, and Proof-of-Reserve verification. The infrastructure uses audited smart contracts, hardware-enforced signing via Cubist Bascule, Chainlink Proof-of-Reserve, and validation from a 15-institution Security Consortium.
What happens during an outage or incident?
Lombard monitors infrastructure 24/7 and handles incident response for custody, settlement, and routing issues. You'll receive status updates via your designated communication channel. Your responsibility is communicating with your users and potentially pausing flows if Lombard recommends it.
Has this been used in production?
Yes. Major platforms including Binance, Bybit, Ledger, Figment, Xverse and Cool Wallet offer Bitcoin products to their users powered by the Lombard SDK.
Does Lombard handle KYC/AML compliance?
No. You remain responsible for your compliance obligations. Communicate your KYC/AML requirements, geographic restrictions, and sanctioned address screening policies during partner onboarding so flows can be configured appropriately.
Can I restrict access by country or user type?
Yes. Enforce geographic and eligibility restrictions in your product layer. Additional restrictions may apply depending on the asset type and custody model you're using.
How do I get help?
Reach out to the Lombard team via Builder Support, or via Discord.
