Wido Docs
Search
⌃K
⚙

JavaScript SDK

Wido Router enables single transaction swaps of any token, including non-liquid tokens like vaults, pools or farms. It is available on all EVM chains.
Wido JavaScript SDK enables integration with full control over the UX. If speed is important to you, try the Wido Widget.

Demo

You can see it live here. For example, try swapping DAI for yvcrvstETH.

API Reference

The API Reference docs can be found at https://unpkg.com/[email protected]/docs/index.html.

Getting Started

In this guide, we will let the user deposit any token into a pool of choice. We will use Wido Router to find the most efficient route to deposit the user's token into the pool, create a transaction bundle and execute the whole bundle as a single transaction.
  1. 1.
    Approve Wido Smart Contract for the Swap
  2. 2.
    Request quote and transaction details from the Wido API
  3. 3.
    Enable the user to execute the transaction from their wallet

Preparation: Install Wido SDK using NPM

npm install --save wido

Step 1: Approve Wido for the Swap transaction

In this step, create an approve transaction to allow the Wido Contract to access the token being transferred (the input token).
import { approve } from "wido"
​
const { data, to } = await approve({
chainId,
fromToken, // Token you wish to zap with.
toToken, // Token you wish to zap into.
amount // (Optional) Amount to allow. It can be left empty for maximum approval.
})
​
console.log(to) // The contract you should send your transaction to
console.log(data) // Unsigned tx that will give Wido permission to spend your tokens
​
const tx = await signer.sendTransaction({ data, to })
​
console.log(tx.hash)
// "0x66acd87c5e..."
​
await tx.wait()
If you have custom approve logic and cannot use Wido'sapprove method, check out the getWidoSpender method below, which you can use to get the address which needs to be approved for spending tokens on the user's behalf. https://docs.joinwido.com/api-guides/router#get-the-contract-address-for-approvals​

Step 2: Receive a Quote

Request a quote for the Zap transaction.
Note: steps object contains details about the transaction route.
import { quote } from "wido"
​
const quoteResult = await quote({
fromChainId, // Chain Id of from token
fromToken, // Token address of from token
toChainId, // Chain Id of to token
toToken, // Token address of to token
amount, // Token amount of from token
slippagePercentage, // Acceptable max slippage for the swap
user, // Address of user placing the order.
})
​
const {
isSupported, // Whether the route is supported or not
steps, // The steps this route will take. Used to show the route breakdown
stepsCount, // Number of steps the route will take
price, // Expected price of `toToken`
minPrice, // Minimum accepted price for a successful transaction
fromTokenUsdPrice, // Price of `fromToken` in US dollars
fromTokenAmount, // Amount of `fromToken` to send
fromTokenAmountUsdValue, // Value of `fromTokenAmount` in US dollars
toTokenUsdPrice, // Price of `toToken` in US dollars
toTokenAmount, // Expected amount of `toToken` to receive
toTokenAmountUsdValue, // Value of `toTokenAmount` in US dollars
expectedSlippage, // Expected slippage calculated from `fromTokenAmountUsdValue` and `toTokenAmountUsdValue`
minToTokenAmount, // Minimum amount of the to token the user is willing to accept for a successful transaction
to, // The contract address where the unsigned transaction needs to be sent
data, // Unsigned transaction data
value, // Amount of native tokens that need to be sent
from, // User address who should be sending the tx
} = quoteResult
​
We do our best to provide accurate pricing (for fromTokenUsdPrice and toTokenUsdPrice), but it might not be available for some tokens. Please reach out if you want dedicated pricing support. Read more on pricing here: https://docs.joinwido.com/api-guides/pricing.

Step 3: Execute the Swap transaction

In this step, execute the Zap transaction using data received from calling the quote.
import { quote } from "wido"
​
const { data, to, value } = await quote({
fromChainId, // Chain Id of the from token
fromToken, // Token address of from token
toChainId, // Chain Id of the to token
toToken, // Token address of to token
amount, // Token amount in from token
slippagePercentage, // Acceptable max slippage for the swap
user, // Address of user placing the order.
})
​
const tx = await signer.sendTransaction({ data, to, value })
​
console.log(tx.hash)
// "0x66acd87c5e..."
​
await tx.wait()

Get list of Supported Tokens

Get the list of supported tokens on all chains or on a specific chain. Zap between any supported token is possible in and across the supported chains.
import { getSupportedTokens } from "wido"
​
const tokenList = await getSupportedTokens({
chainId: [1, 137], // (Optional) Array of chain ids to filter by
protocol: ["dex", "yearn.finance", "aave.com"] // (Optional) Array of protocols to filter by
})
console.log(tokenList)
// [
// {
// chainId: 137,
// address: "0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
// protocol: "dex",
// symbol: "USDC",
// name: "USDC",
// decimals: 6,
// logoURI: "https://polygonscan.com/token/images/centre-usdc_32.png"
// }
// {
// chainId: 1,
// address: "0xa258C4606Ca8206D8aA700cE2143D7db854D168c",
// protocol: "yearn.finance",
// symbol: "yvWETH",
// name: "yvWETH 0.4.2",
// decimals: 18,
// logoURI: "https://rawcdn.githack.com/yearn/yearn-assets/1e6b3fae35b269cbd65bd3ba4489080733a24264/icons/multichain-tokens/1/0xa258C4606Ca8206D8aA700cE2143D7db854D168c/logo-128.png"
// },
// ...
// ]
​
Edit and run this example on RunKit: https://runkit.com/wido/get-supported-tokens.

Get list of User Balances

Get the list of supported tokens found in the user's wallet, on all chains or on a specific chain, that can be used for depositing. Zap between any supported token is possible in and across the supported chains.
import { getBalances } from "wido"
​
const balances = await getBalances(
userAddress, // Address of the user
chainId // Optional Array of chain ids to filter by.
)
console.log(balances)
// [
// {
// chainId: 137,
// address: "0x7ceB23fD6bC0adD59E62ac25578270cFf1b9f619",
// symbol: "WETH",
// name: "Wrapped Ether",
// decimals: 18,
// logoURI: "https://logos.covalenthq.com/tokens/1/0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee.png",
// balance: "3000000000000000",
// balanceUsdValue: "4.08",
// usdPrice: "1360.97"
// },
// ...
// ]
​
We do our best to provide accurate pricing (for balanceUsdValue and usdPrice), but it might not be available for some tokens. Please reach out if you want dedicated pricing support. Read more on pricing here: https://docs.joinwido.com/api-guides/pricing.

Get token allowance

Get the number of tokens that the Wido contract can spend on the user's behalf, as per the ERC-20 standard.
import { getTokenAllowance } from "wido"
​
const { spender, allowance } = await getTokenAllowance({
chainId: 1, // Mainnet
fromToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
toToken: "0xa258C4606Ca8206D8aA700cE2143D7db854D168c", // yvWETH
accountAddress: "0xaCfE4511CE883C14c4eA40563F176C3C09b4c47C", // User
})
​
console.log(spender)
// "0xF2F02200aEd0028fbB9F183420D3fE6dFd2d3EcD" <- Wido contract
console.log(allowance)
// "1157920892373161954235709850086879078..." <- MAX_UINT256
Edit and run this example on RunKit: https://runkit.com/wido/get-token-allowance.

Get the contract address for approvals

Get contract address that the user needs to approve before zapping. As per the ERC20 standard, Wido needs permission to spend tokens on behalf of user.
const { getWidoSpender } = require("wido")
​
const widoSpenderAddress = await getWidoSpender({
chainId: 1, // Mainnet
fromToken: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
toToken: "0xa258C4606Ca8206D8aA700cE2143D7db854D168c", // yvWETH
})
​
console.log(widoSpenderAddress)
// "0xF2F02200aEd0028fbB9F183420D3fE6dFd2d3EcD"
Edit and run this example on RunKit: https://runkit.com/wido/get-wido-spender.
Warning: WidoTokenManager and WidoRouter are two separate contracts. ERC-20 approvals are made to WidoTokenManager and orders are sent to WidoRouter.
When you call approve always send the transaction to the to address returned in the response.
When you call quote always send the transaction to the to address returned in the response.