SDK - Enso Developer Documentation

The Enso SDK provides a set of tools and methods to interact with the Enso API. It includes functionalities for token approvals, routing, quoting, and balance checking. The Route API is a highly-efficient DeFi aggregation and smart order routing REST API. With it, developers can easily tap into optimized routes for DeFi tokens/positions and multi-token swaps across various chains.

View on GitHub

Installation

Install the Enso SDK using your preferred package manager:

npm

npm install @ensofinance/sdk

Quick Start

This example shows how to swap ETH directly to a Yearn vault position:

import { EnsoClient } from '@ensofinance/sdk';

const enso = new EnsoClient({
  apiKey: 'YOUR_API_KEY',
});

async function enterYearnVault() {
  // First, get the transaction data
  const routeData = await enso.getRouteData({
    fromAddress: '0xYourWalletAddress',
    receiver: '0xYourWalletAddress',
    spender: '0xYourWalletAddress',
    chainId: 1,
    amountIn: ['1000000000000000000'], // 1 ETH
    tokenIn: ['0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'], // ETH
    tokenOut: ['0xa258C4606Ca8206D8aA700cE2143D7db854D168c'], // yvWETH
    slippage: 50,
    routingStrategy: 'router',
  });
  
  // The routeData.tx object can now be sent using your preferred web3 library
  // Example with ethers.js:
  // const provider = new ethers.providers.Web3Provider(window.ethereum);
  // const signer = provider.getSigner();
  // const tx = await signer.sendTransaction(routeData.tx);
  // await tx.wait();
  
  console.log('Transaction data:', routeData.tx);
  console.log('Expected yvWETH amount:', routeData.amountOut);
}

enterYearnVault();

Core Concepts

The Enso SDK abstracts complex DeFi operations through several key components:

EnsoClient: The main entry point for all SDK functionalities
Routing Strategies: Different execution paths for transactions
Bundle Actions: Compose multiple DeFi operations in a single transaction
Approvals: Manage token allowances for DeFi interactions
Token Data: Retrieve detailed information about tokens and protocols

Routing Strategies

There are 3 routing strategies available depending on your use case:

router - Uses a single contract which acts as a universal router
delegate - Returns calldata in the form of delegateCalls for smart accounts
delegate-legacy - Legacy version of delegate routing
router-legacy - Legacy version of router routing

Complete Methods Reference

Primary Methods

getRouteData(params: RouteParams)

Calculates the optimal route for token swaps or entering/exiting DeFi positions. Parameters:

fromAddress (Address): Ethereum address of the wallet to send the transaction from
receiver? (Address): Ethereum address of the receiver of the tokenOut
spender? (Address): Ethereum address of the spender of the tokenIn
chainId (number): Chain ID of the network to execute the transaction on
destinationChainId? (number): Chain ID of the destination network for cross-chain bridging
amountIn (Quantity[]): Amount of tokenIn to swap in wei
slippage? (Quantity): Slippage in basis points (1/10000)
minAmountOut? (Quantity[]): Minimum amount out in wei
tokenIn (Address[]): Ethereum address of the token to swap from
tokenOut (Address[]): Ethereum address of the token to swap to
routingStrategy (RoutingStrategy): Routing strategy to use
fee? (Quantity[]): Fee in basis points for each amountIn value
feeReceiver? (Address): Address that will receive the collected fee
ignoreAggregators? (string[]): List of swap aggregators to ignore
ignoreStandards? (string[]): List of standards to ignore
toEoa? (boolean): Flag indicating if gained tokenOut should be sent to EOA
referralCode? (string): Referral code included in on-chain event

Returns: Promise<RouteData>

const routeData = await enso.getRouteData({
  fromAddress: '0xYourWalletAddress',
  receiver: '0xYourWalletAddress',
  spender: '0xYourWalletAddress',
  chainId: 1,
  amountIn: ['1000000000000000000'], // 1 ETH in wei
  tokenIn: ['0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee'], // ETH
  tokenOut: ['0x6b175474e89094c44da98b954eedeac495271d0f'], // DAI
  slippage: 50, // 0.5%
  routingStrategy: 'router',
});

getApprovalData(params: ApproveParams)

Generates transaction data for approving tokens to be spent by Enso contracts. Parameters:

fromAddress (Address): Ethereum address of the wallet to send the transaction from
tokenAddress (Address): ERC20 token address of the token to approve
chainId (number): Chain ID of the network to execute the transaction on
amount (Quantity): Amount of tokens to approve in wei

Returns: Promise<ApproveData>

const approvalData = await enso.getApprovalData({
  fromAddress: '0xYourWalletAddress',
  tokenAddress: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH
  chainId: 1,
  amount: '1000000000000000000', // 1 WETH in wei
});

getBundleData(params: BundleParams, actions: BundleAction[])

Constructs bundled transaction data for multiple DeFi operations in a single transaction. First argument (params):

chainId (number): Chain ID of the network to execute the transaction on
fromAddress (Address): Ethereum address of the wallet sending the transaction
routingStrategy (RoutingStrategy): Execution strategy
receiver? (Address): Default final-output receiver
spender? (Address): Account supplying input assets when supported
refundReceiver? (Address): Dust or applicable bridge-refund receiver
ignoreAggregators? (string[]): Swap aggregators to ignore
referralCode? (string): Referral code included in the on-chain event

Second argument (actions): ordered BundleAction[] request body. Returns: Promise<BundleData>

const bundle = await enso.getBundleData(
  {
    chainId: 1,
    fromAddress: '0x123...',
    routingStrategy: 'delegate',
  },
  [
    {
      protocol: 'enso',
      action: 'route',
      args: {
        tokenIn: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
        tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
        amountIn: '1000000000',
        receiver: '0x123...'
      }
    }
  ]
);

Data Retrieval Methods

getBalances(params: BalanceParams)

Retrieves token balances for a given wallet address. Parameters:

chainId? (number): Chain ID of the network to execute the transaction on
eoaAddress (Address): Address of the EOA to associate with the ensoWallet for balances
useEoa? (boolean): If true, returns balances for the provided eoaAddress instead of the associated ensoWallet

Returns: Promise<WalletBalance[]>

const balances = await enso.getBalances({
  chainId: 1,
  eoaAddress: '0xYourWalletAddress',
  useEoa: true,
});

getTokenData(params: TokenParams)

Fetches detailed information about tokens, including DeFi tokens and their underlying assets. Parameters:

project? (string): The overarching project or platform associated with the DeFi token
protocolSlug? (string): The specific standard integration or version of the DeFi project
underlyingTokens? (MultiAddress): Underlying tokens of defi token
underlyingTokensExact? (MultiAddress): Exact composition of underlying tokens
primaryAddress? (MultiAddress): Ethereum addresses for contract interaction
address? (MultiAddress): Ethereum addresses of the tokens
chainId? (number): Chain ID of the network of the token
type? (TokenType): Type of token (‘defi’ | ‘base’)
apyFrom? (Quantity): Only include tokens with APY over this value
apyTo? (Quantity): Only include tokens with APY below this value
tvlFrom? (Quantity): Only include tokens with TVL over this value
tvlTo? (Quantity): Only include tokens with TVL below this value
page? (number): Pagination page number (pages are of length 1000)
cursor? (number): Cursor for pagination
includeMetadata? (boolean): Whether to include token metadata
name? (string[]): Names of the tokens
symbol? (string[]): Symbols of the tokens

Returns: Promise<PaginatedTokenData>

const tokens = await enso.getTokenData({
  chainId: 1,
  type: 'defi',
  includeMetadata: true,
  page: 1
});

getPriceData(params: PriceParams)

Gets the current price data for a specific token. Parameters:

chainId (number): Chain ID of the network to search for
address (Address): Address of the token to search for

Returns: Promise<PriceData>

const price = await enso.getPriceData({
  chainId: 1,
  address: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', // WETH
});

getMultiplePriceData(params: MultiPriceParams)

Gets price data for multiple tokens. Parameters:

chainId (number): Chain ID of the network to search for
addresses (Address[]): Addresses of tokens to check prices for

Returns: Promise<PriceData[]>

const prices = await enso.getMultiplePriceData({
  chainId: 1,
  addresses: [
    '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH
    '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'  // USDC
  ]
});

Protocol and Standard Methods

getProtocolData(params?: ProtocolParams)

Retrieves information about DeFi protocols supported by Enso. Parameters:

chainId? (number | string): Chain ID of the network to search for
slug? (string): Slug of the project to search for

Returns: Promise<ProtocolData[]>

// Get all protocols
const allProtocols = await enso.getProtocolData();

// Get protocols for a specific chain
const ethereumProtocols = await enso.getProtocolData({ chainId: 1 });

// Get a specific protocol
const aaveProtocol = await enso.getProtocolData({ slug: 'aave-v3' });

getStandards()

Returns standards available for bundling with protocol information and supported actions. Returns: Promise<StandardData[]>

const standards = await enso.getStandards();

getStandardBySlug(slug: string)

Returns a standard matching the given slug with supported actions and chains. Parameters:

slug (string): The protocol slug

Returns: Promise<StandardData[]>

const aaveStandard = await enso.getStandardBySlug('aave-v3');

getActions()

Returns all actions that can be bundled with the /shortcuts/bundle endpoint. Returns: Promise<ActionData[]>

const actions = await enso.getActions();

getActionsBySlug(slug: string)

Gets actions for a specific protocol. Parameters:

slug (string): The protocol slug

Returns: Promise<ActionData[]>

const aaveActions = await enso.getActionsBySlug('aave-v3');

Specialized Methods

getRouteNonTokenized(params: RouteNonTokenizedParams)

Gets execution data for best route to non-tokenized positions. Parameters:

chainId (number): Chain ID of the network to execute the transaction on
fromAddress (Address): Ethereum address of the wallet to send the transaction from
routingStrategy (‘delegate’ | ‘delegate-legacy’): Routing strategy to use
tokenIn (Address[]): Input tokens
positionOut (Address): Non-tokenized position to receive
slippage? (Quantity): Slippage in basis points
fee? (Quantity[]): Fee in basis points
feeReceiver? (Address): Fee receiver address
amountIn (Quantity[]): Amount to send
receiver (Address): Receiver address
spender? (Address): Spender address
referralCode? (string): Referral code

Returns: Promise<RouteData>

const route = await enso.getRouteNonTokenized({
  fromAddress: '0x123...',
  chainId: 1,
  routingStrategy: 'delegate',
  tokenIn: ['0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'],
  positionOut: '0xPositionAddress',
  amountIn: ['1000000000'],
  receiver: '0x123...',
  slippage: 50,
});

getIporShortcut(params, data: IporShortcutInputData)

Returns a transaction for IPOR shortcut operations. Parameters:

chainId? (number): Chain ID (optional)
fromAddress (string): Ethereum address of the wallet
data (IporShortcutInputData): IPOR shortcut input data

Returns: Promise<IporShortcutData>

const iporShortcut = await enso.getIporShortcut(
  { chainId: 1, fromAddress: '0x123...' },
  {
    amountIn: '1000000000000000000',
    tokenIn: '0xTokenAddress',
    tokenBToBuy: '0xTokenBAddress',
    percentageForTokenB: 5000, // 50%
    slippage: 50,
    simulate: true
  }
);

getNonTokenizedPositions(params?: NonTokenizedParams)

Gets all non-tokenized positions with details. Parameters:

project? (string): The overarching project or platform
protocolSlug? (string): The specific standard integration
chainId? (number): Chain ID of the network
destinationChainId? (number): Destination chain ID for cross-chain bridging
address? (Address[]): Ethereum addresses of positions
primaryAddress? (Address[]): Ethereum addresses for contract interaction
page? (number): Pagination page number
cursor? (number): Cursor for pagination

Returns: Promise<PaginatedNonTokenizedPositionData>

const nonTokenizedPositions = await enso.getNonTokenizedPositions({
  chainId: 1,
  project: 'aave'
});

Network and Utility Methods

getNetworks(params?: NetworkParams)

Returns networks supported by Enso. Parameters:

name? (string): Name of the network to search for
chainId? (string): Chain ID of the network to search for

Returns: Promise<ConnectedNetwork[]>

const networks = await enso.getNetworks();
const ethereum = await enso.getNetworks({ chainId: "1" });

getProjects()

Returns supported projects or platforms associated with available protocols. Returns: Promise<Project[]>

const projects = await enso.getProjects();

getProtocolsByProject(project: string)

Returns all protocols available within the given project. Parameters:

project (string): The project name

Returns: Promise<ProtocolData[]>

const aaveProtocols = await enso.getProtocolsByProject('aave');

getAggregators(chainId?: number)

Fetches aggregators supported by Enso. Parameters:

chainId? (number): Chain ID to filter aggregators for

Returns: Promise<string[]>

const aggregators = await enso.getAggregators(1);

getVolume(chainId: number)

Returns total USD and transactions volume for the given chainId. Parameters:

chainId (number): Chain ID to get volume for

Returns: Promise<unknown>

const volume = await enso.getVolume(1);

getAccountId()

Gets the account ID associated with the API key. Returns: Promise<string>

const accountId = await enso.getAccountId();

Working with Large Numbers

The SDK properly handles large numbers common in blockchain transactions:

const wethAmount = "1000000000000000000"; // 1 WETH with 18 decimals
const usdcAmount = "1000000"; // 1 USDC with 6 decimals

Always use base-unit strings for token amounts. Do not use JavaScript numbers.

Bundle actions

Start with the Bundle API guide, then use the Bundle Actions Reference for public composition actions. Query protocol metadata for current protocol-specific availability:

// Get all available actions
const actions = await enso.getActions();

// Get actions for a specific protocol
const aaveActions = await enso.getActionsBySlug("aave-v3");

Common bundle actions include:

Route: Token swaps and conversions
Deposit: Deposit tokens into DeFi protocols
Redeem: Withdraw tokens from DeFi protocols
Approve: Token approvals
Borrow: Borrow tokens from lending protocols
Repay: Repay loans to lending protocols
Transfer: Transfer tokens between addresses
Bridge: Cross-chain token transfers

Error Handling

The SDK includes proper error handling with custom error types:

import { EnsoClient, EnsoApiError } from '@ensofinance/sdk';

try {
  const routeData = await enso.getRouteData(params);
} catch (error) {
  if (error instanceof EnsoApiError) {
    console.error('API Error:', error.statusCode, error.responseData);
  } else {
    console.error('Request Error:', error.message);
  }
}

Best Practices

Use String Representations: Always use string representations for token amounts to avoid precision issues with large numbers
Handle Slippage: Set appropriate slippage values (in basis points) to protect against price movements
Gas Estimation: Use the returned gas estimate to set appropriate gas limits
Error Handling: Implement proper error handling for network issues and API errors
Rate Limiting: Be mindful of API rate limits when making multiple requests

Next Steps

Explore these resources to fully leverage the Enso SDK:

Routing Strategies - Learn about the different routing options and when to use each one
Bundle API - Compose, build, approve, and execute ordered actions
Bundle Actions Reference - Review public action inputs, outputs, and chaining rules
Shortcuts - See practical examples of common DeFi operations implemented with the SDK
Non-tokenized Positions - Discover how to interact with non-tokenized DeFi positions like Aave borrows or Liquity CDPs
GitHub Repository - Access the source code, report issues, or contribute to the SDK
Developer Chat - Join our Telegram group for technical support and discussions

Updated

View on GitHub

​Installation

​Quick Start

​Core Concepts

​Routing Strategies

​Complete Methods Reference

​Primary Methods

​getRouteData(params: RouteParams)

​getApprovalData(params: ApproveParams)

​getBundleData(params: BundleParams, actions: BundleAction[])

​Data Retrieval Methods

​getBalances(params: BalanceParams)

​getTokenData(params: TokenParams)

​getPriceData(params: PriceParams)

​getMultiplePriceData(params: MultiPriceParams)

​Protocol and Standard Methods

​getProtocolData(params?: ProtocolParams)

​getStandards()

​getStandardBySlug(slug: string)

​getActions()

​getActionsBySlug(slug: string)

​Specialized Methods

​getRouteNonTokenized(params: RouteNonTokenizedParams)

​getIporShortcut(params, data: IporShortcutInputData)

​getNonTokenizedPositions(params?: NonTokenizedParams)

​Network and Utility Methods

​getNetworks(params?: NetworkParams)

​getProjects()

​getProtocolsByProject(project: string)

​getAggregators(chainId?: number)

​getVolume(chainId: number)

​getAccountId()

​Working with Large Numbers

​Bundle actions

​Error Handling

​Best Practices

​Next Steps