⚡Zap 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.

Pivot alert: Wido has become Walnut. This docs as well as the Wido Zap API will be discontinued. Read full announcement.

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/wido@latest/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. Approve Wido Smart Contract for the Swap

2. Request quote and transaction details from the Wido API

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

RunKit example: https://runkit.com/wido/approve.

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()

RunKit example: https://runkit.com/wido/quote.

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"
//   },
//   ...
// ]

See the API reference: https://unpkg.com/wido@latest/docs/functions/getSupportedTokens.html.

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

See the API reference: https://unpkg.com/wido@latest/docs/functions/getTokenAllowance.html.

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" 

See the API reference: https://unpkg.com/wido@latest/docs/functions/getWidoSpender.html.

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.