> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trusset.org/llms.txt
> Use this file to discover all available pages before exploring further.
# List Liquidation Bots
> List the liquidation bots of this instance with their on-chain state
Returns the instance's liquidation bots, newest first, with each bot's state read from the chain. It also returns the instance's deployed markets, which are the markets a bot can be connected to. Archived bots are left out unless `includeArchived` is set.
A liquidation bot is a contract the operator deploys and owns, which holds `LIQUIDATOR_ROLE` on the markets it is connected to so that any caller can trigger a liquidation through it. The owner wallet signs every change to a bot. Trusset holds no key to it and never calls it. [Deploy Liquidation Bot](/endpoints/lending/deploy-bot) explains what it does and who calls it.
Chain reads are cached for up to 15 seconds. A read that fails is marked `readFailed`, never reported as a disconnected market.
## Query Parameters
`true` or `1` includes archived bots. Any other value counts as `false`.
## Response Fields
Bot records ordered by `createdAt`, newest first.
Bot ID.
Instance that recorded the bot.
The bot contract's address.
The wallet that deployed the bot, recorded at confirmation.
Display label.
Whether the bot is hidden from the default list.
Hash of the deployment transaction.
When the deployment was confirmed.
Last change to the record.
The bot's live state, or `null` for a record without a contract address. When even the owner cannot be read, this is only `{ "readFailed": true, "isOnChain": null }`.
`true` when the contract answered.
`false` when the contract answered.
The contract's current owner. It differs from `ownerWallet` only if ownership was transferred on-chain outside this API.
Whether the owner paused every trigger.
Most wei refunded to one caller within one block. `0` disables refunds.
Gas price ceiling for refunds, in wei. `0` means no ceiling.
The bot's float, in the network's native coin, as a decimal string.
One entry per deployed, active market of the instance, whether connected or not.
Market ID.
Market contract address.
Collateral token name.
Collateral token symbol.
Borrow asset symbol.
Whether the owner enabled this market on the bot.
Whether the market granted the bot `LIQUIDATOR_ROLE`.
`true` only when both `enabled` and `roleGranted` are `true`. Either alone leaves the bot unable to liquidate on this market.
Present and `true` when either read failed. `connected` is then `false` without being a verdict.
The instance's deployed, active markets, newest first. Each has `id`, `marketAddress`, `collateralTokenName`, `collateralTokenSymbol` and `borrowAssetSymbol`.
The filter applied.
```bash cURL theme={null}
curl "https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots?includeArchived=true" \
-H "X-API-Key: trusset_your_key_here"
```
```typescript TypeScript theme={null}
const res = await fetch(
'https://api.trusset.org/lending-external-securities-v2/api/liquidation-bots',
{ headers: { 'X-API-Key': 'trusset_your_key_here' } }
);
const { data } = await res.json();
const covering = data.bots.filter((bot) =>
bot.onChain?.connections?.some((c) => c.connected)
);
```
```json Response theme={null}
{
"success": true,
"data": {
"bots": [
{
"id": "clx_bot_001",
"instanceId": "inst_abc123",
"botAddress": "0xc40dea7387a290e7ce71784a65ae0ed6bb1ae555",
"ownerWallet": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
"label": "Primary keeper",
"archived": false,
"deployTxHash": "0x1a2531f9e02d8b3660364d25a982585f822fbe8689e811e7b967cbd1d670ba7b",
"createdAt": "2026-09-20T10:00:00.000Z",
"updatedAt": "2026-09-20T10:00:00.000Z",
"onChain": {
"isOnChain": true,
"readFailed": false,
"owner": "0x1234f9a07c6b53d81e2a4f70c9b385d6014a7e52",
"paused": false,
"maxRefundPerCallerPerBlock": "2000000000000000",
"maxRefundGasPrice": "30000000000",
"balance": "0.25",
"connections": [
{
"marketId": "clx_secmarket_001",
"marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"marketName": "Nyala Fund I",
"marketSymbol": "NYF1",
"settlementSymbol": "USDC",
"enabled": true,
"roleGranted": true,
"connected": true
}
]
}
}
],
"markets": [
{
"id": "clx_secmarket_001",
"marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
"collateralTokenName": "Nyala Fund I",
"collateralTokenSymbol": "NYF1",
"borrowAssetSymbol": "USDC"
}
],
"includeArchived": true
},
"error": null,
"metadata": {
"timestamp": "2026-09-25T12:00:00.000Z",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"instanceId": "inst_abc123"
}
}
```
## Error Codes
| Code | HTTP | Cause |
| ----------------- | ----- | ---------------------------------------------------------------- |
| `BOT_READ_FAILED` | `500` | The bot records could not be read. The message is generic; retry |