# Liquidium Docs Full Corpus > Generated from the live Liquidium Payload CMS docs. When CMS docs are added, edited, removed, or republished, this file updates automatically. Canonical docs: https://liquidium.fi/docs Docs index: https://liquidium.fi/docs/llms.txt Sitemap: https://liquidium.fi/sitemap.xml ## Pages - [Welcome to Liquidium](https://liquidium.fi/docs) ([Markdown](https://liquidium.fi/docs/index.md)): Learn how to supply assets, borrow across chains, and use Liquidium's Simple and Advanced loan experiences. - [Quick start](https://liquidium.fi/docs/quick-start) ([Markdown](https://liquidium.fi/docs/quick-start/index.md)): Choose Simple for a one-step loan or use Advanced to manage balances, supply, borrow, repay, and withdraw with Liquidium. - [Simple Loan](https://liquidium.fi/docs/quick-start/simple-loan) ([Markdown](https://liquidium.fi/docs/quick-start/simple-loan/index.md)): Borrow against your assets in one step, no account required. Borrow USDT or USDC against your BTC. - [Your profile](https://liquidium.fi/docs/quick-start/profile) ([Markdown](https://liquidium.fi/docs/quick-start/profile/index.md)): Sign in to Liquidium with Internet Identity or a wallet. Save Simple Loans, link accounts, manage notifications, and access positions across devices. - [Supply](https://liquidium.fi/docs/quick-start/supply) ([Markdown](https://liquidium.fi/docs/quick-start/supply/index.md)): Learn how to supply supported assets, review APY, track confirmations, and use eligible positions as collateral in Liquidium Advanced. - [Borrow](https://liquidium.fi/docs/quick-start/borrow) ([Markdown](https://liquidium.fi/docs/quick-start/borrow/index.md)): Learn how to borrow against supplied collateral, review APY and fees, track delivery, and manage portfolio health in Liquidium Advanced. - [Repay](https://liquidium.fi/docs/quick-start/repay) ([Markdown](https://liquidium.fi/docs/quick-start/repay/index.md)): Learn how to repay an Advanced debt position, choose a wallet or repay address, track confirmation, and understand the effect on portfolio health. - [Withdraw](https://liquidium.fi/docs/quick-start/withdraw) ([Markdown](https://liquidium.fi/docs/quick-start/withdraw/index.md)): Learn how to withdraw eligible supplied assets, choose a wallet or custom address, track processing, and understand liquidity and portfolio-health limits. - [Core concepts](https://liquidium.fi/docs/quick-start/core-concepts) ([Markdown](https://liquidium.fi/docs/quick-start/core-concepts/index.md)): Understanding the key terms and concepts. - [Resources](https://liquidium.fi/docs/resources) ([Markdown](https://liquidium.fi/docs/resources/index.md)): Reference pages for support questions, app data, dashboards, and extra Liquidium resources. - [FAQ](https://liquidium.fi/docs/resources/faq) ([Markdown](https://liquidium.fi/docs/resources/faq/index.md)): Answers about Liquidium Simple Loans, Advanced positions, sign-in, wallets, repayments, collateral, portfolio health, ICP assets, and app behavior. - [Insights](https://liquidium.fi/docs/resources/insights) ([Markdown](https://liquidium.fi/docs/resources/insights/index.md)): Compare live Liquidium insights, markets, rates, caps, and pool risk parameters. - [History](https://liquidium.fi/docs/resources/history) ([Markdown](https://liquidium.fi/docs/resources/history/index.md)): Review Liquidium activity, transaction IDs, exports, and interest history. - [Liquidations Dashboard](https://liquidium.fi/docs/resources/liquidations) ([Markdown](https://liquidium.fi/docs/resources/liquidations/index.md)): Monitor liquidatable positions, recent liquidation events, filters, and data freshness. - [Vaults](https://liquidium.fi/docs/resources/vaults) ([Markdown](https://liquidium.fi/docs/resources/vaults/index.md)): Explore integrated Aave and Morpho vaults, guided strategies, estimated returns, and risk notes. - [Miscellaneous](https://liquidium.fi/docs/resources/miscellaneous) ([Markdown](https://liquidium.fi/docs/resources/miscellaneous/index.md)): Find miscellaneous Liquidium resources, updates, and supporting information across Liquidium’s Bitcoin-native and cross-chain lending products. - [ICP assets and Oisy](https://liquidium.fi/docs/resources/icp-assets-and-oisy) ([Markdown](https://liquidium.fi/docs/resources/icp-assets-and-oisy/index.md)): How to use ckAssets over ICP and connect Oisy to Liquidium. - [Technical Documentation](https://liquidium.fi/docs/technical) ([Markdown](https://liquidium.fi/docs/technical/index.md)): Technical documentation for the Cross-chain loans - [Technical Concepts](https://liquidium.fi/docs/technical/concepts) ([Markdown](https://liquidium.fi/docs/technical/concepts/index.md)): Fundamental mechanics that power the Liquidium protocol - [Interest Rate Model](https://liquidium.fi/docs/technical/concepts/interest-rates) ([Markdown](https://liquidium.fi/docs/technical/concepts/interest-rates/index.md)): How borrow and supply rates are calculated using the two-slope kink model - [Share-Based Accounting](https://liquidium.fi/docs/technical/concepts/share-accounting) ([Markdown](https://liquidium.fi/docs/technical/concepts/share-accounting/index.md)): How positions track balances efficiently using shares and indices - [Health Factor](https://liquidium.fi/docs/technical/concepts/health-factor) ([Markdown](https://liquidium.fi/docs/technical/concepts/health-factor/index.md)): How position safety is measured and liquidation thresholds work - [Liquidations](https://liquidium.fi/docs/technical/concepts/liquidations) ([Markdown](https://liquidium.fi/docs/technical/concepts/liquidations/index.md)): How liquidations protect the protocol and its users - [Architecture](https://liquidium.fi/docs/technical/architecture) ([Markdown](https://liquidium.fi/docs/technical/architecture/index.md)): Deep dive into the canister architecture and system design - [Lending Canister](https://liquidium.fi/docs/technical/architecture/lending-canister) ([Markdown](https://liquidium.fi/docs/technical/architecture/lending-canister/index.md)): Technical overview of the Liquidium Lending Canister, including authentication, position accounting, pool coordination, events, prices, and liquidations. - [BTC Pool Canister](https://liquidium.fi/docs/technical/architecture/btc-pool) ([Markdown](https://liquidium.fi/docs/technical/architecture/btc-pool/index.md)): Bitcoin liquidity custody with boosted withdrawals and UTXO management - [ERC Pool Canister](https://liquidium.fi/docs/technical/architecture/erc-pool) ([Markdown](https://liquidium.fi/docs/technical/architecture/erc-pool/index.md)): Ethereum asset custody with gas fee fronting and DEX integration - [ICP Pool Canister](https://liquidium.fi/docs/technical/architecture/icp-pool) ([Markdown](https://liquidium.fi/docs/technical/architecture/icp-pool/index.md)): Native ICP liquidity custody, deposits, withdrawals, and lending integration. - [Cross-Chain Flow](https://liquidium.fi/docs/technical/architecture/cross-chain) ([Markdown](https://liquidium.fi/docs/technical/architecture/cross-chain/index.md)): How native assets move through the protocol via Chain Key technology - [Operations](https://liquidium.fi/docs/technical/operations) ([Markdown](https://liquidium.fi/docs/technical/operations/index.md)): How user operations flow through the protocol - [Deposits](https://liquidium.fi/docs/technical/operations/deposits) ([Markdown](https://liquidium.fi/docs/technical/operations/deposits/index.md)): How deposits flow through the protocol - inflow detection, subaccounts, and share minting - [Withdrawals](https://liquidium.fi/docs/technical/operations/withdrawals) ([Markdown](https://liquidium.fi/docs/technical/operations/withdrawals/index.md)): How withdrawals flow through the protocol - standard vs boosted paths, fee handling - [Borrowing](https://liquidium.fi/docs/technical/operations/borrowing) ([Markdown](https://liquidium.fi/docs/technical/operations/borrowing/index.md)): How borrowing flows through the protocol - health checks, debt shares, and async execution - [Repayments](https://liquidium.fi/docs/technical/operations/repayments) ([Markdown](https://liquidium.fi/docs/technical/operations/repayments/index.md)): How repayments flow through the protocol - debt detection, share burning, and overpayment handling - [Security](https://liquidium.fi/docs/technical/security) ([Markdown](https://liquidium.fi/docs/technical/security/index.md)): Protocol security guarantees - atomicity, authentication, and reliability - [Atomicity & Write-Ahead Logging](https://liquidium.fi/docs/technical/security/atomicity) ([Markdown](https://liquidium.fi/docs/technical/security/atomicity/index.md)): Two-phase execution model and reliable async operations - [Authentication](https://liquidium.fi/docs/technical/security/authentication) ([Markdown](https://liquidium.fi/docs/technical/security/authentication/index.md)): Multi-chain signature verification and replay protection - [SDK](https://liquidium.fi/docs/sdk) ([Markdown](https://liquidium.fi/docs/sdk/index.md)): Learn what the Liquidium SDK does, which integration paths it supports, and where to find setup steps, API reference, types, and examples. --- --- title: "Welcome to Liquidium" description: "Learn how to supply assets, borrow across chains, and use Liquidium's Simple and Advanced loan experiences." canonical: "https://liquidium.fi/docs" markdown: "https://liquidium.fi/docs/index.md" breadcrumbs: "Docs > Welcome to Liquidium" updated: "2026-08-19T08:01:52.572Z" --- # Welcome to Liquidium Learn how to supply assets, borrow across chains, and use Liquidium's Simple and Advanced loan experiences. Canonical URL: https://liquidium.fi/docs Markdown URL: https://liquidium.fi/docs/index.md ![Quid love](https://liquidium.fi/api/quid-assets/file/quid%20love.svg) Liquidium is a non-custodial lending protocol for supplying assets, earning interest, and borrowing against collateral across supported blockchain networks. **How Liquidium works:** - **Suppliers** provide liquidity and earn variable interest on supported assets. - **Borrowers** use overcollateralized loans to access liquidity without selling their collateral. - All interactions are fully **non-custodial**: supplied assets and loan positions are managed by on-chain smart contracts without a centralized custodian. - Assets originate on their **native chains**, allowing supported collateral and borrowed assets to come from different networks. Liquidium uses Internet Computer canisters to coordinate supported cross-chain transactions. Assets and transaction history remain verifiable onchain. ## Choose your experience - **Simple Loan** — Create and manage a loan without signing in. You can optionally sign in with Internet Identity or a supported wallet to sync loans across devices, reuse saved addresses, and manage notifications. - **Advanced** — Sign in with Internet Identity or a supported wallet to manage balances, supply assets, borrow, repay, and withdraw through the Advanced portfolio. [Open Liquidium](https://app.liquidium.fi/) and use the **Simple/Advanced** selector to choose your flow. For walkthroughs, continue to [Quick start](https://liquidium.fi/docs/quick-start). ## Browse - [Quick start](https://liquidium.fi/docs/quick-start) - [Technical docs](https://liquidium.fi/docs/technical) - [Resources](https://liquidium.fi/docs/resources) - [SDK](https://liquidium.fi/docs/sdk) --- --- title: "Quick start" description: "Choose Simple for a one-step loan or use Advanced to manage balances, supply, borrow, repay, and withdraw with Liquidium." canonical: "https://liquidium.fi/docs/quick-start" markdown: "https://liquidium.fi/docs/quick-start/index.md" breadcrumbs: "Docs > Quick start" updated: "2026-08-19T08:09:10.934Z" --- # Quick start Choose Simple for a one-step loan or use Advanced to manage balances, supply, borrow, repay, and withdraw with Liquidium. Canonical URL: https://liquidium.fi/docs/quick-start Markdown URL: https://liquidium.fi/docs/quick-start/index.md ![Quid swap](https://liquidium.fi/api/quid-assets/file/quid%20swap.svg) Open Liquidium at [https://app.liquidium.fi/](https://app.liquidium.fi/) and use the **Simple/Advanced** selector to choose your flow. Simple lets you create and manage a loan without signing in, while Advanced gives you more control over balances, lending, borrowing, repayments, and withdrawals. You can sign in with on Advanced Internet Identity or a supported wallet and connect to Simple, if needed. - [Simple Loan](https://liquidium.fi/docs/quick-start/simple-loan) - [Your profile](https://liquidium.fi/docs/quick-start/profile) - [Supply](https://liquidium.fi/docs/quick-start/supply) - [Borrow](https://liquidium.fi/docs/quick-start/borrow) - [Repay](https://liquidium.fi/docs/quick-start/repay) - [Withdraw](https://liquidium.fi/docs/quick-start/withdraw) - [Core concepts](https://liquidium.fi/docs/quick-start/core-concepts) --- --- title: "Simple Loan" description: "Borrow against your assets in one step, no account required. Borrow USDT or USDC against your BTC." canonical: "https://liquidium.fi/docs/quick-start/simple-loan" markdown: "https://liquidium.fi/docs/quick-start/simple-loan/index.md" breadcrumbs: "Docs > Quick start > Simple Loan" updated: "2026-08-21T10:52:47.896Z" --- # Simple Loan Borrow against your assets in one step, no account required. Borrow USDT or USDC against your BTC. Canonical URL: https://liquidium.fi/docs/quick-start/simple-loan Markdown URL: https://liquidium.fi/docs/quick-start/simple-loan/index.md A Simple Loan is the fastest way to borrow on Liquidium. Choose what to borrow, review the required collateral, enter where the funds should go, and fund the loan on-chain. No account or wallet connection is required. You can optionally sign in with Internet Identity or a supported wallet to save your Simple Loans to your profile, reuse saved addresses across Simple and Advanced, and manage loan notifications. [Open the Liquidium app](https://app.liquidium.fi/) and select **Simple**. ## Create a Simple Loan ![Simple Loan form for borrowing native USDC against native BTC](https://liquidium.fi/api/media/file/simple-loan-native-borrow-form-darkmode-docs.avif) 1. Under **Borrow**, enter the amount you want to receive and select the borrow asset. 2. Under **Collateral**, select the asset you want to deposit and review the required amount, APY impact, and LTV. 3. Review the network fees, then click **Borrow**. Simple Loans work with air-gapped wallets, hardware wallets, exchange accounts, and other setups that can send the collateral asset and receive the borrowed asset. Use refund and destination addresses you control or can reliably access. ### Sign in or continue without an account Signing in is optional. If you choose to sign in, use Internet Identity or a supported wallet. If you want to remain accountless, close the sign-in prompt and continue creating the Simple Loan. ![Sign in to Liquidium with a wallet or Internet Identity](https://liquidium.fi/api/media/file/simple-loan-sign-in-modal-darkmode.avif) While signed out, the app keeps recent Simple Loans in the current browser. If you sign in later, loans stored in that browser can be synced to your profile. Keep your Loan ID and receipt as reliable backups. ## Set your addresses Enter the addresses Liquidium should use for returned collateral and borrowed funds. Signed-in users can save addresses and reuse them across Simple and Advanced. ![Simple Loan refund and destination fields with saved address controls](https://liquidium.fi/api/media/file/simple-loan-address-book-darkmode-docs.avif) - **Refund address** — on the collateral chain. Your collateral is returned here after the loan is fully repaid or if the deposit fails to open a loan. - **Destination address** — on the borrow chain. Your borrowed funds are sent here after the collateral deposit is received and the loan opens. - **Save** — add an entered address to your profile address book. - **Addresses** — choose a compatible saved address. > Double-check both addresses before generating the loan. They cannot be changed afterward, and funds sent to a wrong address may not be recoverable. For ICP destinations, use the address format shown in the app. Depending on the selected asset and action, the app may request a principal, ICRC-1 account, or AccountIdentifier. > **Native ETH address requirement:** If native ETH is the collateral or borrowed asset, the corresponding refund or destination must be a standard Ethereum wallet address. Smart contract wallet addresses are not supported. Open **Advanced settings** to adjust the loan-delivery window or increase the Max LTV buffer. Confirm that you are responsible for the validity of the addresses, then click **Generate loan**. ## Generate and fund the loan After clicking **Generate loan**, Liquidium creates the loan and shows its funding details. - **Loan ID** — the unique six-character code for the loan. Copy it and save the receipt. - **Supply address** — send the collateral asset here to open the loan or add collateral later. - **Repay address** — send the borrowed asset here to make a partial or full repayment. To open the loan, click **Continue** and send the collateral asset to the displayed supply address. After the deposit confirms and the loan opens, the borrowed asset is sent automatically to the destination address you entered. > Simple Loans always use an LTV buffer of at least 2 percentage points below the maximum LTV. You can increase the Max LTV buffer under Advanced settings, but you cannot set it below 2%. If the position cannot open safely after the deposit is registered, the loan does not open and the collateral is refunded after the failed opening process. Check the current timing and settings shown in the app before funding. The app adds the Loan ID to the page URL. Save the receipt, bookmark or copy the URL, or use the Simple Portfolio to reopen the loan later. ## Manage your loan Select **Simple**, then open **Portfolio** to see the Simple Loans stored in the current browser or synced to your signed-in profile. When active positions exist, the Portfolio can show total collateral, total borrowed value, and blended LTV across those loans. Loans are grouped by status, including **Active**, **Awaiting deposit**, and **Closed**. ![Simple Loan Portfolio showing a closed and repaid loan](https://liquidium.fi/api/media/file/simple-loan-portfolio-darkmode.avif) ### Find your loan Use the Portfolio search or open **Find a loan**. Simple Loans can be found using: - **Loan ID** — enter the six-character ID created with the loan. - **Address or transaction** — search using a refund, destination, supply, or repay address, or a related deposit, borrow, or repayment transaction ID. - **Saved address** — signed-in users can choose a compatible address from their address book. ![Find a Simple Loan by its six-character Loan ID](https://liquidium.fi/api/media/file/simple-loan-find-loan-darkmode.avif) Advanced positions do not use Simple Loan IDs. Select **Advanced** and use the Advanced Portfolio to manage those positions. ### Add collateral Open an active loan and choose **Deposit more**, or send more of the collateral asset to its supply address. Adding collateral lowers the loan's LTV after the deposit confirms. ### Repay your loan Open an active loan and choose **Repay loan**, or send the borrowed asset to its repay address. - The repayment view shows the current amount required to repay the loan fully. - Partial repayments lower the debt and LTV but do not release collateral. - Collateral is returned to the refund address only after the full debt is repaid. > Interest accrues continuously, so the amount required for full repayment grows over time. Check the latest amount immediately before sending a repayment. ### Loan notifications You can enable email notifications without signing in by entering an email address for each Simple Loan. If you are signed in and have added an email address to your profile, that email is used automatically for Simple Loan notifications. You can review or change the notification email from the individual loan. ### Closed and repaid loans After full repayment, the loan moves to **Closed**. The loan details show the returned collateral and transaction history. ![Repaid Simple Loan details with returned collateral and transaction history](https://liquidium.fi/api/media/file/simple-loan-details-darkmode-docs.avif) Removing a loan from recent history does not delete or close the loan. You can still find it using its Loan ID or a related address. ### Liquidations Simple Loans are over-collateralized and can be liquidated if they become too risky. - Each collateral asset has a liquidation threshold. If the LTV reaches it, collateral may be sold to repay the debt. - Up to 50% of the collateral is sold first to restore a safer LTV. In extreme cases, the full collateral can be sold. - Lower the LTV by repaying debt or adding more collateral. ### Loan states While creating or managing a loan, you may see: - **Awaiting deposit** — no collateral has been received yet. - **Deposit detected** — the deposit has been seen and the loan is waiting for the required confirmations. - **Deposit too small** — the received collateral does not support the minimum borrow amount. Send more collateral if instructed. - **Active** — the loan is open and accruing interest. - **Repaid** — the debt is cleared and the collateral has been returned. --- --- title: "Your profile" description: "Sign in to Liquidium with Internet Identity or a wallet. Save Simple Loans, link accounts, manage notifications, and access positions across devices." canonical: "https://liquidium.fi/docs/quick-start/profile" markdown: "https://liquidium.fi/docs/quick-start/profile/index.md" breadcrumbs: "Docs > Quick start > Your profile" updated: "2026-08-27T10:48:18.046Z" --- # Your profile Sign in to Liquidium with Internet Identity or a wallet. Save Simple Loans, link accounts, manage notifications, and access positions across devices. Canonical URL: https://liquidium.fi/docs/quick-start/profile Markdown URL: https://liquidium.fi/docs/quick-start/profile/index.md ![Quid learn](https://liquidium.fi/api/quid-assets/file/quid%20learn.svg) Your Liquidium profile connects your activity across Simple and Advanced, so you can pick up where you left off from one place. Open the Liquidium app to sign in with Internet Identity or a supported wallet. Advanced is available at [app.liquidium.fi/advanced](https://app.liquidium.fi/advanced). For the account-free flow, see [Simple Loans](https://liquidium.fi/docs/quick-start/simple-loan). ![Simple Loan prompt explaining that signed-out loans are saved on this device only](https://liquidium.fi/api/media/file/profile-saved-on-device-darkmode.avif) ## Simple Loans with and without signing in You can create and manage a Simple Loan without signing in. While signed out, recent Simple Loans are saved in the current browser. Signing in keeps those loans on your profile so you can open them from another device. It also lets you reuse saved addresses and automatically applies your configured profile email to Simple Loan notifications. Signed-out users can still enable notifications by entering an email address separately for each loan. ## Sign in to your profile ![Sign in to Liquidium with a wallet or Internet Identity](https://liquidium.fi/api/media/file/simple-loan-sign-in-modal-darkmode.avif) Select **Sign in** in the app, then choose one of the available methods: - **Internet Identity** — access your profile without installing a wallet. - **Connect a wallet** — choose a supported wallet and approve the requested sign-in message. Signing a login or authorization message does not send a transaction or charge a network fee. ### Supported wallets and chains ![Liquidium wallet picker with All chains, Ethereum, Bitcoin, and ICP filters and Oisy as a separate option from WalletConnect](https://liquidium.fi/api/media/file/profile-wallet-picker-icp-darkmode-docs.avif) The wallet picker can be filtered by All chains, Ethereum, Bitcoin, or ICP. Use the picker to see the currently available sign-in options. Oisy appears as its own option in Liquidium; it is not connected through WalletConnect. When you select Ledger under Bitcoin, Liquidium creates or links a Bitcoin-side account, and you approve or sign its interactions in the Ledger Live app. Select Oisy in Liquidium's wallet picker. If Oisy does not yet have an Ethereum account, create or enable one during sign-in, then approve the request in Oisy. After signing in, open Settings, connect the Oisy ICP account, and approve the second request in Oisy. The ICP account is not linked automatically. Once linked, it can handle supported supply, borrow, repay, and withdrawal transactions for ICP, ckBTC, ckETH, ckUSDC, and ckUSDT. Advanced shows supported ICP assets and ckAssets by default after you link the ICP account. Turn off ICP assets to switch back to native-chain routes. Wallet availability can change by chain, browser, and installed extensions. Use the wallet picker in the app as the source of truth when signing in or linking another account. ## Advanced balances, deposits, and withdrawals Profile balances and funding methods are part of the Advanced experience. Use the persistent selector to open Advanced, then manage supported balances, supply positions, loans, and withdrawals from the relevant portfolio and account views. Depending on the asset, the app can use a connected wallet or an asset-specific address. Simple Loans use their own supply, repayment, refund, and destination addresses instead of the Advanced profile balance flow. See [Supply](https://liquidium.fi/docs/quick-start/supply) and [Withdraw](https://liquidium.fi/docs/quick-start/withdraw) for step-by-step instructions. ## What your profile contains ![Signed-in Liquidium profile showing Bitcoin and Ethereum accounts, points, and settings](https://liquidium.fi/api/media/file/profile-account-panel-darkmode-woICP-docs.avif) The account panel can show: - Your profile name and image - Linked Bitcoin, Ethereum, and other supported authorization methods - Available wallet balances - An option to link another account - Your points and leaderboard entry - Access to profile and general settings ## Link another account Open the account panel and select **Link new account**. Choose the chain and wallet you want to add, then follow the approval prompts to prove that you control the new authorization method. The app may ask you to approve the link with an authorization method already connected to the profile. ## Unlink an account ![Manage linked Bitcoin and Ethereum addresses in a Liquidium profile](https://liquidium.fi/api/media/file/profile-linked-addresses-darkmode.avif) Open **Settings**, go to **General**, and select **Manage linked addresses**. Choose the Bitcoin, Ethereum, or other supported address you want to remove and follow the authorization prompt. You must keep at least one authorization method linked so you can continue accessing the profile. If an address controls an active Advanced position, the app may require another address on that chain before it can be removed. ## Profile notifications ![Liquidium profile notification settings with email, Telegram, and alert categories](https://liquidium.fi/api/media/file/profile-notifications-settings-darkmode-docs.avif) Add and verify an email address in your Profile settings to receive supported activity and loan-health alerts. When a profile email is configured, Liquidium uses it automatically for Simple Loan notifications. You can review or change the email from an individual loan. Signed-out Simple Loan users configure an email separately for each loan. Where available, you can also connect Telegram and choose which notification categories to receive: - **Critical alerts** — warnings when portfolio health is at risk - **General** — notifications for completed deposits and other supported activity - **Marketing** — product news and feature updates Notifications are helpful alerts, but you should still monitor portfolio and loan health directly in the app. ## Customize your profile ![Liquidium profile settings for editing a username and profile image](https://liquidium.fi/api/media/file/profile-customization-darkmode.avif) From Profile settings, you can update your username and profile image. Profile information used by the leaderboard may be visible publicly. ## General settings General settings include app preferences such as theme, display currency, language, and portfolio-health format. ## Earn points Users can earn points by interacting with Liquidium. Current activities may include: - Supplying - Borrowing - Repaying - Maintaining a lending streak - Completing challenges - Referring users Point campaigns and tasks can change. Check the [Points page](https://app.liquidium.fi/points) for current tasks and point history, and the [Leaderboard](https://app.liquidium.fi/leaderboard) for rankings. --- --- title: "Supply" description: "Learn how to supply supported assets, review APY, track confirmations, and use eligible positions as collateral in Liquidium Advanced." canonical: "https://liquidium.fi/docs/quick-start/supply" markdown: "https://liquidium.fi/docs/quick-start/supply/index.md" breadcrumbs: "Docs > Quick start > Supply" updated: "2026-08-27T11:22:14.495Z" --- # Supply Learn how to supply supported assets, review APY, track confirmations, and use eligible positions as collateral in Liquidium Advanced. Canonical URL: https://liquidium.fi/docs/quick-start/supply Markdown URL: https://liquidium.fi/docs/quick-start/supply/index.md ![Quid benefit](https://liquidium.fi/api/quid-assets/file/quid%20benefit.svg) ## Supply assets in Advanced [Open Liquidium](https://app.liquidium.fi/) and select **Advanced**, then **Supply**. Sign in with Internet Identity or a supported wallet to manage your Advanced balances and positions. If you only want to create a one-step loan without signing in, use [Simple Loan](https://liquidium.fi/docs/quick-start/simple-loan). Before supplying, keep in mind: - Supply APY is variable and can change with market conditions. - A supply starts earning after the deposit is detected and finalized. - Eligible supplied assets can support borrowing and affect portfolio health. - Supported assets and current rates are shown in the live asset picker. - ICP, ckBTC, ckETH, ckUSDC, and ckUSDT can be supplied directly from a supported connected ICP wallet or through the deposit-address flow shown by the app. ## Submit a supply ![Advanced Supply form showing a USDT amount, current APY, portfolio health, and wallet funding](https://liquidium.fi/api/media/file/advanced-supply-form-darkmode.avif) 1. Open **Advanced** and select **Supply**. 2. Choose a supported asset from the asset picker. 3. Enter an amount or use **Max** and the percentage slider. 4. Review the current APY and amount. 5. Select **Supply**. 6. Approve the requested wallet steps or follow the deposit-address instructions shown by the app. Liquidium supports two funding paths: - **Linked wallet:** Supply directly from a supported connected Ethereum, ICP, or Bitcoin wallet. - **Deposit address:** Send a supported asset to the asset-specific deposit address shown by Liquidium. Anyone can use this path; if you connected Ledger and created or linked a Bitcoin account, send and approve the native BTC transfer to this address through the Ledger Live app. ![ICP supply deposit address showing ICRC-1 and Account ID options, copy control, QR code, and network details](https://liquidium.fi/api/media/file/advanced-icp-deposit-address-darkmode.avif) To use Oisy for ICP assets, sign in to Liquidium with Oisy using its Ethereum account. Then open Settings and connect the ICP account. Once a supported ICP account is connected, Liquidium automatically switches the asset picker to supported ICP assets and ckAssets. Select the asset, confirm that the network shown is ICP, enter the amount, and approve the supply in the wallet. The deposit-address path remains available where offered. ## Track a pending supply During submission, the progress window shows stages such as **Fetching details**, **Approve spending**, and **Send funds**. ![Advanced supply progress showing Fetching details, Approve spending, and Send funds](https://liquidium.fi/api/media/file/advanced-supply-progress-darkmode.avif) After submission, the success screen shows the supplied asset, amount, estimated completion time, and transaction link. Network and protocol finalization times vary by asset and current conditions, so use the estimate shown in the app instead of relying on a fixed confirmation count. ![Successful USDC supply initiation showing the amount, estimated time, transaction link, and notification setup](https://liquidium.fi/api/media/file/advanced-supply-success-darkmode.avif) The supply becomes active after Liquidium detects and finalizes the transaction. Once active, it appears in your Advanced portfolio, begins earning yield, and can be used as collateral when eligible. ![Advanced portfolio showing portfolio health, net APY, net value, interest, and an active USDT supply](https://liquidium.fi/api/media/file/advanced-supply-portfolio-darkmode.avif) For ICP and ckAssets, source-ledger finality and Liquidium's deposit detection and finalization are separate steps. A transfer can be final on the source ledger while the supply is still pending in Liquidium. ## Try it in Demo Mode Use Demo Mode to test supplying, borrowing, and repaying with simulated funds. Demo Mode does not require a real wallet transaction or real assets. Turn Demo Mode off before using real funds. Demo balances and transactions do not carry over to your real profile. ## How supply yield works Supplied assets are added to lending pools and made available to borrowers. Borrowers pay interest, and suppliers earn a variable share through the pool. - APY includes the effect of compounding. - APY changes with utilization and market conditions. - Displayed APY is not a guaranteed future return. - Interest begins accruing after the supply becomes active. ## Use supplied assets as collateral Eligible supplied assets can support Advanced borrowing. Borrowing against a supply changes portfolio health and can expose collateral to liquidation if the position becomes unsafe. Supply positions do not have a fixed term, but withdrawals depend on available liquidity and must not make portfolio health unsafe. See [Withdraw](https://liquidium.fi/docs/quick-start/withdraw) and [Borrow](https://liquidium.fi/docs/quick-start/borrow) for the next steps. --- --- title: "Borrow" description: "Learn how to borrow against supplied collateral, review APY and fees, track delivery, and manage portfolio health in Liquidium Advanced." canonical: "https://liquidium.fi/docs/quick-start/borrow" markdown: "https://liquidium.fi/docs/quick-start/borrow/index.md" breadcrumbs: "Docs > Quick start > Borrow" updated: "2026-08-27T10:43:26.000Z" --- # Borrow Learn how to borrow against supplied collateral, review APY and fees, track delivery, and manage portfolio health in Liquidium Advanced. Canonical URL: https://liquidium.fi/docs/quick-start/borrow Markdown URL: https://liquidium.fi/docs/quick-start/borrow/index.md ![Quid access liquidity](https://liquidium.fi/api/quid-assets/file/quid%20access-liquidity.svg) ## Borrow in Advanced [Open Liquidium](https://app.liquidium.fi/) and select **Advanced**, then **Borrow**. Sign in with Internet Identity or a supported wallet to manage your Advanced balances and positions. Advanced borrowing uses eligible assets already supplied to Liquidium as collateral. If you do not have an active supply position, start with [Supply](https://liquidium.fi/docs/quick-start/supply). If you want a one-step loan without signing in, use [Simple Loan](https://liquidium.fi/docs/quick-start/simple-loan). Before borrowing, keep in mind: - The maximum amount depends on your collateral, portfolio health, pool liquidity, and current market limits. - Borrow APY is variable and can change with utilization and market conditions. - Borrowing adds debt and lowers portfolio health. - The app shows the network fee and estimated amount delivered before confirmation. ## Submit a borrow ![Advanced Borrow form showing USDT amount, portfolio health, projected APY, maximum amount, slider, and liquidity limit](https://liquidium.fi/api/media/file/advanced-borrow-form-darkmode.avif) 1. Open **Advanced** and select **Borrow**. 2. Choose a supported asset from the asset picker. 3. Enter an amount or use **Max** and the percentage slider. 4. Review the current and projected borrow APY, portfolio health, available liquidity, and network fee. 5. Select **Borrow**. 6. Follow the authorization and destination steps shown by the app. With a connected Ledger Bitcoin account, use the borrow destination/address flow shown by Liquidium and complete required approvals or signatures in the Ledger Live app. ![Borrow asset picker showing Bitcoin, Ethereum, USDC, USDT, Internet Computer, borrow APYs, liquidity, and the ICP assets switch](https://liquidium.fi/api/media/file/advanced-borrow-asset-picker-darkmode.avif) Depending on the selected asset and current flow, borrowed funds may be delivered to a supported linked wallet or a compatible destination address. Follow the delivery method shown for that transaction. ![Bitcoin withdrawal address entry for borrowed funds with saved addresses and address confirmation](https://liquidium.fi/api/media/file/advanced-borrow-destination-darkmode.avif) To use Oisy with ICP assets, first connect Oisy to Liquidium through its Ethereum account. Then open Settings and connect the ICP account. Once linked, you can use that ICP account for supported supply, borrow, repay, and withdrawal transactions. ICP and ckAssets are then shown by default in the asset picker; turn off ICP assets to switch back to native-chain assets. See [ICP assets and Oisy](https://liquidium.fi/docs/resources/icp-assets-and-oisy) for supported asset settings and address formats. ![Liquidium Settings showing linked Ethereum and ICP wallet accounts with the option to link another account](https://liquidium.fi/api/media/file/oisy-linked-icp-account-darkmode.avif) > **Native ETH destination:** Native ETH must be sent to a standard Ethereum wallet address. Smart contract wallet addresses are not supported. ## Track a pending borrow During submission, the progress window shows stages such as **Fetching details**, **Approve borrow**, and **Processing borrow**. ![Advanced borrow progress showing Fetching details and Approve borrow completed while Processing borrow continues](https://liquidium.fi/api/media/file/advanced-borrow-progress-darkmode.avif) The success screen shows the borrowed asset, amount, estimated completion time, and transaction link. Timing varies by asset, destination network, and current conditions, so use the live estimate instead of relying on a fixed confirmation time. ![Successful USDT borrow initiation showing the amount, estimated completion time, and transaction reference](https://liquidium.fi/api/media/file/advanced-borrow-success-darkmode.avif) Once the borrow is initiated, the debt can appear in your Advanced Portfolio and affect portfolio health before the outbound transfer reaches its destination. Interest begins accruing when the debt position becomes active. ## Try it in Demo Mode Use Demo Mode to test supplying, borrowing, and repaying with simulated funds. Demo Mode does not require a real wallet transaction or real assets. Turn Demo Mode off before using real funds. Demo balances and transactions do not carry over to your real profile. ## How borrowing works Advanced borrowing uses eligible supplied assets as collateral. Borrowers receive liquidity from supported pools and repay the borrowed amount plus accrued interest. Advanced borrows are over-collateralized. If collateral value falls or debt grows enough to reach the liquidation threshold, the position can be liquidated to help keep the lending pool solvent. ## Understand your borrow terms - Borrow APY is variable and can change over time. - Interest accrues while the debt remains outstanding. - Advanced borrows do not have a fixed repayment date. You can make partial or full repayments. - The outbound network fee is shown before confirmation and may be deducted from the delivered amount. - Available liquidity and market limits can reduce the maximum amount below your collateral-based borrowing capacity. - A position can be liquidated if portfolio health reaches the liquidation threshold. ## Manage a borrowed position Open **Advanced**, then **Portfolio**. The **Borrowed** section shows each borrowed asset, current debt, borrow APY, and accrued interest. ![Advanced portfolio overview showing portfolio health, BTC supplied, USDT borrowed, and Simple Loans](https://liquidium.fi/api/media/file/advanced-borrow-portfolio-darkmode.avif) Expand a borrowed asset to choose **Repay** or **Borrow more**. Borrowing more increases debt and lowers portfolio health. Repaying debt improves portfolio health after the repayment becomes active. See [Repay](https://liquidium.fi/docs/quick-start/repay) for the repayment flow. ## Understanding portfolio health When you borrow against your collateral, it's crucial to understand your **portfolio health** to see your borrowing capacity and avoid liquidations. > [!WARNING] > Borrowing affects your portfolio health as soon as it's initiated, even before the transaction to you has confirmed. ### What is liquidation Liquidation occurs when your borrowing position's health factor becomes too low. When this occurs: - Automated bots may step in to repay part of your debt - In return, they receive some of your collateral at a discount - This mechanism helps maintain protocol stability, though it is generally unfavorable for the borrower Liquidations are a safety mechanism: if the value of your collateral falls too far relative to your borrowed amount, the protocol acts to protect itself and other users. ### Health factor explained Your portfolio health is measured by a **Health Factor** - a simple number that tells you how safe your borrowing position is: > [!TIP] > See advanced Health Factor explanation [here](https://liquidium.fi/docs/technical/concepts/health-factor). The UI displays the portfolio health as a percentage, where: - **100%**: No debt - you haven't borrowed anything - **Above 0% to 99%**: Your position is safe from liquidation - the higher the percentage, the safer you are - **Close to 0%**: You're at risk - the closer to 0%, the higher the liquidation risk - **0%**: Your position can be partially liquidated > [!TIP] > Select the displayed portfolio-health value to switch between percentage and decimal Health Factor formats. A decimal Health Factor of 2.0 is the same as 50% Health in the default UI. A decimal Health Factor of 1.0 is 0% Health and means the position is at the liquidation threshold. For the full conversion table, see [Health Factor](https://liquidium.fi/docs/technical/concepts/health-factor). ### What affects your health factor? Your Health Factor depends on several key factors: **1. Collateral Value** - The total USD value of all assets you've supplied to the protocol - This changes as asset prices fluctuate **2. Debt Value** - The total USD value of everything you've borrowed - Includes interest that accumulates over time **3. Liquidation thresholds** - Each asset has a different risk level called a "liquidation threshold" - This percentage determines how much you can safely borrow against that asset - For example, if Bitcoin has a 74% liquidation threshold, your borrowing power is based on that 74% limit - These thresholds reflect how volatile and liquid each asset is > [!TIP] > Before submitting, expand the transaction details to preview how the borrow affects your APY, portfolio health, and position balance. ![Advanced Borrow form showing the estimated impact of borrowing 147.88 USDT on APY, portfolio health, and position balance](https://liquidium.fi/api/media/file/advanced-portfolio-health-impact-darkmode.avif) > In this example, borrowing 147.88 USDT increases the borrowing APY from 0.967% to 4.128%, lowers portfolio health from 71.1% to 69.4%, and increases the position balance from $2,500 to $2,647.88. ### Weighted liquidation thresholds When you have multiple types of collateral, the protocol calculates a **weighted average** of all your liquidation thresholds. Current market values can change, so always check the latest values on the [Insights page](https://app.liquidium.fi/insights). This weighted threshold is then used to calculate your overall portfolio health. > Click the pie chart icon next to the Borrowed title on the Portfolio tab to open the details modal for weighted liquidation threshold and related risk values. ## Managing liquidation risk ### How much can be liquidated? Liquidation only occurs when your Health Factor reaches 0% or below. However, the amount that can be liquidated depends on your debt to collateral ratio: - **Health Factor at or above -5%** : Up to 50% of a position's debt can be liquidated - **Health Factor below -5%** : Up to 100% of a position's debt can be liquidated, effectively closing the position ### Protecting yourself To reduce liquidation risk: 1. **Monitor portfolio health regularly**, especially during volatile market conditions. 2. **Keep a buffer** instead of borrowing the maximum available amount. 3. **Add more eligible collateral** if portfolio health drops. 4. **Repay debt** to improve the position. See [Repay](https://liquidium.fi/docs/quick-start/repay). 5. **Set up alerts** for supported health and activity events. See [Profile notifications](https://liquidium.fi/docs/quick-start/profile#profile-notifications). Notifications are useful, but you should still monitor the position directly in the app. ## Example scenario Let's say you: - Supply $15,000 worth of Bitcoin and Ethereum - Borrow $6,000 in USDT - Have a weighted liquidation threshold of 74% Your Health Factor would be 1.85: $$ HF = \frac{\$15,000 \times 0.74}{\$6,000} = 1.85 $$ This means you're in a safe position. To find at what price you'd be exposed to liquidation, you can calculate: **Liquidation occurs when**: $$ Collateral\,Value \times Weighted\,Threshold = Debt\,Value $$ In this example: - Current collateral: $15,000 - Debt: $6,000 - Weighted threshold: 74% - Liquidation point: $$ \$6,000 \div 0.74 = \$8,108 $$ So if your collateral value drops from \\$15,000 to \\$8,108 (a \~46% decline), you'd be exposed to liquidation. This could happen if Bitcoin drops significantly while your USDT debt remains the same. --- --- title: "Repay" description: "Learn how to repay an Advanced debt position, choose a wallet or repay address, track confirmation, and understand the effect on portfolio health." canonical: "https://liquidium.fi/docs/quick-start/repay" markdown: "https://liquidium.fi/docs/quick-start/repay/index.md" breadcrumbs: "Docs > Quick start > Repay" updated: "2026-08-27T10:43:12.970Z" --- # Repay Learn how to repay an Advanced debt position, choose a wallet or repay address, track confirmation, and understand the effect on portfolio health. Canonical URL: https://liquidium.fi/docs/quick-start/repay Markdown URL: https://liquidium.fi/docs/quick-start/repay/index.md ![Quid repay](https://liquidium.fi/api/quid-assets/file/quid%20repay.svg) ## Repay in Advanced [Open Liquidium](https://app.liquidium.fi/) and select **Advanced**, then **Portfolio**. Sign in with Internet Identity or a supported wallet to manage your Advanced balances and positions. Expand the asset under **Borrowed** and select **Repay**. You can repay part of the outstanding debt or repay the full available amount. ![Expanded USDT borrowed position showing debt, APY, accrued interest, Repay, and Borrow more actions](https://liquidium.fi/api/media/file/advanced-repay-form-darkmode.avif) If you are repaying a Simple Loan, follow [Repay your Simple Loan](https://liquidium.fi/docs/quick-start/simple-loan#repay-your-loan) instead. ## Submit a repayment 1. Open **Advanced**, then **Portfolio**. 2. Expand the asset you want to repay under **Borrowed**. 3. Select **Repay**. 4. Enter the repayment amount or use **Max** when available. 5. Review the amount and the estimated effect on your debt and portfolio health. 6. Choose a supported linked wallet or the repay address shown by the app. 7. Follow the authorization or transfer steps for that asset. ![Full USDT repayment set to 100%, showing borrowing APY dropping to 0% and portfolio health improving from 71.1% to 100%](https://liquidium.fi/api/media/file/advanced-repay-method-full-darkmode.avif) > Full Repayment ![Partial USDT repayment set to 30%, showing a 750.02 USDT payment and portfolio health improving from 71.1% to 79.8%](https://liquidium.fi/api/media/file/advanced-repay-method-partial-darkmode.avif) > Partial Repayment When repaying from a linked wallet, the app guides you through the required approval and transfer steps. When using a repay address, send only the borrowed asset on the network shown for that position. When repaying with Ledger, use the repay address and exact asset and network shown by the app, and approve the outgoing transfer through the Ledger Live app. Supported ICP assets and ckAssets can be repaid directly from a linked ICP account or through the compatible repay address shown by the app. To use Oisy, first connect it to Liquidium through its Ethereum account, then open Settings and connect the ICP account. After linking, ICP assets and ckAssets are shown by default; turn off ICP assets to switch back to native-chain assets. > **Check the asset, network, and address before sending.** A different asset, the wrong network, or an address not shown for that repayment may not be detected and may not be recoverable. See [ICP assets and Oisy](https://liquidium.fi/docs/resources/icp-assets-and-oisy) for setup details and address formats. ## Track a repayment ![USDT repayment progress showing Fetching details, Approve spending, Send funds, and Processing repayment](https://liquidium.fi/api/media/file/advanced-repay-progress-darkmode.avif) > Process of repaying in app ![Successful USDT repayment initiation showing 2,500 USDT, a 12-minute estimate, and a demo transaction reference](https://liquidium.fi/api/media/file/advanced-repay-success-darkmode.avif) > Success Modal after repayment > A pending repayment can show the expected portfolio health before the repayment becomes active. After submission, the repayment appears under pending actions while it waits for the required confirmations. Once the confirmation threshold is met, protocol finalization takes about 3 minutes. The pending health factor shows the expected portfolio health after pending supplies and repayments are confirmed and processed. > [!WARNING] > Repayments reduce active debt only after they are confirmed and finalized. > [!WARNING] > If the position becomes liquidatable before a pending repayment is processed, liquidation can occur first. Do not rely on an unconfirmed repayment to protect an at-risk position. - **Bitcoin**: Requires 4 confirmations, \~10 minutes per confirmation. - **Ethereum**: Requires 64 confirmations, \~12s per confirmation. > [!TIP] > Learn more about blockchain confirmation times [here](https://www.ledger.com/academy/glossary/blockchain-confirmation) . ## Try it in Demo Mode Use Demo Mode to test supplying, borrowing, repaying, and withdrawing with simulated funds. Demo Mode does not require a real wallet transaction or real assets. Turn Demo Mode off before using real funds. Demo balances and transactions do not carry over to your real profile. ## Repayment terms - Advanced debt has no fixed repayment date. You can make partial or full repayments. - Interest continues accruing while debt remains active. - A processed repayment reduces debt and improves portfolio health, all else being equal. - Repaying debt does not automatically withdraw supplied collateral. After reducing or clearing debt, use [Withdraw](https://liquidium.fi/docs/quick-start/withdraw) to remove eligible supplied assets. - Advanced positions do not use the six-character Simple Loan ID. If support requests a reference, use the relevant transaction, profile, or asset address shown in the app. --- --- title: "Withdraw" description: "Learn how to withdraw eligible supplied assets, choose a wallet or custom address, track processing, and understand liquidity and portfolio-health limits." canonical: "https://liquidium.fi/docs/quick-start/withdraw" markdown: "https://liquidium.fi/docs/quick-start/withdraw/index.md" breadcrumbs: "Docs > Quick start > Withdraw" updated: "2026-08-27T10:43:13.241Z" --- # Withdraw Learn how to withdraw eligible supplied assets, choose a wallet or custom address, track processing, and understand liquidity and portfolio-health limits. Canonical URL: https://liquidium.fi/docs/quick-start/withdraw Markdown URL: https://liquidium.fi/docs/quick-start/withdraw/index.md ![Quid lend](https://liquidium.fi/api/quid-assets/file/quid%20lend.svg) ## Withdraw in Advanced [Open Liquidium](https://app.liquidium.fi/) and select **Advanced**, then **Portfolio**. Sign in with Internet Identity or a supported wallet to manage your Advanced balances and positions. Expand an asset under **Supplied** and select **Withdraw**. Advanced withdrawals remove eligible assets from your supplied position and send them to the destination shown in the app. ![Advanced Portfolio with BTC supplied, USDT borrowed, portfolio health, and the Withdraw action](https://liquidium.fi/api/media/file/advanced-withdraw-portfolio-darkmode-400w.avif) If you repaid an Advanced debt position, the supplied collateral remains in Advanced until you withdraw it. In a [Simple Loan](https://liquidium.fi/docs/quick-start/simple-loan), full repayment returns collateral automatically to the refund address set when the loan was created. ## Submit a withdrawal 1. Open **Advanced**, then **Portfolio**. 2. Expand the asset you want to remove under **Supplied**. 3. Select **Withdraw**. 4. Enter an amount or use **Max** and the percentage slider. 5. Review the amount, the percentage of the supplied position being removed, interest earned, and the network fee. 6. When prompted, choose **Wallet** or **Custom address** and verify the destination. 7. For supported Bitcoin withdrawals, Ledger can be the connected account and destination; confirm the withdrawal and complete the requested approval or signature in the Ledger Live app. The app's **Max** is the amount currently eligible for withdrawal. It can be lower than the supplied balance when you have active debt, when removing more collateral would make portfolio health unsafe, or when pool liquidity or another live limit restricts the outflow. Withdrawing collateral while debt is active lowers portfolio health. Keep a buffer instead of withdrawing the maximum if market movement could put the position near liquidation. ## Choose where the funds go The available destination methods depend on the asset and accounts linked to the profile: - **Wallet:** Send a supported withdrawal to the compatible linked wallet shown by the app. A linked Oisy ICP account can receive ICP, ckBTC, ckETH, ckUSDC, and ckUSDT directly, without entering a withdrawal address. ![Advanced Bitcoin withdrawal form with Wallet selected, amount, position share, and network fee](https://liquidium.fi/api/media/file/advanced-withdraw-wallet-destination-darkmode-400w.avif) - **Custom address:** Enter a compatible destination without linking the receiving wallet. Signed-in users can select a compatible address from the shared Simple and Advanced address book. ![Advanced Bitcoin withdrawal form showing amount, maximum, slider, custom destination, position share, interest, and network fee](https://liquidium.fi/api/media/file/advanced-withdraw-amount-darkmode.avif) Oisy is its own sign-in option in Liquidium; it is not a WalletConnect flow. Select Oisy in Liquidium's wallet picker. If Oisy does not yet have an Ethereum account, create or enable it during the Oisy sign-in flow, then approve the sign-in in Oisy. Next, open **Settings** in Liquidium, connect the Oisy ICP account, and approve the second signing request in Oisy. The ICP account is not linked automatically. Once linked, supported ICP assets and ckAssets are shown by default; turn off **ICP assets** to switch back to native-chain assets. For a custom destination, use the network and exact address type requested by the transaction. ICP-side destinations do not use one universal format. When the app requests a bare ICP principal, do not substitute an ICRC-1 account containing a subaccount or a legacy AccountIdentifier. See [ICP assets and Oisy](https://liquidium.fi/docs/resources/icp-assets-and-oisy) for setup details and current address formats. ![Bitcoin custom withdrawal address with a new-address warning and destination acknowledgement](https://liquidium.fi/api/media/file/advanced-withdraw-custom-address-darkmode-400w.avif) Native custom withdrawal ![ckBTC withdrawal address requesting an ICP principal and destination acknowledgement](https://liquidium.fi/api/media/file/advanced-withdraw-icp-address-darkmode-400w.avif) ckAsset custom withdrawal **Native ETH destination:** Native ETH must be sent to a standard Ethereum wallet address. Smart-contract wallet addresses are not supported. The app validates Ethereum destinations and may require the check to be retried before continuing. The app warns when a destination has no transaction history. Check the asset, network, and full address, then acknowledge that you are responsible for the destination before submitting. An incorrect address, wrong network, or unsupported destination may not be recoverable. Do not submit until the destination matches the asset and network shown by the app. ## Track a withdrawal The progress window shows the steps required for the selected asset. Current withdrawal flows can include **Fetching details**, **Approve withdrawal**, and **Processing withdrawal**. ![Bitcoin withdrawal progress showing Fetching details, Approve withdrawal, and Processing withdrawal](https://liquidium.fi/api/media/file/advanced-withdraw-progress-darkmode-400w.avif) The success screen shows the withdrawn asset, amount, estimated completion time, and transaction link. The supplied balance and portfolio health may update while the outbound transaction is still waiting for destination-network confirmation. ![Successful Bitcoin withdrawal initiation showing the amount, estimated time, and demo transaction reference](https://liquidium.fi/api/media/file/advanced-withdraw-success-darkmode-400w.avif) Use the live estimate and transaction link for the specific withdrawal. Timing varies with the asset, network conditions, protocol processing, and the destination network. > A network fee is deducted from the withdrawn amount. You do not need to hold separate gas for this outflow. Review the live fee before confirming. > Bitcoin timing varies with network conditions. A block is often around ten minutes, but that is not a guaranteed confirmation time. Use the live estimate and transaction link shown for your withdrawal. Learn more about [blockchain confirmations](https://www.ledger.com/academy/glossary/blockchain-confirmation). ### Speeding up eligible Bitcoin outflows Some Bitcoin withdrawals or borrows can be accelerated with CPFP when the original fee rate is too low and the connected Bitcoin wallet controls an eligible output. When available, the speed-up flow compares the current effective fee rate with recommended rates, builds a boost transaction, and asks the wallet to sign it. CPFP can improve confirmation chances, but it does not guarantee immediate confirmation. It may not be available for a withdrawal sent to a custom address or an output the connected wallet does not control. ## Withdrawal limits and liquidity Liquidium uses pooled liquidity. The amount available to withdraw depends on the current position and pool state: - You can withdraw only the amount currently shown as eligible in the app - The eligible amount can be limited by the supplied balance, active debt, portfolio-health requirements, available pool liquidity, live market limits, and network fees - A processed withdrawal reduces the supplied position and can reduce portfolio health when debt remains active - The destination asset and network are shown before confirmation. Follow those values and the live status until the destination transaction confirms > [!TIP] > In rare periods of high demand, a withdrawal can be temporarily limited. Your supplied position remains recorded and secure within the protocol while you wait for liquidity to return, although normal protocol and market risks still apply. Try again later or submit a smaller amount. ## Bitcoin withdrawals below 50,000 sats Bitcoin withdrawals below 50,000 sats (₿0.0005) are processed every five minutes. Even a single withdrawal is processed at the next interval; it does not need to wait for other withdrawals to accumulate. --- --- title: "Core concepts" description: "Understanding the key terms and concepts." canonical: "https://liquidium.fi/docs/quick-start/core-concepts" markdown: "https://liquidium.fi/docs/quick-start/core-concepts/index.md" breadcrumbs: "Docs > Quick start > Core concepts" updated: "2026-08-06T08:55:41.186Z" --- # Core concepts Understanding the key terms and concepts. Canonical URL: https://liquidium.fi/docs/quick-start/core-concepts Markdown URL: https://liquidium.fi/docs/quick-start/core-concepts/index.md ![Quid teach](https://liquidium.fi/api/quid-assets/file/quid%20teach.svg) ## Pools ### What is a pool A pool is a shared liquidity vault for a specific asset (like BTC, USDT, or ETH). Lenders supply assets to the pool to earn interest, while borrowers supply collateral to access this liquidity and pay interest on their loans. The interest paid by borrowers is distributed to lenders as yield. Each pool operates independently with its own interest rates based on supply and demand. > You can find live pool parameters on the [Insights page](https://app.liquidium.fi/insights). ### Dynamic interest rates Interest rates in each pool dynamically adjust based on supply and demand to maintain economically optimal conditions and secure the protocol. When utilization is low, rates are kept low to encourage borrowing. As more funds are borrowed and liquidity becomes scarce, rates increase to incentivize repayments and new supply. This creates a self-balancing system that ensures pools always have adequate liquidity for withdrawals while maximizing capital efficiency. When you enter an amount in Simple Loans or an Advanced supply, borrow, repay, or withdraw form, Liquidium estimates how the action would affect the pool's APY. If the change is significant, the app shows the current APY followed by the projected APY. The projection uses the current pool state and entered amount, so the final rate can change before the action is processed. #### Borrow rate (APY) The annual percentage yield (APY) applied to borrowed funds follows a dynamic model based on pool utilization: - Starts with a base rate when utilization is low - Increases gradually until reaching an "optimal utilization" point - Accelerates rapidly beyond optimal utilization to encourage repayment #### Supply rate (APY) The annual percentage yield (APY) you earn on your supplied assets. Your earnings come from: - Interest paid by borrowers in the pool - Adjusted by how much of the pool is being borrowed - Net of the protocol fee > [!TIP] > APY represents the projected annualized return on your assets, based on the current pool rate and assuming compounding over a one-year period. > [!TIP] > Higher utilization generally leads to better supply rates for lenders. #### Base Rate The minimum interest rate applied to a pool, even at very low utilization. This ensures borrowers always pay interest and lenders receive yield. #### Utilization Rate Utilization measures how much of a pool's supplied liquidity has been borrowed. A simple way to think about it is: Utilization = Total Borrowed / Total Supplied. Equivalently, when a pool exposes available liquidity: Utilization = Total Debt / (Total Debt + Available Liquidity). Low utilization means plenty of liquidity is available, so borrowing rates are usually lower. High utilization means liquidity is more scarce, so borrowing rates usually increase to encourage repayment and new supply. #### Optimal Utilization Rate The target utilization level marks where interest rates change sharply. Below this point, rates grow slowly; above it, they increase rapidly to maintain pool liquidity. ![profile-example](https://liquidium.fi/api/media/file/optimal-utilization.png) #### Liquidation Threshold Each pool has its own liquidation threshold. This threshold helps determine when a borrowing position becomes liquidatable if the value of collateral falls relative to debt. Liquidation threshold is different from max LTV. Max LTV controls how much a user can borrow when opening or increasing a position. Liquidation threshold controls when the position can be liquidated. Max LTV is lower than the liquidation threshold, creating a safety buffer. Portfolio health summarizes how close the full portfolio is to liquidation. When portfolio health gets low, users can improve it by supplying more collateral, repaying debt, or reducing exposure. #### Supply/Borrow Caps Maximum limits set on how much can be supplied to or borrowed from each pool. These risk management tools help prevent any single pool from becoming too large relative to the protocol's overall risk profile. #### Same-asset borrowing Some pools may allow same-asset borrowing, and some may disable it. Same-asset borrowing means a user can borrow the same asset they have supplied, subject to protocol rules, current pool configuration, dust thresholds, and portfolio health. Check the [Insights page](https://app.liquidium.fi/insights) for the current setting on each live market. ## Your profile ### Position Your position tracks your lending and borrowing activity with a specific asset. Each position shows: - How much you've supplied (deposited) - How much you've borrowed - Interest earned on supplies - Interest owed on borrows - Your net balance with that asset You automatically get one position per asset type when you first interact with a pool. ### Health factor Your portfolio health is measured by a **Health Factor** - a simple number that tells you how safe your borrowing position is: > [!TIP] > See advanced Health Factor explanation [here](https://liquidium.fi/docs/technical/concepts/health-factor). The UI displays the portfolio health as a percentage, where: - **100%**: No debt - you haven't borrowed anything - **Above 0% to 99%**: Your position is safe from liquidation - the higher the percentage, the safer you are - **Close to 0%**: You're at risk - the closer to 0%, the higher the liquidation risk - **0%**: Your position can be partially liquidated > [!TIP] > You can switch to traditional decimal format in General Settings if you prefer. ### Collateral Collateral is the set of assets backing your borrow positions. When you borrow, all supplied assets automatically count toward collateral. The protocol requires over-collateralization, meaning the total value of your collateral must exceed the value of your borrow to maintain a safety buffer. ### Weighted average liquidation threshold When you have positions across multiple pools, your overall borrowing limit is determined by the weighted average liquidation threshold of all your collateral. This determines your overall health factor and liquidation risk. ### Net APY Combined effect of all supply and borrow positions on net worth. > [!TIP] > It is possible to have a negative net APY if you accrue more interest from your debt than you earn from your supplied assets. ### Net value The value of supplied assets minus borrowed positions. ### Net interest Interest earned from supplied assets minus interest due on borrowed assets for open positions. Interest accrues continuously and compounds over time. > [!TIP] > If the interest due is higher than the interest earned, the net interest will be negative. ### Current pool parameters Live pool parameters can change over time as markets and protocol configuration evolves. Use the [Insights page](https://app.liquidium.fi/insights) as the source of truth for supported assets, APYs, caps, utilization, LTV, liquidation thresholds, reserve factors, and same-asset borrowing settings. ## Cross-chain architecture ### Native assets everywhere Unlike other platforms that require wrapped tokens or complex bridges, Liquidium lets you use your actual Bitcoin, Ethereum, and other native assets directly. You can: - Supply Bitcoin from your Bitcoin wallet to earn yield - Borrow USDT that gets sent to your Ethereum address - Use your Bitcoin as collateral to borrow assets on other chains - Perform these actions with any supported asset, no matter which chain it lives on ### How it works The protocol runs on IC (Internet Computer), which can natively interact with other blockchains without trusted intermediaries. Behind the scenes, your native assets are represented as "chain-key assets" (like ckBTC for Bitcoin) - these are 1:1 backed by the real assets and secured by [multiple independent nodes](https://dashboard.internetcomputer.org/network/subnets/pzp6e-ekpqk-3c5x7-2h6so-njoeq-mt45d-h3h6c-q3mxf-vpeq5-fk5o7-yae) working together. Running everything on IC enables instant liquidations to keep the protocol healthy. While Bitcoin takes 10-40 minutes per transaction and other chains can be slow during congestion, our liquidation system completes full cycles in just 15 seconds thanks to IC's sub-second finality. > [!TIP] > From your perspective, it's seamless - just send and receive native tokens as usual. The protocol handles all the complexity. Learn more about [IC's Chain Fusion Technology](https://internetcomputer.org/chainfusion) --- --- title: "Resources" description: "Reference pages for support questions, app data, dashboards, and extra Liquidium resources." canonical: "https://liquidium.fi/docs/resources" markdown: "https://liquidium.fi/docs/resources/index.md" breadcrumbs: "Docs > Resources" updated: "2026-06-23T14:32:52.985Z" --- # Resources Reference pages for support questions, app data, dashboards, and extra Liquidium resources. Canonical URL: https://liquidium.fi/docs/resources Markdown URL: https://liquidium.fi/docs/resources/index.md Reference pages for support questions, app data, dashboards, and extra Liquidium resources. ## Pages - [FAQ](https://liquidium.fi/docs/resources/faq) - [Insights](https://liquidium.fi/docs/resources/insights) - [History](https://liquidium.fi/docs/resources/history) - [Liquidations Dashboard](https://liquidium.fi/docs/resources/liquidations) - [Vaults](https://liquidium.fi/docs/resources/vaults) - [Miscellaneous](https://liquidium.fi/docs/resources/miscellaneous) --- --- title: "FAQ" description: "Answers about Liquidium Simple Loans, Advanced positions, sign-in, wallets, repayments, collateral, portfolio health, ICP assets, and app behavior." canonical: "https://liquidium.fi/docs/resources/faq" markdown: "https://liquidium.fi/docs/resources/faq/index.md" breadcrumbs: "Docs > Resources > FAQ" updated: "2026-08-27T11:52:31.776Z" --- # FAQ Answers about Liquidium Simple Loans, Advanced positions, sign-in, wallets, repayments, collateral, portfolio health, ICP assets, and app behavior. Canonical URL: https://liquidium.fi/docs/resources/faq Markdown URL: https://liquidium.fi/docs/resources/faq/index.md Short answers to common Liquidium questions. Live app values, market parameters, and wallet availability can change, so the app is the source of truth at transaction time. ## What is the difference between Simple Loan and Advanced? **Simple Loan** is a one-step borrowing flow that does not require an account. Each loan has its own Loan ID, collateral address, repayment address, and lifecycle. **Advanced** is the portfolio flow for supplying, borrowing, repaying, and withdrawing across supported assets. Sign in with Internet Identity or a supported wallet to manage Advanced balances and positions. See [Simple Loan](https://liquidium.fi/docs/quick-start/simple-loan) and [Quick start](https://liquidium.fi/docs/quick-start) for the full comparison. ## Do I need to sign in? You do not need to sign in to create or manage a Simple Loan. Signed-out loans are saved in the current browser. You can optionally sign in with Internet Identity or a supported wallet to save them to your profile and access them across devices. Advanced requires sign-in because its balances, linked accounts, addresses, and positions are managed through your profile. See [Your profile](https://liquidium.fi/docs/quick-start/profile). ## How do Simple Loan notifications work? Signed-out users can enable email notifications separately for each Simple Loan. If you are signed in and have activated a profile email, that address is automatically used for Simple Loan notifications and can still be reviewed or changed for an individual loan. Notifications are useful, but you should still monitor the loan directly in the app. ## Can I use staked ICP or NNS neurons as collateral? No. Liquidium can only use transferable assets that the app supports as collateral. Locked or staked ICP in NNS neurons cannot be supplied directly as collateral. ## Can I use NFTs as collateral? No. Liquidium.fi only supports the transferable assets shown in the app for supplying, borrowing, and repayment. NFTs cannot be supplied as collateral on Liquidium.fi unless the app explicitly supports them in the future. For Bitcoin Ordinals and other Bitcoin-native NFT-style collateral, see Liquidium's separate Bitcoin-native lending app at https://liquidium.wtf. ## What are the current LTV and liquidation values? Current pool parameters are: | Asset | Max LTV\* | Liquidation threshold\* | Liquidation bonus\* | | --- | --- | --- | --- | | BTC | 65% | 74% | 5% | | ETH | 65% | 74% | 5% | | USDC | 65% | 74% | 5% | | USDT | 65% | 74% | 5% | | ICP | 50% | 70% | 7.5% | \*These values can change. Check the live [Insights page](https://app.liquidium.fi/insights) before opening or adjusting a position. ## Why does support mention Health Factor when the app shows Health %? They are two displays of the same safety calculation. The app defaults to Health %. Technical docs sometimes use decimal Health Factor. A decimal Health Factor of 2.0 equals 50% Health in the app, and a decimal Health Factor of 1.0 equals 0% Health at the liquidation threshold. See [Health Factor](https://liquidium.fi/docs/technical/concepts/health-factor) for the conversion table. ## Can I repay by using my supplied collateral? Not currently. Supplied collateral is not automatically sold or swapped to repay debt. In Advanced, repay with a supported linked wallet or by sending the borrowed asset to the repay address shown in the app. After reducing or clearing debt, withdraw eligible supplied assets separately. ## What happens if I make a partial repayment? For Simple Loans, a partial repayment lowers LTV but does not release collateral; collateral is returned only after the full amount is repaid. In the advanced flow, repayment lowers debt, and supplied collateral is withdrawn separately. ## Do Advanced positions have a Loan ID? No. The six-character Loan ID is specific to Simple Loans. Advanced positions are managed from the Portfolio tab after signing in with Internet Identity or a supported wallet. To repay, expand the borrowed asset and select Repay. To withdraw eligible supplied assets, expand the supplied asset and select Withdraw. ## What should I do if I sent a repayment with the wrong asset, network, or address? Stop sending additional funds and contact support from the button in the bottom-left corner of app.liquidium.fi. Ask to talk to a human and include the transaction hash, asset, network, amount, destination address, and whether this was a Simple Loan or an Advanced position. For Simple Loans, include the Loan ID if you have it. Wrong-asset, wrong-network, or wrong-address transfers are not guaranteed to be recoverable. Support needs the transaction details to investigate what happened. ## Can I use ckBTC, ckETH, ckUSDC, or ckUSDT over ICP? Yes. Supported ICP assets and ckAssets can be supplied, borrowed, repaid, and withdrawn through the methods shown by the app. To use Oisy, select it in Liquidium's wallet picker and approve the Ethereum-account sign-in. Then open Settings, connect the Oisy ICP account, and approve the second request. The ICP account is not linked automatically. Once linked, it can handle supported supply, borrow, repay, and withdrawal transactions for ICP, ckBTC, ckETH, ckUSDC, and ckUSDT. Address-based methods remain available where offered. See [ICP assets and Oisy](https://liquidium.fi/docs/resources/icp-assets-and-oisy) for setup and address details. ## Can I use an air-gapped wallet, hardware wallet, or exchange account? Ledger can connect as a Bitcoin-side account for Advanced; supply to the asset-specific deposit address, follow the app’s destination, repay, and withdrawal address flows for other actions, and complete required approvals in the Ledger Live app. Other air-gapped wallets, hardware wallets, and exchange accounts can still use the address-based Simple Loan flow where compatible. ## Is there a fixed repayment date? No. Liquidium loans do not have monthly repayment dates. Interest accrues over time, and you can repay partially or fully whenever you want as long as the position stays healthy. ## Why is my Simple Loan still awaiting deposit or not started? A Simple Loan may stay pending while the collateral deposit is waiting for chain confirmations. If the deposit is detected but the loan cannot open, check whether the deposit is too small or whether price movement pushed the loan above the max LTV slippage setting. If the loan cannot open, add more collateral if the app asks for it. Otherwise, collateral is refunded to the refund address after the loan fails to open. ## When do I get my Simple Loan collateral back? Collateral is returned to the refund address only after the full debt is repaid. Partial repayments lower LTV but do not release collateral. Use the Simple Loan manage view to check the latest amount due before sending repayment, because interest accrues over time. ## Where can I find my invite code? Open the Liquidium app and use the profile or account menu in the top-right corner. If an invite or referral action is available for your account, the app will show it there. Invite and referral campaigns can change over time, so the app is the source of truth for current availability and rewards. ## Can I use Oisy? Yes. Select Oisy in Liquidium's wallet picker and approve the Ethereum-account sign-in. Then open Settings, connect the Oisy ICP account, and approve the second request. The ICP account is not linked automatically. Once linked, it can handle supported supply, borrow, repay, and withdrawal transactions for ICP, ckBTC, ckETH, ckUSDC, and ckUSDT. See [ICP assets and Oisy](https://liquidium.fi/docs/resources/icp-assets-and-oisy) for the full setup. ## Can I use Phantom for BTC? No. Phantom is supported for EVM flows, but Phantom BTC is not supported because Phantom deprecated BTC support. For BTC flows, use another supported BTC wallet or the address-based flow shown in the app. ## Where can I find transaction history? Open [History](https://app.liquidium.fi/history) to review past and pending transactions, including statuses and transaction IDs where available. ## Can US residents use Liquidium? Availability and eligibility can depend on your location, the app flow, and applicable rules. Review the Liquidium Terms before using the app, and use the app only if you are allowed to do so from your location. The app and Terms are the source of truth for current access and eligibility requirements. ## Does Liquidium have a public bug bounty? Liquidium does not currently publish a fixed public bounty schedule in the docs. If you find a security issue, open the support button in the bottom-left corner of [app.liquidium.fi](https://app.liquidium.fi) and ask to talk to a human so you can report your finding. ## Are Vaults managed investment products? No. Vault docs and examples are educational and operational guidance for using the app. They are not personalized financial advice and do not guarantee returns. --- --- title: "Insights" description: "Compare live Liquidium insights, markets, rates, caps, and pool risk parameters." canonical: "https://liquidium.fi/docs/resources/insights" markdown: "https://liquidium.fi/docs/resources/insights/index.md" breadcrumbs: "Docs > Resources > Insights" updated: "2026-08-14T02:11:09.829Z" --- # Insights Compare live Liquidium insights, markets, rates, caps, and pool risk parameters. Canonical URL: https://liquidium.fi/docs/resources/insights Markdown URL: https://liquidium.fi/docs/resources/insights/index.md The Markets page gives a pool-level view of Liquidium. Use it to compare available pools, inspect live rates and risk parameters, and open supply or borrow actions for a specific asset. Open Markets in the app: [app.liquidium.fi/insights](https://app.liquidium.fi/insights). ## What The Insights Page Shows The Insights page is organized into dashboard sections: \*\*Markets\*\* (available pools, live rates, and risk parameters), \*\*Flows\*\* (daily deposits and loans moving in and out of the protocol), \*\*Loans\*\* (loan mix: how loans are opened, what backs them, and what they borrow), \*\*Revenue\*\* (interest earned, split between suppliers and the protocol), and \*\*Risk\*\* (open positions grouped by health factor). A \*\*Recent activity\*\* section lists the latest supply, borrow, repay, withdraw, and liquidation events. Charts support timeframe selection and sharing. Each pool in the Markets table can be opened for more detail. The expanded pool view includes: - Current utilization. - Available liquidity. - Oracle price. - Total supplied and the pool supply cap. - Total borrowed and the pool borrow cap. - Supply APY. - Borrow APY. - Liquidation threshold. - Max LTV. - Liquidation bonus. - Base rate. - Reserve factor. - Whether same-asset borrowing is allowed for that pool. - Interest-rate curve. - Historical interest-rate chart. - Historical utilization chart. - Links to relevant pool contracts or canister dashboards. Pool values are live protocol/app data. Do not treat screenshots or examples as fixed values. For definitions of core pool fields such as utilization, caps, liquidation threshold, and APY, see [Core concepts](https://liquidium.fi/docs/quick-start/core-concepts). ## Supported Markets The Markets page is the source of truth for currently supported assets and chains. Liquidium may support markets such as: - BTC on Bitcoin. - ICP on the ICP ledger. - Stablecoin markets on Ethereum. Each supported market can have a shareable detail page, such as `https://app.liquidium.fi/insights/icp` for ICP. Supported markets can change over time. Check the live Markets page for the current list before supplying, borrowing, or planning a strategy around a specific asset. ## Supply And Borrow From Markets From an expanded pool, users can start a supply or borrow action for that asset. The action modal uses the same flow as the main Portfolio page, including wallet or address-based methods where supported. ## Utilization And Rates Markets shows current utilization and the selected pool's rate curve so users can see how pool usage affects supply and borrow rates. At a high level, higher utilization generally means liquidity is more scarce and borrowing rates increase. Lower utilization generally means liquidity is more available and borrowing rates decrease. For the full interest-rate model, including the kink model, reserve factor, supply-rate calculation, and index-based accrual, see [Interest Rate Model](https://liquidium.fi/docs/technical/concepts/interest-rates). ## Caps Each pool can have supply and borrow caps. - Supply cap: maximum amount that can be supplied to the pool. - Borrow cap: maximum amount that can be borrowed from the pool. If a cap is reached, users may be unable to supply or borrow more of that asset until liquidity changes or the cap changes. ## Same-Asset Borrowing Some pools may allow users to borrow the same asset they have supplied. Other pools may disable this. The Markets page shows the current same-asset borrowing status for each pool. Same-asset borrowing is subject to pool configuration, dust thresholds, available liquidity, and portfolio health. ## Sharing A Market Expanded market pages can be shared. The app supports copying a market link and sharing a market on X. ## Contract Links The expanded pool page links to relevant contract or canister dashboards where available. These links are informational and should not be used as a substitute for reviewing the active transaction details in the Liquidium app before signing. --- --- title: "History" description: "Review Liquidium activity, transaction IDs, exports, and interest history." canonical: "https://liquidium.fi/docs/resources/history" markdown: "https://liquidium.fi/docs/resources/history/index.md" breadcrumbs: "Docs > Resources > History" updated: "2026-06-29T12:50:41.782Z" --- # History Review Liquidium activity, transaction IDs, exports, and interest history. Canonical URL: https://liquidium.fi/docs/resources/history Markdown URL: https://liquidium.fi/docs/resources/history/index.md The History page shows a user's Liquidium activity and interest history. It helps users review past actions, inspect transaction IDs, and export records. Open History in the app: [app.liquidium.fi/history](https://app.liquidium.fi/history). ## Activity History The activity table can include these action types: - Supply. - Borrow. - Repay. - Withdraw. - Liquidation. Each row can show: - Action type. - Status. - Date. - Asset or pool. - Amount. - One or more transaction IDs when available. Statuses shown by the app include: - Requested. - Pending. - Confirmed. - Failed. Some actions can involve more than one transaction ID. When multiple transaction IDs exist, the UI exposes them individually. ## Exporting History Users can export their history as: - CSV. - Excel. Exports are generated from the same user history data shown in the table. Exports are provided as convenience records for review. Verify them independently before using them for accounting, tax, or reporting purposes. ## Interest History The History page also includes interest charts for a selected token. Users can view: - Lending interest. - Borrowing interest. - Cumulative interest. - Daily or periodic interest. The chart uses the selected pool token and historical position data. If a user has no interest history for that token, the chart may be empty. ## Token Selection History charts are token-specific. The user can choose which pool token to inspect. The available token list comes from the active Liquidium pools. ## Refresh Behavior The app refreshes user history periodically while the page is open. Recent transactions may appear first as pending and update after the app detects the required confirmations and backend processing completes. For more detail on how each operation moves through the protocol, see [Deposits](https://liquidium.fi/docs/technical/operations/deposits), [Borrowing](https://liquidium.fi/docs/technical/operations/borrowing), [Repayments](https://liquidium.fi/docs/technical/operations/repayments), and [Withdrawals](https://liquidium.fi/docs/technical/operations/withdrawals). ## Related Pages - Use Portfolio to manage active supply and borrow positions. - Use [Insights](https://app.liquidium.fi/insights) to inspect pool-level rates and utilization. - Use Liquidations to inspect at-risk accounts and recent liquidation events. --- --- title: "Liquidations Dashboard" description: "Monitor liquidatable positions, recent liquidation events, filters, and data freshness." canonical: "https://liquidium.fi/docs/resources/liquidations" markdown: "https://liquidium.fi/docs/resources/liquidations/index.md" breadcrumbs: "Docs > Resources > Liquidations Dashboard" updated: "2026-06-23T14:33:48.077Z" --- # Liquidations Dashboard Monitor liquidatable positions, recent liquidation events, filters, and data freshness. Canonical URL: https://liquidium.fi/docs/resources/liquidations Markdown URL: https://liquidium.fi/docs/resources/liquidations/index.md The Liquidations page shows accounts that are currently at risk and recent liquidation events. It is intended to make liquidation risk and liquidation activity visible from the app. Open Liquidations in the app: [app.liquidium.fi/liquidations](https://app.liquidium.fi/liquidations). ## Liquidatable Positions The liquidatable positions table can show: - Account. - Collateral positions. - Debt positions. - Health factor. - Liquidation bonus. The page also summarizes: - Total liquidatable value. - Number of positions. - Average health factor. The data can be filtered by pool. ## Recent Liquidations The recent liquidations table shows liquidation events recorded by the app backend. Events can include: - Time. - Borrower/account. - Collateral pool. - Debt pool. - Debt repaid. - Collateral received. - Status. ## Health Factor Health factor indicates how close an account is to liquidation. A lower health factor means higher liquidation risk. The Liquidations page is not a substitute for monitoring your own Portfolio health. Users should use the Portfolio health indicator and warnings to manage their own positions. For the full protocol mechanics, see [Health Factor](https://liquidium.fi/docs/technical/concepts/health-factor) and [Liquidations](https://liquidium.fi/docs/technical/concepts/liquidations). ## Pool Filter Use the pool filter to inspect at-risk positions or liquidation events for one pool instead of all pools. ## Data Freshness The Liquidations page refreshes periodically while open. Liquidation data depends on canister reads and backend event tracking, so the page can lag behind the latest on-chain or canister state during processing. --- --- title: "Vaults" description: "Explore integrated Aave and Morpho vaults, guided strategies, estimated returns, and risk notes." canonical: "https://liquidium.fi/docs/resources/vaults" markdown: "https://liquidium.fi/docs/resources/vaults/index.md" breadcrumbs: "Docs > Resources > Vaults" updated: "2026-07-20T18:17:23.946Z" --- # Vaults Explore integrated Aave and Morpho vaults, guided strategies, estimated returns, and risk notes. Canonical URL: https://liquidium.fi/docs/resources/vaults Markdown URL: https://liquidium.fi/docs/resources/vaults/index.md The Vaults page combines integrated vaults with guided strategies. Integrated Aave V3 and Morpho vaults can be deposited into and withdrawn from directly in the app, while guided strategies walk users through Liquidium and third-party protocol steps. Open Vaults in the app: [app.liquidium.fi/vaults](https://app.liquidium.fi/vaults). Vaults are not automatic managed positions. You choose each transaction and approve it in your wallet. Some strategies support in-app deposits and withdrawals; others link to the relevant external protocol when a step is not integrated. ## What Vault Cards Show Vault cards can show: - Strategy name and protocol. - Supported collateral, borrow, and yield assets. - Estimated net APY and risk level. - Whether the vault is integrated or guided. - Strategy steps and available actions. Integrated vault details can also show live third-party data such as TVL, liquidity, share price, performance fee, your wallet balance, and your current vault position. Availability depends on the protocol and connected wallet. ## Integrated Vault Actions For supported Aave V3 and Morpho vaults, connect the Ethereum wallet that owns the assets or position. The app can guide deposits, approvals, withdrawals, transaction status, and explorer links without sending you to a separate protocol interface. Some ETH strategies can wrap ETH before deposit or unwrap WETH during withdrawal. Review every wallet request, token approval, network fee, and destination before confirming. ## Current Strategy Examples The strategy directory can include examples such as: - Stablecoin yield strategies. - BTC-backed borrowing strategies. - Leverage loop strategies. - Strategies that combine Liquidium borrowing with third-party yield protocols. The exact strategy list can change over time. Use the live Vaults page for the current set of integrated vaults, guided strategies, supported assets, available actions, and estimated returns. ## Risk Vault strategies can introduce risks beyond normal Liquidium borrowing: - Borrow rates are variable. - Third-party yields are variable. - Net APY can become negative. - Collateral volatility can cause liquidation. - Third-party protocols can have smart contract, liquidity, oracle, or operational risk. - Swaps can introduce slippage and execution risk. Liquidium does not control third-party protocols. Users should review each protocol and transaction before proceeding. For borrowing and liquidation-risk basics, see [Borrow](https://liquidium.fi/docs/quick-start/borrow) and [Core concepts](https://liquidium.fi/docs/quick-start/core-concepts). ## Net APY Net APY is an estimate based on the strategy's yield and Liquidium borrowing or supply costs. It can change as Liquidium rates, third-party yields, utilization, or asset prices change. For live Liquidium pool rates, utilization, and market availability, see [Insights](https://app.liquidium.fi/insights). Use the live Vaults page for current strategy estimates. ## Leverage Loop Strategy Leverage loop strategies use borrowed funds to increase exposure to an asset or position. They can amplify returns, but they also amplify risk. Higher leverage increases liquidation risk. Review your portfolio health and every transaction before proceeding. --- --- title: "Miscellaneous" description: "Find miscellaneous Liquidium resources, updates, and supporting information across Liquidium’s Bitcoin-native and cross-chain lending products." canonical: "https://liquidium.fi/docs/resources/miscellaneous" markdown: "https://liquidium.fi/docs/resources/miscellaneous/index.md" breadcrumbs: "Docs > Resources > Miscellaneous" updated: "2026-08-27T10:42:59.878Z" --- # Miscellaneous Find miscellaneous Liquidium resources, updates, and supporting information across Liquidium’s Bitcoin-native and cross-chain lending products. Canonical URL: https://liquidium.fi/docs/resources/miscellaneous Markdown URL: https://liquidium.fi/docs/resources/miscellaneous/index.md Here you’ll find miscellaneous Liquidium resources and supporting information that don’t fit neatly into the main documentation sections, but may still be useful when learning about Liquidium’s products, ecosystem, and updates. ## **Phantom Wallet Bitcoin Connection Update** Phantom Wallet users can no longer connect to Liquidium through Phantom’s previous Bitcoin wallet-connect flow. This is because Phantom removed the Bitcoin connection features that Liquidium previously supported. You can still withdraw Bitcoin from Liquidium by connecting to Liquidium with the Phantom ETH connector. However, Bitcoin deposits now work differently for Phantom users. To deposit Bitcoin, use your native Liquidium Bitcoin deposit address. Copy the deposit address from Liquidium, then send Bitcoin to that address directly from your Phantom wallet. This does not require a wallet connection. For Simple Loans, you can also use the address-based flow without connecting Phantom or any other wallet. ### Step-by-Step explanation: 1. Switch from wallet to your deposit address, by clicking on wallet. ![Wallet Deposit Switch 1.avif](https://liquidium.fi/api/media/file/Wallet%20Deposit%20Switch%201.avif) 2. Copy your Liquidium Bitcoin deposit address. ![Wallet Deposit Switch 2.avif](https://liquidium.fi/api/media/file/Wallet%20Deposit%20Switch%202.avif) 3. Go to Phantom Mobile or Desktop. 4. Choose Bitcoin and paste in your Liquidium Bitcoin deposit address. ![Wallet Deposit Switch 6.avif](https://liquidium.fi/api/media/file/Wallet%20Deposit%20Switch%206.avif) 5. Send the Bitcoin to your Liquidium Bitcoin deposit address. 6. The Bitcoin deposit will be detected within seconds. After 40 minutes your Bitcoin counts towards your collateral. ![Wallet Deposit Switch 5.avif](https://liquidium.fi/api/media/file/Wallet%20Deposit%20Switch%205.avif) For a wallet-connect alternative to Phantom, use a supported Bitcoin option shown in the app, such as Xverse or Ledger; Ledger users can create or link a Bitcoin account, follow Liquidium’s displayed address flows for each action, and approve or sign through the Ledger Live app. --- --- title: "ICP assets and Oisy" description: "How to use ckAssets over ICP and connect Oisy to Liquidium." canonical: "https://liquidium.fi/docs/resources/icp-assets-and-oisy" markdown: "https://liquidium.fi/docs/resources/icp-assets-and-oisy/index.md" breadcrumbs: "Docs > Resources > ICP assets and Oisy" updated: "2026-08-26T11:57:03.956Z" --- # ICP assets and Oisy How to use ckAssets over ICP and connect Oisy to Liquidium. Canonical URL: https://liquidium.fi/docs/resources/icp-assets-and-oisy Markdown URL: https://liquidium.fi/docs/resources/icp-assets-and-oisy/index.md [Liquidium Advanced](https://app.liquidium.fi/advanced) supports native ICP alongside ckBTC, ckETH, ckUSDC, and ckUSDT over ICP. You can use these assets through Liquidium Connect with Oisy or through the address-based methods shown by the app. ## Using ICP assets Enable **ICP assets** when you want to use the ICP version of a supported asset: - BTC becomes ckBTC on ICP. - ETH becomes ckETH on ICP. - USDC becomes ckUSDC on ICP. - USDT becomes ckUSDT on ICP. - Native ICP remains ICP. Always verify the selected asset and network before approving or sending funds. ## Connect Oisy with Liquidium Connect First, create or enable an Ethereum account in Oisy. In Liquidium, open the wallet picker and select **Oisy**. Approve the sign-in request in Oisy. Liquidium uses the Ethereum account to establish your Liquidium sign-in. After signing in, open Liquidium Connect options and link your Oisy ICP account. Approve the second signing request in Oisy. The ICP account is not linked automatically. The Ethereum account does not route ICP assets through Ethereum. Transactions involving ICP or ckAssets are signed using the linked ICP account in Oisy. ## Use ICP assets directly with Oisy Once both accounts are connected, you can use the following assets directly through Oisy for supported supply, borrow, repay, and withdrawal transactions: - ICP - ckBTC - ckETH - ckUSDC - ckUSDT Select the action and asset in Liquidium, confirm that the network is ICP, and approve the transaction in Oisy. You do not need to copy an address when the selected action offers the connected-wallet option. Available assets and markets can change. Always use the live asset picker to confirm current support. ## Address-based deposits and repayments Address-based transfers remain available wherever Liquidium offers them. For a deposit or repayment, send the exact asset to the complete account displayed by Liquidium. A ckAsset ICRC-1 account may include a subaccount. Do not shorten it to the owner principal or convert it to another ICP address format. Your sending wallet must support the complete account format shown by Liquidium. ## Address-based borrows and withdrawals Borrows and withdrawals can also use a destination address where the app provides that option. Enter the exact address format requested by the transaction. When the app asks for a bare ICP principal, do not substitute an ICRC-1 account containing a subaccount or a legacy AccountIdentifier. With **ICP assets** disabled, supported assets use their native networks. For example, USDC and USDT settle over Ethereum. ## Troubleshooting Liquidium Connect Both the sign-in and account-linking requests must be approved in Oisy. If the connection fails: 1. Confirm that an Ethereum account is enabled in Oisy. 2. Open the wallet picker in Liquidium, select Oisy, and approve the sign-in request in Oisy. 3. Open Liquidium Connect options, link your Oisy ICP account, and approve the second signing request in Oisy. 4. If either request does not appear, reopen Liquidium and Oisy before trying again. If the problem continues, contact support from the bottom-left corner of the Liquidium app. Include the complete error message, device, browser, and approximate time. --- --- title: "Technical Documentation" description: "Technical documentation for the Cross-chain loans" canonical: "https://liquidium.fi/docs/technical" markdown: "https://liquidium.fi/docs/technical/index.md" breadcrumbs: "Docs > Technical Documentation" updated: "2026-06-23T14:33:48.077Z" --- # Technical Documentation Technical documentation for the Cross-chain loans Canonical URL: https://liquidium.fi/docs/technical Markdown URL: https://liquidium.fi/docs/technical/index.md ![Quid teach](https://liquidium.fi/api/quid-assets/file/quid%20teach.svg) ## Protocol Overview Liquidium is a **cross-chain lending and borrowing protocol** built on the Internet Computer (IC). It enables users to supply and borrow native blockchain assets (BTC, ICP, ETH, USDT) without holding wrapped tokens from the user's perspective. ### Key Technical Features - **Non-custodial Design**: Assets managed by decentralized canister vaults - **Share-Based Accounting**: Efficient interest accrual without per-user computation - **Dynamic Interest Rates**: Aave-style kink model based on pool utilization - **Two-Phase Execution**: Atomic state updates with reliable async operations - **Subaccount Architecture**: Privacy-preserving deposit and withdrawal flows ### System Architecture The protocol consists of three primary canisters working together: ```mermaid graph TB subgraph Users["Users"] UserBTC[Bitcoin Wallet] UserETH[Ethereum Wallet] end subgraph Liquidium["Liquidium Canisters"] Lending[Lending Canister] BTCPool[BTC Pool] ERCPool[ERC Pool] Lending <-->|Events| BTCPool Lending <-->|Events| ERCPool end subgraph ChainKey["Chain Key Infrastructure"] ckBTC[ckBTC Minter] ckETH[ckETH Minter] end UserBTC -->|Deposit BTC| ckBTC UserETH -->|Deposit ETH/ERC20| ckETH BTCPool <--> ckBTC ERCPool <--> ckETH ``` | Canister | Responsibility | | --- | --- | | **Lending Canister** | Protocol orchestrator - manages accounts, positions, health factors, and coordinates pools | | **BTC Pool** | Bitcoin liquidity - handles ckBTC deposits, withdrawals, and boosted batching | | **ERC Pool** | Ethereum asset liquidity - manages ckETH/ckUSDT with gas fee fronting | > [!TIP] > For the complete implementation details and code references, see the [Architecture Documentation](https://github.com/AegisFinance/liquidium-cross-chain-app/blob/main/LargeTechExplainer.md) on GitHub. --- --- title: "Technical Concepts" description: "Fundamental mechanics that power the Liquidium protocol" canonical: "https://liquidium.fi/docs/technical/concepts" markdown: "https://liquidium.fi/docs/technical/concepts/index.md" breadcrumbs: "Docs > Technical Documentation > Technical Concepts" updated: "2026-04-08T11:45:37.287Z" --- # Technical Concepts Fundamental mechanics that power the Liquidium protocol Canonical URL: https://liquidium.fi/docs/technical/concepts Markdown URL: https://liquidium.fi/docs/technical/concepts/index.md - [Interest Rate Model](https://liquidium.fi/docs/technical/concepts/interest-rates) - [Share-Based Accounting](https://liquidium.fi/docs/technical/concepts/share-accounting) - [Health Factor](https://liquidium.fi/docs/technical/concepts/health-factor) - [Liquidations](https://liquidium.fi/docs/technical/concepts/liquidations) ## Overview Liquidium implements a lending protocol similar to Aave, with adaptations for the Internet Computer's unique execution model. The technical concepts include: ### Interest Rates The protocol uses a **two-slope kink model** where interest rates increase gradually until an optimal utilization point, then accelerate sharply. This incentivizes maintaining healthy pool liquidity. ### Share-Based Accounting Instead of tracking individual user balances, the protocol uses **shares and indices**. Users hold shares that represent their proportion of the pool. Global indices grow over time to reflect accrued interest, making balance calculation as simple as `balance = shares × index`. ### Health Factor Every borrowing position has a **health factor** that measures its safety. When collateral value drops relative to debt (health factor < 1.0), the position becomes eligible for liquidation. ### Liquidations External liquidators can repay a portion of underwater positions and receive the borrower's collateral at a discount. This mechanism ensures the protocol remains solvent even during market volatility. --- --- title: "Interest Rate Model" description: "How borrow and supply rates are calculated using the two-slope kink model" canonical: "https://liquidium.fi/docs/technical/concepts/interest-rates" markdown: "https://liquidium.fi/docs/technical/concepts/interest-rates/index.md" breadcrumbs: "Docs > Technical Documentation > Technical Concepts > Interest Rate Model" updated: "2026-04-08T12:11:25.179Z" --- # Interest Rate Model How borrow and supply rates are calculated using the two-slope kink model Canonical URL: https://liquidium.fi/docs/technical/concepts/interest-rates Markdown URL: https://liquidium.fi/docs/technical/concepts/interest-rates/index.md ## Utilization Rate The utilization rate measures what percentage of supplied assets are currently borrowed: ```plaintext utilization = total_debt / total_supply ``` - **Low utilization** (e.g., 20%): Plenty of liquidity available, lower rates to encourage borrowing - **High utilization** (e.g., 95%): Most funds borrowed, higher rates to encourage repayment ## The Kink Model Interest rates follow a two-slope curve with a "kink" at the optimal utilization point: ```mermaid graph LR subgraph RateCurve["Interest Rate Curve"] A[0%] -->|Slope 1| B[Optimal 92%] B -->|Slope 2 Steep| C[100%] end ``` ### Below Optimal Utilization When utilization is below the optimal point (e.g., 92%), rates grow gradually: ```plaintext borrow_rate = base_rate + (utilization / optimal) × slope_1 ``` ### Above Optimal Utilization When utilization exceeds the optimal point, rates accelerate sharply to incentivize repayments and new deposits: ```plaintext borrow_rate = base_rate + slope_1 + ((utilization - optimal) / (1 - optimal)) × slope_2 ``` ## Example Configuration A typical pool configuration might look like: | Parameter | Value | Description | | --- | --- | --- | | Base Rate | 2% | Minimum APY even at 0% utilization | | Optimal Utilization | 92% | The "kink" point | | Slope 1 | 7% | Linear APR increase from 0% to optimal utilization | | Slope 2 | 300% | Linear APR increase from optimal utilization to 100% utilization | | Reserve Factor | 10% | Protocol share of interest, configurable per pool (e.g., 10%) | ### Rate Calculations **At 50% utilization:** ```plaintext borrow_rate = 2% + (50/92) × 7% = 5.8% APY ``` **At 92% utilization (kink point):** ```plaintext borrow_rate = 2% + 7% = 9% APY ``` **At 98% utilization:** ```plaintext borrow_rate = 2% + 7% + (6/8) × 300% = 234% APY ``` The steep slope above optimal utilization creates strong pressure to repay loans or add supply when liquidity becomes scarce. ## Supply Rate Suppliers earn a portion of the interest paid by borrowers: ```plaintext supply_rate = borrow_rate × utilization × (1 - reserve_factor) ``` **Example at 80% utilization:** ```plaintext borrow_rate = 10% utilization = 80% reserve_factor = 10% supply_rate = 10% × 0.8 × 0.9 = 7.2% APY ``` ### Why the Difference? - **Utilization factor**: Only borrowed funds generate interest - **Reserve factor**: Protocol share of interest, configurable per pool (e.g., 10%) - **Net to suppliers**: Portion of borrower interest distributed to suppliers (e.g., 90%) ## Index-Based Accrual Rather than updating every user's balance continuously, the protocol uses **indices** that grow over time: ```mermaid sequenceDiagram participant Pool participant Index as Borrow Index Note over Pool: Time passes... Pool->>Index: Calculate rate Index->>Index: index *= (1 + rate)^time Note over Index: All debt grows automatically ``` ### Borrow Index (Compounded) ```plaintext new_borrow_index = old_borrow_index × (1 + borrow_rate / YEAR_SECS)^elapsed_seconds ``` ### Lending Index (Linear) ```plaintext new_lending_index = old_lending_index × (1 + lending_rate × elapsed_seconds / YEAR_SECS) ``` > [!TIP] > The index approach means interest accrues in O(1) time regardless of how many users are in the pool. User balances are calculated on-demand as `balance = shares × index`. ## Protocol Revenue The difference between what borrowers pay and what suppliers earn becomes protocol revenue: ```plaintext protocol_revenue = debt_interest - supply_interest ``` This revenue is captured as **treasury shares** that can be claimed by protocol governance. --- --- title: "Share-Based Accounting" description: "How positions track balances efficiently using shares and indices" canonical: "https://liquidium.fi/docs/technical/concepts/share-accounting" markdown: "https://liquidium.fi/docs/technical/concepts/share-accounting/index.md" breadcrumbs: "Docs > Technical Documentation > Technical Concepts > Share-Based Accounting" updated: "2026-04-08T12:11:28.304Z" --- # Share-Based Accounting How positions track balances efficiently using shares and indices Canonical URL: https://liquidium.fi/docs/technical/concepts/share-accounting Markdown URL: https://liquidium.fi/docs/technical/concepts/share-accounting/index.md ## Why Shares? Traditional balance tracking has problems at scale - updating every user's balance on every interest accrual is O(n) complexity and causes rounding errors to accumulate differently per user. Share-based accounting solves this by updating a single global index (O(1) complexity), and deriving user balances on-demand by multiplying their shares by the current index. All users share the same index, eliminating drift. ## Core Data Model ### Position Structure Each user position stores **shares**, not native balances: - `deposit_scaled` - supply shares - `debt_scaled` - debt shares Native balances are derived: - `deposit_native = deposit_scaled × lending_index` - `debt_native = debt_scaled × borrow_index` ### Pool Indices Each pool maintains two indices that grow over time: - `lending_index` - cumulative supply growth (starts at 1.0) - `borrow_index` - cumulative debt growth (starts at 1.0) - `last_updated` - timestamp of last sync ## Balance Calculation ```mermaid graph LR Shares[Shares - Stored] --> Index[Index - Growth Factor] Index --> Balance[Native Balance - Derived] ``` **Supply balance:** `deposit_native = deposit_scaled × lending_index` **Debt balance:** `debt_native = debt_scaled × borrow_index` ## Share Operations ### Minting Shares (Deposit/Borrow) When a user deposits or borrows, shares are minted based on the current index: `shares = native_amount / index` **Example Deposit:** User deposits 100 tokens at lending\_index = 1.05 → shares\_minted = 100 / 1.05 = 95.24 shares ### Burning Shares (Withdraw/Repay) When a user withdraws or repays, shares are burned: **Example Withdraw:** User withdraws after index grows to 1.10 → shares\_burned = 95.24 shares → native\_received = 95.24 × 1.10 = 104.76 tokens (earned 4.76 tokens interest) ## Interest Accrual Example **Initial State (t=0):** - lending\_index = 1.0, borrow\_index = 1.0 - Alice deposits 1000 tokens → 1000 shares - Bob borrows 500 tokens → 500 debt shares **After 1 Year:** - Pool utilization = 50% - Borrow rate = 5.125%, Lending rate = 2.306% - New indices: borrow\_index = 1.0526, lending\_index = 1.0231 **Balances:** - Alice: 1000 shares × 1.0231 = 1023.1 tokens (+2.31% APY) - Bob: 500 shares × 1.0526 = 526.3 tokens debt (+5.26% APY) - Interest gap: 26.3 - 23.1 = 3.2 tokens (protocol revenue) ## RAY Precision All index calculations use **RAY precision** (1e27) to maintain accuracy. This matches Aave's implementation and provides enough precision for tokens with up to 9 decimals plus 18 digits of buffer. > [!TIP] > RAY precision (1e27) prevents rounding errors from accumulating over time, ensuring fair interest distribution across all users. ## Index Synchronization Before any operation, the pool's indices must be synchronized to the current time: ```mermaid sequenceDiagram participant User participant Protocol participant Pool User->>Protocol: deposit/withdraw/borrow/repay Protocol->>Pool: sync_pool(pool_id) Pool->>Pool: Calculate elapsed time Pool->>Pool: Update borrow_index Pool->>Pool: Update lending_index Pool->>Pool: Mint treasury shares Pool-->>Protocol: Synced Protocol->>Protocol: Execute operation ``` This ensures all operations use up-to-date indices for accurate share calculations. ## Key Invariants 1. **Indices never decrease** - they only grow (monotonic) 2. **Shares only change on user actions** - deposit/withdraw/borrow/repay/liquidate 3. **Protocol revenue = debt interest - supply interest** 4. **All calculations use RAY precision** (1e27) --- --- title: "Health Factor" description: "How position safety is measured and liquidation thresholds work" canonical: "https://liquidium.fi/docs/technical/concepts/health-factor" markdown: "https://liquidium.fi/docs/technical/concepts/health-factor/index.md" breadcrumbs: "Docs > Technical Documentation > Technical Concepts > Health Factor" updated: "2026-06-30T14:58:13.747Z" --- # Health Factor How position safety is measured and liquidation thresholds work Canonical URL: https://liquidium.fi/docs/technical/concepts/health-factor Markdown URL: https://liquidium.fi/docs/technical/concepts/health-factor/index.md ## Formula ```plaintext health_factor = (Σ collateral_value_usd × liquidation_threshold) / total_debt_value_usd ``` ### Interpretation | Health Factor | Status | Action | | --- | --- | --- | | ≥ 1.0 | Safe | Position is healthy | | < 1.0 | Liquidatable | Can be liquidated | | No debt | Infinite | No risk | > [!TIP] > In the UI, health factor is displayed as a percentage where 100% = no debt, closer to 0% = higher liquidation risk, and 0% indicates liquidation. ## Current Pool Parameters Each pool has its own Max LTV, liquidation threshold, and liquidation bonus. Max LTV is the highest LTV allowed when opening or increasing a position. The liquidation threshold is the LTV where the position becomes liquidatable. | Asset | Max LTV\* | Liquidation threshold\* | Liquidation bonus\* | | --- | --- | --- | --- | | BTC | 65% | 74% | 5% | | ETH | 65% | 74% | 5% | | USDC | 65% | 74% | 5% | | USDT | 65% | 74% | 5% | | ICP | 50% | 70% | 7.5% | \*These values are current examples. Always check the live [Insights page](https://app.liquidium.fi/insights) before opening or adjusting a position, because pool parameters can change. The table above is informational. The app's live Insights page is the source of truth at transaction time. ## Weighted Average Threshold When a user has collateral across multiple pools, the weighted average liquidation threshold determines overall borrowing capacity: ```plaintext weighted_threshold = Σ (position_collateral_usd × pool_threshold) / total_collateral_usd ``` ## Example ```plaintext User has: - $10,000 in BTC (LT = 74%) - $5,000 in ICP (LT = 70%) Total collateral: $15,000 Weighted threshold: (10000 × 0.74 + 5000 × 0.70) / 15000 = 0.7267 (72.67%) ``` ## Health Factor Calculation Using the weighted threshold: ```plaintext health_factor = (total_collateral × weighted_threshold) / total_debt ``` ## Example ```plaintext User has: - $15,000 collateral (weighted threshold = 72.67%) - $6,000 debt Health factor: (15000 × 0.7267) / 6000 = 1.82 Status: Safe (HF > 1.0) ``` ## Health Factor Calculation Using the weighted threshold: ```plaintext health_factor = (total_collateral × weighted_threshold) / total_debt ``` ### Example ```plaintext User has: - $15,000 collateral (weighted threshold = 81.67%) - $6,000 debt Health factor: (15000 × 0.8167) / 6000 = 2.04 Status: Safe (HF > 1.0) ``` ## Health Factor vs Health Factor Percentage The protocol uses two representations of position safety: - **Health Factor (HF)**: Traditional decimal format (e.g., 2.04, 1.33, 0.96). Values above 1.0 are safe, below 1.0 are liquidatable. - **Health Factor Percentage (HF%)**: Percentage format displayed in the UI (e.g., 51%, 80%, 0%). 100% = no debt, 0% = liquidatable. Users can toggle between these formats in General Settings based on their preference. ### Quick conversion table Liquidium can show position safety as decimal Health Factor, Health %, or LTV. The app defaults to Health %, while technical examples may use decimal Health Factor. | Decimal Health Factor | App Health % | Example LTV at 74% liquidation threshold | Meaning | | --- | --- | --- | --- | | No debt | 100% | 0.0% | No active borrow | | 5.0 | 80.0% | 14.8% | Very large buffer | | 3.0 | 66.7% | 24.7% | Large buffer | | 2.0 | 50.0% | 37.0% | Healthy buffer | | 1.5 | 33.3% | 49.3% | Moderate buffer | | 1.2 | 16.7% | 61.7% | Low buffer | | 1.0 | 0.0% | 74.0% | Liquidation threshold | Formula: - `Health % = max(0, (Health Factor - 1) / Health Factor * 100)` - `LTV = liquidation threshold * (1 - Health % / 100)` The LTV column uses a 74% liquidation threshold as an example. Always check the Insights page for current asset-specific Max LTV and liquidation threshold values before borrowing. ## Health Factor States ```mermaid stateDiagram-v2 [*] --> Healthy Healthy --> Warning: HF drops below 1.2 Warning --> Healthy: Add collateral or repay Warning --> Liquidatable: HF drops below 1.0 Liquidatable --> PartialLiquidation: HF >= 0.95 Liquidatable --> FullLiquidation: HF < 0.95 PartialLiquidation --> PositionRebalanced: After liquidation FullLiquidation --> [*]: Position closed ``` ### State Descriptions | State | Health Factor | What Happens | | --- | --- | --- | | **Healthy** | > 1.2 | Normal operation | | **Warning** | 1.0 - 1.2 | Warning zone, consider adding collateral | | **Liquidatable** | < 1.0 | External liquidators can act | | **Partial Liquidation** | 0.95 - 1.0 | Up to 50% of debt can be repaid | | **Full Liquidation** | < 0.95 | Up to 100% of debt can be repaid | ## What Affects Health Factor ### Decreases Health Factor (More Risk) - Borrowing more assets - Withdrawing collateral - Collateral price dropping - Debt accruing interest - Collateral asset price falling relative to debt asset ### Increases Health Factor (Less Risk) - Repaying debt - Adding more collateral - Collateral price increasing - Debt asset price falling relative to collateral ## Practical Example **Starting position:** ```plaintext Collateral: 1 BTC @ $50,000 = $50,000 (LT = 74%) Debt: $27,000 USDC Health Factor: (50000 × 0.74) / 27000 = 1.37 ✓ Safe ``` **After BTC drops 20%:** ```plaintext Collateral: 1 BTC @ $40,000 = $40,000 Debt: $27,000 USDC Health Factor: (40000 × 0.74) / 27000 = 1.10 ⚠️ At Risk ``` **After BTC drops another 10%:** ```plaintext Collateral: 1 BTC @ $36,000 = $36,000 Debt: $27,000 USDC Health Factor: (36000 × 0.74) / 27000 = 0.99 🔴 Liquidatable ``` Monitor your health factor regularly, especially during volatile market conditions. Maintaining a higher health factor provides a larger safety buffer against liquidation. ## Price Oracle Integration Health factor calculations rely on accurate price data from the **price oracle**: - Prices are fetched from multiple sources - 60-second cache to prevent manipulation - Deviation alerts for unusual price movements The protocol uses USD-denominated prices to calculate collateral and debt values across different assets. --- --- title: "Liquidations" description: "How liquidations protect the protocol and its users" canonical: "https://liquidium.fi/docs/technical/concepts/liquidations" markdown: "https://liquidium.fi/docs/technical/concepts/liquidations/index.md" breadcrumbs: "Docs > Technical Documentation > Technical Concepts > Liquidations" updated: "2026-07-19T18:59:25.047Z" --- # Liquidations How liquidations protect the protocol and its users Canonical URL: https://liquidium.fi/docs/technical/concepts/liquidations Markdown URL: https://liquidium.fi/docs/technical/concepts/liquidations/index.md ## Liquidation Eligibility A position becomes liquidatable when: ```plaintext health_factor < 1.0 ``` This means the risk-adjusted collateral value no longer covers the debt. For the borrower-facing safety display, Liquidium may show position safety as Health %, while technical examples often use decimal Health Factor. See the [Health Factor guide](https://liquidium.fi/docs/technical/concepts/health-factor) for the Health Factor to Health % conversion table and calculation. ## Close Factor The **close factor** determines how much of a position can be liquidated in a single transaction: | Health Factor | Close Factor | Meaning | | --- | --- | --- | | 0.95 - 1.0 | 50% | Partial liquidation | | < 0.95 | 100% | Full liquidation allowed | Partial liquidation gives borrowers a chance to recover their position before complete closure. ## Liquidation Bonus Liquidators receive a bonus as incentive to maintain protocol health: | Asset | Liquidation Bonus | | --- | --- | | BTC | 5%\* | | ETH | 5%\* | | USDC | 5%\* | | USDT | 5%\* | | ICP | 7.5%\* | *Live liquidation bonuses can change. Check the [live Markets page](https://app.liquidium.fi/insights) for current asset-specific liquidation bonuses, liquidation thresholds, and Max LTV values.* The bonus is paid in collateral tokens, meaning liquidators receive more collateral than the debt they repay. ## Liquidation Math ### Collateral Calculation ```plaintext max_repay_amount = position.debt × close_factor repay_value_usd = repay_amount × debt_asset_price bonus_value_usd = repay_value_usd × liquidation_bonus seized_value_usd = repay_value_usd + bonus_value_usd seized_collateral = seized_value_usd / collateral_asset_price ``` ### Protocol Fee The protocol takes a small fee from liquidations: ```plaintext protocol_fee = seized_collateral × protocol_liquidation_fee (e.g., 2%) liquidator_receives = seized_collateral - protocol_fee ``` ## Example Liquidation **Underwater Position:** ```plaintext Borrower: Collateral: 1 BTC @ $50,000 (LT = 74%) Debt: $38,000 USDC Health Factor: (50000 × 0.74) / 38000 = 0.974 (liquidatable) ``` **Liquidator Action:** ```plaintext Close factor: 50% (HF > 0.95) Max repay: $38,000 × 50% = $19,000 USDC Liquidation bonus: 5% Bonus value: $19,000 × 0.05 = $950 Total seized value: $19,000 + $950 = $19,950 Seized BTC: $19,950 / $50,000 = 0.399 BTC Protocol fee (2%): 0.399 × 0.02 = 0.008 BTC Liquidator receives: 0.399 - 0.008 = 0.391 BTC ``` **Result:** ```plaintext Borrower after liquidation: Collateral: 1 - 0.399 = 0.601 BTC Debt: $38,000 - $19,000 = $19,000 USDC New HF: (0.601 × 50000 × 0.74) / 19000 = 1.17 ✓ Safe Liquidator profit: Paid: $19,000 USDC Received: 0.391 BTC = $19,550 Profit: $550 (2.9%) Protocol: Earned: 0.008 BTC = $400 (treasury shares) ``` ## Liquidation Flow 1. The liquidator calls `scan_at_risk_positions` to find eligible positions. 2. The liquidator submits `liquidate` or `liquidate_with_slippage` with a `LiquidationRequest`. 3. The Lending Canister validates the position's Health Factor and calculates the close factor, seized collateral, liquidation bonus, and protocol fee. 4. The protocol atomically updates the borrower's debt and collateral shares and records the liquidation. 5. The debt asset is collected from the liquidator and the seized collateral is sent to the requested receiver principal. ## Atomic State Updates Liquidations update state atomically before any async operations: 1. **Burn borrower's debt shares** - Reduces their debt 2. **Burn borrower's collateral shares** - Seizes collateral 3. **Mint treasury shares** - Protocol fee captured 4. **Record liquidation event** - Audit trail The actual asset transfers (debt repayment, collateral delivery) happen asynchronously via the WAL system. > [!TIP] > Learn more about Write Ahead Logging [here](https://liquidium.fi/docs/technical/security/atomicity). ## Finding Liquidatable Positions The production Lending Canister is: ```plaintext hyk4r-jqaaa-aaaar-qb4ca-cai ``` Use the cursor-based query to find eligible positions: ```plaintext scan_at_risk_positions( cursor: opt principal, scan_limit: nat64, max_results: nat64 ) -> ScanResult ``` Results include the borrower principal, Health Factor, weighted liquidation threshold, pool positions, and total debt. The legacy offset-based query remains available: ```plaintext get_at_risk_positions( offset: nat64, limit: nat64 ) -> vec LiquidatableUser ``` ## Liquidator Requirements To execute a liquidation, the liquidator must: - Have sufficient debt asset to repay the borrowed amount - Call the Lending Canister using their IC principal - Specify the borrower, debt pool, collateral pool, and debt amount - Provide the principal that should receive the collateral Liquidations are publicly callable in production. You do not need to register or have your principal added to an allowlist before submitting a liquidation. The available execution methods are: ```plaintext liquidate(request: LiquidationRequest) liquidate_with_slippage( request: LiquidationRequest, min_collateral_amount: nat ) ``` `liquidate_with_slippage` protects against receiving less than the specified minimum gross collateral amount. > Liquidations are competitive. Successful liquidators typically run automated bots that monitor positions and execute quickly when opportunities arise. > Liquidation execution is separate from the Liquidium SDK. The SDK does not currently provide a liquidation-execution helper. ## Economic Security The liquidation mechanism provides several security guarantees: | Feature | Purpose | | --- | --- | | **Overcollateralization** | Positions start with buffer above liquidation threshold | | **Liquidation bonus** | Incentivizes quick liquidation before bad debt | | **Protocol fee** | Builds treasury for unexpected losses | | **Close factor** | Allows partial recovery for borrowers | | **Price oracles** | Accurate valuations for fair liquidations | --- --- title: "Architecture" description: "Deep dive into the canister architecture and system design" canonical: "https://liquidium.fi/docs/technical/architecture" markdown: "https://liquidium.fi/docs/technical/architecture/index.md" breadcrumbs: "Docs > Technical Documentation > Architecture" updated: "2026-06-22T05:09:05.013Z" --- # Architecture Deep dive into the canister architecture and system design Canonical URL: https://liquidium.fi/docs/technical/architecture Markdown URL: https://liquidium.fi/docs/technical/architecture/index.md - [Lending Canister](https://liquidium.fi/docs/technical/architecture/lending-canister) - [BTC Pool](https://liquidium.fi/docs/technical/architecture/btc-pool) - [ERC Pool](https://liquidium.fi/docs/technical/architecture/erc-pool) - [ICP Pool](https://liquidium.fi/docs/technical/architecture/icp-pool) - [Cross-Chain Flow](https://liquidium.fi/docs/technical/architecture/cross-chain) ## System Overview ```mermaid graph TB subgraph Users["Users"] BTC[Bitcoin Wallet] ETH[Ethereum Wallet] ICP[ICP Account] Liquidator[Liquidator Bot] end subgraph Liquidium["Liquidium Canisters"] Lending[Lending Canister] BTCPool[BTC Pool] ERCPool[ERC Pool] ICPPool[ICP Pool] Lending <-->|Events| BTCPool Lending <-->|Events| ERCPool Lending <-->|Events| ICPPool end subgraph ChainKey["Chain Key"] ckBTCMinter[ckBTC Minter] ckETHMinter[ckETH Minter] ICPLedger[ICP Ledger] end subgraph External["External"] PriceOracle[Price Oracle] DEX[DEX] end BTC -->|Deposit| ckBTCMinter ETH -->|Deposit| ckETHMinter ICP -->|Deposit| ICPLedger BTCPool <--> ckBTCMinter ERCPool <--> ckETHMinter ICPPool <--> ICPLedger Lending --> PriceOracle PriceOracle -->|Prices| Lending ERCPool --> DEX Liquidator --> Lending ``` ## Design Principles ### 1. Separation of Concerns | Canister | Responsibility | | --- | --- | | Lending | Protocol logic (shares, health factor, liquidation) | | Pool | Asset custody (ckAsset operations, blockchain integration) | This separation allows: - Adding new assets without changing lending logic - Asset-specific optimizations (BTC boosting, ERC fee fronting) - Independent upgrades and auditing ### 2. Dual-Phase Execution All critical operations follow a two-phase pattern: Phase 1: Synchronous (Atomic) - Validate request - Update state - Check invariants Phase 2: Asynchronous (WAL-backed) - Execute inter-canister calls - Retry on failure - Idempotent handlers ### 3. Event-Driven Communication Pools notify the lending canister of state changes via events: | Event | Trigger | Action | | --- | --- | --- | | DepositConfirmed | User deposit detected | Mint supply shares | | RepaymentConfirmed | Debt repayment detected | Burn debt shares | | WithdrawalConfirmed | Withdrawal completed | Update records | | BorrowConfirmed | Borrow executed | Update records | ### 4. Subaccount Architecture Each pool uses deterministic subaccounts for user isolation: | Subaccount Type | Purpose | | --- | --- | | Inflow | For deposits and repayments (derived from principal + pool type) | | Outflow | For withdrawals and borrows (derived from address + index) | | BOOST\_SUBACCOUNT | Small BTC withdrawal batching | | FEE\_SUBACCOUNT | ETH gas fee management | ## Communication Patterns | From | To | Method | Purpose | | --- | --- | --- | --- | | User | Lending | borrow\_assets() | Request loan | | User | Lending | withdraw() | Withdraw collateral | | Lending | Pool | withdraw() | Execute withdrawal | | Pool | Lending | notify\_pool\_event() | Deposit/repayment confirmed | | Pool | ckMinter | retrieve\_btc() | Burn ck tokens | | Lending | Price Oracle | Price query | Fetch prices | | ERC Pool | DEX | Token swap | Convert fees to ckETH | ## Trust Boundaries ```mermaid graph LR subgraph Untrusted["Untrusted"] User[User] External[External Chains] end subgraph Trusted["Trusted - IC"] Lending[Lending] Pools[Pools] ChainKey[Chain Key] PriceOracle[Oracle] end User -->|Signed| Lending Lending <-->|IC| Pools Pools <-->|ICRC| ChainKey ChainKey <-->|Cross-Chain| External PriceOracle -->|Prices| Lending ``` ### Boundary Protections | Boundary | Attack Vector | Mitigation | | --- | --- | --- | | User → Lending | Signature forgery | Native-chain signature verification | | User → Lending | Replay attacks | Nonce-based protection | | Lending → Pool | Unauthorized withdrawals | Caller validation | | Pool → ckMinter | Invalid burn amounts | Pre-flight validation | | Oracle → Lending | Price manipulation | Caching, deviation alerts | --- --- title: "Lending Canister" description: "Technical overview of the Liquidium Lending Canister, including authentication, position accounting, pool coordination, events, prices, and liquidations." canonical: "https://liquidium.fi/docs/technical/architecture/lending-canister" markdown: "https://liquidium.fi/docs/technical/architecture/lending-canister/index.md" breadcrumbs: "Docs > Technical Documentation > Architecture > Lending Canister" updated: "2026-08-19T11:17:04.909Z" --- # Lending Canister Technical overview of the Liquidium Lending Canister, including authentication, position accounting, pool coordination, events, prices, and liquidations. Canonical URL: https://liquidium.fi/docs/technical/architecture/lending-canister Markdown URL: https://liquidium.fi/docs/technical/architecture/lending-canister/index.md ## Responsibilities - **Account Management:** Internet Identity and supported multi-chain wallet authentication with profile linking - **Position Tracking:** User collateral and debt positions using share-based accounting - **Interest Accrual:** Calculating and applying interest via global indices - **Health Enforcement:** Validating health factors before operations - **Pool Coordination:** Orchestrating deposits, withdrawals, borrows, and repayments - **Price Integration:** Fetching and caching asset prices from oracles - **Liquidation API:** Exposing interfaces for external liquidator bots ## Production canister The production Lending Canister is: ```plaintext hyk4r-jqaaa-aaaar-qb4ca-cai ``` ## Architecture ```mermaid graph TB subgraph Interface["User Interface Layer"] Auth[Authentication] AccountAPI[Account Management] LendingAPI[Lending Operations] QueryAPI[Query Methods] LiquidationAPI[Liquidation Interface] end subgraph Core["Core Protocol Logic"] Protocol[Protocol Engine] Position[Share Accounting] InterestModel[Interest Rate Model] HealthCalc[Health Factor Calculator] LiquidationLogic[Liquidation Math] end subgraph Controllers["Controllers"] PoolController[Pool Controller] PriceController[Price Controller] EventHandler[Event Handler] end subgraph Storage["Stable Storage"] Accounts[(Accounts)] Pools[(Pool Registry)] Positions[(Positions)] PriceCache[(Price Cache)] end Interface --> Core Core --> Controllers Controllers --> Storage ``` ## Account Management ### Authentication Paths Users can sign in with Internet Identity or authenticate with a supported blockchain wallet. The sequence below documents the wallet-signature path: ```mermaid sequenceDiagram actor User participant Wallet participant Lending User->>Lending: initialize_account(chain, address) Lending-->>User: Challenge message with nonce User->>Wallet: Sign message Wallet-->>User: Signature User->>Lending: SignedRequest(data, signature) alt Bitcoin Lending->>Lending: Verify BIP322 signature else Ethereum Lending->>Lending: Verify EIP-191 signature else Solana Lending->>Lending: Verify Ed25519 signature end Lending->>Lending: Derive Principal from wallet Lending->>Lending: Create account mapping Lending-->>User: Principal ID ``` ### Wallet Abstraction For wallet-authenticated profiles, a wallet is represented as a (Chain, Address) tuple—for example (Bitcoin, "bc1q...") or (Ethereum, "0x..."). The sequence above shows how ownership of that address is verified before it can control the profile. Internet Identity authenticates the user through an Internet Computer delegation and principal; it does not use the wallet-signature flow shown above. Benefits: - Use Internet Identity or existing supported wallets - Strong cryptographic identity - Multi-wallet support per profile - Unified positions across wallets ### Internet Identity and ICP wallets Internet Identity is an authentication method, not a native ICP wallet connection. Supported ICP assets and ckAssets can still use compatible address-based flows where required by the selected operation. ## Position Management Each user's position in a pool is tracked using shares: | Field | Description | | --- | --- | | `user_profile` | Principal of the user | | `pool_id` | Pool canister ID | | `asset` | Asset type (BTC, ETH, USDC, etc.) | | `deposit_scaled` | Supply shares | | `debt_scaled` | Debt shares | | `lending_index_snapshot` | Index at last update | | `borrow_index_snapshot` | Index at last update | ### Core Operations All operations follow the same pattern: 1. Sync pool indices to current time 2. Validate preconditions (caps, liquidity) 3. Update shares (mint or burn) 4. Validate postconditions (health factor) 5. Schedule async execution if needed | Operation | Share Action | Health Check | | --- | --- | --- | | Deposit | Mint supply shares | No (improves health) | | Withdraw | Burn supply shares | Yes (must stay healthy) | | Borrow | Mint debt shares | Yes (must stay healthy) | | Repay | Burn debt shares | No (improves health) | ## Pool Registry The lending canister maintains a registry of all pools with their configuration: | Category | Fields | | --- | --- | | **Identity** | Principal, asset, chain | | **Caps** | Supply cap, borrow cap | | **Share Totals** | Total supply, total debt, treasury shares | | **Interest Rates** | Base rate, slope before, slope after, optimal utilization | | **Indices** | Borrow index, lending index | | **Risk Parameters** | Reserve factor, liquidation threshold, liquidation bonus | ## Event Handling The lending canister receives events from pool canisters via `notify_pool_event()`. Events include: - `DepositConfirmed` - triggers supply share minting - `RepaymentConfirmed` - triggers debt share burning Each event includes a ledger transaction ID for idempotency - if the same transaction ID is processed twice, the duplicate is ignored. ## Background Tasks | Task | Interval | Purpose | | --- | --- | --- | | `sync_pools` | 600s | Update pool indices | | `update_prices` | 300s | Refresh price cache | | `process_wal_ops` | 15s | Execute pending operations | ## Price Integration Prices are fetched from the price oracle and cached with a 60-second expiry. The cache prevents price manipulation attacks and reduces request overhead. --- --- title: "BTC Pool Canister" description: "Bitcoin liquidity custody with boosted withdrawals and UTXO management" canonical: "https://liquidium.fi/docs/technical/architecture/btc-pool" markdown: "https://liquidium.fi/docs/technical/architecture/btc-pool/index.md" breadcrumbs: "Docs > Technical Documentation > Architecture > BTC Pool Canister" updated: "2026-04-08T12:11:18.523Z" --- # BTC Pool Canister Bitcoin liquidity custody with boosted withdrawals and UTXO management Canonical URL: https://liquidium.fi/docs/technical/architecture/btc-pool Markdown URL: https://liquidium.fi/docs/technical/architecture/btc-pool/index.md ## Responsibilities - **Accept ckBTC deposits** from users - **Process withdrawals** (converting ckBTC → BTC) - **Handle borrow requests** from the lending canister - **Optimize fees** via withdrawal batching for small amounts - **Manage UTXOs** for the pool's Bitcoin address ## Architecture ```mermaid graph TB subgraph BTCPool["BTC Pool Canister"] API[Public API] subgraph Core["Core Logic"] PoolLogic[Pool Logic] Dispatcher[Operation Scheduler] end subgraph Withdrawal["Withdrawal Systems"] Standard[Standard Processor] Boosted[Boosted Processor] end subgraph Storage["Stable Storage"] Metadata[(Pool Metadata)] Events[(Event Queue)] Treasury[(Treasury)] Subaccounts[(Subaccount Maps)] Boosts[(Boost Queues)] end subgraph Timers["Background Tasks"] CheckInflows[Check Inflows] ProcessTreasury[Process Treasury] SendEvents[Send Events] ProcessBoosts[Batch Boosts] end end API --> PoolLogic PoolLogic --> Dispatcher PoolLogic --> Standard PoolLogic --> Boosted ``` ## Subaccount Architecture The pool uses deterministic subaccount derivation for user isolation: ### Subaccount Types | Type | Prefix | Purpose | | --- | --- | --- | | Inflow Deposit | `0x1` | User deposits | | Inflow Repay | `0x2` | Debt repayments | | Mapped Outflow | `0x3` | Direct address withdrawals | | Native Outflow | `0x5` | IC Principal transfers | | Boost | Internal | Small withdrawal batching | ### Inflow Subaccounts For deposits and repayments, subaccounts are derived from the user's principal: ```plaintext [prefix, 0x0, length, ...principal_bytes..., ...padding] byte 0 byte 1 byte 2 bytes 3-N bytes N-31 ``` **Example - Deposit subaccount:** ```plaintext [0x1, 0x0, 0x0A, <10 principal bytes>, <19 zero bytes>] ``` ### Outflow Subaccounts (Mapped) Bitcoin addresses can be long, so they're mapped to a u128 index: ```plaintext [0x3, <15 zero bytes>, <16 bytes of u128 index>] ``` The pool maintains bidirectional mappings: - `ADDRESS_OUTFLOW_SUBACCOUNT`: address → index - `ADDRESS_OUTFLOW_SUBACCOUNT_REVERSE`: index → address ### Special Subaccounts **BOOST\_SUBACCOUNT:** ```plaintext [0x0, 0x1, <30 zero bytes>] ``` Holds ckBTC for boosted withdrawals awaiting batching. ## Two-Tier Withdrawal System ### Standard Withdrawals (>50,000 sats) Direct ckBTC burn via the minter: ```mermaid sequenceDiagram participant Pool participant Ledger as ckBTC Ledger participant Minter as ckBTC Minter participant Bitcoin Pool->>Ledger: Transfer to outflow subaccount Pool->>Ledger: Approve minter spending Pool->>Minter: retrieve_btc_with_approval() Minter->>Ledger: Burn ckBTC Minter->>Bitcoin: Send BTC to user ``` ### Boosted Withdrawals (Under 50,000 sats) **Problem:** Bitcoin transaction fees make small withdrawals uneconomical. **Solution:** Batch multiple small withdrawals into a single Bitcoin transaction. ```mermaid stateDiagram-v2 [*] --> WithdrawRequest WithdrawRequest --> CheckAmount CheckAmount --> StandardPath: More than 50k sats CheckAmount --> BoostedPath: Less than 50k sats StandardPath --> BurnCkBTC BurnCkBTC --> BTCOnChain BTCOnChain --> [*] BoostedPath --> TransferToBoost TransferToBoost --> PendingQueue PendingQueue --> BatchProcess: Timer every 5 min BatchProcess --> MultiOutputTx MultiOutputTx --> BroadcastBTC BroadcastBTC --> [*] ``` **Boosted Withdrawal Flow:** 1. Pool transfers ckBTC to `BOOST_SUBACCOUNT` 2. Withdrawal added to pending queue 3. Every 5 minutes, pending withdrawals are processed (even if there's only one) 4. Pool creates multi-output Bitcoin transaction (or single output if only one withdrawal) 5. Transaction signed using threshold ECDSA 6. Transaction broadcast to Bitcoin network 7. Pool fronts BTC immediately from its UTXOs 8. When boost balance exceeds 50k sats, accumulated ckBTC is burned **Benefits:** - Users receive BTC faster - Lower effective fees (shared across batch) - Pool recoups fronted BTC via ckBTC burn ## Inflow Detection The pool scans for new deposits and repayments every 60 seconds: ```mermaid sequenceDiagram participant Timer participant Pool participant Ledger Note over Timer: Every 60 seconds Timer->>Pool: check_for_new_subaccount_inflows() Pool->>Ledger: Get transactions since last_seen Ledger-->>Pool: New transactions loop For each transaction Pool->>Pool: Decode subaccount alt Inflow subaccount Pool->>Pool: Schedule transfer to treasury else Outflow subaccount Pool->>Pool: Schedule outflow processing end end Pool->>Pool: Update last_seen_index ``` ## Treasury Movement Detection After inflows are transferred to treasury, the pool detects and creates events: ```mermaid sequenceDiagram participant Timer participant Pool participant Ledger participant Lending Note over Timer: Every 60 seconds Timer->>Pool: process_treasury_movements() Pool->>Ledger: Get treasury transactions Ledger-->>Pool: Internal transfers loop For each transfer from subaccount Pool->>Pool: Decode source subaccount alt Deposit subaccount Pool->>Pool: Create DepositConfirmed event else Repayment subaccount Pool->>Pool: Create RepaymentConfirmed event end Pool->>Pool: Queue event end Note over Timer: Every 60 seconds Timer->>Pool: process_event_queue() Pool->>Lending: notify_pool_event() Lending-->>Pool: Ack Pool->>Pool: Remove from queue ``` ## Background Tasks | Task | Interval | Purpose | | --- | --- | --- | | `check_for_new_subaccount_inflows` | 60s | Scan for new deposits/repayments | | `process_treasury_movements` | 60s | Detect confirmed deposits, create events | | `process_event_queue` | 60s | Send notifications to lending canister | | `process_boosted_withdrawals` | 300s | Batch small withdrawals | | `check_boosted_withdrawals_status` | 60s | Monitor on-chain confirmations | | `burn_accumulated_boost_ckbtc` | 60s | Recoup fronted BTC | | `frozen_utxos_cleanup` | 12h | Remove stale UTXO locks | ## UTXO Management The pool manages UTXOs for its Bitcoin address: ### UTXO Freezing When UTXOs are used in a transaction, they're temporarily frozen to prevent double-spending: ```rust // After broadcasting transaction for input in used_inputs { FROZEN_UTXOS.insert(input.to_string(), timestamp); } ``` ### UTXO Selection For boosted withdrawals, UTXOs are selected largest-first: ```rust let mut utxos = get_available_utxos(); utxos.sort_by(|a, b| b.value.cmp(&a.value)); // largest first let (selected, fee, total) = fund_transaction(&mut tx, utxos, fee_rate); ``` ### Cleanup Frozen UTXOs are released after 12 hours if their transaction hasn't confirmed: ```rust fn frozen_utxos_cleanup() { let cutoff = now() - 12 * 3600; for (utxo, freeze_time) in FROZEN_UTXOS { if freeze_time < cutoff { FROZEN_UTXOS.remove(&utxo); } } } ``` ## Threshold ECDSA Signing Bitcoin transactions are signed using ICP's threshold ECDSA: ```rust let signature = sign_with_ecdsa(SignWithEcdsaArgument { message_hash: sighash_data, derivation_path: vec![], key_id: EcdsaKeyId { curve: EcdsaCurve::Secp256k1, name: KEY_NAME.to_string(), }, }).await; ``` This provides: - Decentralized key management - No single point of failure - Cryptographic security guarantees --- --- title: "ERC Pool Canister" description: "Ethereum asset custody with gas fee fronting and DEX integration" canonical: "https://liquidium.fi/docs/technical/architecture/erc-pool" markdown: "https://liquidium.fi/docs/technical/architecture/erc-pool/index.md" breadcrumbs: "Docs > Technical Documentation > Architecture > ERC Pool Canister" updated: "2026-04-08T12:11:21.946Z" --- # ERC Pool Canister Ethereum asset custody with gas fee fronting and DEX integration Canonical URL: https://liquidium.fi/docs/technical/architecture/erc-pool Markdown URL: https://liquidium.fi/docs/technical/architecture/erc-pool/index.md ## Responsibilities - **Manage ckERC-20 deposits** from users - **Process withdrawals** with gas fee fronting - **Convert accumulated fees** back to ckETH via DEX - **Handle multi-token support** with unified interface ## Architecture ```mermaid graph TB subgraph ERCPool["ERC Pool Canister"] API[Public API] subgraph Core["Core Logic"] PoolLogic[Pool Logic] FeeManager[Fee Manager] Dispatcher[Operation Scheduler] end subgraph Integration["External Integration"] CkIntegration[ckERC Integration] DexIntegration[DEX Integration] end subgraph Storage["Stable Storage"] Metadata[(Pool Metadata)] Events[(Event Queue)] Treasury[(Treasury)] Subaccounts[(Subaccount Maps)] end subgraph Timers["Background Tasks"] CheckInflows[Check Inflows] ProcessTreasury[Process Treasury] SendEvents[Send Events] SwapFees[Swap Fees] end end API --> PoolLogic PoolLogic --> FeeManager FeeManager --> CkIntegration FeeManager --> DexIntegration ``` ## Subaccount Architecture Similar to the BTC Pool, but with Ethereum-specific outflow encoding: ### Subaccount Types | Type | Prefix | Purpose | | --- | --- | --- | | Inflow Deposit | `0x1` | User deposits | | Inflow Repay | `0x2` | Debt repayments | | ETH Outflow | `0x4` | Ethereum address withdrawals | | Native Outflow | `0x5` | IC Principal transfers | | Fee | Internal | Gas fee management | ### Ethereum Outflow Subaccounts Ethereum addresses are exactly 20 bytes, fitting directly in the subaccount: ```plaintext [0x4, <11 zero bytes>, <20 bytes of Ethereum address>] ``` **Example for `0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb1`:** ```plaintext [0x4, 0x0, ..., 0x74, 0x2d, 0x35, 0xCc, ..., 0xbE, 0xb1] ``` ### FEE\_SUBACCOUNT ```plaintext [0x0, 0x2, <30 zero bytes>] ``` Holds: - **ckETH**: For fronting Ethereum gas fees during withdrawals - **Pool tokens** (e.g., ckUSDT): Accumulated fees from user withdrawals awaiting swap to ckETH to replenish gas reserves ## Gas Fee Fronting **Problem:** Burning ckERC-20 tokens requires paying Ethereum gas fees in ETH. **Solution:** Protocol fronts ckETH for gas, deducts equivalent amount in pool token from withdrawal. ### Fee Calculation Flow ```mermaid sequenceDiagram participant User participant Pool participant Oracle as Price Oracle participant Minter User->>Pool: withdraw(1000 ckUSDC) Pool->>Oracle: Get ETH gas price Oracle-->>Pool: ~0.001 ETH Pool->>Oracle: Get USDC/ETH price Oracle-->>Pool: 1 USDC = 0.0004 ETH Pool->>Pool: Calculate fee in USDC Note over Pool: 0.001 / 0.0004 = 2.5 USDC Pool->>Pool: Net withdrawal = 1000 - 2.5 - fees = 997.5 USDC ``` ### Withdrawal with Fee Fronting ```mermaid sequenceDiagram participant Pool participant ckETH as ckETH Ledger participant ERC as ckUSDC Ledger participant Minter as ckETH Minter participant Ethereum Pool->>ckETH: Front 0.001 ckETH from FEE_SUBACCOUNT Pool->>ERC: Transfer 997.5 ckUSDC to outflow Pool->>ERC: Transfer 2.5 ckUSDC to FEE_SUBACCOUNT Pool->>ckETH: Approve minter: 0.001 ckETH Pool->>ERC: Approve minter: 997.5 ckUSDC Pool->>Minter: withdraw_erc_20(eth_address, 997.5) Minter->>ckETH: Burn 0.001 ckETH (gas) Minter->>ERC: Burn 997.5 ckUSDC Minter->>Ethereum: Send 997.5 USDC to user ``` **Fee Flow Summary:** ```plaintext User requests: 1000 ckUSDC withdrawal Gas fee (ETH): 0.001 ckETH Gas fee (USDC): 2.5 ckUSDC Ledger fees: ~0.5 ckUSDC Net withdrawal: 997.5 ckUSDC Fee to FEE_SUBACCOUNT: 2.5 ckUSDC ckETH fronted: 0.001 ckETH ``` ## Automated Fee Recovery (KongSwap) The pool must replenish its ckETH reserves used for gas fronting. ### Fee Swap Flow ```mermaid stateDiagram-v2 [*] --> CheckBalance CheckBalance --> WaitForFees: Balance less than threshold CheckBalance --> AccumulateFees: Balance at threshold WaitForFees --> [*] AccumulateFees --> InitiateSwap InitiateSwap --> DEX: Swap ckUSDT to ckETH DEX --> ReceiveCkETH ReceiveCkETH --> ReplenishReserves ReplenishReserves --> [*] ``` ### Implementation Every 5 minutes, the pool checks if accumulated fees should be swapped: ```rust async fn swap_fee() { // Check FEE_SUBACCOUNT balance let balance = erc_ledger.balance_of(FEE_SUBACCOUNT).await; // Only swap if above threshold if balance <= min_threshold { return; } // Approve DEX erc_ledger.approve(dex, balance).await; // Execute swap dex.swap(SwapArgs { pay_token: "ckUSDT", receive_token: "ckETH", pay_amount: balance, max_slippage: slippage_tolerance, }).await; // ckETH now in FEE_SUBACCOUNT for future gas fronting } ``` ### DEX Integration | Parameter | Value | | --- | --- | | DEX | Configurable | | Swap Direction | Pool Token → ckETH | | Trigger | Balance > min\_threshold | | Interval | Every 300 seconds | | Slippage | Configurable per pool | ## Minimum Burn Amount Each pool defines a `min_burn_amount` to prevent uneconomical withdrawals: ```rust if net_withdrawal <= metadata.min_burn_amount { return Err("burn amount is too low"); } ``` This ensures: - Withdrawal value > gas fees + protocol fees - Users aren't surprised by high fee ratios - Pool doesn't process dust withdrawals ## Inflow/Outflow Detection The ERC Pool uses the same timer-based detection as the BTC Pool: | Task | Interval | Purpose | | --- | --- | --- | | `check_for_new_subaccount_inflows` | 60s | Scan for deposits/repayments | | `process_treasury_movements` | 60s | Detect confirmed deposits | | `process_event_queue` | 60s | Notify lending canister | | `swap_fees` | 300s | Convert fees to ckETH | | `sync_ledger_fee` | 15s | Update fee cache | ## Pool Metadata Each ERC Pool maintains configuration: ```rust PoolMetadata { ticker: String, // "USDC", "USDT", "ETH" decimals: u8, // Token decimals min_burn_amount: Nat, // Minimum withdrawal cketh_ledger: Principal, // ckETH ledger for gas // DEX configuration dex_swap_enabled: bool, dex_swap_ticker: String, dex_swap_min_threshold: Nat, dex_swap_slippage_tolerance: f64, } ``` ## Multi-Token Support The ERC Pool architecture supports multiple tokens with a unified interface: | Token | Ledger | Minter | Fee Token | | --- | --- | --- | --- | | ckETH | ckETH Ledger | ckETH Minter | ckETH | | ckUSDT | ckUSDT Ledger | ckETH Minter | ckETH | All ERC-20 tokens use the same ckETH minter for withdrawals, with gas paid in ckETH. --- --- title: "ICP Pool Canister" description: "Native ICP liquidity custody, deposits, withdrawals, and lending integration." canonical: "https://liquidium.fi/docs/technical/architecture/icp-pool" markdown: "https://liquidium.fi/docs/technical/architecture/icp-pool/index.md" breadcrumbs: "Docs > Technical Documentation > Architecture > ICP Pool" updated: "2026-06-22T05:09:06.828Z" --- # ICP Pool Canister Native ICP liquidity custody, deposits, withdrawals, and lending integration. Canonical URL: https://liquidium.fi/docs/technical/architecture/icp-pool Markdown URL: https://liquidium.fi/docs/technical/architecture/icp-pool/index.md ## ICP Pool Canister The ICP Pool canister manages native ICP liquidity for Liquidium. Unlike BTC and ERC assets, ICP does not need a Chain Key minter. It moves through the native ICP ledger. Production canister: `r2pk3-4yaaa-aaaar-qb7zq-cai` ## Responsibilities - Accept ICP deposits and repayments through deterministic inflow subaccounts - Sweep funded inflow subaccounts into the pool treasury - Notify the lending canister when deposits and repayments are confirmed - Process borrows and withdrawals to ICP destinations - Track ledger height, queued events, available balance, and quarantined withdrawals ## How ICP differs from BTC and ERC pools | Area | ICP Pool | | --- | --- | | Asset | Native ICP | | Ledger | ICP ledger | | Deposits | User sends ICP to a deposit or repayment subaccount | | Outflows | Pool transfers ICP to the requested destination | | Destination formats | Principal, ICRC-1 account, or AccountIdentifier | | Finality | ICP ledger finality; no Bitcoin or Ethereum confirmation wait | | App authorization | ICP has no linkable wallet in the app, so outflows are signed by a linked BTC or ETH wallet | ## Public interface - `get_inflow_subaccount(Deposit | Repayment)`: returns the deposit or repayment subaccount for a user. - `check_subaccount(blob)`: checks a funded inflow subaccount and schedules the sweep into treasury. - `withdraw(PoolWithdrawRequest)`: processes a lending-approved ICP borrow or withdrawal. - `withdraw_underlying(PoolWithdrawUnderlyingRequest)`: sends native ICP to an underlying destination. - `available_balance()`: returns current pool liquidity. - `ledger_height()`: returns the observed ICP ledger height. - `get_queued_events()`: exposes pending deposit and repayment events for lending synchronization. ## Flow 1. The app gives the user an ICP deposit or repayment address. 2. The user sends ICP on the ICP ledger. 3. The pool detects the funded subaccount and sweeps the balance to treasury. 4. The pool queues a `DepositConfirmed` or `RepaymentConfirmed` event. 5. The lending canister applies the event to the user position. 6. For borrows or withdrawals, lending validates the position and calls the ICP Pool to send native ICP to the requested destination. --- --- title: "Cross-Chain Flow" description: "How native assets move through the protocol via Chain Key technology" canonical: "https://liquidium.fi/docs/technical/architecture/cross-chain" markdown: "https://liquidium.fi/docs/technical/architecture/cross-chain/index.md" breadcrumbs: "Docs > Technical Documentation > Architecture > Cross-Chain Flow" updated: "2026-07-20T20:06:11.762Z" --- # Cross-Chain Flow How native assets move through the protocol via Chain Key technology Canonical URL: https://liquidium.fi/docs/technical/architecture/cross-chain Markdown URL: https://liquidium.fi/docs/technical/architecture/cross-chain/index.md ## Chain Key Technology ICP's Chain Key allows canisters to: - **Hold assets** on other blockchains (Bitcoin, Ethereum) - **Sign transactions** using threshold cryptography - **Verify transactions** from other chains This eliminates the need for: - Centralized bridges - Trusted intermediaries - Manual wrapped-token management ## ckAsset Model Liquidium pools use chain-key assets on ICP. You can enter a supported pool through either the native blockchain or the corresponding ckAsset ledger on ICP, depending on the route shown in the app. Native ICP stays on the ICP ledger and does not need a ckAsset conversion. | Native Asset | Chain Key Asset | Backing | | --- | --- | --- | | BTC | ckBTC | 1:1 backed by L1 BTC | | ETH | ckETH | 1:1 backed by L1 ETH | | USDT | ckUSDT | 1:1 backed by L1 Ethereum USDT | | USDC | ckUSDC | 1:1 backed by L1 Ethereum USDC | | ICP | ICP | Native ICP ledger asset | **Native-chain route:** Send a supported native asset to the native-chain deposit address shown in the app. Chain Key infrastructure mints the corresponding ckAsset before the pool processes it. **ICP ckAsset route:** If you already hold a supported ckAsset, send it directly over ICP to the ICRC-1 deposit address shown in the app. No additional ckAsset minting is required. ## Deposit Routes (Native or ckAsset → Pool) ```mermaid sequenceDiagram actor User participant Bitcoin as Bitcoin Network participant Minter as ckBTC Minter participant Ledger as ckBTC Ledger participant Pool as BTC Pool participant Lending User->>Bitcoin: Send BTC to deposit address Note over Bitcoin: confirmations (~40 min) Bitcoin->>Minter: Transaction confirmed Minter->>Ledger: Mint ckBTC Ledger->>Ledger: Credit user's inflow subaccount Note over Pool: Timer detects new balance Pool->>Ledger: Transfer to treasury Pool->>Pool: Create DepositConfirmed event Pool->>Lending: notify_pool_event() Lending->>Lending: Mint supply shares ``` ### What you do 1. Select the asset and deposit route shown in the app 2. For a native-chain deposit, send the native asset to the Bitcoin or Ethereum address shown 3. For a direct ckAsset deposit, enable ICP assets and send the ckAsset to the ICRC-1 address shown 4. After the transfer confirms and Liquidium processes it, the funds appear in your profile > The destination is asset- and network-specific. Never send native ETH to a ckETH address on ICP or ckETH to an Ethereum address. ## Withdrawal Flow (Pool → ckAsset → Native) ```mermaid sequenceDiagram actor User participant Lending participant Pool as BTC Pool participant Ledger as ckBTC Ledger participant Minter as ckBTC Minter participant Bitcoin as Bitcoin Network User->>Lending: withdraw(amount, btc_address) Lending->>Lending: Validate & burn shares Lending->>Pool: withdraw(request) Pool->>Ledger: Transfer to outflow subaccount alt Standard Withdrawal (> 50k sats) Pool->>Ledger: Approve minter Pool->>Minter: retrieve_btc() Minter->>Ledger: Burn ckBTC Minter->>Bitcoin: Send BTC to user else Boosted Withdrawal (< 50k sats) Pool->>Pool: Add to batch queue Note over Pool: Pool fronts BTC immediately Pool->>Bitcoin: Multi-output transaction end Bitcoin-->>User: BTC received ``` ### What you do 1. Request a withdrawal to your Bitcoin address 2. Lending canister validates health factor 3. Pool processes withdrawal (standard or boosted) 4. Receive native BTC ## Borrow Flow (Cross-Chain) You can supply BTC and borrow USDC across chains: ```mermaid sequenceDiagram actor User participant Lending participant BTCPool as BTC Pool participant USDCPool as USDC Pool participant Minter as ckETH Minter participant Ethereum Note over User: Has BTC collateral User->>Lending: borrow(USDT, amount, eth_address) Lending->>Lending: Check health factor Lending->>Lending: Mint debt shares Lending->>USDCPool: withdraw(request) USDCPool->>USDCPool: Calculate gas fee USDCPool->>USDCPool: Front ckETH for gas USDCPool->>Minter: withdraw_erc_20() Minter->>Ethereum: Send USDT to user Ethereum-->>User: USDT received ``` ### What you do 1. Supply BTC as collateral 2. Request to borrow USDT to your Ethereum address 3. Protocol validates collateral covers the loan 4. Receive USDT on Ethereum ## Repayment Flow ```mermaid sequenceDiagram actor User participant Ethereum participant Minter as ckETH Minter participant Ledger as ckUSDT Ledger participant Pool as USDT Pool participant Lending User->>Ethereum: Send USDT to minter address Ethereum->>Minter: Transaction confirmed Minter->>Ledger: Mint ckUSDT Ledger->>Ledger: Credit user's repayment subaccount Note over Pool: Timer detects new balance Pool->>Ledger: Transfer to treasury Pool->>Pool: Create RepaymentConfirmed event Pool->>Lending: notify_pool_event() Lending->>Lending: Burn debt shares ``` ## Confirmation Requirements Each chain has different finality characteristics: | Chain | Confirmations | Approximate Time | | --- | --- | --- | | Bitcoin | 4 | \~40 minutes | | Ethereum | 64 | \~13 minutes | | ICP | Ledger finality | Usually seconds, then Liquidium finalization | The protocol waits for sufficient confirmations or ledger finality before crediting funds. ## Cross-Chain Architecture Benefits ### 1. Native Asset UX You can deposit and receive supported native assets without manually using a bridge. If you already hold supported ckAssets, use the direct ICP route shown in the app. You do not need to understand the internal conversion process, and you do not need to convert ckAssets back to native assets before using Liquidium. ### 2. Unified Liquidity All supported routes feed the same Liquidium pools: - BTC from a Bitcoin wallet or ckBTC over ICP - ETH from an Ethereum wallet or ckETH over ICP - USDC/USDT from Ethereum or their supported ckAsset ledgers on ICP - ICP from a supported principal, ICRC-1 account, or Account ID - Single health factor across all positions ### 3. Fast Liquidations ICP's sub-second finality enables: - 15-second liquidation cycles - Quick response to price movements - Protocol solvency protection Compare to: - Bitcoin: 10-40 minutes per transaction - Ethereum: 12+ seconds per block ### 4. Decentralized Security Chain Key provides: - No trusted intermediaries - Threshold cryptography (many nodes) - Cryptographic proofs of asset backing ## Deployed Infrastructure The protocol uses ICP's production Chain Key and native ledger infrastructure: | Component | Purpose | | --- | --- | | ckBTC Minter | Mint/burn ckBTC ↔ BTC | | ckETH Minter | Mint/burn ckETH/ckERC-20 ↔ ETH/ERC-20 | | ckBTC Ledger | ICRC-1 ledger for ckBTC | | ckETH Ledger | ICRC-1 ledger for ckETH | | ICP Ledger | Native ICP ledger used by the ICP Pool | | ICP Pool Canister | Native ICP liquidity, deposits, repayments, borrows, and withdrawals | > [!TIP] > Learn more about ICP's Chain Fusion technology at [internetcomputer.org/chainfusion](https://internetcomputer.org/chainfusion). --- --- title: "Operations" description: "How user operations flow through the protocol" canonical: "https://liquidium.fi/docs/technical/operations" markdown: "https://liquidium.fi/docs/technical/operations/index.md" breadcrumbs: "Docs > Technical Documentation > Operations" updated: "2026-04-08T12:11:29.910Z" --- # Operations How user operations flow through the protocol Canonical URL: https://liquidium.fi/docs/technical/operations Markdown URL: https://liquidium.fi/docs/technical/operations/index.md - [Deposits](https://liquidium.fi/docs/technical/operations/deposits) - [Withdrawals](https://liquidium.fi/docs/technical/operations/withdrawals) - [Borrowing](https://liquidium.fi/docs/technical/operations/borrowing) - [Repayments](https://liquidium.fi/docs/technical/operations/repayments) ## Operation Lifecycle All operations follow a similar lifecycle: ```mermaid graph LR User[User Action] --> Validate[Validation] Validate --> State[State Update] State --> Async[Async Execution] Async --> Confirm[Confirmation] ``` ### 1. User Action User initiates operation (deposit, withdraw, borrow, repay) ### 2. Validation - Signature verification - Balance checks - Health factor validation ### 3. State Update - Share minting/burning - Position updates - Index synchronization ### 4. Async Execution - Inter-canister calls - ckAsset operations - Blockchain transactions ### 5. Confirmation - Event notification - Record updates - User notification ## Inflow vs Outflow Operations | Operation | Direction | Initiated By | State Update | | --- | --- | --- | --- | | Deposit | Inflow | Pool (detected) | Mint supply shares | | Repay | Inflow | Pool (detected) | Burn debt shares | | Withdraw | Outflow | User (signed) | Burn supply shares | | Borrow | Outflow | User (signed) | Mint debt shares | ### Inflow Operations Deposits and repayments are **detected** by the pool: 1. User sends native assets to their deposit address 2. ckAsset minter mints tokens to user's subaccount 3. Pool timer detects new balance 4. Pool transfers to treasury and notifies lending canister ### Outflow Operations Withdrawals and borrows are **initiated** by the user: 1. User signs request with their wallet 2. Lending canister validates and updates state 3. Pool executes withdrawal asynchronously 4. User receives native assets ## Subaccount System The protocol uses subaccounts for user isolation and automatic attribution: ### Inflow Subaccounts ```plaintext Deposit: [0x1, 0x0, length, ...principal_bytes...] Repayment: [0x2, 0x0, length, ...principal_bytes...] ``` Each user has unique subaccounts derived from their principal. ### Outflow Subaccounts ```plaintext BTC (mapped): [0x3, ...zeros..., ...u128_index...] ETH (direct): [0x4, ...zeros..., ...20_byte_address...] IC Principal: [0x5, 0x0, length, ...principal_bytes...] ``` ### Benefits - **Privacy**: No shared addresses - **Automatic attribution**: Subaccount identifies user - **Parallel processing**: No account contention - **Simplified reconciliation**: Deterministic mapping --- --- title: "Deposits" description: "How deposits flow through the protocol - inflow detection, subaccounts, and share minting" canonical: "https://liquidium.fi/docs/technical/operations/deposits" markdown: "https://liquidium.fi/docs/technical/operations/deposits/index.md" breadcrumbs: "Docs > Technical Documentation > Operations > Deposits" updated: "2026-07-20T20:06:26.140Z" --- # Deposits How deposits flow through the protocol - inflow detection, subaccounts, and share minting Canonical URL: https://liquidium.fi/docs/technical/operations/deposits Markdown URL: https://liquidium.fi/docs/technical/operations/deposits/index.md ## Deposit Flow Overview ```mermaid sequenceDiagram actor User participant Blockchain as Native Chain participant Minter as ckAsset Minter participant Ledger as ckAsset Ledger participant Pool participant Lending User->>Blockchain: Send native asset to deposit address Note over Blockchain: Wait for confirmations Blockchain->>Minter: Transaction confirmed Minter->>Ledger: Mint ckAsset to user's inflow subaccount Note over Pool: Timer: check_for_new_subaccount_inflows (60s) Pool->>Ledger: Query subaccount balance Pool->>Pool: Schedule transfer to treasury Note over Pool: WAL execution Pool->>Ledger: Transfer from subaccount to treasury Note over Pool: Timer: process_treasury_movements (60s) Pool->>Pool: Detect treasury inflow Pool->>Pool: Create DepositConfirmed event Note over Pool: Timer: process_event_queue (60s) Pool->>Lending: notify_pool_event(DepositConfirmed) Lending->>Lending: Mint supply shares Lending-->>Pool: Ack ``` ## Step 1: Send Assets to a Deposit Address Send assets to the unique deposit address shown in the app for your selected asset, network, and action. Liquidium supports both native-chain deposits and direct ckAsset deposits on ICP. ### Bitcoin Deposits - Send BTC to the Bitcoin deposit address shown in the app - The address is derived from the protocol's threshold ECDSA key - Deposits require 4 confirmations (\~40 minutes) ### Ethereum Asset Deposits - Send supported Ethereum assets to the asset-specific Ethereum deposit address shown in the app - The app displays deposit and repay addresses for each supported Ethereum asset and action - If an address-based flow is unavailable, use the linked-wallet flow or another option shown in the app ### Direct ckAsset Deposits on ICP - You can deposit supported ckAssets, including ckBTC, ckETH, ckUSDC, and ckUSDT, directly over ICP - Enable **ICP assets** in the app, select the asset and action, and send the exact ckAsset to the ICRC-1 deposit address shown - You do not need to send or mint the corresponding native asset first > Always match the asset, network, and address shown in the app. Do not send a native asset to a ckAsset address, a ckAsset to a native-chain address, or a different token to the displayed address. ### Native ICP Deposits - Send ICP to the Account ID or ICRC address shown in the app - The app displays the supported address format for your selected action ## Step 2: Native Asset Conversion, When Needed When you deposit a supported native asset from Bitcoin or Ethereum: - The ckAsset minter detects the confirmed native transaction - The minter creates the corresponding ckAsset tokens, such as ckBTC or ckETH - The tokens are credited to your inflow subaccount When you deposit an existing ckAsset directly over ICP, this conversion step is skipped. The protocol detects the ICRC ledger transfer to your inflow subaccount. ### Inflow Subaccount Encoding Liquidium derives a unique deposit subaccount from your profile principal: - Prefix byte `0x1` indicates deposit type - Followed by principal length and bytes - Padded to 32 bytes ## Step 3: Inflow Detection The pool scans for new deposits every 60 seconds by querying the ledger for transactions since the last seen index. For each transaction to a pool subaccount, it decodes the subaccount type and schedules processing. **Key Features:** - **Batch processing**: Up to 10,000 transactions per scan - **Archive support**: Fetches from ledger archives if needed - **Debouncing**: Each subaccount processed once per scan - **Persistent tracking**: Last seen index stored in stable storage ## Step 4: Transfer to Treasury After detection, funds are transferred from your inflow subaccount to the pool treasury. The treasury is the pool's main account with no subaccount, where all pool liquidity is held. ## Step 5: Treasury Movement Detection The pool monitors the treasury for incoming transfers every 60 seconds. When it detects a transfer from an inflow subaccount, it decodes the source, associates it with the correct Liquidium profile, and creates a `DepositConfirmed` event. ## Step 6: Event Notification Queued events are sent to the lending canister. The event queue is persistent (survives canister upgrades), retries on failure, and processes up to 100 events per tick. ## Step 7: Share Minting The lending canister processes the deposit event: - Checks idempotency and skips events already processed - Syncs pool indices - Validates the supply cap - Mints shares: `shares = deposit_amount / lending_index` Example: A 1.0 BTC deposit at `lending_index = 1.05` mints 0.952 shares. If the index later reaches 1.10, the balance becomes 1.0472 BTC, representing 4.72% earned. ## Timing Summary | Step | Trigger | Latency | | --- | --- | --- | | Source transfer confirmation | Bitcoin, Ethereum, or ICP ledger | Varies by route | | ckAsset minting | Minter | Native-chain deposits only | | Inflow detection | Timer | \~60 sec | | Treasury transfer | WAL | \~30 sec | | Treasury detection | Timer | \~60 sec | | Event notification | Timer | \~60 sec | | Share minting | Event | Immediate | The app shows the estimated time for your selected route. Direct ckAsset deposits typically take about 2 minutes. Native-chain deposits take longer because they also require source-chain confirmations and ckAsset minting. ## Error Handling Multiple layers prevent double-crediting: - Ledger index tracking: Each transaction processed once - PROCESSED\_INFLOWS set: Event deduplication - Subaccount debouncing: One job per subaccount per scan > Deposits are automatically detected after you send the correct asset over the correct network to the exact deposit address shown in the app. --- --- title: "Withdrawals" description: "How withdrawals flow through the protocol - standard vs boosted paths, fee handling" canonical: "https://liquidium.fi/docs/technical/operations/withdrawals" markdown: "https://liquidium.fi/docs/technical/operations/withdrawals/index.md" breadcrumbs: "Docs > Technical Documentation > Operations > Withdrawals" updated: "2026-04-08T12:11:36.330Z" --- # Withdrawals How withdrawals flow through the protocol - standard vs boosted paths, fee handling Canonical URL: https://liquidium.fi/docs/technical/operations/withdrawals Markdown URL: https://liquidium.fi/docs/technical/operations/withdrawals/index.md ## Withdrawal Flow Overview ```mermaid sequenceDiagram actor User participant Lending participant Pool participant Ledger as ckAsset Ledger participant Minter as ckAsset Minter participant Blockchain as Native Chain User->>Lending: withdraw(amount, address) [signed] Note over Lending: Phase 1: Synchronous Lending->>Lending: Verify signature Lending->>Lending: Sync pool indices Lending->>Lending: Burn supply shares Lending->>Lending: Check health factor alt Health Factor OK Lending->>Lending: Schedule async withdrawal Lending-->>User: OutflowDetails else Health Factor Too Low Lending->>Lending: Rollback share burn Lending-->>User: Error: InsufficientCollateral end Note over Lending: Phase 2: Asynchronous Lending->>Pool: withdraw(request) Pool->>Ledger: Transfer to outflow subaccount Note over Pool: Timer detects outflow balance Pool->>Minter: Burn ckAsset Minter->>Blockchain: Send native asset Blockchain-->>User: Asset received ``` ## Two-Phase Execution ### Phase 1: Synchronous (Atomic) All state changes happen atomically before any async work: 1. Verify signature 2. Sync pool indices 3. Burn supply shares 4. Check health factor - if too low, rollback share burn and return error 5. Schedule async withdrawal ### Phase 2: Asynchronous (WAL-backed) The actual withdrawal executes in the background via the Write-Ahead Log. The WAL handles retries on failure and ensures the operation eventually completes. ## Outflow Subaccounts When the pool receives a withdrawal request, it transfers funds to an outflow subaccount: | Pool | Encoding | Description | | --- | --- | --- | | **BTC** | Mapped index | Bitcoin addresses mapped to u128 indices | | **ERC** | Direct encoding | Ethereum addresses (20 bytes) fit directly | | **IC Principal** | Native format | For transfers to IC principals | ## Standard vs Boosted Withdrawals (BTC) The BTC Pool uses two withdrawal paths based on amount: ### Standard Withdrawal (Over 50,000 sats) Direct ckBTC burn via the minter: ```mermaid sequenceDiagram participant Pool participant Ledger participant Minter participant Bitcoin Pool->>Ledger: Transfer to outflow subaccount Pool->>Ledger: Approve minter spending Pool->>Minter: retrieve_btc_with_approval() Minter->>Ledger: Burn ckBTC Minter->>Bitcoin: Send BTC to user address ``` **Characteristics:** - 1:1 economic efficiency - User receives BTC after \~6 confirmations - Higher effective fee ratio for small amounts ### Boosted Withdrawal (Under 50,000 sats) Batched withdrawal for fee efficiency: ```mermaid sequenceDiagram participant Pool participant BoostQueue as Boost Queue participant Bitcoin Pool->>Pool: Transfer to BOOST_SUBACCOUNT Pool->>BoostQueue: Add to pending queue Note over Pool: Timer: every 5 minutes Pool->>Pool: Collect pending withdrawals Pool->>Pool: Create multi-output Bitcoin tx Pool->>Pool: Sign with threshold ECDSA Pool->>Bitcoin: Broadcast transaction Note over Pool: Pool fronts BTC immediately Bitcoin-->>User: BTC received Note over Pool: Later: burn accumulated ckBTC ``` **Characteristics:** - Pool fronts BTC from its UTXOs - Multiple withdrawals batched into one transaction - Lower effective fees (shared across batch) - 0.3% boost fee deducted - Faster user experience ### Decision Logic If amount is under or equal to 50,000 sats, use boosted path (transfer to boost subaccount, add to queue). Otherwise, use standard path (direct ckBTC burn). ## ERC Withdrawals with Gas Fee Fronting ERC-20 withdrawals require Ethereum gas fees. The pool: 1. Gets current ETH gas price from oracle 2. Converts to pool token equivalent 3. Fronts ckETH gas from FEE\_SUBACCOUNT 4. Deducts fee from withdrawal amount 5. Burns both ckETH (gas) and ckToken (withdrawal) 6. Sends native token to user on Ethereum ## Idempotency Withdrawals have multiple deduplication layers: 1. **Request ID tracking** - each withdrawal has a unique ID 2. **WAL operation ID** - unique OpId per operation 3. **Ledger timestamp** - ICRC-1 transfers include timestamps for duplicate detection ## Error Handling | Error | Cause | Recovery | | --- | --- | --- | | Health factor violation | Withdrawal would make position liquidatable | Rollback share burn, return error | | Insufficient liquidity | Pool doesn't have enough funds | WAL retries when liquidity available | | Network failures | Inter-canister call fails | WAL retries with exponential backoff | > [!WARNING] > Withdrawals may reduce your health factor. Ensure you maintain adequate collateral to avoid liquidation. --- --- title: "Borrowing" description: "How borrowing flows through the protocol - health checks, debt shares, and async execution" canonical: "https://liquidium.fi/docs/technical/operations/borrowing" markdown: "https://liquidium.fi/docs/technical/operations/borrowing/index.md" breadcrumbs: "Docs > Technical Documentation > Operations > Borrowing" updated: "2026-06-30T14:58:23.936Z" --- # Borrowing How borrowing flows through the protocol - health checks, debt shares, and async execution Canonical URL: https://liquidium.fi/docs/technical/operations/borrowing Markdown URL: https://liquidium.fi/docs/technical/operations/borrowing/index.md ## Borrow Flow Overview ```mermaid sequenceDiagram actor User participant Wallet participant Lending participant Protocol participant Pool participant Minter participant Blockchain User->>Wallet: Sign borrow request Wallet-->>User: Signature User->>Lending: borrow_assets(SignedRequest) Note over Lending: Phase 1: Synchronous Lending->>Lending: Verify signature & nonce Lending->>Protocol: sync_pool(pool_id) Protocol->>Protocol: Update indices Lending->>Protocol: borrow(user, pool, amount) Protocol->>Protocol: Check liquidity Protocol->>Protocol: Mint debt shares Protocol->>Protocol: Check health factor alt Health Factor OK Lending->>Lending: Schedule async withdrawal Lending-->>User: OutflowDetails else Health Factor Too Low Protocol->>Protocol: Rollback debt shares Lending-->>User: Error: InsufficientCollateral end Note over Lending: Phase 2: Asynchronous Lending->>Pool: withdraw(request) Pool->>Minter: Burn ckAsset Minter->>Blockchain: Send native asset Blockchain-->>User: Asset received ``` ## Two-Phase Execution ### Phase 1: Synchronous (Atomic) All state changes happen atomically: 1. Verify signature 2. Increment nonce (replay protection) 3. Sync pool indices 4. Check liquidity 5. Mint debt shares 6. Check health factor - if too low, rollback and return error 7. Schedule async withdrawal ### Phase 2: Asynchronous (WAL-backed) The borrowed assets are sent to the user via the Write-Ahead Log, which handles retries on failure. ## Health Factor Validation Before approving a borrow, the protocol validates the position will remain healthy: **Example Calculation:** - User has: 1 BTC @ $50,000 = $50,000 collateral (LT = 74%) - Current debt: $20,000 USDC - Current HF: (50000 × 0.74) / 20000 = **1.85** ✓ User wants to borrow $15,000 more: - New debt: $35,000 - New HF: (50000 × 0.74) / 35000 = **1.06** ✓ Approved If user tried to borrow $25,000: - New debt: $45,000 - New HF: (50000 × 0.74) / 45000 = **0.82** ✗ Rejected ## Debt Share Minting Debt is tracked using shares, similar to deposits: `shares = borrow_amount / borrow_index` **Example:** User borrows 1000 USDT at borrow\_index = 1.10 → 909.09 shares minted. After 1 year, index = 1.15: Debt = 909.09 × 1.15 = 1045.45 USDT (45.45 USDT interest owed) ## Cross-Chain Borrowing Users can borrow assets on a different chain than their collateral: ```mermaid sequenceDiagram actor User participant Lending participant BTCPool as BTC Pool participant USDCPool as USDC Pool participant Minter participant Ethereum Note over User: Has 1 BTC collateral User->>Lending: borrow(USDT, $30000, eth_address) Lending->>Lending: Check BTC collateral value Lending->>Lending: Mint USDT debt shares Lending->>Lending: Validate health factor Lending->>USDCPool: withdraw(30000 USDT, eth_address) USDCPool->>USDCPool: Calculate gas fee USDCPool->>Minter: withdraw_erc_20() Minter->>Ethereum: Send USDT Ethereum-->>User: 30000 USDT received ``` **Key points:** - Collateral stays in BTC Pool - Debt tracked in USDT Pool - Health factor considers both positions - User receives native USDT on Ethereum ## Borrow Caps Each pool has a maximum borrow cap to limit protocol risk exposure to any single asset. If the total debt plus the new borrow exceeds the cap, the request is rejected. ## Same-Asset Borrowing Some pools may restrict borrowing the same asset you've supplied. This prevents circular positions that could game the interest rate model. ## Interest Accrual Debt automatically accrues interest through the borrow index: ```mermaid graph LR DebtShares[Debt Shares - Fixed] -->|Multiply| BorrowIndex[Borrow Index - Growing] BorrowIndex --> CurrentDebt[Current Debt - Increasing] ``` **No action required from borrowers** - interest compounds automatically. ## Signature Requirements Borrow requests must be signed with the user's wallet: | Chain | Standard | Format | | --- | --- | --- | | Bitcoin | BIP322 | Message signature | | Ethereum | EIP-191 | personal\_sign | | Solana | Ed25519 | Direct signature | ## Nonce Protection Each account has an incrementing nonce to prevent replay attacks. The provided nonce must match the expected value, and is incremented after each successful request. ## Error Scenarios | Error | Cause | Solution | | --- | --- | --- | | Insufficient Collateral | Health factor would drop below threshold | Add more collateral or borrow less | | No Liquidity | Pool doesn't have enough funds | Wait for deposits or borrow less | | Borrow Cap Exceeded | Pool reached maximum debt | Borrow from different pool or wait | > [!WARNING] > Borrowing creates debt that accrues interest. Monitor your health factor to avoid liquidation during market volatility. --- --- title: "Repayments" description: "How repayments flow through the protocol - debt detection, share burning, and overpayment handling" canonical: "https://liquidium.fi/docs/technical/operations/repayments" markdown: "https://liquidium.fi/docs/technical/operations/repayments/index.md" breadcrumbs: "Docs > Technical Documentation > Operations > Repayments" updated: "2026-06-29T08:22:39.814Z" --- # Repayments How repayments flow through the protocol - debt detection, share burning, and overpayment handling Canonical URL: https://liquidium.fi/docs/technical/operations/repayments Markdown URL: https://liquidium.fi/docs/technical/operations/repayments/index.md ## Repayment Flow Overview ```mermaid sequenceDiagram actor User participant Blockchain as Native Chain participant Minter as ckAsset Minter participant Ledger as ckAsset Ledger participant Pool participant Lending User->>Blockchain: Send native asset to repayment address Note over Blockchain: Wait for confirmations Blockchain->>Minter: Transaction confirmed Minter->>Ledger: Mint ckAsset to repayment subaccount Note over Pool: Timer: check_for_new_subaccount_inflows (60s) Pool->>Ledger: Query subaccount balance Pool->>Pool: Schedule transfer to treasury Note over Pool: WAL execution Pool->>Ledger: Transfer from subaccount to treasury Note over Pool: Timer: process_treasury_movements (60s) Pool->>Pool: Detect treasury inflow from repayment subaccount Pool->>Pool: Create RepaymentConfirmed event Note over Pool: Timer: process_event_queue (60s) Pool->>Lending: notify_pool_event(RepaymentConfirmed) Lending->>Lending: Burn debt shares Lending-->>Pool: Ack ``` ## Repayment Subaccount Repayments use a different prefix than deposits to distinguish them: - Deposit prefix: `0x1` - Repayment prefix: `0x2` This allows the protocol to correctly attribute incoming funds as debt repayment rather than new collateral. ## Detection Process The detection process is identical to deposits: 1. **Inflow Detection** - Pool scans for new balances every 60 seconds 2. **Treasury Transfer** - Funds moved from repayment subaccount to treasury 3. **Event Creation** - Pool creates a `RepaymentConfirmed` event ## Debt Share Burning When the lending canister receives a repayment event: 1. Checks idempotency (skip if already processed) 2. Syncs pool indices 3. Calculates current debt 4. Burns debt shares: `shares_to_burn = repay_amount / borrow_index` 5. Handles any overpayment **Example:** User has 1000 debt shares at borrow\_index = 1.05 → Current debt = 1050 tokens. User repays 525 tokens → Shares burned = 525 / 1.05 = 500 shares → Remaining: 500 shares = 525 tokens debt ## Overpayment Handling If the user sends more than their outstanding debt, the excess becomes protocol service fees. The user's debt is fully cleared. **Why not refund?** - Refunds require another blockchain transaction - Gas costs may exceed overpayment amount - Simplifies protocol logic > [!WARNING] > Overpayments are not automatically refunded. In the connected-wallet advanced flow, copy the current outstanding debt from the app and repay the exact amount shown. ## Partial Repayments Users can repay any amount up to their full debt. The protocol calculates how many debt shares to burn based on the current borrow index. **Example:** - User has 1000 debt shares at borrow\_index = 1.05 → Current debt = 1050 tokens - User repays 525 tokens → Shares burned = 525 / 1.05 = 500 shares - Remaining: 500 shares = 525 tokens debt ## Interest Consideration When repaying, remember that debt accrues interest continuously (even while repayment transactions are processing): ```mermaid graph LR Original[Original Borrow] --> Interest[+ Accrued Interest] Interest --> Total[Total Debt] Total --> Repay[Repayment Amount] ``` **Example (simplified, compounding not shown for clarity):** Borrowed 1000 USDT, 6 months elapsed, 10% APY → Accrued interest: \~50 USDT → Total debt: \~1050 USDT ## Repayment Address Each user has a unique repayment address per pool: | Chain | Method | | --- | --- | | Bitcoin | Same address as deposit, distinguished by subaccount prefix | ## Timing | Step | Trigger | Latency | | --- | --- | --- | | Native tx confirmation | Blockchain | Varies by chain | | ckAsset minting | Minter | Immediate | | Inflow detection | Timer | \~60 sec | | Treasury transfer | WAL | \~30 sec | | Treasury detection | Timer | \~60 sec | | Event notification | Timer | \~60 sec | | Debt share burning | Event | Immediate | ## Health Factor Impact Repaying debt improves your health factor by reducing borrowed debt. It does not withdraw supplied collateral; in the connected-wallet advanced flow, use Withdraw after reducing or clearing debt to remove supplied assets. **Before repayment:** Collateral: $50,000, Debt: $40,000, HF = 1.0 (at risk) **After repaying $10,000:** Collateral: $50,000, Debt: $30,000, HF = 1.33 (safer) ## Idempotency Repayments have the same deduplication as deposits: 1. **Ledger index tracking**: Each transaction processed once 2. **PROCESSED\_INFLOWS set**: Event deduplication 3. **Subaccount debouncing**: One job per subaccount per scan > [!TIP] > Repayments are automatically detected when the supported borrowed asset is sent through the repayment method shown in the app. Wrong-asset, wrong-network, or wrong-address transfers require support investigation and are not guaranteed to be recoverable. --- --- title: "Security" description: "Protocol security guarantees - atomicity, authentication, and reliability" canonical: "https://liquidium.fi/docs/technical/security" markdown: "https://liquidium.fi/docs/technical/security/index.md" breadcrumbs: "Docs > Technical Documentation > Security" updated: "2026-04-08T12:11:37.931Z" --- # Security Protocol security guarantees - atomicity, authentication, and reliability Canonical URL: https://liquidium.fi/docs/technical/security Markdown URL: https://liquidium.fi/docs/technical/security/index.md - [Atomicity & WAL](https://liquidium.fi/docs/technical/security/atomicity) - [Authentication](https://liquidium.fi/docs/technical/security/authentication) ## Security Principles Liquidium implements multiple layers of security: ### 1. Cryptographic Security - **Native-chain signature verification** (BIP322 for Bitcoin, EIP-191 for Ethereum, Ed25519 for Solana) - **Nonce-based replay protection** - **Threshold ECDSA** for Bitcoin transactions, threshold ECDSA for Ethereum, threshold EdDSA for Solana ### 2. State Consistency - **Two-phase execution model** - **Write-ahead logging** for async operations - **Idempotent handlers** prevent double-execution ### 3. Economic Security - **Overcollateralization** requirements - **Liquidation incentives** maintain solvency - **Supply/borrow caps** limit exposure ### 4. Access Control - **Caller validation** for inter-canister calls - **Admin-only configuration methods** requiring authorized principals - **Profile ownership** verification ## Trust Boundaries ```mermaid graph LR subgraph Untrusted["Untrusted Zone"] User[User] External[External Blockchains] end subgraph Trusted["Trusted Zone - IC"] Lending[Lending Canister] Pools[Pool Canisters] ChainKey[Chain Key Infrastructure] PriceOracle[Price Oracle] end User -->|Signed Requests| Lending Lending <-->|Inter-Canister| Pools Pools <-->|ICRC Transfers| ChainKey ChainKey <-->|Cross-Chain| External PriceOracle -->|Prices| Lending ``` ### Boundary Protections | Boundary | Attack Vector | Mitigation | | --- | --- | --- | | User → Lending | Signature forgery | Native-chain signature verification | | User → Lending | Replay attacks | Nonce-based protection | | User → Lending | Unauthorized access | Profile ownership validation | | Lending → Pool | Unauthorized withdrawals | Caller validation | | Lending → Pool | Double execution | WAL idempotency | | Pool → ckMinter | Invalid burn amounts | Pre-flight validation | | Oracle → Lending | Price manipulation | Caching, deviation alerts | | Liquidator → Lending | Griefing attacks | Close factor limits | ## Key Security Properties ### Atomicity All critical state changes happen atomically in a single execution: - No partial state updates - Rollback on validation failure - State committed before async work ### Durability Pending operations survive canister upgrades: - Write-ahead log in stable storage - Automatic retry on failure - No data loss on crashes ### Idempotency Operations can be safely retried: - Unique operation IDs - Processed ID tracking - Ledger-level deduplication ### Authorization Every operation is properly authorized: - Signature verification for user requests - Caller validation for inter-canister calls - Admin checks for configuration changes --- --- title: "Atomicity & Write-Ahead Logging" description: "Two-phase execution model and reliable async operations" canonical: "https://liquidium.fi/docs/technical/security/atomicity" markdown: "https://liquidium.fi/docs/technical/security/atomicity/index.md" breadcrumbs: "Docs > Technical Documentation > Security > Atomicity & Write-Ahead Logging" updated: "2026-04-08T12:11:39.510Z" --- # Atomicity & Write-Ahead Logging Two-phase execution model and reliable async operations Canonical URL: https://liquidium.fi/docs/technical/security/atomicity Markdown URL: https://liquidium.fi/docs/technical/security/atomicity/index.md ## The Challenge IC canisters face unique constraints: - **Execution limits**: Few billion instructions per message - **Async calls**: Inter-canister calls can fail - **Upgrades**: Subnets and Canisters can be upgraded at any time - **Crashes**: Unexpected failures can occur Financial operations must remain consistent despite these challenges. ## Two-Phase Execution Model Every critical operation follows this pattern: ```mermaid sequenceDiagram participant User participant Canister participant State participant WAL participant Pool User->>Canister: Request Operation rect rgb(192,132,252) Note over Canister,State: PHASE 1: SYNCHRONOUS Canister->>Canister: Validate signature Canister->>State: Validate preconditions Canister->>State: Update state atomically Canister->>State: Validate postconditions alt Validation Fails State->>State: ROLLBACK Canister-->>User: Error end end Note over Canister: State committed rect rgb(37,99,235) Note over Canister,Pool: PHASE 2: ASYNCHRONOUS Canister->>WAL: Persist operation Canister-->>User: Success Note over WAL,Pool: Background execution WAL->>Pool: Execute inter-canister call alt Call Succeeds WAL->>WAL: Mark succeeded else Call Fails WAL->>WAL: Schedule retry end end ``` ### Phase 1: Synchronous (Atomic) - All state changes are atomic (all-or-nothing) - User receives immediate feedback - No pending async operations if validation fails - State persists before async work begins **Duration:** Typically < 200ms ### Phase 2: Asynchronous (WAL-backed) - Operations persist across canister upgrades - Automatic retries with exponential backoff - Idempotent execution (safe to retry) - Error tracking for manual intervention **Duration:** Variable (seconds to minutes). ## Write-Ahead Log (WAL) The WAL is a persistent queue of pending async operations stored in stable memory. ### WAL Entry Structure Each entry tracks: - **Kind**: Operation type ("outflow", "liquidation", etc.) - **Status**: Current execution state - **Retry info**: Attempts, max retries, backoff, next attempt time - **Audit trail**: First seen, last update, last error - **Payload**: Operation-specific data ### WAL Status States ```mermaid stateDiagram-v2 [*] --> Enqueued: schedule() Enqueued --> InFlight: Timer picks up InFlight --> Succeeded: Call succeeds InFlight --> FailedRetryable: Call fails InFlight --> FailedPermanent: Max retries FailedRetryable --> InFlight: Retry FailedRetryable --> FailedPermanent: Max retries Succeeded --> [*]: Removed FailedPermanent --> ManualReview ``` | Status | Meaning | | --- | --- | | `Enqueued` | Queued for first execution | | `InFlight` | Currently executing | | `Succeeded` | Completed successfully | | `FailedRetryable` | Failed, will retry | | `FailedPermanent` | Failed, needs intervention | ### Retry Policy Operations use exponential backoff: - Attempt 1: 2 seconds - Attempt 2: 4 seconds - Attempt 3: 8 seconds - Attempt 4: 16 seconds - Attempt 5: 32 seconds Total time before permanent failure: \~62 seconds ### Timer-Based Execution A background timer processes the WAL every 30 seconds, acquiring pending operations in batches of up to 256 and executing those whose next attempt time has passed. ## Idempotency Guarantees Multiple layers prevent double-execution: | Layer | Mechanism | | --- | --- | | **Operation ID** | Unique ID per operation, duplicates rejected | | **Status Check** | Already-succeeded operations skipped | | **Per-Entry Locking** | Exclusive lock prevents concurrent execution | | **Handler Deduplication** | Pool tracks processed withdrawal IDs | ## Failure Scenarios ### Scenario 1: Transient Network Failure User withdraws 1 BTC → Lending Canister burns shares (committed) → Pool call times out **Recovery:** WAL marks FailedRetryable → Waits 2 seconds → Retries → Eventually succeeds ### Scenario 2: Subnet or Canister Upgrade 100 withdrawals pending in WAL → Operator upgrades Subnet or Canister → Heap cleared, timers stopped **Recovery:** post\_upgrade() reinitializes timers → WAL entries preserved (stable storage) → Operations resume ### Scenario 3: Health Factor Violation User tries to withdraw → Lending Canister burns shares → Health factor check fails **Recovery:** Lending Canister re-mints shares (rollback) → No WAL entry created → User receives immediate error ### Scenario 4: Permanent Failure Withdrawal with invalid address → Pool rejects permanently → WAL marks FailedPermanent **Recovery:** Admin investigates → Fixes root cause → Manually resets operation → Retry succeeds ## Atomic Operations Table | Operation | Atomic State Changes | Async Operations | | --- | --- | --- | | **Deposit** | Mint supply shares | Pool-initiated | | **Withdraw** | Burn supply shares, health check | Pool withdrawal, ckAsset burn | | **Borrow** | Mint debt shares, health check | Pool withdrawal, ckAsset burn | | **Repay** | Burn debt shares | Pool-initiated | | **Liquidate** | Burn debt, burn collateral, mint treasury | Collateral transfer, change refund | ## Persistence Properties The WAL uses stable storage that survives: - Canister upgrades - Canister crashes - Node restarts > [!TIP] > The WAL ensures that once a user's state is updated, the corresponding async operation will eventually complete, even across canister upgrades and network failures. --- --- title: "Authentication" description: "Multi-chain signature verification and replay protection" canonical: "https://liquidium.fi/docs/technical/security/authentication" markdown: "https://liquidium.fi/docs/technical/security/authentication/index.md" breadcrumbs: "Docs > Technical Documentation > Security > Authentication" updated: "2026-04-08T12:11:41.099Z" --- # Authentication Multi-chain signature verification and replay protection Canonical URL: https://liquidium.fi/docs/technical/security/authentication Markdown URL: https://liquidium.fi/docs/technical/security/authentication/index.md ## Authentication Overview ```mermaid sequenceDiagram actor User participant Wallet participant Lending User->>Lending: initialize_account(chain, address) Lending->>Lending: Generate nonce Lending-->>User: Challenge message User->>Wallet: Sign message Wallet-->>User: Signature User->>Lending: SignedRequest(data, signature, account, chain) alt Bitcoin Lending->>Lending: Verify BIP322 signature else Ethereum Lending->>Lending: Verify EIP-191 signature else Solana Lending->>Lending: Verify Ed25519 signature end Lending->>Lending: Derive Principal Lending->>Lending: Increment nonce Lending-->>User: Success ``` ## Wallet Abstraction Users are identified by their wallet address as a `(Chain, Address)` tuple: - `(Bitcoin, "bc1q...")` - `(Ethereum, "0x...")` - `(Solana, "7Np4...")` ### Principal Derivation A deterministic principal is derived from the wallet: `Principal = SHA224(chain:address) + 0x02` This creates a unique, verifiable identity for each wallet. ## Signature Verification | Chain | Standard | Description | | --- | --- | --- | | **Bitcoin** | BIP322 | Message signing standard, supports P2WPKH, P2TR, P2PKH, P2SH-P2WPKH | | **Ethereum** | EIP-191 | personal\_sign standard with prefix, recovers signer address | | **Solana** | Ed25519 | Direct signature verification against public key | ## Message Format Signed requests include: - **data**: Operation-specific data - **signature**: Wallet signature - **account**: User's account identifier - **chain**: Bitcoin, Ethereum, or Solana The message to sign includes: 1. Current nonce (replay protection) 2. Request data (operation-specific) 3. Timestamp (optional freshness check) ## Replay Protection ### Nonce System Each account has an incrementing nonce. The provided nonce must match the expected value, and is incremented after each successful request. ```mermaid sequenceDiagram participant User participant Lending User->>Lending: get_nonce(account) Lending-->>User: nonce = 5 User->>User: Sign message with nonce 5 User->>Lending: SignedRequest(nonce=5, ...) Lending->>Lending: Verify nonce == 5 ✓ Lending->>Lending: Increment nonce to 6 Lending-->>User: Success Note over User,Lending: Replay attempt User->>Lending: SignedRequest(nonce=5, ...) [replay] Lending->>Lending: Verify nonce == 6 ✗ Lending-->>User: Error: InvalidNonce ``` ### Properties - **Monotonic**: Nonces only increase - **Per-account**: Each account has its own nonce - **Atomic increment**: Nonce incremented with operation ## Account Initialization New accounts are initialized with a challenge-response flow: 1. User calls `initialize_account(chain, address)` 2. Protocol generates random nonce and returns challenge message 3. User signs challenge with their wallet 4. User submits signature to `complete_initialization` 5. Protocol verifies signature and creates account ## Multi-Wallet Profiles Users can link multiple wallets to a single profile: **Benefits:** - Unified positions across wallets - Deposit from Bitcoin, withdraw to Ethereum - Single health factor for all collateral ## Authorization Checks | Context | Verification | | --- | --- | | **User Operations** | Signature verification + account ownership + nonce increment | | **Inter-Canister Calls** | Caller must be the lending canister | | **Admin Operations** | Caller must have admin privileges | ## Security Properties | Property | Mechanism | | --- | --- | | **Authentication** | Cryptographic signature verification | | **Non-repudiation** | Only private key holder can sign | | **Replay protection** | Incrementing nonce per account | | **Freshness** | Nonce must match expected value | | **Authorization** | Profile ownership verification | > [!TIP] > Users can interact with Liquidium using their existing wallets. No new keys or accounts needed - just sign with Bitcoin, Ethereum, or Solana. --- --- title: "SDK" description: "Learn what the Liquidium SDK does, which integration paths it supports, and where to find setup steps, API reference, types, and examples." canonical: "https://liquidium.fi/docs/sdk" markdown: "https://liquidium.fi/docs/sdk/index.md" breadcrumbs: "Docs > SDK" updated: "2026-05-27T21:44:30.867Z" --- # SDK Learn what the Liquidium SDK does, which integration paths it supports, and where to find setup steps, API reference, types, and examples. Canonical URL: https://liquidium.fi/docs/sdk Markdown URL: https://liquidium.fi/docs/sdk/index.md The Liquidium SDK helps developers add Liquidium lending & borrowing flows to their own apps without building the protocol integration from scratch. Use the SDK when you want to: - Fetch available lending offers - Create and manage loan requests - Connect a user flow to Liquidium lending infrastructure - Work with typed request and response objects - Build your own frontend or backend experience on top of Liquidium ## How the SDK fits in Your app calls the SDK for Liquidium-specific actions. The SDK handles the request shapes, response types, and protocol details needed to work with Liquidium lending flows. You still control the product experience. The SDK gives you the developer interface for the Liquidium parts of the flow. ## When to use the SDK Use the SDK if you are building: - A lending or borrowing interface - A marketplace experience that includes Liquidium loans - Internal tooling for Liquidium-backed workflows - A backend service that needs to read or create Liquidium lending data If you only want to understand how Liquidium works, start with Technical Concepts and Architecture. If you are ready to implement, continue to the developer docs. ## Developer docs The developer docs include setup steps, API reference, request and response types, and examples. SDK Docs: [Open SDK developer docs](https://liquidium-inc.github.io/liquidium-sdk/) ### Useful Resources GitHub: [https://github.com/Liquidium-Inc/liquidium-sdk](https://github.com/Liquidium-Inc/liquidium-sdk) SDK: [https://www.npmjs.com/package/@liquidium/client](https://www.npmjs.com/package/@liquidium/client) AI Agent SDK Integration Skill (Codex, Claude Code, Cursor, etc.): `npx skills add Liquidium-Inc/liquidium-sdk/skills/liquidium-sdk-integration`