Full Liquidation

⚠ Preview SDK

This guide requires the SDK next release channel. Install the preview SDK before using these APIs.

A full liquidation is a purchase of a Credit Account's complete collateral portfolio at the liquidation discount.

Text

required underlying = total collateral value × liquidation discount

The transaction sends that underlying from the liquidator to the Credit Account, transfers the account's enabled collateral balances to the liquidator, settles the debt, and closes the account.

This guide covers the Gearbox-specific steps for one liquidation attempt: find candidates, inspect one candidate, and obtain the execution payload.

Before continuing, install and attach the Gearbox SDK. The caller supplies these inputs:

Variable	Type	Meaning
`sdk`	`OnchainSDK`	Attached Gearbox SDK instance
`liquidator`	`Address`	Address that will pay for the liquidation and receive its outputs
`supportedMainCollateral`	`Address[]`	Main collateral assets used to shortlist accounts
`supportedRepaymentTokens`	`Address[]`	Tokens the liquidator is willing to pay

1. Find liquidatable accounts

getLiquidatableAccounts() returns unhealthy accounts and expired accounts with debt. Each result includes its creditAccount address, so no separate address discovery is required.

TypeScript

import { isAddressEqual } from "viem";

const collateralCandidates = await sdk.liquidations.getLiquidatableAccounts({
  assets: supportedMainCollateral,
});

const candidates = collateralCandidates.filter(candidate =>
  supportedRepaymentTokens.some(token =>
    isAddressEqual(token, candidate.repaymentAmount.token),
  ),
);

candidates is a LiquidatableAccount[]. Each candidate contains:

Field	Type	Meaning
`creditAccount`	`Address`	Credit Account to inspect or liquidate
`creditManager`	`Address`	Credit Manager in which the account is opened
`network`	`NetworkType`	Network on which the account exists
`asset`	`Address`	Main collateral asset used for discovery filtering
`totalValue.token`	`Address`	Token in which the account value is expressed
`totalValue.balance`	`bigint`	Estimated account value in that token's native decimals
`totalValueUSD`	`bigint`	Estimated account value in USD with 8 decimals
`repaymentAmount.token`	`Address`	Estimated payment token
`repaymentAmount.balance`	`bigint`	Estimated payment amount in that token's native decimals
`estimatedProfit.token`	`Address`	Token in which gross profit is estimated
`estimatedProfit.balance`	`bigint`	Gross profit estimate before gas and funding costs
`isDelayed`	`boolean`	Whether the account contains delayed-redemption collateral
`paused`	`boolean`	Whether its Credit Facade is paused

assets matches only candidate.asset, the account's main collateral. Use details.receivedAssets to validate the complete collateral portfolio. Candidate amounts are discovery estimates; use getLiquidationDetails() for the exact selected liquidation path before execution.

2. Inspect one candidate

Choose one candidate from the filtered candidates list. creditAccount is the address of that candidate's Credit Account, and details is its fresh liquidation preview for the supplied liquidator:

TypeScript

const candidate = candidates[0];
if (!candidate) throw new Error("No supported liquidation candidates");

const creditAccount = candidate.creditAccount;
const details = await sdk.liquidations.getLiquidationDetails({
  creditAccount,
  liquidator,
});

if (details.paused) throw new Error("Credit Facade is paused");
if (details.isCreditAccountFrozen) throw new Error("Credit Account is frozen");
if (!details.isLiquidatorEligible) {
  throw new Error(`Liquidator is not eligible for ${details.kycProtocol}`);
}
if (
  !supportedRepaymentTokens.some(token =>
    isAddressEqual(token, details.repaymentAmount.token),
  )
) {
  throw new Error("Unsupported payment token");
}

buildLiquidationTx() can be called without this step, but details is the pre-execution preview. Use it to verify the approval, exact payment, complete received-asset list, and eligibility before execution.

details is a preview, not a transaction:

Field	Type	Meaning
`repaymentAmount.token`	`Address`	ERC-20 the liquidator pays
`repaymentAmount.balance`	`bigint`	Exact payment amount in that token's native decimals
`receivedAssets`	`ReceivedAsset[]`	Complete list of immediate and delayed outputs
`receivedAssets[].isDelayed`	`boolean`	Whether this output settles after the liquidation transaction
`receivedAssets[].token`	`Address`	ERC-20 the liquidator receives now or after settlement
`receivedAssets[].amount`	`bigint`	Immediate amount, or exact/estimated delayed amount, in native decimals
`receivedAssets[].redeemerAddress`	`Address \| undefined`	Redeemer assigned to the liquidator for a delayed output
`receivedAssets[].claimableAt`	`bigint \| undefined`	Estimated settlement time; `undefined` means the output is immediate or claimable now
`approve.token`	`Address`	ERC-20 that must be approved, when approval is required
`approve.spender`	`Address`	Exact contract address that receives the allowance
`approve.amount`	`bigint`	Required allowance with the SDK's execution buffer
`estimatedProfit.token`	`Address`	Token in which gross profit is estimated
`estimatedProfit.balance`	`bigint`	Gross profit estimate before gas and funding costs, in the token's native decimals
`isLiquidatorEligible`	`boolean`	Whether this wallet may receive restricted assets
`isCreditAccountFrozen`	`boolean`	Whether frozen collateral prevents liquidation
`isDelayed`	`boolean`	Whether some proceeds settle after the liquidation transaction

The payment token is specific to the selected liquidation path. If details.approve.token is DefaultRWAUnderlying, the SDK builds the liquidation call but does not obtain that token for the liquidator. First obtain the RWA underlying by depositing its configured ERC-20 asset.

Some dedicated RWA liquidation paths accept the configured ERC-20 asset and wrap it during execution. In that case, details.approve.token already reports that asset. Always use the token, spender, and amount returned in details.approve for the selected path.

Use receivedAssets to confirm that the liquidator supports the complete outcome, rather than relying only on the main-asset discovery filter. When an item has isDelayed: true, redeemerAddress identifies the contract holding that redemption request. Executing the liquidation assigns the redeemer—and the future claim it represents—to the liquidator. See Preview before liquidation for the delayed-output workflow.

3. Obtain the execution payload

Build immediately before execution so that the SDK uses current prices and selects the correct liquidation contract. This call recomputes the liquidation data independently; it does not consume the details object:

TypeScript

const transaction = await sdk.liquidations.buildLiquidationTx({
  creditAccount,
  liquidator,
});

When details.approve is present, approve its token for its spender and amount. Use details.approve.spender as the approval target.

transaction contains the unsigned liquidation call. Pass the approval requirement and transaction to the operator's existing transaction pipeline, which handles allowance state, simulation, gas policy, signing, submission, and monitoring.

Integration boundary

This page provides Gearbox discovery, outcome inspection, approval requirements, and unsigned liquidation calldata. The operator's existing infrastructure owns execution and service operation.

Full Liquidation

1. Find liquidatable accounts

2. Inspect one candidate

3. Obtain the execution payload

Integration boundary

Sources