> ## 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.

# Settle Expired Auction

> Route unsold collateral from an expired auction to the liquidation router

Closes a Dutch auction that reached its end time without selling out, and transfers the unsold collateral to the market's liquidation router. This creates a pending liquidation and hands the position over to the manual settlement workflow.

Until this is called, an expired auction leaves the collateral in limbo: no longer purchasable, and not yet available for an off-platform sale.

<Warning>
  Requires the registered wallet to hold `LIQUIDATOR_ROLE` on the market, the same role [Liquidate Loan](/endpoints/external-securities-lending/liquidate) needs.
</Warning>

## Path Parameters

<ParamField path="marketId" type="string" required>Market ID.</ParamField>

## Body Parameters

<ParamField body="auctionId" type="integer" required>
  Auction ID. Must be a positive integer sent as a JSON number.
</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="txHash" type="string">Transaction hash. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="auctionId" type="integer">Auction ID, echoed back. Returned when confirming with `txHash`.</ResponseField>
    <ResponseField name="action" type="string">`SIGN_TRANSACTION` when `txHash` is omitted.</ResponseField>
    <ResponseField name="transaction" type="object">`{ to, data }` for the `settleExpiredAuction` call. Returned when `txHash` is omitted.</ResponseField>
  </Expandable>
</ResponseField>

## What Happens Next

After settlement the unsold collateral sits at the liquidation router as a `PENDING` liquidation, visible through [Get Pending Liquidations](/endpoints/external-securities-lending/get-pending-liquidations). From there the standard manual workflow applies: withdraw for sale, report proceeds, settle. The 7 day write-off clock starts at this point, not at the original liquidation.

<Note>
  If the market has no liquidation router configured, the contract releases the collateral back to the borrower and charges the outstanding debt to the insurance fund instead. Confirm router configuration through [Get Liquidation Config](/endpoints/external-securities-lending/get-liquidation-config) before letting auctions expire.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/{marketId}/settle-expired-auction" \
    -H "X-API-Key: trusset_your_key_here" \
    -H "Content-Type: application/json" \
    -d '{"auctionId": 3}'
  ```
</RequestExample>

<ResponseExample>
  ```json Calldata Response theme={null}
  {
    "success": true,
    "data": {
      "action": "SIGN_TRANSACTION",
      "transaction": { "to": "0x70A0...", "data": "0x..." },
      "functionName": "settleExpiredAuction"
    }
  }
  ```

  ```json Confirmed Response theme={null}
  {
    "success": true,
    "data": {
      "txHash": "0xabc...def",
      "auctionId": 3
    }
  }
  ```

  ```json Error - Missing Role theme={null}
  {
    "success": false,
    "error": {
      "code": "LIQUIDATOR_ROLE_MISSING",
      "message": "Issuer wallet 0x123...456 does not hold LIQUIDATOR_ROLE on market 0x70A0...9c2d. Grant it via the market configuration flow.",
      "calldata": {
        "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
        "data": "0x...",
        "description": "Grant LIQUIDATOR_ROLE to the issuer wallet (requires market DEFAULT_ADMIN_ROLE)"
      }
    }
  }
  ```

  ```json Error - Not Expired theme={null}
  {
    "success": false,
    "error": {
      "code": "SETTLE_PREFLIGHT_FAILED",
      "message": "Transaction reverted on-chain"
    }
  }
  ```
</ResponseExample>

## Errors

| Code                      | HTTP  | Cause                                                                             |
| ------------------------- | ----- | --------------------------------------------------------------------------------- |
| `LIQUIDATOR_ROLE_MISSING` | `400` | The registered wallet lacks `LIQUIDATOR_ROLE`. The error carries grant `calldata` |
| `RELAYER_NOT_CONFIGURED`  | `400` | No verified wallet is registered on this instance                                 |
| `SETTLE_PREFLIGHT_FAILED` | `400` | Simulation reverted. The auction has not expired, or was already settled          |
| `SETTLE_FAILED`           | `400` | The transaction failed on-chain                                                   |
| `NO_MARKET_ADDRESS`       | `400` | The market has no on-chain address recorded                                       |