Euler V2 SDK

Installation

npm install @eulerxyz/euler-v2-sdk

Example Usage (Multiply + Simulation)

import { buildEulerSDK, getSubAccountAddress } from "@eulerxyz/euler-v2-sdk";
import { mainnet } from "viem/chains";
import { parseUnits } from "viem";

// Set EULER_SDK_RPC_URL_1=https://your-rpc-url in the environment.
const sdk = await buildEulerSDK();

const owner = "0xYourEOA";
const subAccount = getSubAccountAddress(owner, 1);

const account = await sdk.accountService.fetchAccount(mainnet.id, owner, {
  populateVaults: true,
});

const quotes = await sdk.swapService.getDepositQuote({
  chainId: mainnet.id,
  fromVault: "0xLiabilityVault",
  toVault: "0xLongVault",
  fromAccount: subAccount,
  toAccount: subAccount,
  fromAsset: "0xLiabilityAsset",
  toAsset: "0xLongAsset",
  amount: parseUnits("50", 6),
  origin: owner,
  slippage: 0.5,
  deadline: Math.floor(Date.now() / 1000) + 1800,
});

const plan = sdk.executionService.planMultiplyWithSwap({
  account,
  collateralVault: "0xCollateralVault",
  collateralAmount: parseUnits("100", 6),
  collateralAsset: "0xCollateralAsset",
  swapQuote: quotes[0]!,
});

const simulation = await sdk.simulationService.simulateTransactionPlan(
  mainnet.id,
  owner,
  plan,
  { stateOverrides: true }
);

// Use simulated account and vaults state in the UI.
// Use simulation.canExecute or errors to decide whether and how to execute this plan in your app.
// See /examples/utils/executor.ts

What This SDK Is For

@eulerxyz/euler-v2-sdk provides everything needed to interact with Euler V2 lending contracts:

• fetching account, vault, wallet balance/allowance, and market data
• planning and composing EVC transaction batches
• resolving approvals (approve/Permit2 paths)
• simulating transactions before execution
• handling vault swaps, wallet-to-wallet swaps, pricing, rewards, rEUL locks, Safe smart-account detection, Public Labels V3 metadata, visibility and geo policies, and deployed addresses
• fetching Data V3 oracle adapter assessments and indexed router state

The SDK is built with dependency injection, so you can use buildEulerSDK() for a default setup, run individual services in isolation, or modify the behavior with your custom implementations.

Configuration

Runtime config can come from buildEulerSDK({ config }), supported explicit SDK options, EULER_SDK_* environment variables, or SDK defaults. RPC URLs are supplied through config.rpcUrls or EULER_SDK_RPC_URL_<chainId>. See the full Configuration Reference and Config Through Env for all options and defaults.

Docs Table of Contents

All docs are in ./docs.

1. Configuration - All buildEulerSDK() options, defaults, and service overrides.
2. Config Through Env - EULER_SDK_* environment variables and matching config fields.
3. Basic Usage - Fast setup and common account/vault/wallet usage patterns.
4. SDK Architecture Overview - High-level architecture, dependency injection model, and composition options.
5. Services - Service map, top-level entry points, and lower-level support services.
6. Wallet Service - Native/ERC20 balances and direct/Permit2 allowance reads.
7. Execution Service - encodeX vs planX, approvals flow, named operation groups, mergePlans, and describeBatch.
8. Simulations and State Overrides - Plan simulation flow, validation output, and state override utilities.
9. Swaps - Swap quote APIs and how swap payloads fit into plans.
10. CoW Swaps - CoW quote metadata, CoW-specific planners, order submission, status polling, and cancellation.
11. Position Migration Service - Cross-protocol position migration (Aave V3, Morpho Blue, MetaMorpho) into and out of Euler, with authorizations and swaps.
12. Rewards Service - Reward reads, viewer-aware eligibility, and provider-specific claim planning.
13. rEUL Lock Service - rEUL lock reads and unlock transaction planning.
14. Fee Flow Service - FeeFlow state reads, eligible-vault filtering, and buy-plan construction.
15. Safe Account Service - Safe smart-account detection and signer configuration reads.
16. Pricing System - Price data pipeline, fallback behavior, and pricing integration points.
17. Fallback System - V3 → onchain/subgraph/direct fallback chains, trigger semantics, and onFallback telemetry.
18. Data Architecture - Entities/adapters/services layering, population model, and data flow.
19. Cross-Service Data Population - How services enrich entities with prices, rewards, labels, and nested vaults.
20. Block-Pinned Reads - Reading every on-chain value at one block (number or EIP-1898 hash) and bundling lens reads into one eth_call.
21. Portfolio - High-level savings/borrows abstraction built from populated accounts.
22. Entity Reference - Property-level reference for exported entity shapes.
23. Account Computed Properties - Health factor/LTV/net-value computed fields and data prerequisites.
24. Caching External Data Queries - query* decoration pattern for caching/logging/profiling.
25. Plugins - Plugin system for read-path and plan-path extensions.
26. Labels and vault assessments - Published metadata, visibility and raw assessment reads.
27. Decoding Smart Contract Errors - Revert decoding utilities for better error handling.
28. Entity Diagnostics - Sidecar metadata for data normalization, fallbacks, and per-field warnings.
29. Adding a Chain - What the SDK reads at runtime per chain, and the per-chain entries kept in this repository.

Examples

Runnable examples are in ./examples, including end-to-end execution flows and simulations against a fork.

Comparison, parity-check, and other test-oriented scripts and reports live under ./test/parity.

Release Process

This package is published through the repo-local RELEASE.md playbook and the local $publish skill.

Git tags and GitHub Releases are the release-note source of truth. The committed package.json does not carry a release version; $publish derives the npm version from the euler-v2-sdk-vX.Y.Z tag, including prerelease tags such as euler-v2-sdk-vX.Y.Z-beta.0.

The publish flow verifies npm auth, runs pnpm -C packages/euler-v2-sdk run release:check, creates and pushes an euler-v2-sdk-vX.Y.Z tag from the selected main commit, temporarily writes the tag version for npm, dry-runs the package, publishes with npm publish --access public --provenance=false, restores the working tree, and creates the GitHub Release against the verified tag from a generated notes file. Prereleases publish with the matching npm dist-tag, for example npm publish --access public --tag beta --provenance=false.

Publishing uses the operator's local npm session. npm may prompt for a one-time password or provide a browser authentication URL; complete that prompt before the publish process exits.

Default labels service

buildEulerSDK().eulerLabelsService uses Public Labels V3 (public / latest), sharing the configured V3 endpoint, API key and query cache. Results preserve live visibility, managing entities and geo policies; failed reads reject without falling back to files. Use eulerLabelsV3AdapterConfig for dataset, publication or transport customization. Applications supply custom labels flows through servicesOverrides.eulerLabelsService. See Labels for source selection and trust semantics.

V3 labels without assessments

PublicLabelsV3MetadataAdapter reads published labels, entity profiles/addresses and live geo policies without visibility: it enumerates /labels/vaults without include=visibility and never reads a direct verdict. Select it explicitly for consumers that perform their own verification; it is not an automatic fallback from PublicLabelsV3Adapter.

import { PublicLabelsV3MetadataAdapter, normalizePublicLabelsMetadata } from '@eulerxyz/euler-v2-sdk/public-labels';

const adapter = new PublicLabelsV3MetadataAdapter({ endpoint: 'https://v3.euler.finance', labelSet: 'public' });
const snapshot = await adapter.fetchPublicLabelsSnapshot(146);
const metadata = normalizePublicLabelsMetadata(146, snapshot.publicLabels);
// metadata.candidateVaultAddresses / candidateEarnVaultAddresses are fetch candidates.
// verifiedVaultAddresses and earnVaults remain empty; independent verification is required.

The snapshot carries source: 'v3-metadata' and no visibility verdicts. Metadata-only normalization preserves product notExplorable and vault notExplorableLend/notExplorableBorrow flags; Earn uses its lend-side flag plus product hiding. Deprecation alone does not hide a vault. Assessed normalization remains independent of these raw flags. Both adapters share publication selection and metadata mapping; the assessed adapter still requires live verdicts, attached to the labels enumeration by include=visibility or read directly for rows not evaluated yet. The application owns chain selection, governance verification, discovery and geo enforcement.