> For the complete documentation index, see [llms.txt](https://docs.moonwell.fi/moonwell/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.moonwell.fi/moonwell/developers/protocol/comptroller/contract-interactions.md).

# Contract Interactions

## Market Membership

### Enter Markets

Enable supplied assets as collateral. You must enter a market before you can borrow against it. You can enter multiple markets in a single call.

```solidity
function enterMarkets(address[] memory mTokens) public returns (uint[] memory)
```

| Parameter   | Type        | Description                                      |
| ----------- | ----------- | ------------------------------------------------ |
| `mTokens`   | `address[]` | The list of mToken addresses to enter            |
| **returns** | `uint[]`    | An array of error codes per market (0 = success) |

**Solidity**

```solidity
Comptroller comptroller = Comptroller(0x...);

address[] memory markets = new address[](2);
markets[0] = address(mUSDC);
markets[1] = address(mWETH);

uint[] memory errors = comptroller.enterMarkets(markets);
require(errors[0] == 0 && errors[1] == 0, "enterMarkets failed");
```

***

### Exit Market

Remove an asset from your collateral set. This will fail if you have an outstanding borrow in this market, or if exiting would make your position undercollateralized.

```solidity
function exitMarket(address mTokenAddress) external returns (uint)
```

| Parameter       | Type      | Description                                           |
| --------------- | --------- | ----------------------------------------------------- |
| `mTokenAddress` | `address` | The mToken to exit                                    |
| **returns**     | `uint`    | 0 on success, otherwise an [Error code](#error-codes) |

***

### Check Membership

Check whether an account has entered a specific market.

```solidity
function checkMembership(address account, MToken mToken) external view returns (bool)
```

***

### Get Assets In

Get the list of markets an account has entered.

```solidity
function getAssetsIn(address account) external view returns (MToken[] memory)
```

| Parameter   | Type       | Description                                       |
| ----------- | ---------- | ------------------------------------------------- |
| `account`   | `address`  | The account to query                              |
| **returns** | `MToken[]` | Array of mToken addresses the account has entered |

***

## Liquidity & Liquidation

### Get Account Liquidity

Calculate an account's available borrowing capacity (or shortfall if underwater). Values are denominated in USD with 18 decimals of precision.

```solidity
function getAccountLiquidity(address account) public view returns (uint, uint, uint)
```

| Parameter   | Type                 | Description                     |
| ----------- | -------------------- | ------------------------------- |
| `account`   | `address`            | The account to evaluate         |
| **returns** | `(uint, uint, uint)` | `(error, liquidity, shortfall)` |

* If `liquidity > 0`: the account can borrow up to this USD value
* If `shortfall > 0`: the account is underwater and can be liquidated

**Solidity**

```solidity
Comptroller comptroller = Comptroller(0x...);

(uint err, uint liquidity, uint shortfall) = comptroller.getAccountLiquidity(account);
require(err == 0, "liquidity check failed");

if (shortfall > 0) {
    // Account is liquidatable
} else {
    // Account can borrow up to `liquidity` USD worth
}
```

***

### Get Hypothetical Account Liquidity

Calculate what an account's liquidity would be if a hypothetical redeem or borrow were executed. Useful for simulating whether an action would make a position unsafe.

```solidity
function getHypotheticalAccountLiquidity(
    address account,
    address mTokenModify,
    uint redeemTokens,
    uint borrowAmount
) public view returns (uint, uint, uint)
```

| Parameter      | Type                 | Description                                             |
| -------------- | -------------------- | ------------------------------------------------------- |
| `account`      | `address`            | The account to simulate                                 |
| `mTokenModify` | `address`            | The mToken market to hypothetically interact with       |
| `redeemTokens` | `uint`               | The number of mTokens to hypothetically redeem          |
| `borrowAmount` | `uint`               | The amount of underlying to hypothetically borrow       |
| **returns**    | `(uint, uint, uint)` | `(error, hypotheticalLiquidity, hypotheticalShortfall)` |

***

### Liquidation Calculate Seize Tokens

Calculate how many collateral mTokens a liquidator would seize for a given repay amount.

```solidity
function liquidateCalculateSeizeTokens(
    address mTokenBorrowed,
    address mTokenCollateral,
    uint actualRepayAmount
) external view returns (uint, uint)
```

| Parameter           | Type           | Description                                                        |
| ------------------- | -------------- | ------------------------------------------------------------------ |
| `mTokenBorrowed`    | `address`      | The market in which the borrow is being repaid                     |
| `mTokenCollateral`  | `address`      | The market in which collateral will be seized                      |
| `actualRepayAmount` | `uint`         | The amount of underlying being repaid                              |
| **returns**         | `(uint, uint)` | `(error, seizeTokens)` - the number of collateral mTokens to seize |

***

## Market Information

### Get All Markets

Returns the list of all mToken markets currently listed in the protocol.

```solidity
function getAllMarkets() public view returns (MToken[] memory)
```

***

### Markets

Query the collateral factor and listing status of a specific market.

```solidity
function markets(address mToken) external view returns (bool isListed, uint collateralFactorMantissa)
```

| Return                     | Type   | Description                                                    |
| -------------------------- | ------ | -------------------------------------------------------------- |
| `isListed`                 | `bool` | Whether the market is listed in the Comptroller                |
| `collateralFactorMantissa` | `uint` | The collateral factor, scaled by `1e18` (e.g. `0.75e18` = 75%) |

***

### Close Factor

The maximum percentage of a borrower's debt that can be repaid in a single liquidation.

```solidity
function closeFactorMantissa() public view returns (uint)
```

Scaled by `1e18`. For example, `0.5e18` means a liquidator can repay up to 50% of the borrow in one transaction.

Typical range: `0.05e18` (5%) to `0.9e18` (90%). Note: the setter performs an admin check only - range validation is **not enforced on-chain**.

***

### Liquidation Incentive

The discount on collateral that liquidators receive, expressed as a multiplier.

```solidity
function liquidationIncentiveMantissa() public view returns (uint)
```

Scaled by `1e18`. For example, `1.1e18` means liquidators receive a 10% discount on seized collateral.

***

### Borrow Caps

```solidity
function borrowCaps(address mToken) public view returns (uint)
```

Returns the maximum amount of underlying that can be borrowed from a market. A value of `0` means no cap.

***

### Supply Caps

```solidity
function supplyCaps(address mToken) public view returns (uint)
```

Returns the maximum amount of underlying that can be supplied to a market. A value of `0` means no cap.

***

## Rewards

### Claim Reward

Claim accrued WELL rewards. Multiple overloads are available depending on how targeted you want the claim to be.

```solidity
// Claim all rewards for msg.sender across all markets
function claimReward() public

// Claim all rewards for a specific account
function claimReward(address holder) public

// Claim rewards for a specific account in specific markets
function claimReward(address holder, MToken[] memory mTokens) public

// Claim rewards for multiple accounts, specifying markets and sides
function claimReward(
    address[] memory holders,
    MToken[] memory mTokens,
    bool borrowers,
    bool suppliers
) public
```

| Parameter   | Type        | Description                          |
| ----------- | ----------- | ------------------------------------ |
| `holders`   | `address[]` | The accounts to claim for            |
| `mTokens`   | `MToken[]`  | The markets to claim from            |
| `borrowers` | `bool`      | Whether to claim borrow-side rewards |
| `suppliers` | `bool`      | Whether to claim supply-side rewards |

**Solidity**

```solidity
Comptroller comptroller = Comptroller(0x...);

// Simple: claim everything for yourself
comptroller.claimReward();

// Targeted: claim supply-side rewards only, for specific markets
MToken[] memory markets = new MToken[](1);
markets[0] = MToken(mUSDC);
address[] memory holders = new address[](1);
holders[0] = msg.sender;
comptroller.claimReward(holders, markets, false, true);
```

***

## Events

| Event                     | Parameters                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| `MarketListed`            | `MToken mToken`                                                                            |
| `MarketEntered`           | `MToken mToken, address account`                                                           |
| `MarketExited`            | `MToken mToken, address account`                                                           |
| `NewCloseFactor`          | `uint oldCloseFactorMantissa, uint newCloseFactorMantissa`                                 |
| `NewCollateralFactor`     | `MToken mToken, uint oldCollateralFactorMantissa, uint newCollateralFactorMantissa`        |
| `NewLiquidationIncentive` | `uint oldLiquidationIncentiveMantissa, uint newLiquidationIncentiveMantissa`               |
| `NewPriceOracle`          | `PriceOracle oldPriceOracle, PriceOracle newPriceOracle`                                   |
| `NewPauseGuardian`        | `address oldPauseGuardian, address newPauseGuardian`                                       |
| `ActionPaused`            | `string action, bool pauseState`                                                           |
| `ActionPaused`            | `MToken mToken, string action, bool pauseState`                                            |
| `NewBorrowCap`            | `MToken indexed mToken, uint newBorrowCap`                                                 |
| `NewBorrowCapGuardian`    | `address oldBorrowCapGuardian, address newBorrowCapGuardian`                               |
| `NewSupplyCap`            | `MToken indexed mToken, uint newSupplyCap`                                                 |
| `NewSupplyCapGuardian`    | `address oldSupplyCapGuardian, address newSupplyCapGuardian`                               |
| `NewRewardDistributor`    | `MultiRewardDistributor oldRewardDistributor, MultiRewardDistributor newRewardDistributor` |

***

## Error Codes

All Comptroller functions that return a `uint` use `0` for success. Non-zero values correspond to:

| Code | Name                            | Description                                  |
| ---- | ------------------------------- | -------------------------------------------- |
| 0    | `NO_ERROR`                      | Success                                      |
| 1    | `UNAUTHORIZED`                  | Caller is not authorized                     |
| 2    | `COMPTROLLER_MISMATCH`          | mToken's comptroller does not match          |
| 3    | `INSUFFICIENT_SHORTFALL`        | Account is not underwater (cannot liquidate) |
| 4    | `INSUFFICIENT_LIQUIDITY`        | Not enough liquidity for the operation       |
| 5    | `INVALID_CLOSE_FACTOR`          | Close factor is outside valid range          |
| 6    | `INVALID_COLLATERAL_FACTOR`     | Collateral factor exceeds maximum (90%)      |
| 7    | `INVALID_LIQUIDATION_INCENTIVE` | Liquidation incentive is invalid             |
| 8    | `MARKET_NOT_ENTERED`            | Account has not entered this market          |
| 9    | `MARKET_NOT_LISTED`             | Market is not listed in the Comptroller      |
| 10   | `MARKET_ALREADY_LISTED`         | Market has already been listed               |
| 11   | `MATH_ERROR`                    | Internal math error                          |
| 12   | `NONZERO_BORROW_BALANCE`        | Cannot exit market with outstanding borrows  |
| 13   | `PRICE_ERROR`                   | Oracle returned an invalid price             |
| 14   | `REJECTION`                     | Comptroller rejected the operation           |
| 15   | `SNAPSHOT_ERROR`                | Account snapshot failed                      |
| 16   | `TOO_MANY_ASSETS`               | Account has entered too many markets         |
| 17   | `TOO_MUCH_REPAY`                | Repay amount exceeds allowed close amount    |

***

## Failure Info

The `info` field in the `Failure` event provides granular context. These correspond to the `ComptrollerErrorReporter.FailureInfo` enum:

| Code | Name                                          |
| ---- | --------------------------------------------- |
| 0    | `ACCEPT_ADMIN_PENDING_ADMIN_CHECK`            |
| 1    | `ACCEPT_PENDING_IMPLEMENTATION_ADDRESS_CHECK` |
| 2    | `EXIT_MARKET_BALANCE_OWED`                    |
| 3    | `EXIT_MARKET_REJECTION`                       |
| 4    | `SET_CLOSE_FACTOR_OWNER_CHECK`                |
| 5    | `SET_CLOSE_FACTOR_VALIDATION`                 |
| 6    | `SET_COLLATERAL_FACTOR_OWNER_CHECK`           |
| 7    | `SET_COLLATERAL_FACTOR_NO_EXISTS`             |
| 8    | `SET_COLLATERAL_FACTOR_VALIDATION`            |
| 9    | `SET_COLLATERAL_FACTOR_WITHOUT_PRICE`         |
| 10   | `SET_IMPLEMENTATION_OWNER_CHECK`              |
| 11   | `SET_LIQUIDATION_INCENTIVE_OWNER_CHECK`       |
| 12   | `SET_LIQUIDATION_INCENTIVE_VALIDATION`        |
| 13   | `SET_MAX_ASSETS_OWNER_CHECK`                  |
| 14   | `SET_PENDING_ADMIN_OWNER_CHECK`               |
| 15   | `SET_PENDING_IMPLEMENTATION_OWNER_CHECK`      |
| 16   | `SET_PRICE_ORACLE_OWNER_CHECK`                |
| 17   | `SUPPORT_MARKET_EXISTS`                       |
| 18   | `SUPPORT_MARKET_OWNER_CHECK`                  |
| 19   | `SET_PAUSE_GUARDIAN_OWNER_CHECK`              |
| 20   | `SET_GAS_AMOUNT_OWNER_CHECK`                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.moonwell.fi/moonwell/developers/protocol/comptroller/contract-interactions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.