Trusset Protocol - Infrastructure for Asset Tokenization

POST

lending-external-securities-v2

api

positions

{marketId}

add-collateral

curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/add-collateral" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"loanId": 5, "amount": "200"}'

const url = `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/add-collateral`;
const headers = {
  'X-API-Key': 'trusset_your_key_here',
  'Content-Type': 'application/json'
};

const res = await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ loanId: 5, amount: '200' })
});
const { data } = await res.json();

const hashes: string[] = [];
for (const step of data.steps) {
  const tx = await borrowerWallet.sendTransaction(step.transaction);
  await tx.wait();
  hashes.push(tx.hash);
}

await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ loanId: 5, txHash: hashes[data.confirmStepIndex] })
});

{
  "success": true,
  "data": {
    "action": "SIGN_TRANSACTIONS",
    "steps": [
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x3c5e8b1d7f9a2046c8e1b3d5f7a9c0e2d4b6f8a1",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "approve",
        "description": "Approve the custody adapter to pull collateral"
      },
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "addCollateral"
      }
    ],
    "mode": "CUSTODY",
    "confirmStepIndex": 1,
    "confirmWith": {
      "endpoint": "POST /lending-external-securities-v2/api/positions/cmssh7p1k0001cghxq2m4v8rz/add-collateral",
      "field": "txHash",
      "body": { "loanId": "5", "txHash": null }
    }
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x7e4a2c9f1b5d3086a2e4c6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f5a7c9e2b4d6f8",
    "loanId": "5",
    "amount": "200.0"
  }
}

Adds security tokens to an open loan, raising its health factor without repaying debt. This is the fastest way for a borrower to move a position away from liquidation. Only the loan’s borrower can sign it: the contract reverts for any other sender. CUSTODY markets require an approval on the collateral token first, returned as an explicit step. FREEZE markets do not. A paused market does not block adding collateral.

Path Parameters

string

required

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

Body Parameters

integer

required

On-chain loan ID. A positive integer. Accepted as a JSON number or as a numeric string, so the value Get Loan returns passes straight back.

string

Security tokens to add, as a positive decimal string. Parsed at the collateral token’s decimals. Required when building calldata, not needed on the confirm call. On a token whose ERC-1400 granularity() is above one base unit, it must be a whole multiple of the granularity.

string

Hash of the transaction you broadcast for this operation. Send it to confirm the transaction and record the result. Omit it to receive the calldata.

Response Fields

object

Show child attributes

string

SIGN_TRANSACTIONS when txHash is omitted.

array

One step in FREEZE markets. Two in CUSTODY markets, where an approve for the custody adapter precedes addCollateral.

string

FREEZE or CUSTODY. Returned when txHash is omitted.

integer

Index of the addCollateral step. Returned when txHash is omitted.

object

{ endpoint, field, body }: this route, txHash as the field, and a body carrying loanId with txHash: null. Returned when txHash is omitted.

string

Transaction hash. Returned when confirming with txHash.

string

Loan ID, echoed back as a string. Returned when confirming with txHash.

string

Collateral added, read from the mined transaction. Returned when confirming with txHash.

Adding collateral is bounded by the market’s maxUserCollateral and maxTotalCollateral caps. Both are checked against the loan’s borrower before any transaction is offered, so a pledge over a cap is refused with SUPPLY_CAP_EXCEEDED or USER_SUPPLY_CAP_EXCEEDED rather than reverting on-chain. Read headroom directly with Get Supply Caps.

While a Dutch auction is open against the loan, the contract reverts the top-up. The API does not check for an open auction before offering calldata.

curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/add-collateral" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"loanId": 5, "amount": "200"}'

const url = `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/add-collateral`;
const headers = {
  'X-API-Key': 'trusset_your_key_here',
  'Content-Type': 'application/json'
};

const res = await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ loanId: 5, amount: '200' })
});
const { data } = await res.json();

const hashes: string[] = [];
for (const step of data.steps) {
  const tx = await borrowerWallet.sendTransaction(step.transaction);
  await tx.wait();
  hashes.push(tx.hash);
}

await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ loanId: 5, txHash: hashes[data.confirmStepIndex] })
});

{
  "success": true,
  "data": {
    "action": "SIGN_TRANSACTIONS",
    "steps": [
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x3c5e8b1d7f9a2046c8e1b3d5f7a9c0e2d4b6f8a1",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "approve",
        "description": "Approve the custody adapter to pull collateral"
      },
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "addCollateral"
      }
    ],
    "mode": "CUSTODY",
    "confirmStepIndex": 1,
    "confirmWith": {
      "endpoint": "POST /lending-external-securities-v2/api/positions/cmssh7p1k0001cghxq2m4v8rz/add-collateral",
      "field": "txHash",
      "body": { "loanId": "5", "txHash": null }
    }
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x7e4a2c9f1b5d3086a2e4c6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f5a7c9e2b4d6f8",
    "loanId": "5",
    "amount": "200.0"
  }
}

Error Codes

Code	HTTP	Cause
`NO_MARKET_ADDRESS`	`400`	The market has no on-chain address recorded
`MISSING_MARKET_ID`	`400`	`marketId` is longer than 100 characters
`VALIDATION_ERROR`	`400`	`loanId` is not a positive integer, or `amount` is missing on the build call, not a positive decimal string, or carries more decimal places than the collateral token supports
`LOAN_NOT_ACTIVE`	`400`	The loan is closed and can no longer be modified
`COLLATERAL_ADAPTER_NOT_AUTHORIZED`	`400`	The adapter lacks the agent role (`FREEZE`) or allow-listed or verified holder status (`CUSTODY`) on the collateral token
`FREEZE_MODE_UNSUPPORTED_TOKEN`	`400`	The token does not implement the ERC-3643 freeze interface
`SUPPLY_CAP_EXCEEDED`	`400`	The pledge would push total collateral past `maxTotalCollateral`
`USER_SUPPLY_CAP_EXCEEDED`	`400`	The pledge would push this borrower past `maxUserCollateral`
`INSUFFICIENT_FREE_COLLATERAL`	`400`	On a `FREEZE` market, the borrower holds fewer unfrozen tokens than `amount`. `details` carries `holder`, `balance`, `frozen` and `free`
`COLLATERAL_TRANSFER_RESTRICTED`	`400`	The collateral token’s compliance rules block moving this collateral into the custody adapter
`COLLATERAL_GRANULARITY_MISMATCH`	`400`	`amount` is not a whole multiple of the collateral token’s ERC-1400 granularity, so the token would refuse the transfer. The message names the nearest amounts that are
`LOAN_NOT_FOUND`	`404`	No loan with that ID exists on this market
`MARKET_NOT_FOUND`	`404`	No market with this ID on your instance
`MARKET_STATE_UNAVAILABLE`	`503`	The market could not be read to check its supply caps, or the collateral token’s granularity could not be read. Retry shortly
`LOAN_STATE_UNAVAILABLE`	`503`	The loan could not be read from the network. Retry shortly

Confirming with txHash can also return any transaction verification error.

curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/add-collateral" \
  -H "X-API-Key: trusset_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"loanId": 5, "amount": "200"}'

const url = `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/add-collateral`;
const headers = {
  'X-API-Key': 'trusset_your_key_here',
  'Content-Type': 'application/json'
};

const res = await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ loanId: 5, amount: '200' })
});
const { data } = await res.json();

const hashes: string[] = [];
for (const step of data.steps) {
  const tx = await borrowerWallet.sendTransaction(step.transaction);
  await tx.wait();
  hashes.push(tx.hash);
}

await fetch(url, {
  method: 'POST',
  headers,
  body: JSON.stringify({ loanId: 5, txHash: hashes[data.confirmStepIndex] })
});

{
  "success": true,
  "data": {
    "action": "SIGN_TRANSACTIONS",
    "steps": [
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x3c5e8b1d7f9a2046c8e1b3d5f7a9c0e2d4b6f8a1",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "approve",
        "description": "Approve the custody adapter to pull collateral"
      },
      {
        "action": "SIGN_TRANSACTION",
        "transaction": {
          "to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
          "data": "0x...",
          "value": "0",
          "chainId": 11155111
        },
        "functionName": "addCollateral"
      }
    ],
    "mode": "CUSTODY",
    "confirmStepIndex": 1,
    "confirmWith": {
      "endpoint": "POST /lending-external-securities-v2/api/positions/cmssh7p1k0001cghxq2m4v8rz/add-collateral",
      "field": "txHash",
      "body": { "loanId": "5", "txHash": null }
    }
  }
}

{
  "success": true,
  "data": {
    "txHash": "0x7e4a2c9f1b5d3086a2e4c6b8d0f1a3c5e7b9d2f4a6c8e0b1d3f5a7c9e2b4d6f8",
    "loanId": "5",
    "amount": "200.0"
  }
}

Overview

MiCA Register

Customers

Tokenization

Trading

Lending

Operators

Asset Register

Vaults

Seller Financing

Add Collateral

Path Parameters

Body Parameters

Response Fields

Error Codes

​Path Parameters

​Body Parameters

​Response Fields

​Error Codes

Path Parameters

Body Parameters

Response Fields

Error Codes