Morpho SDK

pnpm add @morpho-org/morpho-sdk@5.0.0 viem
# or
yarn add @morpho-org/morpho-sdk@5.0.0 viem
# or
npm install @morpho-org/morpho-sdk@5.0.0 viem

import "dotenv/config";
import { type Address, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import { morphoViemExtension } from "@morpho-org/morpho-sdk";

// Private-key account: this is the connected account the SDK enforces as the signer.
const account = privateKeyToAccount(process.env.PRIVATE_KEY as Address);

// This is the account the builders must be told about (see the invariant below).
const USER_ADDRESS = account.address;

// Extend a viem wallet client with the Morpho namespace. `client.morpho` exposes the
// stateless entity factories: `vaultV1`, `vaultV2`, and `blue`.
const client = createWalletClient({
  account,
  chain: mainnet,
  transport: http(process.env.RPC_URL),
}).extend(
  morphoViemExtension({
    // Collect EIP-712 permit / permit2 signatures instead of only on-chain ERC-20
    // approvals; defaults to `false` (classic approvals only).
    supportSignature: true,
    // Analytics metadata stamped onto every transaction the namespace builds.
    // `timestamp` is optional; `origin` is required when `metadata` is passed.
    metadata: { origin: "my-app", timestamp: true },
    // Allow entity fetchers to use deployless multicall for on-chain reads.
    supportDeployless: true,
  }),
);

// Builder = signer invariant:
// The `userAddress` you pass to any builder MUST equal the account connected to THIS
// extended client, and the SAME client MUST sign and send the resulting transaction.
// It is enforced by `validateUserAddress`, which throws `MissingClientPropertyError`
// when the client has no connected account, or `AddressMismatchError` when the
// connected account does not match `userAddress`.

import { MarketParams } from "@morpho-org/morpho-sdk/entities";

// Three entity factories - chainId is mandatory (validated against the viem client).
const vaultV2 = client.morpho.vaultV2(
  "0xVaultV2Address0000000000000000000000000000" as Address,
  mainnet.id,
);

// `blue()` derives and validates the market id from these params, so construct a
// `MarketParams` instance - a raw object literal has no id and throws MarketIdMismatchError.
const market = client.morpho.blue(
  new MarketParams({
    loanToken: "0xLoanToken00000000000000000000000000000000" as Address,
    collateralToken: "0xCollateralToken00000000000000000000000000" as Address,
    oracle: "0xOracle0000000000000000000000000000000000" as Address,
    irm: "0xIrm00000000000000000000000000000000000000" as Address,
    lltv: 945000000000000000n, // 94.5%
  }),
  mainnet.id,
);

// Every action that touches user tokens or positions returns:
//   - buildTx(signatures?)          - produces the final viem `Transaction`
//   - getRequirements()             - pre-flight: ERC-20 approvals, Permit/Permit2,
//                                     Morpho `setAuthorization` for GeneralAdapter1
//
// Typical flow:
//   1. const deposit = vault.deposit({ ... })
//   2. const requirements = await deposit.getRequirements()
//   3. For each requirement: send the approval / authorization tx,
//      OR ask the user to sign the permit and capture `RequirementSignature`.
//   4. const tx = deposit.buildTx(signatures?)
//   5. Send `tx` with the SAME viem client used to build it.
const vaultData = await vaultV2.getData();

const deposit = vaultV2.deposit({
  amount: 1_000000000000000000n,
  userAddress: USER_ADDRESS,
  vaultData,
});

const requirements = await deposit.getRequirements();
// requirements: (ERC20Approval tx | Permit/Permit2 Requirement)[]

const tx = deposit.buildTx(/* [requirementSignature] */);
// `tx` is a deep-frozen `{ to, value, data, action }`.

import { type Address, parseUnits } from "viem";
import { mainnet } from "viem/chains";
import { morphoViemExtension } from "@morpho-org/morpho-sdk";

// Fetches on-chain vault state with accrued interest.
// Returns an `AccrualVaultV2` with: address, asset, totalAssets, totalSupply,
// share/asset conversion helpers (`toShares`, `toAssets`), curated allocations,
// and adapters used by `forceWithdraw` / `forceRedeem`.
const vaultData = await vault.getData();

// Routed through Bundler3 via GeneralAdapter1 - enforces `maxSharePrice`
// (ERC-4626 inflation-attack guard) and supports atomic native-token wrapping.
const deposit = vault.deposit({
  amount: parseUnits("1", 18),
  userAddress,
  vaultData,
  // slippageTolerance defaults to 0.03% (max 10%).
});

const requirements = await deposit.getRequirements();
// e.g. [erc20Approval tx for GeneralAdapter1] OR [Permit / Permit2 signature requirement]

const depositTx = deposit.buildTx(/* [requirementSignature] */);

// For vaults whose underlying asset is the chain's wNative token (WETH on mainnet),
// you can deposit native ETH that the bundler atomically wraps before depositing.
const nativeDeposit = vault.deposit({
  nativeAmount: parseUnits("1", 18), // 1 ETH wrapped → WETH → deposited
  userAddress,
  vaultData,
});
const nativeDepositTx = nativeDeposit.buildTx();

// Mixed (ERC-20 + native) is also supported in a single bundle:
const mixedDeposit = vault.deposit({
  amount: parseUnits("0.5", 18),       // already-held WETH
  nativeAmount: parseUnits("0.5", 18), // raw ETH wrapped at execution
  userAddress,
  vaultData,
});
const mixedDepositTx = mixedDeposit.buildTx();

// Direct vault call - no bundler overhead, no Morpho authorization required.
const withdraw = vault.withdraw({
  amount: parseUnits("0.5", 18),
  userAddress,
});
const withdrawTx = withdraw.buildTx();

// Direct vault call - same as withdraw but specifies an exact share amount,
// so it is immune to share-price drift between quoting and execution.
const redeem = vault.redeem({
  shares: parseUnits("1", 18),
  userAddress,
});
const redeemTx = redeem.buildTx();

// Encodes N `forceDeallocate` calls + 1 `withdraw` in a single VaultV2 multicall.
// Use this when the vault's idle liquidity is insufficient and you need to
// pull liquidity back from specific markets/adapters before withdrawing.
const forceWithdraw = vault.forceWithdraw({
  deallocations: [
    {
      adapter: "0xAdapter0000000000000000000000000000000000",
      amount: parseUnits("0.5", 18),
    },
  ],
  withdraw: { amount: parseUnits("0.5", 18) },
  userAddress, // penalty source AND withdraw recipient
});
const forceWithdrawTx = forceWithdraw.buildTx();

// Share-based counterpart to forceWithdraw. The deallocated total must be
// >= the asset-equivalent of the redeemed shares; apply a buffer for share-price drift.
const forceRedeem = vault.forceRedeem({
  deallocations: [
    {
      adapter: "0xAdapter0000000000000000000000000000000000",
      amount: parseUnits("1.01", 18), // small buffer over target assets
    },
  ],
  redeem: { shares: parseUnits("1", 18) },
  userAddress,
});
const forceRedeemTx = forceRedeem.buildTx();

import { type Address, parseUnits } from "viem";
import { mainnet } from "viem/chains";
import { morphoViemExtension } from "@morpho-org/morpho-sdk";
import { MarketParams } from "@morpho-org/morpho-sdk/entities";

// Construct a Morpho Blue (MarketV1) entity from its `MarketParams`.
// The unique market id is derivable from these five fields.
const market = client.morpho.blue(
  new MarketParams({
    loanToken: "0xLoanToken00000000000000000000000000000000",
    collateralToken: "0xCollateralToken00000000000000000000000000",
    oracle: "0xOracle0000000000000000000000000000000000",
    irm: "0xIrm00000000000000000000000000000000000000",
    lltv: 860000000000000000n, // 86%
  }),
  mainnet.id,
);

// On-chain reads with accrued interest:
const marketData = await market.getMarketData();
const positionData = await market.getPositionData(userAddress);
//   positionData: AccrualPosition with health metrics
//     { borrowAssets, collateral, supplyShares, borrowShares,
//       maxBorrowAssets, ltv, isHealthy, market, ... }

// Routed through Bundler3 via GeneralAdapter1.
// `getRequirements()` returns the ERC-20 approval (or Permit / Permit2 signature)
// for the collateral token to GeneralAdapter1.
const supplyCollateral = market.supplyCollateral({
  amount: parseUnits("1", 18),
  userAddress,
  // nativeAmount: parseUnits("1", 18) // when collateral is wNative
});

const supplyReqs = await supplyCollateral.getRequirements();
const supplyTx = supplyCollateral.buildTx(/* [requirementSignature] */);

// Routed through Bundler3 via `morphoBorrow`. Requires GeneralAdapter1 to be
// authorized on Morpho - `getRequirements()` returns the `setAuthorization`
// transaction if it has not been done yet.
//
// Always pass a **fresh** `positionData` - stale data may cause unexpected
// health-check failures or unexpected slippage protection.
const borrow = market.borrow({
  amount: parseUnits("500", 6), // 500 USDC, for example
  userAddress,
  positionData,
});

const borrowReqs = await borrow.getRequirements();
const borrowTx = borrow.buildTx();

// Atomic supply-then-borrow in a single bundle. Validates an LLTV buffer (0.5%
// by default, max 10%) so a fresh position is not instantly liquidatable.
//
// `getRequirements()` returns IN PARALLEL:
//   - ERC-20 approval / Permit / Permit2 for the collateral token to GeneralAdapter1
//   - `morpho.setAuthorization(generalAdapter1, true)` if not yet authorized
const supplyCollateralBorrow = market.supplyCollateralBorrow({
  amount: parseUnits("1", 18),
  borrowAmount: parseUnits("500", 6),
  userAddress,
  positionData,
});

const supplyBorrowReqs = await supplyCollateralBorrow.getRequirements();
const supplyBorrowTx = supplyCollateralBorrow.buildTx(/* [requirementSignature] */);

// Two modes - exactly one of `assets` / `shares`:
//   - `assets`: partial repay by exact asset amount.
//   - `shares`: full repay by exact share count, immune to interest accrued
//               between quote and inclusion (recommended for "close position").
//
// Repay does NOT require Morpho authorization - only an ERC-20 approval (or
// permit) on the loan token to GeneralAdapter1.

// Partial repay by assets
const partialRepay = market.repay({
  assets: parseUnits("100", 6),
  userAddress,
  positionData,
});
const partialRepayTx = partialRepay.buildTx(/* [requirementSignature] */);

// Full repay by shares
const fullRepay = market.repay({
  shares: positionData.borrowShares,
  userAddress,
  positionData,
});

const repayReqs = await fullRepay.getRequirements();
const fullRepayTx = fullRepay.buildTx(/* [requirementSignature] */);

// Direct call to `morpho.withdrawCollateral()` - no bundler, no GeneralAdapter1.
// `msg.sender` MUST be `onBehalf`, so this is a single self-signed transaction.
// The SDK validates the resulting position health using the LLTV buffer.
const withdrawCollateral = market.withdrawCollateral({
  amount: parseUnits("0.25", 18),
  userAddress,
  positionData,
});
const withdrawCollateralTx = withdrawCollateral.buildTx();

// Atomic repay → withdraw collateral via Bundler3.
// Bundle order is critical: repay FIRST, then withdraw.
//
// `getRequirements()` returns IN PARALLEL:
//   - ERC-20 approval / Permit / Permit2 for the loan token (for repay)
//   - `morpho.setAuthorization(generalAdapter1, true)` if not yet authorized (for withdraw)
//
// The SDK simulates the repay before validating that the resulting position
// can sustain the requested collateral withdrawal.
const repayWithdrawCollateral = market.repayWithdrawCollateral({
  assets: parseUnits("100", 6), // or { shares: ... }
  withdrawAmount: parseUnits("0.25", 18),
  userAddress,
  positionData,
});

const repayWithdrawReqs = await repayWithdrawCollateral.getRequirements();
const repayWithdrawTx = repayWithdrawCollateral.buildTx(/* [requirementSignature] */);

const sourceMarketParams = new MarketParams({
  loanToken: "0xLoanToken00000000000000000000000000000000",
  collateralToken: "0xCollateralToken00000000000000000000000000",
  oracle: "0xSourceOracle0000000000000000000000000000",
  irm: "0xIrm00000000000000000000000000000000000000",
  lltv: 860000000000000000n,
});

const targetMarketParams = new MarketParams({
  loanToken: "0xLoanToken00000000000000000000000000000000",
  collateralToken: "0xCollateralToken00000000000000000000000000",
  oracle: "0xTargetOracle0000000000000000000000000000",
  irm: "0xIrm00000000000000000000000000000000000000",
  lltv: 915000000000000000n,
});

const sourceMarket = client.morpho.blue(sourceMarketParams, mainnet.id);
const targetMarket = client.morpho.blue(targetMarketParams, mainnet.id);

const sourcePosition = await sourceMarket.getPositionData(userAddress);
const targetPosition = await targetMarket.getPositionData(userAddress);

const refinance = sourceMarket.refinance({
  userAddress,
  positionData: sourcePosition,
  target: {
    marketParams: targetMarketParams,
    positionData: targetPosition,
  },
  collateralAmount: parseUnits("5", 18),
  borrowAssets: parseUnits("5", 18),
});

const refinanceRequirements = await refinance.getRequirements();

for (const requirement of refinanceRequirements) {
  await client.sendTransaction(requirement);
}

const refinanceTx = refinance.buildTx();
await client.sendTransaction(refinanceTx);

// Assets mode: migrate an exact debt amount.
const assetsModeRefinance = sourceMarket.refinance({
  userAddress,
  positionData: sourcePosition,
  target: {
    marketParams: targetMarketParams,
    positionData: targetPosition,
  },
  collateralAmount: parseUnits("5", 18),
  borrowAssets: parseUnits("2", 18),
});

// Shares mode: full-close source debt.
const sharesModeRefinance = sourceMarket.refinance({
  userAddress,
  positionData: sourcePosition,
  target: {
    marketParams: targetMarketParams,
    positionData: targetPosition,
  },
  collateralAmount: sourcePosition.collateral,
  borrowShares: sourcePosition.borrowShares,
});

// Collateral-only mode.
const collateralOnlyRefinance = sourceMarket.refinance({
  userAddress,
  positionData: sourcePosition,
  target: {
    marketParams: targetMarketParams,
    positionData: targetPosition,
  },
  collateralAmount: parseUnits("5", 18),
});

// Pass an explicit `reallocations` array when the borrowed market lacks
// liquidity but a MetaMorpho vault you trust has spare capacity in another
// market it allocates to. The SDK encodes a `PublicAllocator.reallocateTo()`
// call for each entry and prepends it to the bundle, BEFORE `morphoBorrow`.
const reallocations: VaultReallocation[] = [
  {
    vault: "0xVaultV1Address0000000000000000000000000000",
    fee: 0n, // PublicAllocator fee in native token (often 0)
    withdrawals: [
      {
        marketParams: {
          loanToken: "0xLoanToken00000000000000000000000000000000",
          collateralToken:
            "0xSourceCollateralToken000000000000000000000",
          oracle: "0xSourceOracle0000000000000000000000000000",
          irm: "0xIrm00000000000000000000000000000000000000",
          lltv: 860000000000000000n,
        },
        amount: parseUnits("2000", 6),
      },
    ],
  },
];

const borrowWithRealloc = market.borrow({
  amount: parseUnits("500", 6),
  userAddress,
  positionData,
  reallocations,
});

const borrowWithReallocTx = borrowWithRealloc.buildTx();
// `borrowWithReallocTx.value` includes the sum of every PublicAllocator fee.

// Or let the SDK compute the optimal reallocation set for you:
//   1. `getReallocationData` - fetch ReallocationData for candidate vaults.
//   2. `getReallocations`    - derive the `VaultReallocation[]` from a target borrow size.
const reallocationData = await market.getReallocationData({
  vaultAddresses: [
    "0xVaultV1Address0000000000000000000000000000",
  ] as Address[],
  block: { number: 0n, timestamp: 0n }, // populate from your viem client
});

const computed = market.getReallocations({
  reallocationData,
  operation: "borrow",
  amount: parseUnits("500", 6),
});

const borrowAuto = market.borrow({
  amount: parseUnits("500", 6),
  userAddress,
  positionData,
  reallocations: computed,
});

const borrowAutoTx = borrowAuto.buildTx();

const block = await client.getBlock();

const targetReallocationData = await targetMarket.getReallocationData({
  vaultAddresses: [
    "0xVaultV1Address0000000000000000000000000000",
  ] as Address[],
  block: {
    number: block.number,
    timestamp: BigInt(block.timestamp),
  },
});

const targetReallocations = targetMarket.getReallocations({
  reallocationData: targetReallocationData,
  operation: "borrow",
  amount: parseUnits("5", 18),
});

const refinanceWithReallocations = sourceMarket.refinance({
  userAddress,
  positionData: sourcePosition,
  target: {
    marketParams: targetMarketParams,
    positionData: targetPosition,
  },
  collateralAmount: parseUnits("5", 18),
  borrowAssets: parseUnits("5", 18),
  targetReallocations,
});

const refinanceWithReallocationsTx = refinanceWithReallocations.buildTx();
// `refinanceWithReallocationsTx.value` includes PublicAllocator fees from `targetReallocations`.