> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle Liquidation Timeout

> Write off a liquidation that could not be settled within 7 days

Writes off a liquidation the operator was unable to settle. The market clears the outstanding debt, draws on the insurance fund to cover it, and reconciles the pool's liquidity. The record moves to `WRITTEN_OFF`.

This is a loss-recognition step, not a recovery step. Use it when collateral proved unsellable within the window, or when a sale realised nothing.

<Warning>
  Write-off does not touch the liquidation router. Whatever collateral the router still holds stays there, and the backend will refuse further action on the record because `WRITTEN_OFF` is terminal. Dispose of or return the collateral before calling this, otherwise it is stranded.
</Warning>

## Path Parameters

<ParamField path="liquidationId" type="string" required>
  Liquidation ID on the market's router. The market-local ID needed on-chain is resolved automatically.
</ParamField>

## Body Parameters

<ParamField body="marketId" type="string">
  Names the market whose liquidation you mean. Every market runs its own liquidation router and IDs restart at `1` on each of them, so the same `liquidationId` can exist on several markets in one instance. Supply this when it does, otherwise the call is refused with `AMBIGUOUS_LIQUIDATION_ID` and the response lists the candidates.
</ParamField>

<ParamField body="txHash" type="string">
  Hash of the transaction you broadcast for this operation. Send it to confirm the transaction and record the result. Omit it to receive the calldata.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="liquidationId" type="string">Router liquidation ID, echoed back.</ResponseField>
    <ResponseField name="marketLiquidationId" type="string">Market-local ID the contract call used. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="txHash" type="string">Transaction hash. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="success" type="boolean">Nested inside `data` on the calldata response.</ResponseField>
    <ResponseField name="action" type="string">`SIGN_TRANSACTION`. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="transaction" type="object">Unsigned transaction, `{ to, data, value, chainId }`, targeting the market contract. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="functionName" type="string">`handleLiquidationTimeout`. Returned when `txHash` is omitted.</ResponseField>
  </Expandable>
</ResponseField>

## The 7 Day Window

The clock starts when the router receives the collateral, which is `onChainData.timestamp` on [Get Pending Liquidations](/endpoints/lending/get-pending-liquidations). Calling before the window has elapsed is refused with `LIQUIDATION_NOT_TIMED_OUT`, and the error carries `eligibleAt` so the retry time is exact.

## What the Write-Off Does

<Steps>
  <Step title="Close the pending liquidation">
    The market marks its pending liquidation settled so the debt stops counting against `pendingLiquidationDebt`.
  </Step>

  <Step title="Draw on the insurance fund">
    The outstanding debt is presented to the market's insurance fund, which covers as much as its balance allows.
  </Step>

  <Step title="Reconcile the pool">
    Any shortfall between the covered amount and the principal is deducted from pool liquidity. Liquidity providers absorb what the insurance fund could not.
  </Step>
</Steps>

<Warning>
  This call requires the signing wallet to hold `DEFAULT_ADMIN_ROLE` on the market contract, which is a higher privilege than the `LIQUIDATOR_ROLE` and router `OPERATOR_ROLE` the other liquidation endpoints need. Unlike those endpoints, a missing role is not detected in advance and carries no remediation calldata: it reverts on-chain and surfaces as `TIMEOUT_TX_REVERTED`. Confirm the wallet holds market admin before relying on this path.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/handle-timeout/14" \
    -H "X-API-Key: trusset_your_key_here" \
    -H "Content-Type: application/json"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/lending-external-securities/api/liquidations/handle-timeout/${liquidationId}`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'trusset_your_key_here',
        'Content-Type': 'application/json'
      }
    }
  );
  const { success, data, error } = await res.json();
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "liquidationId": "14",
      "marketLiquidationId": "2",
      "txHash": "0xabc...def"
    }
  }
  ```

  ```json Error - Too Early theme={null}
  {
    "success": false,
    "error": {
      "code": "LIQUIDATION_NOT_TIMED_OUT",
      "message": "Liquidation 14 cannot be written off yet.",
      "eligibleAt": "2025-06-22T11:30:00.000Z"
    }
  }
  ```

  ```json Error - Already Resolved theme={null}
  {
    "success": false,
    "error": {
      "code": "ALREADY_SETTLED",
      "message": "Already settled or written off"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                        | HTTP  | Cause                                                                                                           |
| --------------------------- | ----- | --------------------------------------------------------------------------------------------------------------- |
| `MISSING_ID`                | `400` | No liquidation ID in the path                                                                                   |
| `AMBIGUOUS_LIQUIDATION_ID`  | `400` | This ID exists on more than one market in your instance. The error carries `candidates`; resend with `marketId` |
| `ALREADY_SETTLED`           | `400` | The liquidation is already settled or written off                                                               |
| `LIQUIDATION_NOT_TIMED_OUT` | `400` | The window has not elapsed. The error carries `eligibleAt`                                                      |
| `TX_NOT_VERIFIED`           | `400` | The confirmed transaction targets a different liquidation                                                       |
| `TIMEOUT_TX_REVERTED`       | `400` | The write-off reverted. `error.txHash` carries the hash when one exists                                         |
| `TIMEOUT_FAILED`            | `400` | The write-off could not be prepared and no more specific code applied                                           |
| `LIQUIDATION_NOT_FOUND`     | `404` | No liquidation with that ID on your instance, and none could be adopted from chain                              |
| `MARKET_NOT_FOUND`          | `404` | `marketId` was supplied but names no market on your instance                                                    |