DocumentationOpen App

Credit Accounts

Query and manage Gearbox credit accounts using the SDK. Credit accounts are isolated smart contracts that hold collateral and debt positions on behalf of users.

Creating a Service

Use createCreditAccountService for credit account operations:

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

const sdk = await GearboxSDK.attach({ client, marketConfigurators: [] });

// Create service (310 = V3.1)
const service = createCreditAccountService(sdk, 310);

Querying Credit Accounts

Get All Accounts for a Credit Manager

TypeScript
const accounts = await service.getCreditAccounts(
  { creditManager: cmAddress },
  sdk.currentBlock
);

for (const account of accounts) {
  console.log(`Account: ${account.addr}`);
  console.log(`  Owner: ${account.owner}`);
  console.log(`  Debt: ${account.debt}`);
  console.log(`  Health Factor: ${account.healthFactor}`);
}

Filter by Owner

TypeScript
const myAccounts = await service.getCreditAccounts(
  {
    creditManager: cmAddress,
    owner: myAddress,
  },
  sdk.currentBlock
);

Account Data Structure

Each credit account includes:

FieldTypeDescription
addraddressCredit Account contract address
owneraddressAccount owner
creditManageraddressParent Credit Manager
debtuint256Total debt (principal + interest)
healthFactoruint256Current HF (10000 = 1.0)
tokensTokenInfo[]Token balances and values
isLiquidatablebooleanWhether account can be liquidated

Reading Account State

Health Factor

TypeScript
const account = accounts[0];

// Health factor is scaled by 10000 (10000 = 1.0)
const hf = Number(account.healthFactor) / 10000;
console.log(`Health Factor: ${hf.toFixed(4)}`);

if (account.isLiquidatable) {
  console.log('Account is liquidatable!');
}

Token Balances

TypeScript
for (const token of account.tokens) {
  console.log(`${token.symbol}:`);
  console.log(`  Balance: ${token.balance}`);
  console.log(`  Value (underlying): ${token.balanceInUnderlying}`);
  console.log(`  LT: ${token.lt / 100}%`);
}

Debt Breakdown

TypeScript
console.log(`Total Debt: ${account.debt}`);
console.log(`Principal: ${account.borrowedAmount}`);
console.log(`Accrued Interest: ${account.cumulativeQuotaInterest}`);
console.log(`Quota Fees: ${account.quotaFees}`);

Market Discovery

Find the market for a credit manager:

TypeScript
const market = sdk.marketRegister.findByCreditManager(cmAddress);
const creditFacade = market.creditFacade;

console.log(`Credit Facade: ${creditFacade.address}`);
console.log(`Pool: ${market.pool.address}`);

Opening a Credit Account

TypeScript
// Build multicall with SDK helpers
const calls = [
  service.prepareAddCollateral(usdcAddress, 10000n * 10n ** 6n),
  service.prepareIncreaseDebt(40000n * 10n ** 6n),
];

// Get credit facade
const market = sdk.marketRegister.findByCreditManager(cmAddress);

// Open account
const hash = await market.creditFacade.write.openCreditAccount([
  ownerAddress,
  calls,
  0n, // referralCode
]);

Closing a Credit Account

TypeScript
// Build close multicall - typically repay and withdraw
const closeCalls = [
  service.prepareDecreaseDebt(account.debt), // Repay all debt
  // Withdraw remaining collateral handled automatically
];

const hash = await market.creditFacade.write.closeCreditAccount([
  account.addr,
  closeCalls,
]);

Complete Example

TypeScript
import { GearboxSDK, createCreditAccountService } from '@gearbox-protocol/sdk';
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

async function queryAccounts(cmAddress: `0x${string}`) {
  const client = createPublicClient({
    chain: mainnet,
    transport: http(),
  });

  const sdk = await GearboxSDK.attach({
    client,
    marketConfigurators: [],
  });

  const service = createCreditAccountService(sdk, 310);

  // Get all accounts
  const accounts = await service.getCreditAccounts(
    { creditManager: cmAddress },
    sdk.currentBlock
  );

  console.log(`Found ${accounts.length} credit accounts\n`);

  for (const account of accounts) {
    const hf = Number(account.healthFactor) / 10000;

    console.log(`Account: ${account.addr}`);
    console.log(`  Owner: ${account.owner}`);
    console.log(`  Debt: ${account.debt}`);
    console.log(`  Health Factor: ${hf.toFixed(4)}`);
    console.log(`  Liquidatable: ${account.isLiquidatable}`);

    // Token breakdown
    console.log(`  Tokens:`);
    for (const token of account.tokens) {
      if (token.balance > 0n) {
        console.log(`    ${token.symbol}: ${token.balance}`);
      }
    }

    console.log('');
  }
}

queryAccounts('0x...').catch(console.error);

Learn More