Quickstart
yarn add @depay/web3-exchanges
or
npm install --save @depay/web3-exchanges
import Exchanges from '@depay/web3-exchanges'
Exchanges.uniswap_v2
Exchanges.orca
// scoped
Exchanges.ethereum.uniswap_v2 // Ethereum scoped uniswap_v2
Exchanges.solana.orca
let routes
routes = await Exchanges.route({
blockchain: 'ethereum',
tokenIn: '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb',
tokenOut: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
amountIn: 1
})
routes = await Exchanges.route({
blockchain: 'solana',
tokenIn: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
tokenOut: '4k3Dyjzvzp8eMZWUXbBCjEvwSkkk59S5iCNLY3QrkX6R',
amountIn: 1
})
import { getWallets } from '@depay/web3-wallets'
const wallet = getWallets()[0]
const account = await wallet.account()
// check if prep is required to facilitate swap/exchange
const preparation = await route.getPrep({ account })
let permit2
if(prep?.transaction) {
await wallet.sendTransaction(prep.transaction)
} else if (prep?.signature) {
let signature = await wallet.sign(prep.signature)
permit2 = {...prep.signature.message, signature}
}
// use connected wallet to sign and send the swap transaction
const transaction = await route.getTransaction({ account, permit2 })
wallet.sendTransaction(transaction)
Support
This library supports the following blockchains:
This library supports the following decentralized exchanges:
Ethereum:
BNB Smart Chain:
Polygon:
Solana:
Optimism:
Base:
Arbitrum:
Fantom:
Avalanche:
Gnosis:
Platform specific packaging
In case you want to use and package only specific platforms, use the platform-specific package:
EVM (Ethereum Virtual Machine) platform specific packaging
import Exchanges from '@depay/web3-exchanges-evm'
SVM (Solana Virtual Machine) platform specific packaging
import Exchanges from '@depay/web3-exchanges-svm'
Data Structures
Exchange
Decentralized exchange data is provided in the following structure:
{
name: String (e.g. uniswap_v2)
label: String (e.g. Uniswap v2)
logo: String (base64 encoded PNG)
protocol: String (uniswap_v2, uniswap_v3 etc.)
fee: Array (e.g. [100, 500, 3000, 10000]; available fee teirs on the exchange)
slippage: Boolean (indicates if exchange has slippage)
blockchains: String (e.g. ['ethereum'])
[blockchain]: {
router: Object (contains 'address' and 'api' to interact with the exchange router)
factory: Object (contains 'address' and 'api' to interact with the exchange factory)
pair: Object (contains 'api' to interact with an exchange pair)
quoter: Object (contains 'address' and 'api' to interact with the exchange quoter)
}
}
Swap
A Swap configuration is fed into the route function:
{
blockchain: String (e.g. 'ethereum')
tokenIn: String (e.g. '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb')
tokenOut: String (e.g. '0xdAC17F958D2ee523a2206206994597C13D831ec7')
amountIn: Human Readable Number (e.g. 1.2 and converted internally to BigNumber) or BigNumber if passed as string
amountInMax: Human Readable Number (e.g. 1.2 and converted internally to BigNumber) or BigNumber if passed as string
amountOut: Human Readable Number (e.g. 1.2 and converted internally to BigNumber) or BigNumber if passed as string
amountOutMin: Human Readable Number (e.g. 1.2 and converted internally to BigNumber) or BigNumber if passed as string
}
tokenIn: The token put into the swap (out of wallet)amountIn: The exact amount of tokenIn put into the swap (out of wallet)amountInMax: The max. amount of tokenIn put into the swap (out of wallet)tokenOut: The token expected to come out of the swap (into wallet)amountOut: The exact amount of tokenOut expected to come out of the swap (into wallet)amountOutMin: The min. amount of tokenOut expected to come out of the swap (into wallet)
The following combinations of provided amounts are possible:
- Pass
amountOutMin. Swap will return at leastamountOutMininto the wallet.amountInwill be calculated automatically and can vary. - Pass
amountOut. Swap will take at maxamountInMaxout of the wallet (calculated based on provided, exactamountOut).amountInMaxwill be calculated automatically and can vary. - Pass
amountInMax. Swap will take at maxamountInMaxout of the wallet.amountOutwill be calculated automatically and can vary. - Pass
amountIn. Swap will return at leastamountOutMininto the the wallet (calculated based on provided, exactamountIn).amountOutMinwill be calculated automatically and can vary.
Route
Routes are returned by calling route on Exchanges or a single exchange.
A single Route has the following structure:
{
blockchain: String (e.g. 'ethereum')
tokenIn: String (e.g. '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb')
decimalsIn: Integer (e.g. 18)
tokenOut: String (e.g. '0xdAC17F958D2ee523a2206206994597C13D831ec7')
decimalsOut: Integer (e.g. 18)
path: Array (e.g. ['0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb', '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', '0xdAC17F958D2ee523a2206206994597C13D831ec7'])
pools: Object ([{ pool }])
amounts: [BigNumber] (e.g. ['1000000000000000000', '2300000000000000000', '9900000000000000000'])
amountIn: BigNumber (e.g. '1000000000000000000')
amountOutMin: BigNumber (e.g. '32000000000000000000')
amountOut: BigNumber (e.g. '32000000000000000000')
amountInMax: BigNumber (e.g. '1000000000000000000')
exchange: Exchange (see [Exchange data structure](#exchange))
getPrep: async function (returns transaction object for approvals or signature request for permit2)
getTransaction: async function (returns transaction object –> see @depay/web3-wallets for details)
}
See @depay/web3-wallets for details about the transaction format.
Slippage
This library applies slippage strategies to amounts for the following combinations:
- If
amountOutMinis provided, slippage is applied toamountIn. - If
amountOutis provided, slippage is applied toamountInMax. - If
amountInMaxis provided, slippage is applied toamountOut. - If
amountInis provided, slippage is applied toamountOutMax.
Auto Slippage
Auto slippage applies 0.5% default slippage.
For blockchains that allow to receive quotes for previous blocks (EVM), auto slippage additionally checks for:
-
Extreme Direction
-
Extreme Base Volatility
And applies a higher than default slippage (0.5%) if required.
Extreme Directional Price Change
If there is a clear directional change of the price for the last 3 blocks, the target price will be projected according to the velocity of the last 3 blocks.
Example Extreme Directional Price Change
Current Price: $1'500
Last 3 Blocks: $1'500, $1'470, $1'440
Velocity: $30 per block
Projection: $1'530
Slippage 2%
Slippage of 2% will be applied, because it's higher than default slippage.
For downwards projections slippage is not required as the transaction would not fail.
Extreme Base Volatility
If there is extreme base volatility in the last 3 blocks, none-directional, the target price will be the highest price over the last 3 blocks plus the smallest price change over the last 3 blocks.
Example Extreme Base Volatility
Current Price: $1'500
Last 3 Blocks: $1'500, $1'490, $1'520
Smallest Change: $10
Highest Price: $1'520
Projection: $1'530 ($1'520 + $10)
Slippage 2%
Slippage of 2% will be applied, because it's higher than default slippage.
Functionalities
Access exchange directly
import Exchanges from '@depay/web3-exchanges'
Exchanges.uniswap_v2
Access exchange scoped for a given blockchain
import Exchanges from '@depay/web3-exchanges'
Exchanges.arbitrum.uniswap_v3
route: Routes a Swap configuration and returns routes to perform the Swap
import Exchanges from '@depay/web3-exchanges'
let routes = Exchanges.route({
blockchain: 'ethereum'
tokenIn: '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb',
tokenOut: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
amountOutMin: 2
})
route can also be called on an exchange:
import Exchanges from '@depay/web3-exchanges'
let route = await Exchanges.ethereum.uniswap_v2.route({
tokenIn: '0xa0bEd124a09ac2Bd941b10349d8d224fe3c955eb',
tokenOut: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
amountIn: 1
})
Development
yarn install
yarn dev