Trusset Protocol - Infrastructure for Asset Tokenization

POST

lending-external-securities

api

liquidations

{marketId}

liquidate

{loanId}

curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/{marketId}/liquidate/7" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

const res = await fetch(
  `https://api.trusset.org/lending-external-securities/api/liquidations/${marketId}/liquidate/7`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      signedPrice: {
        price: signed.price,
        timestamp: signed.timestamp,
        validUntil: signed.validUntil,
        signature: signed.signature
      }
    })
  }
);
const { data } = await res.json();

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": "14",
    "auctionId": null,
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "collateralSeized": "220.000000000000000000",
    "debtRepaid": "21159.200000",
    "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
  }
}

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": null,
    "auctionId": "3",
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "collateralSeized": null,
    "debtRepaid": null,
    "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
  }
}

{
  "success": true,
  "data": {
    "action": "SIGN_TRANSACTION",
    "transaction": {
      "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
      "data": "0x...",
      "value": "0",
      "chainId": 11155111
    },
    "functionName": "liquidate",
    "readiness": {
      "routerAddress": "0x067a3feea46649adad8e31c33b3a4d8774b8d8cf",
      "routerAuthorized": true,
      "routerTokenEligible": true,
      "operatorRoleReady": true,
      "liquidatorRoleReady": true,
      "signerAddress": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
      "collateralTransferChecked": true,
      "collateralTransferAllowed": true,
      "collateralTransferCode": null,
      "saleRecipient": "0x5a72e0b41d3f8c62079ae4b1d38f0c95261ba473",
      "saleDeliveryChecked": true,
      "saleDeliveryAllowed": true,
      "saleDeliveryCode": null,
      "priceStale": false,
      "priceAge": 184,
      "seizureConfigured": true,
      "isConfigured": true,
      "canSeizeNow": true,
      "canRealizeNow": true,
      "blockedReason": null
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LOAN_NOT_LIQUIDATABLE",
    "message": "Loan 7 is healthy: health factor 1.204813 is at or above the 1.0 liquidation threshold, so liquidate reverts.",
    "loan": {
      "loanId": "7",
      "active": true,
      "healthFactor": "1.204813",
      "healthFactorThreshold": "1.0",
      "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LIQUIDATION_NOT_READY",
    "message": "The liquidation router is not an eligible holder of the collateral token."
  }
}

Liquidates a loan whose health factor is below 1.0. What the transaction produces depends on the market’s useDutchAuction setting. With Dutch auctions disabled, collateral is seized and transferred to the market’s liquidation router, and a pending liquidation is created. The response carries liquidationId and collateralSeized, and settlement becomes a manual operator workflow. With Dutch auctions enabled, an auction is opened instead. The response carries auctionId and borrower, while liquidationId, collateralSeized, and debtRepaid are all null. No pending liquidation exists yet. One is created only if the auction expires unsold and is settled with Settle Expired Auction.

The signing wallet must hold LIQUIDATOR_ROLE on the market. Role state is reported in readiness but never blocks the calldata. You sign in your own environment, so the wallet this API knows about is not necessarily the one that will call. A wallet without the role has its transaction reverted on-chain rather than rejected here. Pass signerAddress to have readiness answer for the wallet you intend to use.

Path Parameters

string

required

Market ID.

integer

required

On-chain loan ID. Must be a positive integer.

Body Parameters

object

EIP-712 signed price from Sign Price, applied atomically with the liquidation. Omit to price against the stored oracle value. Nothing is signed on your behalf. A stale stored price is refused with PRICE_STALE. Either push a NAV with Sync Oracle Price, or supply a signedPrice here.

Show child attributes

string

Price in base units.

integer

Signing timestamp.

integer

Signature expiry.

string

EIP-712 signature.

string

Wallet you intend to liquidate with. Used to resolve readiness against that address rather than against your instance’s registered wallet. It does not appear in the transaction and does not gate it.

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.

Response Fields

Without txHash the response is the unsigned liquidate call, alongside a readiness object describing every gate the contract passes through.

object

Show child attributes

string

SIGN_TRANSACTION. Returned when txHash is omitted.

object

Unsigned transaction, { to, data, value, chainId }. Returned when txHash is omitted.

string

liquidate. Returned when txHash is omitted.

object

Realization readiness for this market. Returned when txHash is omitted, and also attached to the errors below.

Show child attributes

string

Liquidation router for this market.

boolean

Whether the router accepts seizures from this market.

boolean

Whether the collateral token permits the router to hold it.

boolean

Whether the resolved signer holds LIQUIDATOR_ROLE. Null when it could not be read.

boolean

Whether the resolved signer holds the router’s operator role.

string

The address readiness was resolved against.

boolean

Whether the token would allow the seizure transfer to the router. collateralTransferChecked and collateralTransferCode accompany it. See Transfer Restriction Codes.

string

Recipient the lender of record fixed for onward sale, or null.

boolean

Whether the token would allow the onward transfer to that recipient. saleDeliveryChecked and saleDeliveryCode accompany it.

boolean

Whether the oracle price is outside its window. priceAge in seconds accompanies it.

boolean

Whether every gate up to and including the seizure is satisfied.

boolean

Whether onward delivery to the sale recipient is also satisfied.

boolean

seizureConfigured and the price is not stale.

boolean

isConfigured and the price is not stale.

string

The first gate that fails, in words. Null when nothing blocks.

integer

Loan ID, echoed back. Returned when confirming with txHash.

string

Liquidation ID on the market’s router. Use this on every settlement endpoint. null in Dutch auction mode. Returned when confirming with txHash.

string

Dutch auction ID. null in instant liquidation mode. Returned when confirming with txHash.

string

Transaction hash. Returned when confirming with txHash.

string

Collateral moved to the router, in collateral token units. null in Dutch auction mode. Returned when confirming with txHash.

string

Debt covered by the seizure, in borrow asset units. null in Dutch auction mode. Returned when confirming with txHash.

string

Borrower address, or null when it could not be resolved. Returned when confirming with txHash.

Seizure Bounds

A liquidation does not close the whole loan. The amount seized is bounded by closeFactor, capping how much of the debt one call can repay, and marked up by liquidationPenalty. A deeply underwater loan therefore needs several liquidations to clear, or resolves through the auction path. There is no auto-sell for external securities. Once collateral reaches the router it stays there until an operator sells it and settles the proceeds. See Settle Liquidation.

curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/{marketId}/liquidate/7" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

const res = await fetch(
  `https://api.trusset.org/lending-external-securities/api/liquidations/${marketId}/liquidate/7`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      signedPrice: {
        price: signed.price,
        timestamp: signed.timestamp,
        validUntil: signed.validUntil,
        signature: signed.signature
      }
    })
  }
);
const { data } = await res.json();

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": "14",
    "auctionId": null,
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "collateralSeized": "220.000000000000000000",
    "debtRepaid": "21159.200000",
    "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
  }
}

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": null,
    "auctionId": "3",
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "collateralSeized": null,
    "debtRepaid": null,
    "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
  }
}

{
  "success": true,
  "data": {
    "action": "SIGN_TRANSACTION",
    "transaction": {
      "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
      "data": "0x...",
      "value": "0",
      "chainId": 11155111
    },
    "functionName": "liquidate",
    "readiness": {
      "routerAddress": "0x067a3feea46649adad8e31c33b3a4d8774b8d8cf",
      "routerAuthorized": true,
      "routerTokenEligible": true,
      "operatorRoleReady": true,
      "liquidatorRoleReady": true,
      "signerAddress": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
      "collateralTransferChecked": true,
      "collateralTransferAllowed": true,
      "collateralTransferCode": null,
      "saleRecipient": "0x5a72e0b41d3f8c62079ae4b1d38f0c95261ba473",
      "saleDeliveryChecked": true,
      "saleDeliveryAllowed": true,
      "saleDeliveryCode": null,
      "priceStale": false,
      "priceAge": 184,
      "seizureConfigured": true,
      "isConfigured": true,
      "canSeizeNow": true,
      "canRealizeNow": true,
      "blockedReason": null
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LOAN_NOT_LIQUIDATABLE",
    "message": "Loan 7 is healthy: health factor 1.204813 is at or above the 1.0 liquidation threshold, so liquidate reverts.",
    "loan": {
      "loanId": "7",
      "active": true,
      "healthFactor": "1.204813",
      "healthFactorThreshold": "1.0",
      "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LIQUIDATION_NOT_READY",
    "message": "The liquidation router is not an eligible holder of the collateral token."
  }
}

Error Codes

Errors raised while building calldata carry the full readiness object alongside code and message, so the failing gate can be inspected without a second call.

Code	HTTP	Cause
`MARKET_NOT_CONFIGURED`	`400`	The market has no address or no oracle recorded
`INVALID_LOAN_ID`	`400`	`loanId` is not a positive integer
`LIQUIDATION_NOT_READY`	`400`	The router is not authorized on the market, or the collateral token will not let the router hold the seized tokens
`COLLATERAL_TRANSFER_RESTRICTED`	`400`	The collateral token’s compliance rules block the seizure transfer to the router
`PRICE_STALE`	`400`	The oracle price is stale, so `liquidate` reverts. Push a NAV or supply a `signedPrice`
`LOAN_NOT_ACTIVE`	`400`	The loan is closed, so there is nothing to realize. The error carries `loan`
`LOAN_NOT_LIQUIDATABLE`	`400`	The loan’s health factor is at or above `1.0`. The error carries `loan`
`TX_NOT_VERIFIED`	`400`	The confirmed transaction liquidates a different loan
`LIQUIDATION_FAILED`	`400`	The liquidation could not be prepared or confirmed and no more specific code applied
`MARKET_NOT_FOUND`	`404`	No market with this ID on your instance

A missing LIQUIDATOR_ROLE shows as liquidatorRoleReady: false in readiness rather than as an error. Resolve it through Set Liquidator Role when the market admin drives the grant.

curl -X POST "https://api.trusset.org/lending-external-securities/api/liquidations/{marketId}/liquidate/7" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

const res = await fetch(
  `https://api.trusset.org/lending-external-securities/api/liquidations/${marketId}/liquidate/7`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'trusset_your_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      signedPrice: {
        price: signed.price,
        timestamp: signed.timestamp,
        validUntil: signed.validUntil,
        signature: signed.signature
      }
    })
  }
);
const { data } = await res.json();

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": "14",
    "auctionId": null,
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "collateralSeized": "220.000000000000000000",
    "debtRepaid": "21159.200000",
    "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
  }
}

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": null,
    "auctionId": "3",
    "txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
    "collateralSeized": null,
    "debtRepaid": null,
    "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
  }
}

{
  "success": true,
  "data": {
    "action": "SIGN_TRANSACTION",
    "transaction": {
      "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
      "data": "0x...",
      "value": "0",
      "chainId": 11155111
    },
    "functionName": "liquidate",
    "readiness": {
      "routerAddress": "0x067a3feea46649adad8e31c33b3a4d8774b8d8cf",
      "routerAuthorized": true,
      "routerTokenEligible": true,
      "operatorRoleReady": true,
      "liquidatorRoleReady": true,
      "signerAddress": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
      "collateralTransferChecked": true,
      "collateralTransferAllowed": true,
      "collateralTransferCode": null,
      "saleRecipient": "0x5a72e0b41d3f8c62079ae4b1d38f0c95261ba473",
      "saleDeliveryChecked": true,
      "saleDeliveryAllowed": true,
      "saleDeliveryCode": null,
      "priceStale": false,
      "priceAge": 184,
      "seizureConfigured": true,
      "isConfigured": true,
      "canSeizeNow": true,
      "canRealizeNow": true,
      "blockedReason": null
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LOAN_NOT_LIQUIDATABLE",
    "message": "Loan 7 is healthy: health factor 1.204813 is at or above the 1.0 liquidation threshold, so liquidate reverts.",
    "loan": {
      "loanId": "7",
      "active": true,
      "healthFactor": "1.204813",
      "healthFactorThreshold": "1.0",
      "borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LIQUIDATION_NOT_READY",
    "message": "The liquidation router is not an eligible holder of the collateral token."
  }
}

Overview

MiCA Register

Customers

Stock Tokenization

Trading

Stock Lending

External Securities Lending

Liquidate Loan

Path Parameters

Body Parameters

Response Fields

Seizure Bounds

Error Codes

​Path Parameters

​Body Parameters

​Response Fields

​Seizure Bounds

​Error Codes

Path Parameters

Body Parameters

Response Fields

Seizure Bounds

Error Codes