Skip to main content

​
Overview

This quickstart guide will help you integrate with Gearbox Protocol Core V3, including interacting with pools, opening credit accounts, and executing leveraged operations.
1

Install Dependencies

First, install the Gearbox Protocol Core V3 contracts:
npm install @gearbox-protocol/core-v3
Or if using Foundry:
forge install Gearbox-protocol/core-v3
2

Import Interfaces

Import the necessary interfaces in your Solidity contract:
import "@gearbox-protocol/core-v3/contracts/interfaces/IPoolV3.sol";
import "@gearbox-protocol/core-v3/contracts/interfaces/ICreditFacadeV3.sol";
import "@gearbox-protocol/core-v3/contracts/interfaces/ICreditManagerV3.sol";
3

Connect to a Pool

Interact with a Gearbox lending pool (ERC-4626 compliant):
// Get pool instance
IPoolV3 pool = IPoolV3(poolAddress);

// Deposit assets to earn yield
uint256 shares = pool.deposit(amount, receiver);

// Withdraw assets
uint256 assets = pool.redeem(shares, receiver, owner);

// Check available liquidity
uint256 liquidity = pool.availableLiquidity();
4

Open a Credit Account

Open a credit account through the Credit Facade:
ICreditFacadeV3 creditFacade = ICreditFacadeV3(creditFacadeAddress);

// Prepare multicall operations
MultiCall[] memory calls = new MultiCall[](2);

// Add collateral
calls[0] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.addCollateral,
        (collateralToken, collateralAmount)
    )
});

// Increase debt
calls[1] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.increaseDebt,
        (borrowAmount)
    )
});

// Open credit account
address creditAccount = creditFacade.openCreditAccount(
    onBehalfOf,
    calls,
    referralCode
);

​
Pool Interactions

​
Depositing and Withdrawing

Gearbox V3 pools implement the ERC-4626 standard: 
IPoolV3 pool = IPoolV3(poolAddress);

// Standard deposit
uint256 shares = pool.deposit(assets, receiver);

// Mint specific shares amount
uint256 assets = pool.mint(shares, receiver);

// Deposit with referral code
uint256 shares = pool.depositWithReferral(assets, receiver, referralCode);

​
Credit Account Operations

​
Opening a Credit Account

Credit accounts are opened through the CreditFacadeV3 contract, which provides the user-facing interface.
ICreditFacadeV3 creditFacade = ICreditFacadeV3(creditFacadeAddress);

// Check debt limits
(uint128 minDebt, uint128 maxDebt) = creditFacade.debtLimits();

// Prepare operations
MultiCall[] memory calls = new MultiCall[](3);

// 1. Add collateral
calls[0] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.addCollateral,
        (token, amount)
    )
});

// 2. Increase debt
calls[1] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.increaseDebt,
        (debtAmount)
    )
});

// 3. Set collateral check parameters (optional)
calls[2] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.setFullCheckParams,
        (collateralHints, minHealthFactor)
    )
});

// Open account
address creditAccount = creditFacade.openCreditAccount(
    msg.sender,
    calls,
    0 // referral code
);

​
Managing an Existing Account

// Execute multicall on existing account
creditFacade.multicall(creditAccount, calls);

// Prepare operations for managing debt
MultiCall[] memory manageCalls = new MultiCall[](2);

// Add more collateral
manageCalls[0] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.addCollateral,
        (token, additionalAmount)
    )
});

// Withdraw some collateral
manageCalls[1] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.withdrawCollateral,
        (token, withdrawAmount, recipient)
    )
});

creditFacade.multicall(creditAccount, manageCalls);

​
Closing a Credit Account

// Prepare closing operations
MultiCall[] memory closeCalls = new MultiCall[](1);

// Decrease debt to zero
closeCalls[0] = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.decreaseDebt,
        (type(uint256).max) // repay all debt
    )
});

// Close the account
creditFacade.closeCreditAccount(creditAccount, closeCalls);

​
Working with Quotas

Quotas allow borrowing specific tokens beyond the base debt. Quota changes affect account’s interest payments.
// Update quota for a token
MultiCall memory updateQuotaCall = MultiCall({
    target: address(creditFacade),
    callData: abi.encodeCall(
        ICreditFacadeV3Multicall.updateQuota,
        (
            quotaToken,        // token to update quota for
            int96(quotaChange), // positive to increase, negative to decrease
            uint96(minQuota)   // minimum quota after update
        )
    )
});

MultiCall[] memory calls = new MultiCall[](1);
calls[0] = updateQuotaCall;

creditFacade.multicall(creditAccount, calls);

// Check max quota multiplier
uint256 maxQuotaMultiplier = creditFacade.maxQuotaMultiplier(); // Returns 2

​
Liquidations

​
Full Liquidation

// Check if account is liquidatable
ICreditManagerV3 creditManager = ICreditManagerV3(
    creditFacade.creditManager()
);

bool isLiquidatable = creditManager.isLiquidatable(
    creditAccount,
    PERCENTAGE_FACTOR // 100% health factor
);

if (isLiquidatable) {
    // Prepare liquidation calls (swap collateral, etc.)
    MultiCall[] memory liquidationCalls = new MultiCall[](1);
    
    // Execute liquidation
    creditFacade.liquidateCreditAccount(
        creditAccount,
        msg.sender, // recipient of remaining funds
        liquidationCalls
    );
}

​
Partial Liquidation

// Partially liquidate by repaying specific amount
uint256 seizedAmount = creditFacade.partiallyLiquidateCreditAccount(
    creditAccount,
    collateralToken,     // token to seize
    repaidAmount,        // underlying amount to repay
    minSeizedAmount,     // minimum collateral to receive
    msg.sender,          // recipient
    priceUpdates         // on-demand price feed updates
);

​
Querying Account Information

ICreditManagerV3 creditManager = ICreditManagerV3(creditManagerAddress);

// Get account info
(
    uint256 debt,
    uint256 cumulativeIndexLastUpdate,
    uint128 cumulativeQuotaInterest,
    uint128 quotaFees,
    uint256 enabledTokensMask,
    uint16 flags,
    uint64 lastDebtUpdate,
    address borrower
) = creditManager.creditAccountInfo(creditAccount);

// Calculate collateral and debt
CollateralDebtData memory cdd = creditManager.calcDebtAndCollateral(
    creditAccount,
    CollateralCalcTask.DEBT_COLLATERAL
);

// Check enabled tokens
uint256 tokensMask = creditManager.enabledTokensMaskOf(creditAccount);

// Get liquidation thresholds
uint16 lt = creditManager.liquidationThresholds(token);

​
Best Practices

Multicall Batching

Always batch operations in multicalls to save gas and ensure atomic execution with collateral checks.

Health Factor Monitoring

Monitor your credit account’s health factor to avoid liquidation. Stay above 100% (10000 in basis points).

Collateral Management

Diversify collateral and avoid forbidden tokens that trigger safe pricing modes.

Gas Optimization

Use collateral hints in setFullCheckParams to reduce gas costs during collateral checks.

​
Next Steps

API Reference

Explore detailed contract interfaces

Concepts

Learn more about Credit Account mechanics

Build docs developers (and LLMs) love

Get started for freeTalk to us