> ## 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>
  The signing wallet must hold `LIQUIDATOR_ROLE` on the market, the same role [Liquidate Loan](/endpoints/lending/liquidate) needs. The check only runs when you pass `signerAddress`; without it the calldata is returned regardless and a wallet without the role has its transaction reverted on-chain.
</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="signerAddress" type="string">
  Wallet you intend to settle with. Supplying it turns on a `LIQUIDATOR_ROLE` check against that address, so the call is refused with `LIQUIDATOR_ROLE_MISSING` rather than handing back calldata that reverts. Omit it and no role check runs, because you sign in your own environment and the wallet this API knows about is not necessarily the one that will call.
</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="auctionId" type="integer">Auction ID, echoed back.</ResponseField>
    <ResponseField name="success" type="boolean">Nested inside `data` on the calldata response.</ResponseField>
    <ResponseField name="action" type="string">`SIGN_TRANSACTION` when `txHash` is omitted.</ResponseField>
    <ResponseField name="transaction" type="object">Unsigned transaction, `{ to, data, value, chainId }`, for the `settleExpiredAuction` call. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="functionName" type="string">`settleExpiredAuction`. Returned when `txHash` is omitted.</ResponseField>
    <ResponseField name="txHash" type="string">Transaction hash. Returned when confirming with `txHash`.</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/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/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": "Wallet 0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52 does not hold LIQUIDATOR_ROLE on market 0x70a0e25c7b768b87e658348b3b577678a173e038. Grant it via the roles flow.",
      "calldata": {
        "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
        "data": "0x...",
        "description": "Grant LIQUIDATOR_ROLE to 0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52 (requires market DEFAULT_ADMIN_ROLE)"
      }
    }
  }
  ```

  ```json Error - Not Expired theme={null}
  {
    "success": false,
    "error": {
      "code": "AUCTION_NOT_EXPIRED",
      "message": "An auction can only be settled after it expires. Auction 3 runs until 2025-06-15T14:00:00.000Z, in 42 minutes. Bid on it to clear it sooner, or retry after that time.",
      "eligibleAt": "2025-06-15T14:00:00.000Z"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code                        | HTTP  | Cause                                                                                        |
| --------------------------- | ----- | -------------------------------------------------------------------------------------------- |
| `NO_MARKET_ADDRESS`         | `400` | The market has no on-chain address recorded                                                  |
| `VALIDATION_ERROR`          | `400` | `auctionId` is not a positive integer, or `signerAddress` is not a valid address             |
| `AUCTION_NOT_ACTIVE`        | `400` | The auction was already fully bought or settled, so settling it again reverts                |
| `AUCTION_NOT_EXPIRED`       | `400` | The auction is still running. The error carries `eligibleAt`                                 |
| `LIQUIDATOR_ROLE_MISSING`   | `400` | `signerAddress` was supplied and lacks `LIQUIDATOR_ROLE`. The error carries grant `calldata` |
| `WALLET_NOT_CONFIGURED`     | `400` | No signer wallet could be resolved for the role check                                        |
| `TX_NOT_VERIFIED`           | `400` | The confirmed transaction settles a different auction                                        |
| `AUCTION_STATE_UNAVAILABLE` | `400` | The auction could not be read on-chain, so whether it has expired is unknown. Retry shortly  |
| `SETTLE_FAILED`             | `400` | The settlement could not be prepared or confirmed and no more specific code applied          |
| `MARKET_NOT_FOUND`          | `404` | No market with this ID on your instance                                                      |