Liquidations
Get Liquidatable Loans
List loans that can be liquidated now, on health or on an expired term
GET
/
lending-external-securities-v2
/
api
/
liquidations
/
{marketId}
/
liquidatable-loans
curl "https://api.trusset.org/lending-external-securities-v2/api/liquidations/{marketId}/liquidatable-loans" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/liquidatable-loans`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (data.onChainError) throw new Error(`Scan failed: ${data.onChainError}`);
const onTerm = data.liquidatableLoans.filter((loan) => loan.trigger !== 'HEALTH');
{
"success": true,
"data": {
"totalActiveLoans": 12,
"liquidatableLoans": [
{
"loanId": "7",
"borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"collateralAmount": "500.0",
"principal": "42000.0",
"accruedInterest": "318.4",
"healthFactor": "0.942",
"trigger": "HEALTH"
},
{
"loanId": "9",
"borrower": "0x4e1b2c93d07a5f68e3b9d15c02a7f4e6b8d31a90",
"collateralAmount": "220.0",
"principal": "15000.0",
"accruedInterest": "96.25",
"healthFactor": "1.61",
"trigger": "TERM",
"term": {
"dueAt": "1780300800",
"effectiveDueAt": "1780300800",
"graceEnd": "1780560000",
"enforceable": true
}
}
],
"termedLoans": [
{
"loanId": "9",
"borrower": "0x4e1b2c93d07a5f68e3b9d15c02a7f4e6b8d31a90",
"dueAt": "1780300800",
"effectiveDueAt": "1780300800",
"graceEnd": "1780560000",
"enforceable": true
}
],
"auctionedLoans": []
}
}
{
"success": true,
"data": {
"totalActiveLoans": 0,
"liquidatableLoans": [],
"termedLoans": [],
"auctionedLoans": []
}
}
Scans the market’s active loans and returns every loan that Liquidate Loan would accept now. A loan qualifies on either of two triggers. Its health factor is below
1.0, or its term has run past its effective due date plus the grace period, however healthy its collateral is. A market that makes open-ended loans has only the first trigger.
The first scan reads every loan the market has ever opened. Later scans read only the loans still known to be active plus any opened since, so the cost grows with the active book. Poll it on a schedule rather than per page view.
A failed chain read is not reported as an error. If the market’s loan counter cannot be read, the response carries
totalActiveLoans: 0 and empty lists. A loan whose own read fails is left out, and when the term reads fail, loans that qualify only on their term are missing too. An empty liquidatableLoans is therefore not proof that the book is healthy. onChainError appears only when composing the response fails after the reads.Path Parameters
string
required
The market’s record ID, as
id on List Markets, not its contract address. See Market IDs. At most 100 characters.Response Fields
object
Show child attributes
Show child attributes
integer
Active loans scanned.
array
Loans that qualify now on either trigger. A loan with an open auction, running or expired but not yet settled, is listed under
auctionedLoans instead.Show child attributes
Show child attributes
string
On-chain loan ID. Pass this to Liquidate Loan.
string
Borrower address.
string
Collateral pledged, in collateral token units.
string
Outstanding principal, in borrow asset units.
string
Accrued unpaid interest, in borrow asset units.
string
Health factor at 18 decimal places. At or above
1.0 when the loan qualifies on its term alone.string
HEALTH, TERM or HEALTH_AND_TERM. A loan realized on its term, whatever its health, is realized whole at the term penalty.object
The loan’s term, present when it carries one. Same fields as the entries of
termedLoans.array
Every active loan that carries a term, enforceable or not. Empty on a market that runs no loan terms.
Show child attributes
Show child attributes
string
On-chain loan ID.
string
Borrower address.
string
Unix seconds the loan falls due under its own term.
string
Unix seconds of the effective due date:
dueAt, or the market’s due floor when that is later.string
Unix seconds the grace period ends. After this the loan is liquidatable whatever its health.
boolean
Whether the term can be enforced now.
array
Active loans with a Dutch auction still open on the market’s auction venue.
liquidate refuses these until the auction clears or is settled after expiry.Show child attributes
Show child attributes
string
On-chain loan ID.
string
Borrower address.
string
The auction realizing this loan.
integer
Unix seconds when bidding closes.
boolean
string
Collateral still for sale, in collateral token units.
string
Debt the auction has not yet discharged, in borrow asset units.
string
The loan’s health factor at 18 decimal places.
string
Why the loan is not offered for liquidation, in words.
string
Present only when composing the response failed. The counter then reads
0 and liquidatableLoans is empty. See the warning above.Health factors are computed against the oracle’s stored price, and term enforceability against the time of the read. If the price is stale the health figures are stale too, and Liquidate Loan refuses every loan with
PRICE_STALE until a fresh price is on the oracle or the call carries an accepted signedPrice. Push a current price with Sync Oracle Price before acting on this list.curl "https://api.trusset.org/lending-external-securities-v2/api/liquidations/{marketId}/liquidatable-loans" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/liquidatable-loans`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (data.onChainError) throw new Error(`Scan failed: ${data.onChainError}`);
const onTerm = data.liquidatableLoans.filter((loan) => loan.trigger !== 'HEALTH');
{
"success": true,
"data": {
"totalActiveLoans": 12,
"liquidatableLoans": [
{
"loanId": "7",
"borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"collateralAmount": "500.0",
"principal": "42000.0",
"accruedInterest": "318.4",
"healthFactor": "0.942",
"trigger": "HEALTH"
},
{
"loanId": "9",
"borrower": "0x4e1b2c93d07a5f68e3b9d15c02a7f4e6b8d31a90",
"collateralAmount": "220.0",
"principal": "15000.0",
"accruedInterest": "96.25",
"healthFactor": "1.61",
"trigger": "TERM",
"term": {
"dueAt": "1780300800",
"effectiveDueAt": "1780300800",
"graceEnd": "1780560000",
"enforceable": true
}
}
],
"termedLoans": [
{
"loanId": "9",
"borrower": "0x4e1b2c93d07a5f68e3b9d15c02a7f4e6b8d31a90",
"dueAt": "1780300800",
"effectiveDueAt": "1780300800",
"graceEnd": "1780560000",
"enforceable": true
}
],
"auctionedLoans": []
}
}
{
"success": true,
"data": {
"totalActiveLoans": 0,
"liquidatableLoans": [],
"termedLoans": [],
"auctionedLoans": []
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
MISSING_MARKET_ID | 400 | marketId is longer than 100 characters |
NO_MARKET_ADDRESS | 400 | The market has no on-chain address recorded |
MARKET_NOT_FOUND | 404 | No market with this ID on your instance |
⌘I
curl "https://api.trusset.org/lending-external-securities-v2/api/liquidations/{marketId}/liquidatable-loans" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/liquidations/${marketId}/liquidatable-loans`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
if (data.onChainError) throw new Error(`Scan failed: ${data.onChainError}`);
const onTerm = data.liquidatableLoans.filter((loan) => loan.trigger !== 'HEALTH');
{
"success": true,
"data": {
"totalActiveLoans": 12,
"liquidatableLoans": [
{
"loanId": "7",
"borrower": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"collateralAmount": "500.0",
"principal": "42000.0",
"accruedInterest": "318.4",
"healthFactor": "0.942",
"trigger": "HEALTH"
},
{
"loanId": "9",
"borrower": "0x4e1b2c93d07a5f68e3b9d15c02a7f4e6b8d31a90",
"collateralAmount": "220.0",
"principal": "15000.0",
"accruedInterest": "96.25",
"healthFactor": "1.61",
"trigger": "TERM",
"term": {
"dueAt": "1780300800",
"effectiveDueAt": "1780300800",
"graceEnd": "1780560000",
"enforceable": true
}
}
],
"termedLoans": [
{
"loanId": "9",
"borrower": "0x4e1b2c93d07a5f68e3b9d15c02a7f4e6b8d31a90",
"dueAt": "1780300800",
"effectiveDueAt": "1780300800",
"graceEnd": "1780560000",
"enforceable": true
}
],
"auctionedLoans": []
}
}
{
"success": true,
"data": {
"totalActiveLoans": 0,
"liquidatableLoans": [],
"termedLoans": [],
"auctionedLoans": []
}
}