Positions & Queries
Get Loan
Read a loan directly from the market contract
GET
/
lending-external-securities
/
api
/
positions
/
{marketId}
/
loan
/
{loanId}
curl "https://api.trusset.org/lending-external-securities/api/positions/{marketId}/loan/5" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities/api/positions/${marketId}/loan/5`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const liquidatable = data.active && parseFloat(data.healthFactor) < 1;
{
"success": true,
"data": {
"loanId": "5",
"borrower": "0xabc...def",
"collateralAmount": "1000.000000000000000000",
"principal": "50000.000000",
"accruedInterest": "128.750000",
"healthFactor": "1.842000000000000000",
"active": true,
"compliance": {
"mode": "FREEZE",
"holder": "0xabc...def",
"restricted": false,
"code": null,
"reason": null,
"collateralReturnable": true,
"willEscrowOnRelease": false,
"escrowedCollateral": null,
"escrowedCollateralRaw": null,
"holderVerified": true,
"holderAddressFrozen": false,
"tokenPaused": false,
"checkedAt": "2026-09-05T11:58:12.000Z"
}
}
}
{
"success": false,
"error": {
"code": "LOAN_NOT_FOUND",
"message": "Loan not found"
}
}
{
"success": false,
"error": {
"code": "INVALID_LOAN_ID",
"message": "Valid loan ID required"
}
}
Returns live loan state by numeric loan ID, read from the contract with no database involvement. Use this when you need authoritative figures for a payoff quote, a health check, or a liquidation decision.
Path Parameters
string
required
Market ID.
integer
required
On-chain loan ID. Must be a positive integer.
Response Fields
object
Show child attributes
Show child attributes
string
Loan ID, echoed back.
string
Borrower address.
string
Collateral pledged, in collateral token units.
string
Outstanding principal, in borrow asset units.
string
Interest accrued and unpaid, in borrow asset units.
string
Health factor at 18 decimal places.
1.0 is the liquidation boundary. null on a loan that is no longer active, because a closed loan has no health.boolean
Whether the loan is open.
false once it is repaid, closed, or fully liquidated.object
What the collateral token would currently permit for this borrower. See below.
null when the market records no collateral token, or when the probe could not run.Compliance
The collateral is a third-party security token whose issuer can freeze an address, revoke an identity, or pause the token after the loan opened. This block is that state, probed at request time. It is the difference between a loan that looks healthy and one whose collateral can actually be released.object
Show child attributes
Show child attributes
string
FREEZE or CUSTODY, the market’s collateral mode.string
The borrower this verdict is about, lowercased.
boolean
true when something would block the collateral moving. false when every probe answered and none did. null when the token does not answer the probes at all, which is unknown rather than clear.string
Machine-readable reason, when there is one.
string
One sentence naming what is blocking, or why the state could not be established.
boolean
Whether the token would accept a return of this collateral to the borrower right now.
null when unchecked.boolean
true when a release would be escrowed on the adapter rather than delivered, because the token would refuse the transfer. Custody markets only.string
Collateral already sitting in escrow for this holder, in collateral units. Custody markets only. Claim it with Claim Escrowed Collateral.
string
The same figure in base units.
boolean
Whether the borrower is still a verified identity on the token’s register.
null when unreadable.boolean
Whether the token has frozen this address.
null when unreadable.boolean
Whether the collateral token is paused.
null when unreadable.string
When this verdict was established. It does not move while the verdict is unchanged, so it reads as the age of the finding rather than the age of the request.
Treat
restricted: null as unknown, never as unrestricted. It means the collateral token answers neither the transfer probe nor the holder probes, so nothing about its compliance state has been established.Total payoff is
principal plus accruedInterest. Interest accrues per block, so add a small margin when quoting a full repayment. The contract caps repayment at the actual debt, so a slight overpayment is not transferred.curl "https://api.trusset.org/lending-external-securities/api/positions/{marketId}/loan/5" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities/api/positions/${marketId}/loan/5`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const liquidatable = data.active && parseFloat(data.healthFactor) < 1;
{
"success": true,
"data": {
"loanId": "5",
"borrower": "0xabc...def",
"collateralAmount": "1000.000000000000000000",
"principal": "50000.000000",
"accruedInterest": "128.750000",
"healthFactor": "1.842000000000000000",
"active": true,
"compliance": {
"mode": "FREEZE",
"holder": "0xabc...def",
"restricted": false,
"code": null,
"reason": null,
"collateralReturnable": true,
"willEscrowOnRelease": false,
"escrowedCollateral": null,
"escrowedCollateralRaw": null,
"holderVerified": true,
"holderAddressFrozen": false,
"tokenPaused": false,
"checkedAt": "2026-09-05T11:58:12.000Z"
}
}
}
{
"success": false,
"error": {
"code": "LOAN_NOT_FOUND",
"message": "Loan not found"
}
}
{
"success": false,
"error": {
"code": "INVALID_LOAN_ID",
"message": "Valid loan ID required"
}
}
⌘I
curl "https://api.trusset.org/lending-external-securities/api/positions/{marketId}/loan/5" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities/api/positions/${marketId}/loan/5`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const liquidatable = data.active && parseFloat(data.healthFactor) < 1;
{
"success": true,
"data": {
"loanId": "5",
"borrower": "0xabc...def",
"collateralAmount": "1000.000000000000000000",
"principal": "50000.000000",
"accruedInterest": "128.750000",
"healthFactor": "1.842000000000000000",
"active": true,
"compliance": {
"mode": "FREEZE",
"holder": "0xabc...def",
"restricted": false,
"code": null,
"reason": null,
"collateralReturnable": true,
"willEscrowOnRelease": false,
"escrowedCollateral": null,
"escrowedCollateralRaw": null,
"holderVerified": true,
"holderAddressFrozen": false,
"tokenPaused": false,
"checkedAt": "2026-09-05T11:58:12.000Z"
}
}
}
{
"success": false,
"error": {
"code": "LOAN_NOT_FOUND",
"message": "Loan not found"
}
}
{
"success": false,
"error": {
"code": "INVALID_LOAN_ID",
"message": "Valid loan ID required"
}
}