DocumentationOpen App

Debt Management

Borrow from or repay to the pool. Debt operations directly affect your credit account's health factor.

Why

You manage debt when:

  • Increasing leverage - Borrow more to amplify exposure
  • Taking profit - Repay debt while keeping collateral positions
  • Reducing risk - Lower debt to improve health factor
  • Closing account - Repay all debt before withdrawal

What

Increase Debt

increaseDebt borrows the underlying asset from the pool to your Credit Account:

  1. Pool transfers underlying to Credit Account
  2. Debt parameters (principal + interest) are recalculated
  3. Health factor decreases

Decrease Debt

decreaseDebt repays debt from Credit Account's underlying balance:

  1. Underlying is transferred from Credit Account to pool
  2. Debt parameters are recalculated
  3. Health factor increases

Repayment order (when not paying full debt):

  1. Quota-related fees (quota increase fees)
  2. Accrued quota interest
  3. Interest + interest fee (split pro-rata if partial)
  4. Principal

This means partial payments may not reduce your principal at all.

How

Borrow More

TypeScript
import { GearboxSDK, createCreditAccountService } from '@gearbox-protocol/sdk';

const sdk = await GearboxSDK.attach({ client, marketConfigurators: [] });
const service = createCreditAccountService(sdk, 310);
const market = sdk.marketRegister.findByCreditManager(cmAddress);

const calls = [
  service.prepareIncreaseDebt(40_000n * 10n ** 6n), // Borrow 40,000 USDC
];

await market.creditFacade.write.multicall([creditAccountAddress, calls]);

Repay Debt

TypeScript
const calls = [
  service.prepareDecreaseDebt(10_000n * 10n ** 6n), // Repay 10,000 USDC
];

await market.creditFacade.write.multicall([creditAccountAddress, calls]);

Repay All Debt

Pass type(uint256).max equivalent to repay everything:

TypeScript
const MAX_UINT256 = 2n ** 256n - 1n;

const calls = [
  // Zero all quotas FIRST (required before full repayment)
  service.prepareUpdateQuota(quotedToken1, BigInt.asIntN(96, -1n * 2n ** 95n), 0n),
  service.prepareUpdateQuota(quotedToken2, BigInt.asIntN(96, -1n * 2n ** 95n), 0n),
  // Then repay all debt
  service.prepareDecreaseDebt(MAX_UINT256),
];

await market.creditFacade.write.multicall([creditAccountAddress, calls]);

Common Pattern: Add Collateral + Borrow

TypeScript
const calls = [
  // First add collateral
  service.prepareAddCollateral(usdcAddress, 10_000n * 10n ** 6n),
  // Then borrow (5x leverage)
  service.prepareIncreaseDebt(40_000n * 10n ** 6n),
  // Set quota for destination token
  service.prepareUpdateQuota(wethAddress, 50_000n * 10n ** 6n, 50_000n * 10n ** 6n),
];

// Don't forget approval to Credit Manager!
await usdcContract.write.approve([market.creditManager.address, 10_000n * 10n ** 6n]);

await market.creditFacade.write.openCreditAccount([ownerAddress, calls, 0n]);

Gotchas

One Debt Update Per Block

You cannot increase AND decrease debt in the same block. This constraint prevents manipulation:

TypeScript
// WRONG - will revert on second operation
const calls = [
  service.prepareIncreaseDebt(amount1),
  service.prepareDecreaseDebt(amount2), // Reverts!
];

// CORRECT - one multicall, one debt operation
const calls = [
  service.prepareIncreaseDebt(netAmount),
];

Zero All Quotas Before Full Repayment

Non-zero quotas with zero debt is an invalid state. Zero your quotas BEFORE the final debt repayment:

TypeScript
const INT96_MIN = BigInt.asIntN(96, -1n * 2n ** 95n);

const calls = [
  // Zero quotas first
  service.prepareUpdateQuota(token1, INT96_MIN, 0n),
  service.prepareUpdateQuota(token2, INT96_MIN, 0n),
  // Then full repayment
  service.prepareDecreaseDebt(MAX_UINT256),
];

Debt Must Stay in Range

After any debt change, the principal must be either:

  • Zero (fully repaid), OR
  • Within [minDebt, maxDebt] range

You cannot have debt between 0 and minDebt.

Forbidden Tokens Block Borrowing

If your account has forbidden tokens enabled as collateral, you cannot increase debt. Disable them first.

Interest Accrues Continuously

When repaying "the full amount", the debt may have grown since you read it. Add a buffer:

TypeScript
// Read current total debt
const accountData = await service.getCreditAccountData(creditAccountAddress);
const totalDebt = accountData.debt;

// Add 0.1% buffer for interest accrual
const repayAmount = totalDebt + (totalDebt / 1000n);

// Or just use MAX_UINT256 to repay whatever the current amount is
const calls = [service.prepareDecreaseDebt(MAX_UINT256)];

Cannot Decrease on Open / Increase on Close

  • decreaseDebt is prohibited when opening an account
  • increaseDebt is prohibited when closing an account

Learn More