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 taking care of the Bundler3 / GeneralAdapter1 plumbing, slippage protection, ERC-20 approvals, Permit / Permit2 signatures, Morpho authorizations, native-token wrapping, Blue-to-Blue refinance, and shared-liquidity reallocations for you.

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 PublicAllocator.

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, per entity - 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@5.4.1 viem@^2.0.0
# or
yarn add @morpho-org/morpho-sdk@5.4.1 viem@^2.0.0
# or
npm install @morpho-org/morpho-sdk@5.4.1 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 on-chain pre-requisites that must be satisfied first.

A requirement is one of:

• An ERC-20 approval transaction the user must send first (approving the bundler - or Morpho - to pull tokens).
• A Permit / Permit2 signature request - 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 }).
• A Morpho authorization - morpho.setAuthorization(generalAdapter1, true). Required once per user for borrow, supplyCollateralBorrow, 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 bundle as a setAuthorizationWithSig 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 are the exception: they submit signed offers to the Midnight mempool instead of returning a viem Transaction you send yourself - 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(generalAdapter1, 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 bundles for honest integrators, not a defense against a malicious builder. The signer remains responsible for reviewing what they sign. See BUNDLER3.md for the deeper Bundler3 / GeneralAdapter1 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.
• Bundler3 is the default route for any operation that touches a user's tokens or position; direct calls are reserved for surfaces with no attack surface (vault withdraw / redeem, morpho.withdrawCollateral).
• Slippage protection is always on. maxSharePrice (deposits, loan-asset supply, repay) and minSharePrice (borrows, loan-asset withdraw) are computed from fresh on-chain state and your slippage tolerance; the LLTV buffer additionally protects collateral operations.
• Refinance markets must be compatible. Source and target markets must be different and must share loanToken and collateralToken.
• Refinance uses fresh source and target positions. Always pass fresh source and target positionData; the SDK validates source residual health and target aggregate health with the LLTV buffer.
• Refinance shares mode overshoots and sweeps. Shares mode overshoots the target borrow with slippage, repays source shares, then sweeps residual loan tokens back into target debt or user.
• Collateral-only refinance skips target health validation. It skips target health / oracle validation because it cannot worsen target debt health.

Resources

• Repository: morpho-org/sdks · packages/morpho-sdk
• Package: @morpho-org/morpho-sdk on npm
• Architecture: ARCHITECTURE.md
• Bundler3 / GeneralAdapter1 deep-dive: BUNDLER3.md
• Examples: examples/example.ts
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md
• Lower-level primitives: @morpho-org/morpho-sdk/entities · @morpho-org/morpho-sdk/fetch