# Bot System

> Markdown export of the Gearbox Protocol documentation page for agents and retrieval systems.

Canonical page: https://docs.gearbox.finance/developers/gm-bots
Source file: content/developers/gm-bots.mdx
Section router: https://docs.gearbox.finance/developers/llms.txt
Section full export: https://docs.gearbox.finance/developers/llms-full.txt

Gearbox features a granular bot permission system that allows automated management of Credit Accounts. Bots can execute operations on behalf of account owners with specific, revocable permissions.

## Architecture

| Component | Description |
| --- | --- |
| **BotListV3** | Registry storing `(bot, creditManager, creditAccount) → permissions` |
| **IBot interface** | Bots implement `requiredPermissions()` to declare needed permissions |
| **CreditFacadeV3** | Entry point for bot execution via `botMulticall` |

## Permission Model

Permissions are stored as a `uint192` bitmask. Account owners grant specific permissions to specific bots:

| Permission | Operation |
| --- | --- |
| `ADD_COLLATERAL` | Add funds to account |
| `INCREASE_DEBT` | Borrow more from pool |
| `DECREASE_DEBT` | Repay debt |
| `WITHDRAW_COLLATERAL` | Withdraw assets |
| `UPDATE_QUOTA` | Change token quotas |
| `SET_BOT_PERMISSIONS` | Manage other bots |
| `EXTERNAL_CALLS` | Execute adapter calls |

## Granting Permissions

Account owners grant permissions via a multicall operation:

```typescript
const calls = [
  service.setBotPermissions(
    creditAccount,
    botAddress,
    ADD_COLLATERAL_PERMISSION | EXTERNAL_CALLS_PERMISSION
  ),
];

await facade.multicall(creditAccount, calls);
```

## Bot Execution

Bots execute via `botMulticall` on the Credit Facade:

```typescript
// Bot calls botMulticall with the account and operations
await facade.botMulticall(creditAccount, [
  service.addCollateral(creditAccount, tokenAddress, amount),
  // ... other permitted operations
]);
```

The Facade checks the bot's permissions before each operation. If a bot attempts an unpermitted action, the transaction reverts.

## Safety Model

- **Isolation** — each permission grant is scoped to a specific `(bot, creditManager, creditAccount)` tuple
- **Immutability** — bots cannot modify their own permissions
- **DAO forbid list** — the DAO can globally forbid malicious bots
- **Collateral check** — bot multicalls undergo the same solvency check as user multicalls

## Revoking Permissions

```typescript
// Revoke all permissions for a bot
await facade.multicall(creditAccount, [
  service.setBotPermissions(creditAccount, botAddress, 0),
]);
```

## Learn More

- [Liquidation Bots Guide](https://docs.gearbox.finance/developers/gm-guide-bots) — Building a complete liquidation bot
- [Credit Accounts](https://docs.gearbox.finance/developers/gm-accounts) — Account lifecycle and operations
- [Multicalls](https://docs.gearbox.finance/developers/gm-accounts-multicalls) — Building multicall transactions