Liquidation Bots
Deploy Liquidation Bot
Build the transaction that deploys a liquidation bot owned by the signing wallet
POST
/
lending-external-securities-v2
/
api
/
liquidation-bots
curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"signerAddress": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52"}'
const base = 'https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots';
const headers = { 'X-API-Key': 'trusset_your_key_here', 'Content-Type': 'application/json' };
const res = await fetch(base, {
method: 'POST',
headers,
body: JSON.stringify({ signerAddress: await wallet.getAddress() })
});
const { data } = await res.json();
const tx = await wallet.sendTransaction(data.transaction);
await tx.wait();
const confirm = await fetch(`${base}/confirm-deploy`, {
method: 'POST',
headers,
body: JSON.stringify({ txHash: tx.hash, label: 'Primary keeper' })
});
const { data: confirmed } = await confirm.json();
{
"success": true,
"data": {
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0xd4300263bbe96f12c6c53b3ad24fcda4648cda5a",
"data": "0x...",
"value": "0",
"chainId": 11155111
},
"functionName": "deployShim",
"ownerWallet": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
"confirmWith": { "endpoint": "confirm-deploy", "txHash": true }
},
"error": null,
"metadata": {
"timestamp": "2026-09-20T09:58:00.000Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"instanceId": "inst_abc123"
}
}
{
"success": false,
"data": null,
"error": {
"code": "SHIM_NOT_CONFIGURED",
"message": "Liquidation bots are not configured for this network"
}
}
Builds the transaction that deploys a liquidation bot through the liquidation bot factory. The wallet that signs it becomes the bot’s owner. Broadcast it, then record the bot with Confirm Bot Deployment.
The owner is whichever wallet signs the transaction, not the
ownerWallet this call returns. ownerWallet only names the wallet the call expects to sign. Ownership decides who can withdraw the bot’s float, so sign with the wallet that should hold it.What a liquidation bot does
A liquidation bot is a liquidation shim: a small contract that holdsLIQUIDATOR_ROLE on the markets connected to it, so no wallet has to. Its liquidate(market, loanId, signedPrice) is open to any caller. It forwards the call to the lending module, which checks the bot’s role, the price and whether the loan is liquidatable, and reverts otherwise. Seized collateral goes where the market sends it, never to the caller.
On a market whose router runs the atomic sale, that is a sale to the sale recipient inside the same transaction, and a liquidation the sale recipient cannot buy reverts. settlesAtomically on List Liquidation Bots reports this per market.
After a liquidation succeeds, the bot refunds the caller’s gas from its float of the network’s native coin, within the refund policy set with Bot Action. A reverted liquidation pays nothing. A refund transfer that fails is skipped rather than undoing the liquidation.
The bot also forwards settleExpiredAuction(market, auctionId). The lending module on this surface has no such function, because its auction module settles expired auctions for any caller, so this path reverts on its markets.
Who calls it
Trusset has no signer and never calls a bot. A liquidation through a bot is a transaction someone else sends: a keeper the operator runs, or any third party. The API builds no calldata for the bot’sliquidate. Liquidate Loan builds a direct market call for a wallet that holds the role itself, so encode the bot call from the bot contract’s ABI.
Who controls it
Only the owner can enable or disable markets on the bot, pause it, set its refund policy and withdraw its float. The factory keeps no role on a bot it deploys, and Trusset holds no key to it. The bot is not upgradeable: replacing one means deploying another and moving the market roles to it. A bot does nothing until it is connected. Connect Bot enables a market on the bot and has the market grant itLIQUIDATOR_ROLE. Fund Bot adds the float that pays refunds.
Body Parameters
string
Wallet expected to sign, returned as
ownerWallet. It does not enter the calldata, since the owner is whoever signs. Omit it to name the instance’s registered wallet.Response Fields
object
Show child attributes
Show child attributes
curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"signerAddress": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52"}'
const base = 'https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots';
const headers = { 'X-API-Key': 'trusset_your_key_here', 'Content-Type': 'application/json' };
const res = await fetch(base, {
method: 'POST',
headers,
body: JSON.stringify({ signerAddress: await wallet.getAddress() })
});
const { data } = await res.json();
const tx = await wallet.sendTransaction(data.transaction);
await tx.wait();
const confirm = await fetch(`${base}/confirm-deploy`, {
method: 'POST',
headers,
body: JSON.stringify({ txHash: tx.hash, label: 'Primary keeper' })
});
const { data: confirmed } = await confirm.json();
{
"success": true,
"data": {
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0xd4300263bbe96f12c6c53b3ad24fcda4648cda5a",
"data": "0x...",
"value": "0",
"chainId": 11155111
},
"functionName": "deployShim",
"ownerWallet": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
"confirmWith": { "endpoint": "confirm-deploy", "txHash": true }
},
"error": null,
"metadata": {
"timestamp": "2026-09-20T09:58:00.000Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"instanceId": "inst_abc123"
}
}
{
"success": false,
"data": null,
"error": {
"code": "SHIM_NOT_CONFIGURED",
"message": "Liquidation bots are not configured for this network"
}
}
Error Codes
| Code | HTTP | Cause |
|---|---|---|
VALIDATION_ERROR | 400 | signerAddress is not a 0x-prefixed 40-hex address |
WALLET_NOT_CONFIGURED | 412 | No signerAddress was sent and the instance has no verified wallet |
SHIM_NOT_CONFIGURED | 503 | No liquidation bot factory is configured for the instance’s network |
BOT_DEPLOY_FAILED | 500 | An unexpected failure. The message is generic; retry |
⌘I
curl -X POST "https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots" \
-H "X-API-Key: trusset_your_key_here" \
-H "Content-Type: application/json" \
-d '{"signerAddress": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52"}'
const base = 'https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots';
const headers = { 'X-API-Key': 'trusset_your_key_here', 'Content-Type': 'application/json' };
const res = await fetch(base, {
method: 'POST',
headers,
body: JSON.stringify({ signerAddress: await wallet.getAddress() })
});
const { data } = await res.json();
const tx = await wallet.sendTransaction(data.transaction);
await tx.wait();
const confirm = await fetch(`${base}/confirm-deploy`, {
method: 'POST',
headers,
body: JSON.stringify({ txHash: tx.hash, label: 'Primary keeper' })
});
const { data: confirmed } = await confirm.json();
{
"success": true,
"data": {
"action": "SIGN_TRANSACTION",
"transaction": {
"to": "0xd4300263bbe96f12c6c53b3ad24fcda4648cda5a",
"data": "0x...",
"value": "0",
"chainId": 11155111
},
"functionName": "deployShim",
"ownerWallet": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
"confirmWith": { "endpoint": "confirm-deploy", "txHash": true }
},
"error": null,
"metadata": {
"timestamp": "2026-09-20T09:58:00.000Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"instanceId": "inst_abc123"
}
}
{
"success": false,
"data": null,
"error": {
"code": "SHIM_NOT_CONFIGURED",
"message": "Liquidation bots are not configured for this network"
}
}