SDK
Enso SDK is a JavaScript library for interacting with Enso API.
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:
Quick Start
This example shows how to swap ETH directly to a Yearn vault position:
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 routerdelegate
- Returns calldata in the form of delegateCalls for smart accountsdelegate-legacy
- Legacy version of delegate routingrouter-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 fromreceiver?
(Address): Ethereum address of the receiver of the tokenOutspender?
(Address): Ethereum address of the spender of the tokenInchainId
(number): Chain ID of the network to execute the transaction ondestinationChainId?
(number): Chain ID of the destination network for cross-chain bridgingamountIn
(Quantity[]): Amount of tokenIn to swap in weislippage?
(Quantity): Slippage in basis points (1/10000)minAmountOut?
(Quantity[]): Minimum amount out in weitokenIn
(Address[]): Ethereum address of the token to swap fromtokenOut
(Address[]): Ethereum address of the token to swap toroutingStrategy
(RoutingStrategy): Routing strategy to usefee?
(Quantity[]): Fee in basis points for each amountIn valuefeeReceiver?
(Address): Address that will receive the collected feeignoreAggregators?
(string[]): List of swap aggregators to ignoreignoreStandards?
(string[]): List of standards to ignoretoEoa?
(boolean): Flag indicating if gained tokenOut should be sent to EOAreferralCode?
(string): Referral code included in on-chain event
Returns: Promise<RouteData>
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 fromtokenAddress
(Address): ERC20 token address of the token to approvechainId
(number): Chain ID of the network to execute the transaction onamount
(Quantity): Amount of tokens to approve in wei
Returns: Promise<ApproveData>
getBundleData(params: BundleParams, actions: BundleAction[])
Constructs bundled transaction data for multiple DeFi operations in a single transaction.
Parameters:
chainId
(number): Chain ID of the network to execute the transaction onfromAddress
(Address): Ethereum address of the wallet to send the transaction fromroutingStrategy
(RoutingStrategy): Routing strategy to usereceiver?
(Address): Ethereum address of the receiver of the tokenOutspender?
(Address): Ethereum address of the spender of the tokenInignoreAggregators?
(string[]): List of swap aggregators to ignorereferralCode?
(string): Referral code included in on-chain eventignoreStandards?
(string[]): List of standards to ignoreactions
(BundleAction[]): Array of actions to bundle
Returns: Promise<BundleData>
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 oneoaAddress
(Address): Address of the EOA to associate with the ensoWallet for balancesuseEoa?
(boolean): If true, returns balances for the provided eoaAddress instead of the associated ensoWallet
Returns: Promise<WalletBalance[]>
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 tokenprotocolSlug?
(string): The specific standard integration or version of the DeFi projectunderlyingTokens?
(MultiAddress): Underlying tokens of defi tokenunderlyingTokensExact?
(MultiAddress): Exact composition of underlying tokensprimaryAddress?
(MultiAddress): Ethereum addresses for contract interactionaddress?
(MultiAddress): Ethereum addresses of the tokenschainId?
(number): Chain ID of the network of the tokentype?
(TokenType): Type of token (‘defi’ | ‘base’)apyFrom?
(Quantity): Only include tokens with APY over this valueapyTo?
(Quantity): Only include tokens with APY below this valuetvlFrom?
(Quantity): Only include tokens with TVL over this valuetvlTo?
(Quantity): Only include tokens with TVL below this valuepage?
(number): Pagination page number (pages are of length 1000)cursor?
(number): Cursor for paginationincludeMetadata?
(boolean): Whether to include token metadataname?
(string[]): Names of the tokenssymbol?
(string[]): Symbols of the tokens
Returns: Promise<PaginatedTokenData>
getPriceData(params: PriceParams)
Gets the current price data for a specific token.
Parameters:
chainId
(number): Chain ID of the network to search foraddress
(Address): Address of the token to search for
Returns: Promise<PriceData>
getMultiplePriceData(params: MultiPriceParams)
Gets price data for multiple tokens.
Parameters:
chainId
(number): Chain ID of the network to search foraddresses
(Address[]): Addresses of tokens to check prices for
Returns: Promise<PriceData[]>
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 forslug?
(string): Slug of the project to search for
Returns: Promise<ProtocolData[]>
getStandards()
Returns standards available for bundling with protocol information and supported actions.
Returns: Promise<StandardData[]>
getStandardBySlug(slug: string)
Returns a standard matching the given slug with supported actions and chains.
Parameters:
slug
(string): The protocol slug
Returns: Promise<StandardData[]>
getActions()
Returns all actions that can be bundled with the /shortcuts/bundle
endpoint.
Returns: Promise<ActionData[]>
getActionsBySlug(slug: string)
Gets actions for a specific protocol.
Parameters:
slug
(string): The protocol slug
Returns: Promise<ActionData[]>
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 onfromAddress
(Address): Ethereum address of the wallet to send the transaction fromroutingStrategy
(‘delegate’ | ‘delegate-legacy’): Routing strategy to usetokenIn
(Address[]): Input tokenspositionOut
(Address): Non-tokenized position to receiveslippage?
(Quantity): Slippage in basis pointsfee?
(Quantity[]): Fee in basis pointsfeeReceiver?
(Address): Fee receiver addressamountIn
(Quantity[]): Amount to sendreceiver
(Address): Receiver addressspender?
(Address): Spender addressreferralCode?
(string): Referral code
Returns: Promise<RouteData>
getIporShortcut(params, data: IporShortcutInputData)
Returns a transaction for IPOR shortcut operations.
Parameters:
chainId?
(number): Chain ID (optional)fromAddress
(string): Ethereum address of the walletdata
(IporShortcutInputData): IPOR shortcut input data
Returns: Promise<IporShortcutData>
getNonTokenizedPositions(params?: NonTokenizedParams)
Gets all non-tokenized positions with details.
Parameters:
project?
(string): The overarching project or platformprotocolSlug?
(string): The specific standard integrationchainId?
(number): Chain ID of the networkdestinationChainId?
(number): Destination chain ID for cross-chain bridgingaddress?
(Address[]): Ethereum addresses of positionsprimaryAddress?
(Address[]): Ethereum addresses for contract interactionpage?
(number): Pagination page numbercursor?
(number): Cursor for pagination
Returns: Promise<PaginatedNonTokenizedPositionData>
Network and Utility Methods
getNetworks(params?: NetworkParams)
Returns networks supported by Enso.
Parameters:
name?
(string): Name of the network to search forchainId?
(string): Chain ID of the network to search for
Returns: Promise<ConnectedNetwork[]>
getProjects()
Returns supported projects or platforms associated with available protocols.
Returns: Promise<Project[]>
getProtocolsByProject(project: string)
Returns all protocols available within the given project.
Parameters:
project
(string): The project name
Returns: Promise<ProtocolData[]>
getAggregators(chainId?: number)
Fetches aggregators supported by Enso.
Parameters:
chainId?
(number): Chain ID to filter aggregators for
Returns: Promise<string[]>
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>
getAccountId()
Gets the account ID associated with the API key.
Returns: Promise<string>
Working with Large Numbers
The SDK properly handles large numbers common in blockchain transactions:
Bundle Actions
The Bundle API supports a variety of actions for interacting with DeFi protocols. For an up-to-date reference of all available actions and their parameters:
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:
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
- Available Actions for Bundle API - Explore all supported DeFi actions like swaps, deposits, borrows, and more
- 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