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

# In a clone of github.com/morpho-org/morpho-sdk
git clone https://github.com/morpho-org/morpho-sdk.git
cd morpho-sdk
pnpm install
pnpm run build:link
 
# In your application
pnpm link @morpho-org/morpho-sdk

import "dotenv/config";
import { type Address, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { mainnet } from "viem/chains";
import { MorphoClient } from "@morpho-org/morpho-sdk";
 
// `MorphoClient` wraps a viem client and is the entry point for all SDK actions.
//
// Builder = signer: `userAddress` MUST equal the connected viem account, and the
// SAME client must sign the transaction. The SDK enforces this via
// `validateUserAddress` (throws `MissingClientPropertyError` / `AddressMismatchError`).
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
 
const walletClient = createWalletClient({
  account,
  chain: mainnet,
  transport: http(process.env.RPC_URL_MAINNET),
});
 
const morpho = new MorphoClient(walletClient, {
  // Enables Permit / Permit2 in `getRequirements()` to skip the extra approval tx.
  supportSignature: true,
  // Use deployless reads for chains where the SDK's helpers are not yet deployed.
  supportDeployless: false,
  // Optional metadata stamped into bundler calldata for attribution / tracing.
  metadata: { origin: "my-app" },
});
 
const USER_ADDRESS = account.address as Address;

// Three entity factories - chainId is mandatory (validated against the viem client).
const vaultV2 = morpho.vaultV2(
  "0xVaultV2Address0000000000000000000000000000" as Address,
  mainnet.id,
);
 
const market = morpho.marketV1(
  {
    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(requirementSignature?) - produces the final viem `Transaction`
//   - getRequirements()             - pre-flight: ERC-20 approvals, Permit/Permit2,
//                                     Morpho `setAuthorization` for GeneralAdapter1
//
// Typical flow:
//   1. const { buildTx, getRequirements } = vault.deposit({ ... })
//   2. const requirements = await getRequirements()
//   3. For each requirement: send the approval / authorization tx,
//      OR ask the user to sign the permit and capture `RequirementSignature`.
//   4. const tx = buildTx(signature?)
//   5. Send `tx` with the SAME viem client used to build it.
const accrualVault = await vaultV2.getData();
 
const deposit = vaultV2.deposit({
  amount: 1_000000000000000000n,
  userAddress: USER_ADDRESS,
  accrualVault,
});
 
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 { MorphoClient } 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 accrualVault = await vault.getData();

// Routed through Bundler3 via GeneralAdapter1 - enforces `maxSharePrice`
// (ERC-4626 inflation-attack guard) and supports atomic native-token wrapping.
const { buildTx, getRequirements } = vault.deposit({
  amount: parseUnits("1", 18),
  userAddress,
  accrualVault,
  // slippageTolerance defaults to 0.03% (max 10%).
});
 
const requirements = await getRequirements();
// e.g. [erc20Approval tx for GeneralAdapter1] OR [Permit / Permit2 signature requirement]
 
const tx = 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 { buildTx: buildNativeDepositTx } = vault.deposit({
  nativeAmount: parseUnits("1", 18), // 1 ETH wrapped → WETH → deposited
  userAddress,
  accrualVault,
});
 
// Mixed (ERC-20 + native) is also supported in a single bundle:
const { buildTx: buildMixedDepositTx } = vault.deposit({
  amount: parseUnits("0.5", 18),       // already-held WETH
  nativeAmount: parseUnits("0.5", 18), // raw ETH wrapped at execution
  userAddress,
  accrualVault,
});

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

// 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 { buildTx: buildRedeemTx } = vault.redeem({
  shares: parseUnits("1", 18),
  userAddress,
});
const redeemTx = buildRedeemTx();

// 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 { buildTx: buildForceWithdrawTx } = vault.forceWithdraw({
  deallocations: [
    {
      adapter: "0xAdapter0000000000000000000000000000000000",
      amount: parseUnits("0.5", 18),
    },
  ],
  withdraw: { amount: parseUnits("0.5", 18) },
  userAddress, // penalty source AND withdraw recipient
});

// 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 { buildTx: buildForceRedeemTx } = vault.forceRedeem({
  deallocations: [
    {
      adapter: "0xAdapter0000000000000000000000000000000000",
      amount: parseUnits("1.01", 18), // small buffer over target assets
    },
  ],
  redeem: { shares: parseUnits("1", 18) },
  userAddress,
});

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

// Construct a Morpho Blue (MarketV1) entity from its `MarketParams`.
// The unique market id is derivable from these five fields.
const market = morpho.marketV1(
  {
    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 { buildTx: buildSupplyTx, getRequirements: getSupplyReqs } =
  market.supplyCollateral({
    amount: parseUnits("1", 18),
    userAddress,
    // nativeAmount: parseUnits("1", 18) // when collateral is wNative
  });
 
const supplyReqs = await getSupplyReqs();
const supplyTx = buildSupplyTx(/* 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 { buildTx: buildBorrowTx, getRequirements: getBorrowReqs } = market.borrow({
  amount: parseUnits("500", 6), // 500 USDC, for example
  userAddress,
  positionData,
});
 
const borrowReqs = await getBorrowReqs();
const borrowTx = buildBorrowTx();

// 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 { buildTx: buildSupplyBorrowTx, getRequirements: getSupplyBorrowReqs } =
  market.supplyCollateralBorrow({
    amount: parseUnits("1", 18),
    borrowAmount: parseUnits("500", 6),
    userAddress,
    positionData,
  });
 
const supplyBorrowReqs = await getSupplyBorrowReqs();
const supplyBorrowTx = buildSupplyBorrowTx(/* 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 { buildTx: buildPartialRepayTx } = market.repay({
  assets: parseUnits("100", 6),
  userAddress,
  positionData,
});
 
// Full repay by shares
const { buildTx: buildFullRepayTx, getRequirements: getRepayReqs } = market.repay(
  {
    shares: positionData.borrowShares,
    userAddress,
    positionData,
  },
);
 
const repayReqs = await getRepayReqs();
const fullRepayTx = buildFullRepayTx(/* 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 { buildTx: buildWithdrawCollateralTx } = market.withdrawCollateral({
  amount: parseUnits("0.25", 18),
  userAddress,
  positionData,
});
const withdrawCollateralTx = buildWithdrawCollateralTx();

// 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 { buildTx: buildRepayWithdrawTx, getRequirements: getRepayWithdrawReqs } =
  market.repayWithdrawCollateral({
    assets: parseUnits("100", 6), // or { shares: ... }
    withdrawAmount: parseUnits("0.25", 18),
    userAddress,
    positionData,
  });
 
const repayWithdrawReqs = await getRepayWithdrawReqs();
const repayWithdrawTx = buildRepayWithdrawTx(/* requirementSignature? */);

// 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 { buildTx: buildBorrowWithReallocTx } = market.borrow({
  amount: parseUnits("500", 6),
  userAddress,
  positionData,
  reallocations,
});
 
const borrowWithReallocTx = buildBorrowWithReallocTx();
// `borrowWithReallocTx.value` includes the sum of every PublicAllocator fee.

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