Morpho SDK

Introduction

The Morpho SDK (@morpho-org/morpho-sdk) is the default and recommended SDK for building applications on top of Morpho.

It is the abstraction layer that simplifies the Morpho protocol: it produces ready-to-send viem transactions for VaultV2 and Variable Rate - Blue Market (Morpho Blue) on every EVM-compatible chain Morpho is deployed on - plus Fixed Rate - Midnight Market through the same flow - while routing operations through Morpho Bundles. Blue and Vault flows support ERC-20 approvals and, where available, Permit or Permit2 signatures; MidnightBundlesV2 token pulls use a separate standard ERC-20 approval. The SDK also handles Morpho authorizations, native-token wrapping, vault share-price protection, Blue-to-Blue refinance, and Vault V2 shared-liquidity reallocations.

The SDK also supports refinance: atomically moving a borrower's collateral and debt from one Morpho Blue market to another market that shares the same loan token and collateral token, optionally using shared liquidity through the Vault V2 Blue Public Allocator.

For shared-liquidity implementation, use the Vault V2 Public Allocator guide.

If you are integrating Morpho into a wallet, dApp, partner app, agent, or backend service, this is the SDK you want.

Choose your product

Each Morpho product surface has its own subpage. Find the product you are shipping and go straight there - every subpage reuses the same client Setup and getRequirements / buildTx flow documented on this page, so adding a second product later is only a new entity factory call.

Actions overview

Every action the SDK builds, grouped by product, with the route each transaction takes and why:

This page documents the shared client setup and the getRequirements / buildTx flow; the VaultV2, Blue Market, and fixed-rate Midnight surfaces are each documented on their own subpage. VaultV1 (MetaMorpho) mirrors the VaultV2 vault surface and adds a V1→V2 migration.

Installation

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

viem is a peer dependency (^2.0.0) and must be installed alongside the SDK.

Setup

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
// four stateless entity factories: `vaultV1`, `vaultV2`, `blue`, and `midnight`.
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.
    // `origin` is hexadecimal calldata (at most 8 hex chars / 4 bytes, even
    // length, optional 0x prefix), NOT a clear-text name - an invalid origin
    // is dropped with only a console warning.
    metadata: { origin: "0xbeef01", 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.
// Signature requirements enforce it when `sign(client, userAddress)` is called, via
// `validateUserAddress` - throwing `MissingClientPropertyError` when the client has
// no connected account, or `AddressMismatchError` when the connected account does
// not match `userAddress`. Transaction builders do not re-validate at build time.

Extend your viem client with morphoViemExtension() to add the client.morpho namespace. That namespace exposes four entity factories:

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

// 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,
);

client.morpho.midnight(chainId) returns the fixed-rate Midnight market surface bound to the same viem client; see the Midnight subpage.

Extension options

Pass these options to morphoViemExtension(...):

The getRequirements flow

Every action that touches a user's tokens or positions returns the same shape:

• buildTx(signatures?) - returns the final, deep-frozen viem Transaction ({ to, value, data, action }). Collected requirement signatures are passed as an array.
• getRequirements() - returns the onchain pre-requisites that must be satisfied first.

A requirement is one of:

• An ERC-20 approval transaction the user must send first (approving the bundles contract - or Morpho - to pull tokens).
• A Permit / Permit2 signature request for supported Blue and Vault flows - a signable Requirement: call requirement.sign(client, userAddress) to collect the EIP-712 RequirementSignature, then pass it back into buildTx([signature]) as an array. Enabled with morphoViemExtension({ supportSignature: true }). MidnightBundlesV2 uses standard ERC-20 approvals instead.
• A Morpho authorization - morpho.setAuthorization(blueBundlesV1, true). Required once per user for borrow, supplyCollateralBorrow, withdrawCollateral, repayWithdrawCollateral, loan-asset withdraw, and refinance. The SDK only returns it if it is missing. With supportSignature: true it comes back as a signable Requirement instead of a transaction, and the signed authorization is folded into the BlueBundlesV1 call - no standalone transaction needed.

The canonical end-to-end flow - the same dispatch loop works for every vault, market, and Midnight taker action. Midnight maker flows use a distinct asynchronous flow to publish offers through MidnightBundlesV2 - see the Midnight subpage.

import { parseUnits, publicActions } from "viem";
import {
  isRequirementSignature,
  type RequirementSignature,
} from "@morpho-org/morpho-sdk";

// `client` is the extended wallet client from Setup; viem's `publicActions`
// adds `waitForTransactionReceipt` / `getBlock` for the requirement flow.
const publicClient = client.extend(publicActions);

const vaultData = await vaultV2.getData();

const deposit = vaultV2.deposit({
  amount: parseUnits("1", 18), // the vault asset has 18 decimals here
  userAddress: USER_ADDRESS,
  vaultData,
});

// 1. Resolve the on-chain pre-requisites.
const requirements = await deposit.getRequirements();

// 2. Dispatch every requirement: sign the signable ones (off-chain), send the
//    rest as transactions (on-chain) and wait for inclusion.
const signatures: RequirementSignature[] = [];

for (const requirement of requirements) {
  if (isRequirementSignature(requirement)) {
    // Permit / Permit2 / Morpho authorization signature request. `sign` runs
    // the EIP-712 signing flow and enforces builder = signer: it throws
    // `AddressMismatchError` unless the client's connected account equals
    // `USER_ADDRESS` (or `MissingClientPropertyError` when none is connected).
    signatures.push(await requirement.sign(client, USER_ADDRESS));
  } else {
    // ERC-20 approval or Morpho `setAuthorization` transaction. It must be
    // mined before the final transaction can execute.
    const hash = await client.sendTransaction(requirement);
    await publicClient.waitForTransactionReceipt({ hash });
  }
}

// 3. Build the final transaction, passing the collected signatures.
const tx = deposit.buildTx(signatures);
// `tx` is a deep-frozen `{ to, value, data, action }`.

// 4. Send it with the SAME client that built it.
await client.sendTransaction(tx);

isRequirementSignature splits the off-chain signature requests from the on-chain transactions. When you need finer-grained dispatch - for example different wallet-prompt copy per requirement - the SDK also exports isRequirementApproval and isRequirementBlueAuthorization:

import {
  isRequirementApproval,
  isRequirementBlueAuthorization,
  isRequirementSignature,
} from "@morpho-org/morpho-sdk";

for (const requirement of requirements) {
  if (isRequirementApproval(requirement)) {
    // ERC-20 approval transaction - `requirement.action.args` is { spender, amount }.
  } else if (isRequirementBlueAuthorization(requirement)) {
    // `morpho.setAuthorization(blueBundlesV1, true)` transaction.
  } else if (isRequirementSignature(requirement)) {
    // Signable requirement - `requirement.action.type` is "permit", "permit2",
    // or "authorization".
  }
}

Builder = signer

userAddress MUST equal the connected account on the viem client used to build the transaction, and the SAME client MUST sign and send it.

Transaction builders do not re-validate this at build time - you must keep userAddress aligned with the signing account yourself. The invariant is enforced when a signature requirement is signed: sign(client, userAddress) runs validateUserAddress, which throws MissingClientPropertyError (no connected account) or AddressMismatchError (account mismatch).

This invariant exists because some bundles - particularly repayWithdrawCollateral - mix explicit onBehalf = userAddress (repay) with implicit msg.sender (transfer-from + withdraw). Splitting the builder and the signer would atomically repay one user's debt while withdrawing another user's collateral.

This is a build-time guard against accidental mixed-account calls for honest integrators, not a defense against a malicious builder. The signer remains responsible for reviewing what they sign. See ARCHITECTURE.md for the deeper Morpho Bundles context.

Fetching state

Each entity exposes thin wrappers over the canonical viem fetchers (re-exported from @morpho-org/morpho-sdk/fetch), so you always pass fresh, accrued data into the builders:

These data objects are the canonical entity classes re-exported from @morpho-org/morpho-sdk/entities. Refer to that module for the full type surface, accrual math, and helpers.

Errors and invariants

The SDK uses dedicated error classes (no generic Errors) so you can branch on failure modes deterministically. A few highlights:

The full list lives in src/types/error.ts.

Key invariants

• Builder = signer. The viem client used to build a transaction MUST be the one used to sign and send it.
• Transaction objects are deep-frozen. They cannot be mutated after buildTx.
• No any. Strict TypeScript across the entire surface, with discriminated unions for every action type.
• Chain id is mandatory. Every entity is constructed against a specific chain id, validated against the viem client.
• Morpho Bundles are the route for every Blue and Vault write that touches a user's tokens or position: Blue writes call BlueBundlesV1, vault deposits/withdrawals/redemptions call VaultBundlesV1, and in-kind exits and Vault V2 force withdrawals call VaultExitBundlesV1. The exception is VaultV2 forceRedeem, a plain vault multicall that needs no allowance to a Bundles contract; Midnight actions from Morpho SDK 7.0.0 use MidnightBundlesV2 - see the Actions overview.
• Vault deposits are share-price protected. maxSharePrice is computed from fresh onchain state and your slippageTolerance; the LLTV buffer additionally protects Blue borrow, collateral-withdrawal, and refinance legs. Blue write calls accept no share-price bounds or slippageTolerance input.
• Refinance markets must be compatible. Source and destination markets must be different and must share loanToken and collateralToken.
• Refinance migrates the full position. It always moves the entire msg.sender position and validates the complete destination position against the LLTV buffer. Always pass fresh source and destination positionData.
• Refinance is msg.sender-only. There is no on-behalf migration, and no partial or collateral-only mode.

Resources

• Repository: morpho-org/sdks · packages/morpho-sdk
• Package: @morpho-org/morpho-sdk on npm
• Architecture: ARCHITECTURE.md
• Migration guide from Morpho SDK 6 to Morpho SDK 7.0.0: MIGRATION-v6-to-v7.md
• v5 → v6 migration guide: MIGRATION-v5-to-v6.md
• Examples: examples/example.ts
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md
• Lower-level primitives: @morpho-org/morpho-sdk/entities · @morpho-org/morpho-sdk/fetch