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();

if (data.auctionId) {
  // Dutch auction opened, monitor bids
} else {
  // collateral sits at the router, begin the settlement workflow
}

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

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": null,
    "auctionId": "3",
    "txHash": "0xabc...def",
    "collateralSeized": null,
    "debtRepaid": null,
    "borrower": "0xabc...def"
  }
}

{
  "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)"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LIQUIDATION_PREFLIGHT_FAILED",
    "message": "execution reverted: LoanStillHealthy"
  }
}

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. The calldata is returned whether or not it does, so a wallet without the role will have its transaction reverted on-chain rather than rejected here.

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. If the stored price is stale, the backend signs a fresh one automatically before executing.

Show child attributes

string

Price in base units.

integer

Signing timestamp.

integer

Signature expiry.

string

EIP-712 signature.

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

object

Show child attributes

integer

Loan ID, echoed back.

string

Global liquidation ID on the router. Use this on every settlement endpoint. null in Dutch auction mode.

string

Dutch auction ID. null in instant liquidation mode.

string

Transaction hash.

string

Collateral moved to the router, in collateral token units. null in Dutch auction mode.

string

Debt covered by the seizure, in borrow asset units. null in Dutch auction mode.

string

Borrower address, or null when it could not be resolved.

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();

if (data.auctionId) {
  // Dutch auction opened, monitor bids
} else {
  // collateral sits at the router, begin the settlement workflow
}

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

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": null,
    "auctionId": "3",
    "txHash": "0xabc...def",
    "collateralSeized": null,
    "debtRepaid": null,
    "borrower": "0xabc...def"
  }
}

{
  "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)"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LIQUIDATION_PREFLIGHT_FAILED",
    "message": "execution reverted: LoanStillHealthy"
  }
}

Errors

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
`LIQUIDATOR_ROLE_MISSING`	`400`	The registered wallet lacks `LIQUIDATOR_ROLE`. The error carries grant `calldata` for the market admin
`RELAYER_NOT_CONFIGURED`	`400`	No verified wallet is registered on this instance
`LIQUIDATION_PREFLIGHT_FAILED`	`400`	Gas estimation reverted. Most often the loan is still healthy, or the router cannot receive the collateral token
`LIQUIDATION_FAILED`	`400`	The transaction failed on-chain

LIQUIDATOR_ROLE_MISSING returns ready-to-sign calldata under error.calldata. You can also resolve it through Set Liquidator Role when the registered wallet holds the market admin role.

Get Liquidatable Loans

Get Pending Liquidations

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();

if (data.auctionId) {
  // Dutch auction opened, monitor bids
} else {
  // collateral sits at the router, begin the settlement workflow
}

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

{
  "success": true,
  "data": {
    "loanId": 7,
    "liquidationId": null,
    "auctionId": "3",
    "txHash": "0xabc...def",
    "collateralSeized": null,
    "debtRepaid": null,
    "borrower": "0xabc...def"
  }
}

{
  "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)"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "LIQUIDATION_PREFLIGHT_FAILED",
    "message": "execution reverted: LoanStillHealthy"
  }
}

Overview

MiCA Register

Customers

Stock Tokenization

Trading

Stock Lending

External Securities Lending

Liquidate Loan

Path Parameters

Body Parameters

Response Fields

Seizure Bounds

Errors

​Path Parameters

​Body Parameters

​Response Fields

​Seizure Bounds

​Errors

Path Parameters

Body Parameters

Response Fields

Seizure Bounds

Errors