API reference

The SDK exports LiquidiumClient, error types, constants, module request types, response types, and wallet action types from @liquidium/client.

Client modules

The client provides the following modules:

Module	Purpose
client.accounts	Profile lifecycle, account lookup, and linked wallets
client.activities	Activity lists and receipt-oriented status
client.history	User history and confirmed protocol-wide activity through the Liquidium SDK API
client.simpleLoans	Accountless Simple Loans with generated deposit and repayment targets
client.lending	Supply, borrow, withdraw, recovery, and inflow reporting
client.liquidations	Candidate scanning, liquidation execution, and status lookup
client.market	Pools, prices, and pool rate lookups
client.positions	Per-pool positions, health, and aggregate stats
client.quote	Pure quote helpers from market inputs

Shared status types

Use LiquidiumStatus for flow state across Simple Loans, activities, lending responses, and history entries.

The following types define shared status data:

Type	Purpose
LiquidiumStatus	Operation, state, and optional confirmation progress
LiquidiumOperation	deposit, borrow, repayment, withdrawal, or liquidation
LiquidiumState	action_required, confirming, processing, active, completed, failed, or expired
Activity	Inflow or outflow activity returned by activity APIs
GetActivityStatusResponse	Found or missing result from client.activities.getStatus(...)

For UI guidance, see the status system.

For APR and estimated APY semantics, see market data.

Error behavior

Public SDK methods can reject with LiquidiumError. Branch on its stable LiquidiumErrorCode value instead of parsing message.

client.simpleLoans.create(...) can also reject with SimpleLoanCreatedError after the remote loan is created but before the SDK loads its hydrated state. Recover the loan with the error's loanId or ref. Do not call create(...) again.

For retry decisions and recovery code, see Handle errors.

Profile recovery

• client.lending.getRecoveryBalance(profileId, poolId) reads the live recovery balance in base units.
• client.lending.prepareRecovery(request) returns a RecoveryAction for BTC/ETH message signing.
• client.lending.recover(request) accepts a RecoverWithWalletRequest or RecoverWithIcpRequest and returns a RecoveryResult.

Recovery reads balances independently of positions and rejection history. A result contains the gross amount, ledgerCanisterId, recovery transfer blockIndex, and a processing status. It does not contain an activities API outflow ID. Except for the ICP pool, it does not confirm final wallet delivery. See Recover profile funds for authorization, fees, and tracking.

Liquidations

Use client.liquidations.scan(request) for cursor-based candidate discovery, client.liquidations.liquidate(request) for automatic debt-ledger allowance handling and execution, and client.liquidations.getLiquidation(liquidationId) for status lookup. Approval failures throw LiquidiumError with code LIQUIDATION_APPROVAL_FAILED; in this case, liquidation was not submitted.

minCollateralAmount is required in collateral-asset base units. The canister enforces it before transfer fees on bad-debt and hybrid paths only; normal collateral-backed liquidations ignore it and allow smaller partial fills. buyBadDebt defaults to false. Setting it to true permits bad-debt repayment but can still use the normal path. See Minimum collateral and partial fills.

The SDK exports these public types:

Type	Purpose
ScanLiquidationsRequest	Optional cursor, accounts to scan, and maximum candidates to return
LiquidationScanResult	Candidates, scanned account count, and next cursor
LiquidationCandidate	Liquidatable borrower, health factor, total debt, and pool positions
LiquidationCandidatePosition	Pool, asset, debt, collateral, threshold, bonus, and protocol fee
LiquidationCandidateAsset	Supported asset symbol or legacy SOL candidate symbol
ExecuteLiquidationRequest	Borrower, pools, debt amount, receiver, required minimum collateral, and optional bad-debt choice
LiquidationResult	Liquidation id, timestamp, amounts, assets, lifecycle state, and transfer states
LiquidationAmounts	Debt repaid and net collateral received in base units
LiquidationAsset	Chain-key ledger principal or unknown asset type
CkLiquidationAsset	Chain-key ledger route with its required ledger canister principal
UnknownLiquidationAsset	Asset route the lending canister cannot identify
LiquidationStatus	Progress, success, or failed lifecycle status
LiquidationProgressStatus	Pending or processing lifecycle state without an error
LiquidationSuccessStatus	Successful lifecycle state without an error
LiquidationFailedStatus	Failed lifecycle state with its required protocol error
LiquidationTransfer	Pending, successful, or failed collateral or change transfer
LiquidationPendingTransfer	Pending transfer without an error
LiquidationSuccessTransfer	Successful transfer without an error
LiquidationFailedTransfer	Failed transfer with its required error

See Liquidations for allowance, slippage, receiver, and refund requirements.

History

Use client.history.getUserTransactionHistory(profileId, filters?) for paginated profile transaction history. It accepts cursor, limit, market, poolId, operations, states, from, and to.

Use client.history.getLiquidationHistory(profileId, filters?) for paginated liquidation history. It accepts cursor, limit, market, poolId, from, and to.

Continue pagination with the opaque nextCursor value.

Use client.history.getProtocolActivity(filters?) for recent confirmed activity across the protocol. It calls GET /v2/history/activities, accepts poolId, operations, and limit, and returns an unpaginated array with each pool's asset, decimals, and base-unit amount. History and protocol activity entries expose txids?: string[].

Asset identifiers

AssetIdentifier is a union of named types for each supported asset and transfer-chain pair.

Type	Asset	Chain
BtcOnBtcAssetIdentifier	BTC	BTC
EthOnEthAssetIdentifier	ETH	ETH
UsdcOnEthAssetIdentifier	USDC	ETH
UsdtOnEthAssetIdentifier	USDT	ETH
BtcOnIcpAssetIdentifier	BTC	ICP
EthOnIcpAssetIdentifier	ETH	ICP
IcpOnIcpAssetIdentifier	ICP	ICP
UsdcOnIcpAssetIdentifier	USDC	ICP
UsdtOnIcpAssetIdentifier	USDT	ICP

Generated reference

The generated API reference is built from the @liquidium/client exports.

Regenerate it with TypeDoc and typedoc-plugin-markdown after changing exported APIs:

pnpm docs:api