Trusset Protocol - Infrastructure for Asset Tokenization

GET

lending-external-securities-v2

api

positions

{marketId}

escrowed-surplus

{holderAddress}

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

const res = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/escrowed-surplus/${holder}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { success, data, error } = await res.json();
if (!success) throw new Error(`${error.code}: ${error.message}`);
const owed = data.claimable ? `${data.escrowed} ${data.asset.symbol}` : null;

{
  "success": true,
  "data": {
    "marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
    "holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "escrowedRaw": "1532400000",
    "escrowed": "1532.4",
    "claimable": true,
    "asset": {
      "address": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
      "symbol": "USDC",
      "decimals": 6
    }
  }
}

{
  "success": false,
  "error": {
    "code": "SURPLUS_UNREADABLE",
    "message": "The escrowed surplus could not be read from the network right now."
  }
}

Returns the realization surplus the market contract holds in escrow for one address. The amount is in the settlement token (stablecoin) and covers every loan of that address on this market, not a single loan. A surplus arises when a liquidation’s sale or auction proceeds exceed what the market may keep. The market keeps the debt the loan owed at seizure plus a penalty on it, and pays the rest to the borrower recorded on the liquidation. The penalty is the market’s liquidation penalty on a health liquidation and the loan’s term penalty on a term realization. If the settlement token refuses the payout, the market escrows the amount under the borrower’s address instead of reverting the settlement. The borrower withdraws it with Claim Surplus. This is not collateral escrow. A CUSTODY market’s adapter escrows collateral tokens when their return is blocked, which Get Escrowed Collateral reads. A surplus is held by the market itself, in the borrow asset, on FREEZE and CUSTODY markets alike.

Path Parameters

string

required

Market ID.

string

required

Address to read the escrow for, usually the borrower on a liquidation. 0x followed by 40 hex characters.

Response Fields

object

Show child attributes

string

The market contract holding the escrow.

string

The address queried, lowercased.

string

Escrowed surplus in the borrow asset’s smallest unit. "0" when nothing is held.

string

The same amount as a decimal string in borrow asset units. "0.0" when nothing is held.

boolean

true when the escrow is above zero, so Claim Surplus has something to pay out.

object

The market’s borrow asset, in which the surplus is held.

Show child attributes

string

Token address.

string

Token symbol.

integer

Token decimals.

claimable: true says an escrow exists, not that a claim will succeed. The claim repeats the refused transfer, so it reverts while the settlement asset still refuses the borrower.

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

const res = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/escrowed-surplus/${holder}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { success, data, error } = await res.json();
if (!success) throw new Error(`${error.code}: ${error.message}`);
const owed = data.claimable ? `${data.escrowed} ${data.asset.symbol}` : null;

{
  "success": true,
  "data": {
    "marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
    "holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "escrowedRaw": "1532400000",
    "escrowed": "1532.4",
    "claimable": true,
    "asset": {
      "address": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
      "symbol": "USDC",
      "decimals": 6
    }
  }
}

{
  "success": false,
  "error": {
    "code": "SURPLUS_UNREADABLE",
    "message": "The escrowed surplus could not be read from the network right now."
  }
}

Error Codes

Code	HTTP	Cause
`VALIDATION_ERROR`	`400`	`holderAddress` is not `0x` followed by 40 hex characters
`NO_MARKET_ADDRESS`	`400`	The market has no on-chain address recorded
`MISSING_MARKET_ID`	`400`	The market ID is longer than 100 characters
`MARKET_NOT_FOUND`	`404`	No market with this ID on your instance
`SURPLUS_UNREADABLE`	`503`	The market’s escrow could not be read from the network. Retry shortly

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

const res = await fetch(
  `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/escrowed-surplus/${holder}`,
  { headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { success, data, error } = await res.json();
if (!success) throw new Error(`${error.code}: ${error.message}`);
const owed = data.claimable ? `${data.escrowed} ${data.asset.symbol}` : null;

{
  "success": true,
  "data": {
    "marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
    "holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
    "escrowedRaw": "1532400000",
    "escrowed": "1532.4",
    "claimable": true,
    "asset": {
      "address": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
      "symbol": "USDC",
      "decimals": 6
    }
  }
}

{
  "success": false,
  "error": {
    "code": "SURPLUS_UNREADABLE",
    "message": "The escrowed surplus could not be read from the network right now."
  }
}

Overview

MiCA Register

Customers

Tokenization

Trading

Lending

Asset Register

Vaults

Get Escrowed Surplus

Path Parameters

Response Fields

Error Codes

​Path Parameters

​Response Fields

​Error Codes

Path Parameters

Response Fields

Error Codes