Positions & Queries
List Positions
List every borrowing position recorded for a market
GET
/
lending-external-securities-v2
/
api
/
positions
/
{marketId}
/
positions
curl "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/positions" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/positions`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const atRisk = data.positions.filter(
p => (p.healthFactor !== null && parseFloat(p.healthFactor) < 1.1) || p.term?.enforceable === true
);
{
"success": true,
"data": {
"positions": [
{
"id": "secpos_014",
"marketId": "clx_secmarket_001",
"onChainLoanId": "5",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"payeeAddress": null,
"payeeCustomer": null,
"customerId": null,
"customerAttributedAt": null,
"collateralAmount": "1000.0",
"borrowedAmount": "50000.0",
"interestAccrued": "961.643835",
"healthFactor": "1.842",
"priceAtBorrow": "104.82",
"dueAt": "1796630400",
"fixedRate": "650",
"status": "ACTIVE",
"liquidated": false,
"liquidatedAt": null,
"closedAt": null,
"openedAt": "2026-06-10T08:00:00.000Z",
"lastUpdated": "2026-09-26T11:58:00.000Z",
"transactions": [
{
"id": "sectx_002",
"marketId": "clx_secmarket_001",
"positionId": "secpos_014",
"txType": "BORROW",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "50000.0",
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"timestamp": "2026-06-10T08:00:00.000Z"
},
{
"id": "sectx_001",
"marketId": "clx_secmarket_001",
"positionId": "secpos_014",
"txType": "DEPOSIT",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "1000.0",
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"timestamp": "2026-06-10T08:00:00.000Z"
}
],
"term": {
"dueAt": "1796630400",
"effectiveDueAt": "1796630400",
"graceEnd": "1796889600",
"enforceable": false,
"termGracePeriod": "259200",
"termPenaltyBps": 300,
"stamped": true,
"termSource": "STAMPED"
},
"fixedRateBps": 650,
"compliance": {
"mode": "FREEZE",
"holder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"restricted": false,
"code": null,
"reason": null,
"collateralReturnable": true,
"willEscrowOnRelease": false,
"escrowedCollateral": null,
"escrowedCollateralRaw": null,
"holderVerified": true,
"holderAddressFrozen": false,
"tokenPaused": false,
"checkedAt": "2026-09-26T11:58:12.000Z"
}
}
]
}
}
Returns every position recorded for a market, newest first, each with its five most recent transactions. There is no pagination: the whole book comes back in one response.
The endpoint reconciles against the chain in two steps before it answers. First, an event sweep records loans opened by any wallet and writes terminal statuses from the
LoanClosed and LoanLiquidated events and auction starts it finds. The sweep runs at most once a minute per market.
Second, a live read of the open positions pulls collateral, principal, interest, health factor, due date and stamped rate from the market contract and writes them back to the records. If the chain is unreachable, both steps are skipped and stored values are returned unchanged.
Live state is fetched for the first 50 open positions only. Beyond that the stored values are served, so a market with more than 50 open loans returns a mix. The compliance block is attached to those open positions for at most 25 distinct borrowers.
status is never inferred from the live read. A terminal label is written only by the confirm calls and the event sweep that can attest to it. A loan the chain reports as closed therefore keeps its recorded status until its evidence arrives.
Path Parameters
string
required
Response Fields
object
Show child attributes
Show child attributes
array
Position records ordered by
openedAt descending.Show child attributes
Show child attributes
string
Position ID. Use it with Get Position and Get Position Statement.
string
Market ID.
string
Numeric loan ID on the market contract. Null when the position was recorded without a linked chain loan.
string
Borrower address, lowercased.
string
The wallet the market pays this loan’s draws to when it was opened with a
payToAddress, lowercased. Null when the loan pays its borrower. See Pay the proceeds to another wallet.object
The customer of your instance that holds the payee wallet, as its primary or a linked wallet:
id, name, country, status, customerType, investorType, verifiedAt, externalId and linkedWallet. Null when the loan has no payee or no customer of your instance holds the wallet.string
string
ISO 8601 timestamp the attribution was made or last moved. Null when the loan is unattributed.
string
Collateral posted, in collateral token units.
string
Outstanding principal, in borrow asset units.
string
Interest accrued and unpaid, in borrow asset units.
string
Health factor as a decimal string. At or above
1.0 the loan is healthy, below 1.0 it is liquidatable on health. Null once the status is not ACTIVE, and for an open loan with no debt.string
Collateral price recorded when the loan was opened, in borrow asset units.
string
Unix seconds this loan falls due, as last read from the chain. Null on an open-ended loan, and until a live read has recorded it.
string
The stamped rate in basis points as stored on the record. Null until a live read has recorded it.
string
One of
ACTIVE, REPAID, LIQUIDATED.boolean
Whether any collateral was seized from this position. A partial liquidation sets it while
status stays ACTIVE.string
ISO 8601 timestamp of the first seizure, or null.
string
ISO 8601 timestamp of closure, or null.
string
ISO 8601 timestamp the loan opened. It is the block time of the opening transaction where known, otherwise the time the record was written.
string
ISO 8601 timestamp of the last write.
array
The five most recent transactions on this position, newest first. Each carries
id, marketId, positionId, txType, userAddress, amount, txHash and timestamp.object
The loan’s term state, with the same fields as
term on Get Loan: dueAt, effectiveDueAt, graceEnd, enforceable, termGracePeriod, termPenaltyBps, stamped and termSource. Present only when this response read the loan from the chain, which covers at most the first 50 open and the first 50 closed positions. Absent or null on an open-ended loan. enforceable is the term trigger: true once the grace period after the effective due date has run out, whatever the health factor.integer
The rate stamped on this loan when it opened, in basis points.
0 when the market’s rate model was not in FIXED mode at signing. Present under the same condition as term.Positions are recorded when a loan is opened through this API on confirm, and are backfilled from chain events by the sweep. A loan opened by a wallet signing calldata directly is picked up by the next sweep, rather than at broadcast time.
curl "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/positions" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/positions`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const atRisk = data.positions.filter(
p => (p.healthFactor !== null && parseFloat(p.healthFactor) < 1.1) || p.term?.enforceable === true
);
{
"success": true,
"data": {
"positions": [
{
"id": "secpos_014",
"marketId": "clx_secmarket_001",
"onChainLoanId": "5",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"payeeAddress": null,
"payeeCustomer": null,
"customerId": null,
"customerAttributedAt": null,
"collateralAmount": "1000.0",
"borrowedAmount": "50000.0",
"interestAccrued": "961.643835",
"healthFactor": "1.842",
"priceAtBorrow": "104.82",
"dueAt": "1796630400",
"fixedRate": "650",
"status": "ACTIVE",
"liquidated": false,
"liquidatedAt": null,
"closedAt": null,
"openedAt": "2026-06-10T08:00:00.000Z",
"lastUpdated": "2026-09-26T11:58:00.000Z",
"transactions": [
{
"id": "sectx_002",
"marketId": "clx_secmarket_001",
"positionId": "secpos_014",
"txType": "BORROW",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "50000.0",
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"timestamp": "2026-06-10T08:00:00.000Z"
},
{
"id": "sectx_001",
"marketId": "clx_secmarket_001",
"positionId": "secpos_014",
"txType": "DEPOSIT",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "1000.0",
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"timestamp": "2026-06-10T08:00:00.000Z"
}
],
"term": {
"dueAt": "1796630400",
"effectiveDueAt": "1796630400",
"graceEnd": "1796889600",
"enforceable": false,
"termGracePeriod": "259200",
"termPenaltyBps": 300,
"stamped": true,
"termSource": "STAMPED"
},
"fixedRateBps": 650,
"compliance": {
"mode": "FREEZE",
"holder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"restricted": false,
"code": null,
"reason": null,
"collateralReturnable": true,
"willEscrowOnRelease": false,
"escrowedCollateral": null,
"escrowedCollateralRaw": null,
"holderVerified": true,
"holderAddressFrozen": false,
"tokenPaused": false,
"checkedAt": "2026-09-26T11:58:12.000Z"
}
}
]
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
MISSING_MARKET_ID | 400 | The market ID is longer than 100 characters |
MARKET_NOT_FOUND | 404 | No market with this ID on your instance |
⌘I
curl "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/positions" \
-H "X-API-Key: trusset_your_key_here"
const res = await fetch(
`https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/positions`,
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const atRisk = data.positions.filter(
p => (p.healthFactor !== null && parseFloat(p.healthFactor) < 1.1) || p.term?.enforceable === true
);
{
"success": true,
"data": {
"positions": [
{
"id": "secpos_014",
"marketId": "clx_secmarket_001",
"onChainLoanId": "5",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"payeeAddress": null,
"payeeCustomer": null,
"customerId": null,
"customerAttributedAt": null,
"collateralAmount": "1000.0",
"borrowedAmount": "50000.0",
"interestAccrued": "961.643835",
"healthFactor": "1.842",
"priceAtBorrow": "104.82",
"dueAt": "1796630400",
"fixedRate": "650",
"status": "ACTIVE",
"liquidated": false,
"liquidatedAt": null,
"closedAt": null,
"openedAt": "2026-06-10T08:00:00.000Z",
"lastUpdated": "2026-09-26T11:58:00.000Z",
"transactions": [
{
"id": "sectx_002",
"marketId": "clx_secmarket_001",
"positionId": "secpos_014",
"txType": "BORROW",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "50000.0",
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"timestamp": "2026-06-10T08:00:00.000Z"
},
{
"id": "sectx_001",
"marketId": "clx_secmarket_001",
"positionId": "secpos_014",
"txType": "DEPOSIT",
"userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "1000.0",
"txHash": "0x9f2c41d8b7e05a3164c2870fbd935e1a4c7802db6135ea9048f7c21b5d3ea41b",
"timestamp": "2026-06-10T08:00:00.000Z"
}
],
"term": {
"dueAt": "1796630400",
"effectiveDueAt": "1796630400",
"graceEnd": "1796889600",
"enforceable": false,
"termGracePeriod": "259200",
"termPenaltyBps": 300,
"stamped": true,
"termSource": "STAMPED"
},
"fixedRateBps": 650,
"compliance": {
"mode": "FREEZE",
"holder": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"restricted": false,
"code": null,
"reason": null,
"collateralReturnable": true,
"willEscrowOnRelease": false,
"escrowedCollateral": null,
"escrowedCollateralRaw": null,
"holderVerified": true,
"holderAddressFrozen": false,
"tokenPaused": false,
"checkedAt": "2026-09-26T11:58:12.000Z"
}
}
]
}
}