Borrowing
Claim Surplus
Withdraw a realization surplus the market escrowed after a blocked payout
POST
/
lending-external-securities-v2
/
api
/
positions
/
{marketId}
/
claim-surplus
curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/claim-surplus" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"}'
const url = `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/claim-surplus`;
const headers = {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
};
const built = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify({ holderAddress: await wallet.getAddress() })
});
const { data } = await built.json();
const tx = await wallet.sendTransaction(data.transaction);
await tx.wait();
const confirmed = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify({ txHash: tx.hash })
});
const { data: claim } = await confirmed.json();
{
"success": true,
"data": {
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"data": "0x27ff02e3",
"value": "0",
"chainId": 11155111
},
"functionName": "claimSurplus",
"description": "Claim 1532.4 USDC of realization surplus escrowed on the market for 0xabc7f1093d5e26b804a1c3f78de025916b47c0d3. claimSurplus credits msg.sender, so it must be signed from that wallet.",
"holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"escrowedSurplus": "1532.4",
"confirmWith": "claimSurplus"
}
}
{
"success": true,
"data": {
"txHash": "0x3c7e9a15d2f04b86a1e5c3907db48f2e6a91c0d57b3e28f4a6d19c0e5b72a384",
"claimedBy": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "1532.4"
}
}
{
"success": false,
"error": {
"code": "NO_ESCROWED_SURPLUS",
"message": "The market holds no escrowed surplus for 0xabc7f1093d5e26b804a1c3f78de025916b47c0d3; claimSurplus reverts InvalidAmount on an empty claim, so nothing is offered. A surplus is escrowed only when the settlement-asset transfer to the borrower fails at settlement."
}
}
Builds the transaction that pays an escrowed realization surplus out of the market contract to the borrower, then confirms it once mined. The surplus is held in the settlement token (stablecoin).
A liquidation’s proceeds above the debt plus the penalty belong to the borrower, and the market pays them out during settlement. When the settlement token refuses that transfer, the market escrows the amount under the borrower’s address rather than reverting the settlement. Get Escrowed Surplus reads the balance. This endpoint withdraws it, on
Confirming with
FREEZE and CUSTODY markets alike.
The claim repeats the refused transfer of the settlement asset, so it reverts while that asset still refuses the borrower, after the borrower has paid gas. The calldata is returned without checking whether the transfer would now be accepted. Lift the restriction on the borrower’s address first, then claim.
claimSurplus() takes no arguments and pays the whole escrow of the wallet that signs it. The borrower must sign from the address the surplus was escrowed for. Signing with any other wallet claims that wallet’s own escrow, or reverts when it has none. holderAddress only decides whose escrow is checked before the calldata is handed back. It does not appear in the transaction and cannot redirect the payout.
Path Parameters
string
required
Body Parameters
SendholderAddress to build the transaction, or txHash to confirm one already mined. At least one is required. When both are sent, txHash wins and the call confirms.
string
Address whose escrowed surplus is to be claimed,
0x followed by 40 hex characters. The market’s escrow for it is read first, and an empty escrow is refused with NO_ESCROWED_SURPLUS rather than handing back a transaction that reverts.string
Hash of the mined claim,
0x followed by 64 hex characters. Send it to confirm the claim and record it. Omit it to receive the calldata.Response Fields
object
Show child attributes
Show child attributes
string
SIGN_TRANSACTION. Returned when txHash is omitted.object
Unsigned transaction,
{ to, data, value, chainId }, calling claimSurplus on the market contract. Returned when txHash is omitted.string
claimSurplus. Returned when txHash is omitted.string
One sentence naming the amount, the asset symbol and the holder, and stating that the holder’s wallet must sign. Returned when
txHash is omitted.string
The holder whose escrow was read, lowercased. Returned when
txHash is omitted.string
The escrow the claim would pay out, as a decimal string in borrow asset units. Returned when
txHash is omitted.string
claimSurplus, the function whose transaction hash confirms the claim. Send that hash back to this endpoint as txHash. Returned when txHash is omitted.string
Transaction hash. Returned when confirming with
txHash.string
Address the surplus was paid to, lowercased, read from the market’s
SurplusClaimed event. Falls back to the transaction’s sender when the event could not be read. Returned when confirming with txHash.string
Amount paid out, as a decimal string in borrow asset units, read from the same event. Null when the event could not be read. Returned when confirming with
txHash.string
receipt-log when the claim ran through another contract, such as a smart account. The claim was then verified by the market’s SurplusClaimed event rather than by the transaction’s own target. Absent otherwise.string
The contract the outer transaction was sent to. Present with
verifiedBy.string
The wallet that sent the outer transaction. Present with
verifiedBy.A confirmed claim is recorded on the market’s transaction ledger as
SURPLUS_CLAIMED, which List Transactions returns. It is not recorded against a single position, because the escrow belongs to the address and the market’s SurplusClaimed event names no loan.curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/claim-surplus" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"}'
const url = `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/claim-surplus`;
const headers = {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
};
const built = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify({ holderAddress: await wallet.getAddress() })
});
const { data } = await built.json();
const tx = await wallet.sendTransaction(data.transaction);
await tx.wait();
const confirmed = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify({ txHash: tx.hash })
});
const { data: claim } = await confirmed.json();
{
"success": true,
"data": {
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"data": "0x27ff02e3",
"value": "0",
"chainId": 11155111
},
"functionName": "claimSurplus",
"description": "Claim 1532.4 USDC of realization surplus escrowed on the market for 0xabc7f1093d5e26b804a1c3f78de025916b47c0d3. claimSurplus credits msg.sender, so it must be signed from that wallet.",
"holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"escrowedSurplus": "1532.4",
"confirmWith": "claimSurplus"
}
}
{
"success": true,
"data": {
"txHash": "0x3c7e9a15d2f04b86a1e5c3907db48f2e6a91c0d57b3e28f4a6d19c0e5b72a384",
"claimedBy": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "1532.4"
}
}
{
"success": false,
"error": {
"code": "NO_ESCROWED_SURPLUS",
"message": "The market holds no escrowed surplus for 0xabc7f1093d5e26b804a1c3f78de025916b47c0d3; claimSurplus reverts InvalidAmount on an empty claim, so nothing is offered. A surplus is escrowed only when the settlement-asset transfer to the borrower fails at settlement."
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
NO_MARKET_ADDRESS | 400 | The market has no on-chain address recorded |
VALIDATION_ERROR | 400 | Neither holderAddress nor txHash was sent, or one of them is malformed |
MISSING_MARKET_ID | 400 | The market ID is longer than 100 characters |
MARKET_NOT_FOUND | 404 | No market with this ID on your instance |
NO_ESCROWED_SURPLUS | 409 | The market holds no escrowed surplus for holderAddress. Claiming would revert |
SURPLUS_UNREADABLE | 503 | The escrow could not be read from the network, so no transaction is offered. Retry shortly |
txHash can also return any transaction verification error.⌘I
curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/positions/{marketId}/claim-surplus" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3"}'
const url = `https://api.trusset.org/lending-external-securities-v2/api/positions/${marketId}/claim-surplus`;
const headers = {
'X-API-Key': 'trusset_your_key_here',
'Content-Type': 'application/json'
};
const built = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify({ holderAddress: await wallet.getAddress() })
});
const { data } = await built.json();
const tx = await wallet.sendTransaction(data.transaction);
await tx.wait();
const confirmed = await fetch(url, {
method: 'POST',
headers,
body: JSON.stringify({ txHash: tx.hash })
});
const { data: claim } = await confirmed.json();
{
"success": true,
"data": {
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"data": "0x27ff02e3",
"value": "0",
"chainId": 11155111
},
"functionName": "claimSurplus",
"description": "Claim 1532.4 USDC of realization surplus escrowed on the market for 0xabc7f1093d5e26b804a1c3f78de025916b47c0d3. claimSurplus credits msg.sender, so it must be signed from that wallet.",
"holderAddress": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"escrowedSurplus": "1532.4",
"confirmWith": "claimSurplus"
}
}
{
"success": true,
"data": {
"txHash": "0x3c7e9a15d2f04b86a1e5c3907db48f2e6a91c0d57b3e28f4a6d19c0e5b72a384",
"claimedBy": "0xabc7f1093d5e26b804a1c3f78de025916b47c0d3",
"amount": "1532.4"
}
}
{
"success": false,
"error": {
"code": "NO_ESCROWED_SURPLUS",
"message": "The market holds no escrowed surplus for 0xabc7f1093d5e26b804a1c3f78de025916b47c0d3; claimSurplus reverts InvalidAmount on an empty claim, so nothing is offered. A surplus is escrowed only when the settlement-asset transfer to the borrower fails at settlement."
}
}