# Full Liquidation

> Markdown export of the Gearbox Protocol documentation page for agents and retrieval systems.

Canonical page: https://docs.gearbox.finance/developers/full-liquidation
Source file: content/developers/full-liquidation.mdx
Section router: https://docs.gearbox.finance/developers/llms.txt
Section full export: https://docs.gearbox.finance/developers/llms-full.txt

> **⚠ Preview SDK**
>
> This guide requires the SDK `next` release channel. [Install the preview
> SDK](https://docs.gearbox.finance/developers/sdk-setup#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](https://docs.gearbox.finance/developers/sdk-setup).
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](https://docs.gearbox.finance/developers/obtain-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](https://docs.gearbox.finance/developers/delayed-redemptions#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.

## Sources

- [Gearbox SDK](https://github.com/Gearbox-protocol/sdk)
- [Standard liquidation construction](https://github.com/Gearbox-protocol/periphery-v3/blob/af447ac4619ad7943d5aa7d6914dbce34a7b243e/contracts/compressors/LiquidationCompressor.sol#L100-L180)
- [Delayed-redemption liquidation construction](https://github.com/Gearbox-protocol/periphery-v3/blob/af447ac4619ad7943d5aa7d6914dbce34a7b243e/contracts/compressors/subcompressors/liquidation/SecuritizeLiquidationSubcompressor.sol)
- [`CreditFacadeV3.liquidateCreditAccount`](https://github.com/Gearbox-protocol/core-v3/blob/510fc6541c3767ce825929b4c311826fe81d6fa5/contracts/credit/CreditFacadeV3.sol#L280-L370)