Trusset Protocol - Infrastructure for Asset Tokenization

GET

lending-external-securities-v2

api

positions

{marketId}

positions

{positionId}

curl "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/positions/{positionId}" \
  -H "X-API-Key: trusset_your_key_here"

const res = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/positions/${positionId}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const surplusToClaim = data.surplus?.claimable === true ? data.surplus.escrowed : null;

{
  "success": true,
  "data": {
    "positionId": "secpos_014",
    "onChainLoanId": "5",
    "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "payeeAddress": null,
    "payeeCustomer": null,
    "borrowedAmount": "50000.0",
    "collateralAmount": "1000.0",
    "accumulatedInterest": "961.643835",
    "healthFactor": "1.842",
    "priceAtBorrow": "104.82",
    "currentPrice": "109.4",
    "collateralValue": "109400",
    "collateralValueAtBorrow": "104820",
    "dueAt": "1796630400",
    "term": {
      "dueAt": "1796630400",
      "effectiveDueAt": "1796630400",
      "graceEnd": "1796889600",
      "enforceable": false,
      "termGracePeriod": "259200",
      "termPenaltyBps": 300,
      "stamped": true,
      "termSource": "STAMPED"
    },
    "fixedRateBps": 650,
    "customerId": null,
    "customerAttributedAt": null,
    "status": "ACTIVE",
    "openedAt": "2026-06-10T08:00:00.000Z",
    "closedAt": null,
    "liquidatedAt": null,
    "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"
    },
    "surplus": {
      "returned": "0.000000",
      "escrowed": null,
      "claimable": false,
      "escrowReadFailed": false
    },
    "realizationLoss": null,
    "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",
        "recordedByThisInstance": true
      },
      {
        "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",
        "recordedByThisInstance": true
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "POSITION_NOT_FOUND",
    "message": "Position not found"
  }
}

Returns a single position record merged with live loan data from the market contract, plus every transaction recorded against it. This is the endpoint behind a position detail view. On-chain values take precedence where a linked onChainLoanId exists. Stored values are used as a fallback when the chain read returns nothing. Unlike List Positions, this read does not write the chain figures back to the record.

Path Parameters

string

required

The market’s record ID, as id on List Markets, not its contract address. See Market IDs.

string

required

Position ID, from List Positions. A position of another market returns POSITION_NOT_FOUND.

Response Fields

object

Show child attributes

string

Position record ID.

string

Numeric loan ID on the market contract, or null when the position has no 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

Outstanding principal in borrow asset units.

string

Collateral pledged, in collateral token units.

string

Interest accrued and unpaid, in borrow asset units. The same figure is named interestAccrued on List Positions.

string

Health factor as a decimal string. Below 1.0 the loan is liquidatable on health. Null once the recorded 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. Useful for computing price movement since origination.

string

The price the market’s oracle currently stores, in borrow asset units. It is not checked for staleness here. Null when the market has no configured oracle or the price is zero or unreadable.

string

collateralAmount valued at currentPrice, in borrow asset units. Null when there is no current price.

string

collateralAmount valued at priceAtBorrow. It prices the collateral held now at the opening price, not the collateral posted at opening.

string

Unix seconds the loan falls due, from the chain where readable and the stored record otherwise. Null on an open-ended loan.

object

The loan’s term state, with the same fields as term on Get Loan: dueAt, effectiveDueAt, graceEnd, enforceable, termGracePeriod, termPenaltyBps, stamped and termSource. Null on an open-ended loan, or when the chain read returned nothing.

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. Falls back to the stored rate, and is null when neither is known.

string

The customer this loan is attributed to, set when Open Loan was confirmed with a clientReference. Null when the loan is unattributed.

string

ISO 8601 timestamp the attribution was made or last moved. Null when the loan is unattributed.

string

ACTIVE, REPAID, or LIQUIDATED.

string

ISO 8601 timestamp the loan opened.

string

ISO 8601 timestamp the position closed, or null.

string

ISO 8601 timestamp of the first seizure, or null.

object

What the collateral token would currently permit for this borrower. It says whether the address is frozen, the identity still verified, or the token paused, and whether a release would be delivered or escrowed. Identical in shape to the block on Get Loan, where each field is described. null when the probe could not run.

object

Realization surplus: sale or auction proceeds above the debt plus penalty, which belong to the borrower. Null when it could not be assembled.

Show child attributes

string

Surplus paid out to the borrower for this loan, summed from its history, in borrow asset units.

string

Surplus the market holds in escrow for this borrower’s address, in borrow asset units. It covers every loan of the address on this market, not this loan alone. Read only when collateral was seized from this position, and null otherwise.

boolean

true when escrowed is above zero. Claim it with Claim Surplus.

boolean

true when collateral was seized but the escrow could not be read, so a null escrowed means unknown rather than none.

object

What the realizations of this loan’s collateral cost the market, summed over its liquidation records, in borrow asset units. Read only when collateral was seized from this position. Null otherwise, and when no liquidation record of the loan is on file or the figures could not be assembled.

Show child attributes

integer

Liquidation records found for this loan.

integer

Records not yet settled or written off.

boolean

false when the market’s record of a liquidation could not be read, so the sums below may be short.

string

Debt the market wrote off at seizure because the collateral did not cover it.

string

The part of that write-off the insurance reserve paid.

string

Principal the liquidity pool absorbed at settlement because the proceeds and the insurance reserve together fell short.

string

What the insurance reserve paid at settlement.

string

The loss the liquidity pool bears: the write-off at seizure the reserve did not pay, plus the settlement shortfall.

object

symbol and decimals of the borrow asset.

array

Every transaction on this loan, newest first, up to 1,000 rows. Each carries id, marketId, positionId, txType, userAddress, amount, txHash and timestamp. Where another Trusset instance on the same network also tracks this market, its rows for the same loan are merged in once per transaction. recordedByThisInstance tells them apart, and a row recorded only by the other instance carries null marketId and positionId. A claim of escrowed collateral appears as ESCROW_CLAIMED. On a loan with escrowed collateral, a claim the custody adapter paid out that is not yet on record is read from the chain and booked by this call.

status is read from the stored record and is not re-derived from chain state here. A loan repaid without a confirm call can still read ACTIVE until the next reconciliation pass. For a live view of whether the loan is open, read active from Get Loan. List Positions also reconciles before it returns.

A printable record of the same loan, with every transaction verified against the chain, is available from Get Position Statement.

curl "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/positions/{positionId}" \
  -H "X-API-Key: trusset_your_key_here"

const res = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/positions/${positionId}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const surplusToClaim = data.surplus?.claimable === true ? data.surplus.escrowed : null;

{
  "success": true,
  "data": {
    "positionId": "secpos_014",
    "onChainLoanId": "5",
    "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "payeeAddress": null,
    "payeeCustomer": null,
    "borrowedAmount": "50000.0",
    "collateralAmount": "1000.0",
    "accumulatedInterest": "961.643835",
    "healthFactor": "1.842",
    "priceAtBorrow": "104.82",
    "currentPrice": "109.4",
    "collateralValue": "109400",
    "collateralValueAtBorrow": "104820",
    "dueAt": "1796630400",
    "term": {
      "dueAt": "1796630400",
      "effectiveDueAt": "1796630400",
      "graceEnd": "1796889600",
      "enforceable": false,
      "termGracePeriod": "259200",
      "termPenaltyBps": 300,
      "stamped": true,
      "termSource": "STAMPED"
    },
    "fixedRateBps": 650,
    "customerId": null,
    "customerAttributedAt": null,
    "status": "ACTIVE",
    "openedAt": "2026-06-10T08:00:00.000Z",
    "closedAt": null,
    "liquidatedAt": null,
    "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"
    },
    "surplus": {
      "returned": "0.000000",
      "escrowed": null,
      "claimable": false,
      "escrowReadFailed": false
    },
    "realizationLoss": null,
    "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",
        "recordedByThisInstance": true
      },
      {
        "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",
        "recordedByThisInstance": true
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "POSITION_NOT_FOUND",
    "message": "Position not found"
  }
}

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
`POSITION_NOT_FOUND`	`404`	No position with this ID in this market

curl "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/positions/{positionId}" \
  -H "X-API-Key: trusset_your_key_here"

const res = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/positions/${positionId}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const surplusToClaim = data.surplus?.claimable === true ? data.surplus.escrowed : null;

{
  "success": true,
  "data": {
    "positionId": "secpos_014",
    "onChainLoanId": "5",
    "userAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "payeeAddress": null,
    "payeeCustomer": null,
    "borrowedAmount": "50000.0",
    "collateralAmount": "1000.0",
    "accumulatedInterest": "961.643835",
    "healthFactor": "1.842",
    "priceAtBorrow": "104.82",
    "currentPrice": "109.4",
    "collateralValue": "109400",
    "collateralValueAtBorrow": "104820",
    "dueAt": "1796630400",
    "term": {
      "dueAt": "1796630400",
      "effectiveDueAt": "1796630400",
      "graceEnd": "1796889600",
      "enforceable": false,
      "termGracePeriod": "259200",
      "termPenaltyBps": 300,
      "stamped": true,
      "termSource": "STAMPED"
    },
    "fixedRateBps": 650,
    "customerId": null,
    "customerAttributedAt": null,
    "status": "ACTIVE",
    "openedAt": "2026-06-10T08:00:00.000Z",
    "closedAt": null,
    "liquidatedAt": null,
    "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"
    },
    "surplus": {
      "returned": "0.000000",
      "escrowed": null,
      "claimable": false,
      "escrowReadFailed": false
    },
    "realizationLoss": null,
    "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",
        "recordedByThisInstance": true
      },
      {
        "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",
        "recordedByThisInstance": true
      }
    ]
  }
}

{
  "success": false,
  "error": {
    "code": "POSITION_NOT_FOUND",
    "message": "Position not found"
  }
}

Overview

MiCA Register

Customers

Tokenization

Trading

Lending

Operators

Asset Register

Vaults

Seller Financing

Get Position

Path Parameters

Response Fields

Error Codes

​Path Parameters

​Response Fields

​Error Codes

Path Parameters

Response Fields

Error Codes