Skip to main content

​
Overview

Gearbox Protocol Core V3 provides onchain credit and composable leverage for DeFi protocols. The integration involves interacting with three main components:
  • Credit Facade - User-facing interface for account management and multicalls
  • Credit Manager - Core logic for debt, collateral, and account state
  • Price Oracle - Price feeds for collateral valuation

​
Core Components

​
Credit Facade

The ICreditFacadeV3 interface is the primary entry point for users: 
interface ICreditFacadeV3 {
    function creditManager() external view returns (address);
    function underlying() external view returns (address);
    function debtLimits() external view returns (uint128 minDebt, uint128 maxDebt);
    
    function openCreditAccount(
        address onBehalfOf,
        MultiCall[] calldata calls,
        uint256 referralCode
    ) external payable returns (address creditAccount);
    
    function multicall(
        address creditAccount,
        MultiCall[] calldata calls
    ) external payable;
    
    function closeCreditAccount(
        address creditAccount,
        MultiCall[] calldata calls
    ) external payable;
}

​
MultiCall Structure

All account operations use the MultiCall pattern for batched execution: 
struct MultiCall {
    address target;  // Credit facade or adapter address
    bytes callData;  // Encoded function call
}

​
Integration Steps

1

Get Contract Addresses

Query the Credit Facade and Manager addresses from Gearbox’s contracts registry:
address creditFacade = 0x...; // Get from registry
ICreditFacadeV3 facade = ICreditFacadeV3(creditFacade);

address creditManager = facade.creditManager();
address underlying = facade.underlying();
(uint128 minDebt, uint128 maxDebt) = facade.debtLimits();
2

Prepare Token Approvals

Approve the Credit Manager to spend tokens that will be added as collateral:
IERC20(underlying).approve(creditManager, amount);
3

Build MultiCall Array

Construct operations for account initialization:
MultiCall[] memory calls = new MultiCall[](2);

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

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

Execute Integration

Open account or execute multicall:
// Open new account
address creditAccount = facade.openCreditAccount(
    msg.sender,
    calls,
    0 // referralCode
);

// Or execute on existing account
facade.multicall(creditAccount, calls);

​
Reading Account State

Query account information using the Credit Manager: 
ICreditManagerV3 manager = ICreditManagerV3(creditManager);

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

// Get debt and collateral data
CollateralDebtData memory data = manager.calcDebtAndCollateral(
    creditAccount,
    CollateralCalcTask.DEBT_COLLATERAL
);

​
Error Handling

All operations perform collateral checks at the end of execution. Ensure your multicalls maintain sufficient health factor (at least 10000 bps = 100%).
Common revert reasons:
  • Insufficient collateral - Health factor below minimum after operations
  • Debt limits violated - Debt outside [minDebt, maxDebt] range
  • Forbidden tokens - Attempting to increase debt or withdraw with forbidden tokens enabled
  • Debt update in same block - Cannot update debt twice in the same block

​
Next Steps

Opening Credit Accounts

Learn the complete flow for opening accounts

Managing Debt

Increase and decrease debt on accounts

Working with Adapters

Interact with external protocols via adapters

Price Oracles

Understand price feed integration

Build docs developers (and LLMs) love

Get started for freeTalk to us