TL;DR

@liquidium/client is the TypeScript SDK for building on Liquidium.
Accountless Simple Loans are the fastest integration path. They do not require a Liquidium profile, wallet adapter, or signed borrow message.
Advanced profile flows support persistent supply, borrow, repayment, withdrawal, position, and history experiences.
Current supported assets are BTC, ETH, USDC, USDT, and ICP. Depending on the asset, users can transfer on its native chain or use a chain-key asset such as ckBTC or ckUSDC over ICP.
Rates, liquidity, fees, limits, transfer routes, and completion times change with live market and network conditions. Integrations need to read current SDK responses instead of hardcoding them.

The Liquidium SDK lets wallets, exchanges, portfolio tools, and other products put Liquidium borrowing and lending inside their own interface.

The package gives TypeScript applications one client for accountless Simple Loans, profile-based lending, market data, quotes, positions, activities, and history. Your product owns the user experience and wallet integration. Liquidium handles the protocol-specific requests and responses underneath.

This guide covers @liquidium/client@0.8.2, the latest stable release at the time of this update. Check the SDK changelog before shipping against a newer release.

What the Liquidium SDK covers

Install the stable package with npm install @liquidium/client. Import LiquidiumClient from the package and create a client with new LiquidiumClient() to use the production defaults.

The client exposes eight main modules:

simpleLoans creates, restores, finds, and tracks accountless loans.
accounts creates and resolves profiles and reads linked wallets.
lending handles Advanced supply, borrow, withdrawal, and repayment inflows.
positions reads balances, debt, borrowing power, and health.
market returns pools, prices, rates, liquidity, caps, and other reserve data.
quote calculates LTV and validates proposed loan amounts against current market inputs.
activities tracks active and completed operations.
history returns user, liquidation, and protocol activity.

The developer documentation has setup guides, examples, and the generated API reference.

Start with accountless Simple Loans

Simple Loans fit checkout-style borrowing. A user chooses collateral, the asset to borrow, and the destination and refund addresses. The SDK creates a generated backing profile and returns the loan reference plus the transfer instructions needed to fund and manage it.

Calling client.simpleLoans.create(...) or client.simpleLoans.get(...) does not require a profile ID, wallet adapter, or signed borrow message. The integrating product still needs to help the user send collateral, verify destination addresses, save the loan reference, and monitor the resulting status.

For a BTC-backed USDC loan using native Bitcoin collateral and Ethereum delivery, the integration sequence is:

Find the BTC and USDC pools with client.market.findPool(...) using Asset.BTC with Chain.BTC and Asset.USDC with Chain.ETH.
Fetch current prices and validate the proposed amounts and LTV.
Call client.simpleLoans.create(...) with the collateral pool, borrow pool, base-unit amounts, maximum LTV, deposit window, USDC destination, and BTC refund destination.
Read the native BTC funding quote from loan.initialDeposit.targets[Chain.BTC].
Save loan.ref and show the returned target address and fee-inclusive amount.

Use the working Simple Loans source for the complete request and error handling.

Transfer-target maps are partial. Your integration must check that the selected chain entry exists before showing an address or asking the user to send funds.

Save loan.ref as soon as the loan is created. Reload the loan with client.simpleLoans.get({ ref }) before displaying repayment instructions so the amount, fees, and repayment target are current.

For the user-facing flow, read the Simple Loan documentation.

Native-chain and ICP routes

The SDK separates the asset from the chain used for transfer. This matters because the same Liquidium pool can accept or deliver an asset through more than one rail.

BTC can move as native BTC on Bitcoin or as ckBTC over ICP.
ETH can move as native ETH on Ethereum or as ckETH over ICP.
USDC and USDT can move as ERC-20 tokens on Ethereum or as ckUSDC and ckUSDT over ICP.
ICP moves on ICP.

In SDK requests, use the underlying asset with an explicit chain. For example, use asset: Asset.BTC with chain: Chain.ICP for a ckBTC route. Do not use ckBTC as the asset value.

Native and chain-key representations share the underlying lending pool. A native ETH route and a ckETH route do not represent two separate ETH markets with separate rates.

Simple Loans expose available deposit and repayment routes through chain-keyed targets maps. Advanced supply flows also require an explicit chain. Check the returned route instead of assuming that every asset is available on every chain.

For address formats and current ckAsset behavior, use the ICP assets and Oisy documentation.

Use Advanced flows for persistent profiles

Profile-based flows fit applications that manage lending positions across sessions. They support profile creation, signed borrowing and withdrawal actions, supply and repayment inflows, position monitoring, and transaction history.

Advanced actions require more wallet orchestration than Simple Loans. Profile creation uses a signed authorization flow. Borrow and withdrawal actions also need a compatible signer. Supply can use a wallet-executed transfer, a generated deposit address, or an Ethereum contract interaction when the asset and route support it.

The SDK can read the wallets linked to a profile, but it does not expose general-purpose link and unlink methods. Products that need full account management should plan that work separately from the core lending integration.

Use the Advanced path when your product needs:

a persistent supply and borrow dashboard
several positions managed as one portfolio
health-factor and borrowing-power views
repeated signed borrow or withdrawal actions
native, ckAsset, deposit-address, or supported contract-interaction supply flows
user and protocol activity history

The Liquidium app follows the same product split. Simple Loans can be created while signed out. Advanced requires sign-in for persistent balances and positions. See Your Liquidium profile for the current app behavior.

Rates and liquidity are live inputs

An integration should never hardcode an APY, maximum borrow amount, pool limit, or completion time.

Liquidium rates change with pool utilization. Available liquidity, supply and borrow caps, frozen status, same-asset borrowing rules, and asset prices can also change. Use client.market.listPools() and client.market.getAssetPrices() immediately before calculating a quote or enabling an action.

Current pools expose estimated supply and borrow APYs. These estimates apply the current rate over a full year. They are not guaranteed future returns or fixed loan terms.

Network confirmation and protocol finalization times also vary. BTC, Ethereum, and ICP routes have different fee and confirmation behavior. Show the current status and estimate returned by the product rather than promising a fixed settlement time.

What builders can ship

The SDK supports more than a standalone lending page. A wallet can put a Simple Loan flow next to a user's assets. A portfolio product can combine balances with Liquidium position and health data. An exchange or treasury tool can create address-based borrowing flows without sending the user through a separate Liquidium interface.

The Liquidium integration in OISY is a live example of Liquidium lending inside a wallet experience.

The repository also ships examples for:

An included AI-agent integration skill documents the current modules, route rules, amount formatting, and signing requirements. Install it with npx skills add Liquidium-Inc/liquidium-sdk/skills/liquidium-sdk-integration.

Automated strategies and managed vault products can use the SDK as one part of their infrastructure. The SDK does not provide a ready-made vault engine, automated risk policy, or custody system. Teams building those products need their own execution service, monitoring, signing controls, and risk logic.

Build with Liquidium

Start with Simple Loans unless your product needs a persistent profile dashboard. Read the Liquidium SDK page, open the developer documentation, and use the GitHub repository for current examples and release notes.

FAQs

What is the Liquidium SDK?

The Liquidium SDK is the @liquidium/client TypeScript package. It exposes accountless Simple Loans, profile-based lending, market data, quotes, positions, activities, and history.

Do Simple Loan users need a Liquidium profile?

No. The SDK creates a generated backing profile for the loan. simpleLoans.create(...) and simpleLoans.get(...) do not require the user to create a profile, connect a wallet adapter, or sign a borrow message.

What is the difference between Simple and Advanced?

Simple Loans use a loan reference and dedicated transfer targets for a short, accountless borrow flow. Advanced uses a persistent profile for supplied balances, debt, portfolio health, repeated actions, and history.

Which assets does the SDK support?

The current public asset set is BTC, ETH, USDC, USDT, and ICP. Supported transfer chains depend on the asset and the returned route. Check live pool and target data before presenting an action.

Can the SDK use ckBTC or other ckAssets?

Yes. Use the underlying asset with Chain.ICP. The SDK can return ckBTC, ckETH, ckUSDC, and ckUSDT transfer targets where those routes are available.

Are borrow rates or completion times fixed?

No. Rates change with utilization, and available liquidity can change. Fees and completion times depend on the asset, transfer chain, network conditions, and protocol processing state.

Does the SDK include automated vault strategies?

No. Teams can build strategy or vault products around the SDK, but they must supply the automation, monitoring, signing controls, and risk policy.

Liquidium SDK Guide: Simple Loans and Advanced Flows