Rubic SDK
Table of contents
- Description
- Installation
- Usage
-
API
-
Core
- SDK.createSDK static method
- sdk.updateConfiguration method
- sdk.instantTrades readonly field
- sdk.crossChain readonly field
- sdk.crossChainSymbiosisManger readonly field
- sdk.tokens readonly field
- sdk.web3PublicService readonly field
- sdk.web3Private readonly field
- sdk.gasPriceApi readonly field
- sdk.cryptoPriceApi readonly field
- Instant Trades Manager
-
Instant Trade
- instantTrade.swap method
- instantTrade.encode method
- instantTrade.needApprove method
- instantTrade.type readonly field
- instantTrade.from readonly field
- instantTrade.to readonly field
- instantTrade.gasFeeInfo mutable field
- instantTrade.slippageTolerance mutable field
- instantTrade.toTokenAmountMin getter
- instantTrade.deadlineMinutes mutable field
- instantTrade.path readonly field
- isUniswapV2LikeTrade function
- isUniswapV3LikeTrade function
- isOneInchLikeTrade function
- isZrxLikeTradeLikeTrade function
- Cross Chain Manager
- Wrapped Cross Chain Trade
- Cross Chain Trade
- Celer Cross Chain Trade and Rubic Cross Chain Trade
- Symbiosis Cross Chain Trade
- Cross Chain Symbiosis Manager
-
Tokens
-
Tokens Manager
- tokensManager.createTokenFromStruct method
- tokensManager.createToken method
- tokensManager.createTokensFromStructs method
- tokensManager.createTokens method
- tokensManager.createPriceTokenFromStruct method
- tokensManager.createPriceToken method
- tokensManager.createPriceTokenAmountFromStruct method
- tokensManager.createPriceTokenAmount method
- Token
- PriceToken
- PriceTokenAmount
-
Tokens Manager
-
Core
Description
In dApps a lot of business logic is often concentrated on the frontend for interacting with the blockchain. This SDK is built on the basis of Rubic multichain DeFi frontend part. SDK is a library for interacting with various dexes, as well as Rubic cross-chain swaps. It also includes a number of utilities useful when working with Ethereum.
Supported DEX-es
- Ethereum
- Binance Smart Chain
- Polygon
- Avalanche
- Fantom
- Moonriver
- Harmony
- Arbitrum
- Aurora
Multi-Chain swaps supported blockchains
Ethereum, Binance Smart Chain, Polygon, Avalanche, Fantom, Moonriver, Harmony, Aurora, Arbitrum
Installation
Installation with cdn
<script src="https://unpkg.com/rubic-sdk@latest/dist/rubic-sdk.min.js"></script>
Installation with npm and webpack (React, ...)
npm install rubic-sdk
npm install --save-dev http-browserify https-browserify stream-browserify crypto-browserify
- modify webpack.config.js. If you use create-react-app, run
npm run eject
to extract config- add to
plugins
new webpack.ProvidePlugin({ Buffer: ['buffer', 'Buffer'], process: 'process/browser' })
- add
resolve.fallback
"fallback": { "fs": false, "constants": false, "querystring": false, "url": false, "path": false, "os": false, "http": require.resolve("http-browserify"), "https": require.resolve("https-browserify"), "zlib": false, "stream": require.resolve("stream-browserify"), "crypto": require.resolve("crypto-browserify") }
- add to
Installation with npm for Angular
npm install rubic-sdk
npm install --save-dev stream-browserify assert https-browserify os-browserify stream-http crypto-browserify process buffer
- Modify tsconfig.json
{ "compilerOptions": { ... "paths" : { ... "stream": ["./node_modules/stream-browserify"], "assert": ["./node_modules/assert"], "https": ["./node_modules/https-browserify"], "os": ["./node_modules/os-browserify"], "http": ["./node_modules/stream-http"], "crypto": ["./node_modules/crypto-browserify"] } }
- Modify polyfills.ts
import Process = NodeJS.Process; export interface AppWindow extends Window { process: Process; Buffer: Buffer; } (window as AppWindow).process = window.process || require('process'); (window as AppWindow).Buffer = (window as any).Buffer || require('buffer').Buffer;
Usage
Get started after cdn installation
<script>
// you have to declare rpc links only for networks you will use
const configuration = {
rpcProviders: {
ETH: {
mainRpc: '<your ethereum rpc>'
},
BSC: {
mainRpc: '<your bsc rpc>'
}
},
// if you are whitelisted integrator, provide your wallet address here
providerAddress: '0x0000000000000000000000000000000000000000'
}
async function main() {
// create SDK instance
const sdk = await RubicSDK.SDK.createSDK(configuration);
// define example trade parameters
const blockchain = 'ETH';
const fromTokenAddress = '0x0000000000000000000000000000000000000000';
const fromAmount = 1;
const toTokenAddress = '0xdac17f958d2ee523a2206206994597c13d831ec7';
// calculate trades
const trades = await sdk.instantTrades
.calculateTrade({blockchain, address: fromTokenAddress}, fromAmount, toTokenAddress);
console.log(trades);
}
main();
</script>
Get started after npm installation
-
Create configuration
import { BLOCKCHAIN_NAME, Configuration } from 'rubic-sdk'; // you have to declare rpc links only for networks you will use export const configuration: Configuration = { rpcProviders: { [BLOCKCHAIN_NAME.ETHEREUM]: { mainRpc: '<your ethereum rpc>' }, [BLOCKCHAIN_NAME.BINANCE_SMART_CHAIN]: { mainRpc: '<your bsc rpc>' } }, // if you are whitelisted integrator, provide your wallet address here providerAddress: '0x0000000000000000000000000000000000000000' }
-
Create sdk instance
const sdk = await SDK.createSDK(configuration);
-
Use sdk instance for trade calculation
import { BLOCKCHAIN_NAME } from 'rubic-sdk'; const blockchain = BLOCKCHAIN_NAME.ETHEREUM; const fromTokenAddress = '0x0000000000000000000000000000000000000000'; // ETH const fromAmount = 1; const toTokenAddress = '0xdac17f958d2ee523a2206206994597c13d831ec7'; // USDT const trades = await sdk.instantTrades.calculateTrade( { blockchain, address: fromTokenAddress }, fromAmount, toTokenAddress ); // explore trades info Object.entries(trades).forEach(([tradeType, trade]) => console.log(tradeType, `to amount: ${trade.to.tokenAmount.toFormat(3)}`) )
-
When user connects wallet (e.g. MetaMask) you should change configuration to use non-view contracts methods, and being able to use trade
swap
method. You not have to recalculate trades after it.import { BLOCKCHAIN_NAME, Configuration, WalletProvider } from 'rubic-sdk'; const accounts: string[] = await window.ethereum.request({ method: 'eth_requestAccounts' }); const chainId = await window.ethereum.request({ method: 'eth_chainId' }); const walletProvider: WalletProvider = { address: accounts[0], chainId, core: window.ethereum } export const configuration: Configuration = { rpcProviders: { [BLOCKCHAIN_NAME.ETHEREUM]: { mainRpc: '<your ethereum rpc>' }, [BLOCKCHAIN_NAME.BINANCE_SMART_CHAIN]: { mainRpc: '<your bsc rpc>' } }, // if you are whitelisted integrator, provide your wallet address here providerAddress: '0x0000000000000000000000000000000000000000', walletProvider } await sdk.updateConfiguration(configuration);
-
Now you can use
swap
method of trade instance. Approve transaction will be sent automatically if needed.const onConfirm = (hash: string) => console.log(hash); const receipt = await trades[TRADE_TYPE.UNISWAP_V2].swap({ onConfirm });
Get started with cross-chain swaps
Steps 1. and 2. is the same. You can use single sdk instance for instant trades and cross-chain swaps calculations.
- Use sdk instance for trade calculation
import { BLOCKCHAIN_NAME, BINANCE_SMART_CHAIN } from 'rubic-sdk'; const fromBlockchain = BLOCKCHAIN_NAME.ETHEREUM; const fromTokenAddress = '0x0000000000000000000000000000000000000000'; // ETH const fromAmount = 1; const toBlockchain = BLOCKCHAIN_NAME.BINANCE_SMART_CHAIN; const toTokenAddress = '0xe9e7cea3dedca5984780bafc599bd69add087d56'; // BUSD const trade = await sdk.crossChain.calculateTrade( { blockchain: fromBlockchain, address: fromTokenAddress }, fromAmount, { blockchain: toBlockchain, address: toTokenAddress } );
Step 4. is the same.
- Now you can use
swap
method of trade instance. Approve transaction will be sent automatically if needed.const onConfirm = (hash: string) => console.log(hash); const receipt = await trade.swap({ onConfirm });
Get started with tokens
You can pass type TokenBaseStruct = { blockchain: BLOCKCHAIN_NAME; address: string; }
to calculateTrade
method,
but also you can pass Token
. You can use SDK to create Token
, PriceToken
, or PriceTokenAmount
.
import { BLOCKCHAIN_NAME } from 'rubic-sdk';
const token = await sdk.tokens.createToken({
blockchain: BLOCKCHAIN_NAME.ETHEREUM,
address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
});
console.log(token.symbol); // USDT
console.log(token.name); // Tether USD
console.log(token.decimals); // 6
If you need token price, you can create PriceToken
import { BLOCKCHAIN_NAME } from 'rubic-sdk';
const token = await sdk.tokens.createPriceToken({
blockchain: BLOCKCHAIN_NAME.ETHEREUM,
address: '0xdac17f958d2ee523a2206206994597c13d831ec7'
});
console.log(token.price.toFormat(2)); // 1.00
You can create PriceTokenAmount
if you want to store amount of tokens in the same object, e.g. user balance, or from/to amount:
import BigNumber from 'bignumber.js';
import { BLOCKCHAIN_NAME } from 'rubic-sdk';
const token = await sdk.tokens.createPriceTokenAmount({
blockchain: BLOCKCHAIN_NAME.ETHEREUM,
address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
tokenAmount: new BigNumber(1)
});
console.log(token.tokenAmount.toNumber()); // 1
console.log(token.stringWeiAmount); // 1000000
API
Core
SDK.createSDK static method
SDK.createSDK(configuration: Configuration): Promise<SDK>
Creates new sdk instance. Changes dependencies of all sdk entities according to new configuration (even for entities created with other previous sdk instances).
Parameter | Type | Description |
---|---|---|
configuration | Configuration | Object contains main sdk settings like .env: rpc providers links, wallet object... |
Configuration structure
interface Configuration {
readonly rpcProviders: Partial<Record<BLOCKCHAIN_NAME, RpcProvider>>;
readonly walletProvider?: WalletProvider;
readonly httpClient?: HttpClient;
}
interface RpcProvider {
readonly mainRpc: string;
readonly spareRpc?: string;
readonly mainPrcTimeout?: number;
readonly healthCheckTimeout?: number;
}
interface WalletProvider {
readonly core: provider | Web3;
readonly address: string;
readonly chainId: number | string;
}
Configuration description:
Property | Type | Description | Default |
---|---|---|---|
rpcProviders | Partial<Record<BLOCKCHAIN_NAME, RpcProvider>> |
Rpc data to connect to blockchains you will use. You have to pass rpcProvider for each blockchain you will use with sdk. | Not set. |
walletProvider? | WalletProvider |
Required to use swap , approve and other methods which sends transactions. But you can calculate and encode trades without walletProvider . Pass it when user connects wallet. Please note that address and chainId must match account address and selected chainId in the user wallet. |
Not set. |
httpClient? | HttpClient |
You can pass you own httpClient (e.g. HttpClient in Angular) if you have it to not duplicate http clients and decrease bundle size. Please note that default axios or native js fetch clients can't be used as HttpClient without modifications. Your http client must return promise which will resolve with parsed response body (like Angular httpClient). See interface below. |
Lazy loading axios with interceptor. |
HttpClient interface:
interface HttpClient {
post<ResponseBody>(url: string, body: Object): Promise<ResponseBody>;
get<ResponseBody>(
url: string,
options?: {
headers?: {
[header: string]: string | string[];
};
params?: {
[param: string]:
| string
| number
| boolean
| ReadonlyArray<string | number | boolean>;
};
}
): Promise<ResponseBody>;
}
RpcProvider description:
Property | Type | Description | Default |
---|---|---|---|
mainRpc | string |
Rpc link. Copy it from your rpc provider (like Infura, Quicknode, Getblock, Moralis, ...) website. | Not set. |
spareRpc? | string |
Same as mainRpc . Will be used instead mainRpc if mainRpc is out of timeout = mainPrcTimeout . |
Not set. |
mainPrcTimeout? | number | Specifies timeout in ms after that mainRpc will be replaced with spareRpc (if spareRpc is defined) |
10_000 |
healthCheckTimeout? | number | Before the mainRpc link is applied to the sdk, all the mainRpc links will be checked for operability by receiving from the blockchain and verifying the predefined data. If an error occurs during the request, the received data does not match the specified one, or the timeout is exceeded, the mainRpc will be replaced with a spare one. This healthCheckTimeout parameter allows you to set the maximum allowable timeout when checking the mainRpc . |
4_000 |
sdk.updateConfiguration method
sdk.updateConfiguration(configuration: Configuration): Promise<void>
Updates sdk configuration and sdk entities dependencies. Call it if user connects wallet, or user changes network or account in him wallet.
sdk.instantTrades readonly field
sdk.instantTrades: InstantTradesManager
Instant trades manager object. Use it to calculate and create instant trades. See more.
sdk.crossChain readonly field
sdk.crossChain: CrossChainManager
Cross-chain trades manager object. Use it to calculate and create cross-chain trades. See more.
sdk.crossChainSymbiosisManager readonly field
sdk.crossChainSymbiosisManager: CrossChainSymbiosisManager
Cross-chain symbiosis manager object. Use it to get pending trades and symbiosis and revert them. See more.
sdk.tokens readonly field
sdk.tokens: TokensManager
Tokens manager object. Use it to fetch tokens data, to create new Token
, PriceToken
, PriceTokenAmount
objects. See more.
sdk.web3PublicService readonly field
sdk.web3PublicService: Web3PublicService
Use it to get Web3Public
instance by blockchain name to get read information from blockchain.
const web3Public = sdk.web3PublicService.getWeb3Public(BLOCKCHAIN_NAME.ETHEREUM);
const ethBalance = await web3Public.getBalance('<user address>');
const tokenBalance = await web3Public.getBalance('<user address>', '<token address>');
Explore Web3Public class to see available methods.
sdk.web3Private readonly field
sdk.web3Private: Web3Private
Use it to send transactions and execute smart contracts methods.
const web3Private = sdk.web3Private;
const transacionReceipt = await web3Private.transferTokens('<constract address>', ',toAddress>', 1000);
Explore Web3Private class to see available methods.
sdk.gasPriceApi readonly field
sdk.gasPriceApi: GasPriceApi
Use it to get gas price information.
const gasPriceApi = sdk.gasPriceApi;
const gasPrice = await gasPriceApi.getGasPrice(BLOCKCHAIN_NAME.ETHEREUM);
Explore GasPriceApi class to see available methods.
sdk.cryptoPriceApi readonly field
sdk.cryptoPriceApi: CoingeckoApi
Use it to get crypto price information.
const cryptoPriceApi = sdk.cryptoPriceApi;
const tokenUSDPrice = await cryptoPriceApi.getErc20TokenPrice('<token address>', '<BLOCKCHAIN_NAME.>');
Explore CoingeckoApi class to see available methods.
Instant Trades Manager
sdk.instantTrades.calculateTrade method
sdk.instantTrades.calculateTrade(
fromToken:
| Token
| {
address: string;
blockchain: BLOCKCHAIN_NAME;
},
fromAmount: string | number,
toToken: Token | string,
options?: SwapManagerCalculationOptions
): Promise<InstantTrade[]>
ℹ️ ️ You have to set up rpc provider🌐 for network in which you will calculate trade.
Method calculates instant trades parameters and estimated output amount.
sdk.instantTrades.calculateTrade method parameters:
Parameter | Type | Description |
---|---|---|
fromToken |
Token | { address: string; blockchain: BLOCKCHAIN_NAME;}
|
Token sell. |
fromAmount |
string | number
|
Amount in token units (not in wei!) to swap. |
toToken |
Token | string
|
Token to get. You can pass Token object, or string token address. Must has same blockchain as fromToken if passed as Token. |
options? | SwapManagerCalculationOptions |
Swap calculation options. |
SwapManagerCalculationOptions description:
Option | Type | Description | Default |
---|---|---|---|
timeout? | number |
Specify trade calculation timeout in ms (same timeout for every provider separately). | 3000 |
disabledProviders? | TradeType[] |
Specify providers which must be ignored. | [] |
gasCalculation? |
'disabled' | 'calculate' | 'rubicOptimisation'
|
Disable estimated gas calculation, or use rubic gas optimisation to consider the gas fee when calculating route profit (works only for UniswapV2-like and UniswapV3-like providers.). | 'calculate' |
disableMultihops? | boolean |
Disable not direct swap routes. It can help to reduce gas fee, but can worsen the exchange rate. Better use gasCalculation = 'rubicOptimisation' when it is possible. |
false |
slippageTolerance? | number |
Swap slippage in range 0 to 1. Defines minimum amount that you can get after swap. Can be changed after trade calculation for every trade separately (excluding 0x trade). | 0.02 |
deadlineMinutes? | number |
Transaction deadline in minutes (countdown from the transaction sending date). Will be applied only for UniswapV2-like and UniswapV3-like trades. Can be changed after trade calculation for every trade separately. | 20 |
Returns Promise<InstantTrade[]>
-- list of successful calculated trades.
sdk.instantTrades.blockchainTradeProviders readonly field
readonly sdk.instantTrades.blockchainTradeProviders: Readonly<Record<BLOCKCHAIN_NAME, Partial<TypedTradeProviders>>
If you need to calculate trade with the special provider options, you can get needed provider instance in sdk.instantTrades.blockchainTradeProviders
and calculate trade directly via this instance.
// calculate trade with exact output
const trade = await sdk.instantTrades.blockchainTradeProviders[BLOCKCHAIN_NAME.ETHEREUM][TRADE_TYPE.UNISWAP_V2]
.calculateDifficultTrade(from, to, weiAmount, 'output', options);
Instant Trade
instantTrade.swap method
instantTrade.swap(options?: SwapTransactionOptions): Promise<TransactionReceipt>
ℹ️ ️ You have to set up wallet provider👛 for network in which you will execute trade swap.
Method checks balance, network id correctness, and executes swap transaction. A transaction confirmation window will open in the connected user's wallet. If user has not enough allowance, the method will automatically send approve transaction before swap transaction.
instantTrade.swap method parameters:
Parameter | Type | Description |
---|---|---|
options? | SwapTransactionOptions |
Additional swap transaction options. |
SwapTransactionOptions description:
Option | Type | Description | Default |
---|---|---|---|
onConfirm? | (hash: string) => void |
Callback that will be called after the user signs swap transaction. | Not set. |
onApprove? | (hash: string) => void |
Callback that will be called after the user signs approve transaction. If user has enough allowance, this callback won't be called. | Not set. |
gasPrice? | string |
Specifies gas price in wei for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
gasLimit? | string |
Specifies gas limit for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
Returns Promise<TransactionReceipt>
-- swap transaction receipt. Promise will be resolved, when swap transaction gets to block.
instantTrade.encode method
instantTrade.encode(options?: EncodeTransactionOptions): Promise<TransactionConfig>
ℹ️ ️ You have to set up rpc provider🌐 for trade network for which you will call encode.
If you don't want to execute transaction instantly (e.g. if you use SDK in the server-side), you can get full transaction data
to pass it to the transaction when you need to send it, you can use instantTrade.encode
method.
instantTrade.encode method parameters:
Parameter | Type | Description |
---|---|---|
options | EncodeTransactionOptions |
Additional options. Optional for uniswapV3-like and 0x trades, but required for uniswapV2-like and 1inch trades. |
EncodeTransactionOptions description:
Option | Type | Description | Default |
---|---|---|---|
fromAddress | string |
Not needed for uniswapV3-like and 0x trades, but required for uniswapV2-like and 1inch trades. Address of account which will executes swap transaction by encoded data. This address must has enough allowance to successfully encode. | Not set. |
gasPrice? | string |
Specifies gas price in wei for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
gasLimit? | string |
Specifies gas limit for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
Returns Promise<TransactionConfig>
-- web3 transaction structure to send.
instantTrade.needApprove method
instantTrade.needApprove(): Promise<boolean>
ℹ️ ️ You have to set up rpc provider🌐 for trade network for which you will call needApprove.
Swap method will automatically call approve if needed, but you can use methods pair needApprove
-approve
if you want to know if approve is needed before execute swap to show user double button, or swap stages in UI.
instantTrade.needApprove Returns Promise<boolean>
-- True if approve required, that is user has not enough allowance. Otherwise false.
instantTrade.approve method
instantTrade.approve(options?: BasicTransactionOptions): Promise<TransactionReceipt>
ℹ️ ️ You have to set up wallet provider👛 for network in which you will execute trade swap.
Use approve
if you want to show swap stages in UI after allowance check via needApprove
method.
instantTrade.approve method parameters:
Parameter | Type | Description |
---|---|---|
options | BasicTransactionOptions |
Additional transaction options. |
BasicTransactionOptions description:
Option | Type | Description | Default |
---|---|---|---|
onTransactionHash? | (hash: string) => void |
Callback that will be called after the user signs the approve transaction. | |
gasPrice? | string |
Specifies gas price in wei for approve transaction. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
gasLimit? | string |
Specifies gas limit for approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
Returns Promise<TransactionReceipt>
-- approve transaction receipt. Promise will be resolved, when swap transaction gets to block.
instantTrade.type readonly field
readonly instantTrade.type: TradeType
Instant trade type (like TRADE_TYPE.UNISWAP_V2
, TRADE_TYPE.QUICK_SWAP
, ...).
instantTrade.from readonly field
readonly instantTrade.from: PriceTokenAmount
Token to sell with price in USD per 1 token unit and selling amount.
instantTrade.to readonly field
readonly instantTrade.to: PriceTokenAmount
Token to buy with price in USD per 1 token unit and estimated get amount (not to be confused with instantTrade.toTokenAmountMin
).
instantTrade.gasFeeInfo mutable field
instantTrade.gasFeeInfo: GasFeeInfo | null
where
interface GasFeeInfo {
readonly gasLimit?: BigNumber;
readonly gasPrice?: BigNumber;
readonly gasFeeInEth?: BigNumber;
readonly gasFeeInUsd?: BigNumber;
}
Information about predicted gas fee connected to this trade. Will be null if option gasCalculation
was set as 'disabled'
when trade was calculated.
Some properties of gasFeeInfo
can be undefined if there are errors while gas fetching.
Can be changed: just modify gasFeeInfo field.
instantTrade.slippageTolerance mutable field
instantTrade.slippageTolerance: number
Swap slippage in range 0 to 1. Defines minimum amount that you can get after swap. Can be changed (excluding 0x trade): just modify slippageTolerance field.
instantTrade.toTokenAmountMin getter
instantTrade.toTokenAmountMin: PriceTokenAmount
Is same as instantTrade.to
, but amount less than instantTrade.to
by (instantTrade.slippageTolerance * 100)
percent.
instantTrade.deadlineMinutes mutable field
instantTrade.deadlineMinutes: number
⚠️ Is available only in uniswapV2-like and uniswapV3-like trades.
Transaction deadline in minutes (countdown from the transaction sending date). Can be changed: just modify deadlineMinutes field.
instantTrade.path readonly field
instantTrade.path: ReadonlyArray<Token>
⚠️ Is not available for 0x trades.
Swap path. E.g. if you change ETH to LINK path might be [ETH, USDT, LINK].
Path elements is Token
, so you can get address, symbol and other properties of each element.
If you sell, or get native coin (like ETH, BNB, MATIC, ...) in swap, path[0]
or path[path.length -1]
won't be wrapped tokens like WETH, but will be native tokens.
isUniswapV2LikeTrade function
function isUniswapV2LikeTrade(trade: InstantTrade): trade is UniswapV2AbstractTrade
Type guard checks that trade is UniswapV2AbstractTrade. Use it to parse result of sdk.instantTrades.calculateTrade
and
show specific uniswapV2 trade data like deadline
and path
, or use its specific methods.
List of uniswapV2LikeTrades/Providers:
- UniSwap V2
- SushiSwap Ethereum
- PancakeSwap
- SushiSwap Bsc
- QuickSwap
- SushiSwap Polygon
- Joe
- Pangolin
- SushiSwap Avalanche
- SpiritSwap
- SpookySwap
- SushiSwap Fantom
- SushiSwap Harmony
- Solarbeam
- SushiSwap Moonriver
isUniswapV3LikeTrade function
function isUniswapV3LikeTrade(trade: InstantTrade): trade is UniSwapV3Trade
Type guard checks that trade is UniSwapV3Trade. Use it to parse result of sdk.instantTrades.calculateTrade
and
show specific UniSwapV3 trade data, or use its specific methods.
List of uniswapV2LikeTrades/Providers:
- UniSwapV3
- (Algebra and UniSwapV3 Polygon soon!)
isOneInchLikeTrade function
function isOneInchLikeTrade(trade: InstantTrade): trade is OneinchTrade
Type guard checks that trade is OneinchTrade. Use it to parse result of sdk.instantTrades.calculateTrade
and
show specific OneinchTrade trade data, or use its specific methods.
List of OneinchTrade/Providers:
- OneInch Ethereum
- OneInch Bsc
- OneInch Polygon
isZrxLikeTradeLikeTrade function
function isZrxLikeTradeLikeTrade(trade: InstantTrade): trade is ZrxTrade
Type guard checks that trade is 0x Trade. Use it to parse result of sdk.instantTrades.calculateTrade
and
show specific 0x Trade trade data, or use its specific methods.
List of OneinchTrade/Providers:
- 0x Ethereum
- (other blockchains for 0x soon!)
Cross Chain Manager
⚠️ Danger: Currently, Cross Chain Manager uses dev-mode contracts. Its' logic is the same as of prod-mode contracts, but settings (such as minimum amount of tokens to sell) are different.
sdk.crossChain.calculateTrade method
sdk.crossChain.calculateTrade(
fromToken:
| Token
| {
address: string;
blockchain: BLOCKCHAIN_NAME;
},
fromAmount: string | number,
toToken:
| Token
| {
address: string;
blockchain: BLOCKCHAIN_NAME;
},
options?: CrossChainOptions
): Promise<WrappedCrossChainTrade>
ℹ️ ️ You have to set up rpc provider🌐 for network in which you will calculate trade.
Method calculates WrappedCrossChainTrade.
sdk.crossChain.calculateTrade method parameters:
Parameter | Type | Description |
---|---|---|
fromToken |
Token | { address: string; blockchain: BLOCKCHAIN_NAME;}
|
Token to sell. |
fromAmount |
string | number
|
Amount in token units (not in wei!) to swap. |
toToken |
Token | { address: string; blockchain: BLOCKCHAIN_NAME;}
|
Token to get. |
options? | CrossChainOptions |
Swap calculation options. |
CrossChainOptions description:
Option | Type | Description | Default |
---|---|---|---|
fromSlippageTolerance | number |
Swap slippage in range 0 to 1. Defines minimum amount after swap in first blockchain (for Celer and Rubic). | 0.02 |
toSlippageTolerance | number |
Swap slippage in range 0 to 1. Defines minimum amount that you can get after swap in second blockchain (for Celer and Rubic). | 0.02 |
slippageTolerance | number |
Swap slippage in range 0 to 1. Defines minimum amount that you can get after swap (for Symbiosis). | 0.04 |
fromAddress | string |
User wallet address to calculate trade for (for Symbiosis). | Connected wallet address |
deadline | number |
Deadline of the trade in minutes (for Symbiosis). | 20 |
gasCalculation |
'enabled' | 'disabled'
|
Disables or enables gas limit and gas price calclation. | 'enabled' |
disabledProviders | CrossChainTradeType[] |
Disables passed providers. | [] |
Wrapped Cross Chain Trade
interface WrappedCrossChainTrade {
trade: CrossChainTrade | null;
minAmountError?: BigNumber;
maxAmountError?: BigNumber;
}
Wraps cross chain trade and possible min max amount errors. If minAmountError
or maxAmountError
are not empty, then you must display an error, because swap
method will return error.
Cross Chain Trade
Stores information about trade and provides method to make swap.
Extends to types: CelerCrossChainTrade
, RubicCrossChainTrade
, SymbiosisCrossChainTrade
.
crossChainTrade.swap method
crossChainTrade.swap(options?: SwapTransactionOptions): Promise<TransactionReceipt>
ℹ️ ️ You have to set up wallet provider👛 for network in which you will execute trade swap.
Method checks balance, network id correctness, cross-chain contracts state and executes swap transaction. A transaction confirmation window will open in the connected user's wallet. If user has not enough allowance, the method will automatically send approve transaction before swap transaction.
crossChainTrade.swap method parameters:
Parameter | Type | Description |
---|---|---|
options? | SwapTransactionOptions |
Additional swap transaction options. |
SwapTransactionOptions description:
Option | Type | Description | Default |
---|---|---|---|
onConfirm? | (hash: string) => void |
Callback that will be called after the user signs swap transaction. | Not set. |
onApprove? | (hash: string) => void |
Callback that will be called after the user signs approve transaction. If user has enough allowance, this callback won't be called. | Not set. |
gasPrice? | string |
Specifies gas price in wei for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
gasLimit? | string |
Specifies gas limit for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
Returns Promise<TransactionReceipt>
-- swap transaction receipt in first blockchain. Promise will be resolved, when swap transaction gets to block.
crossChainTrade.needApprove method
crossChainTrade.needApprove(): Promise<boolean>
ℹ️ ️ You have to set up rpc provider🌐 for trade network for which you will call needApprove.
Swap method will automatically call approve if needed, but you can use methods pair needApprove
-approve
if you want to know if approve is needed before execute swap to show user double button, or swap stages in UI.
crossChainTrade.needApprove Returns Promise<boolean>
-- True if approve is required, that is user doesn't have enough allowance. Otherwise, false.
crossChainTrade.approve method
crossChainTrade.approve(options?: BasicTransactionOptions): Promise<TransactionReceipt>
ℹ️ ️ You have to set up wallet provider👛 for network in which you will execute trade swap.
Use approve
if you want to show swap stages in UI after allowance check via needApprove
method.
crossChainTrade.approve method parameters:
Parameter | Type | Description |
---|---|---|
options | BasicTransactionOptions |
Additional transaction options. |
BasicTransactionOptions description:
Option | Type | Description | Default |
---|---|---|---|
onTransactionHash? | (hash: string) => void |
Callback that will be called after the user signs the approve transaction. | |
gasPrice? | string |
Specifies gas price in wei for approve transaction. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
gasLimit? | string |
Specifies gas limit for approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
Returns Promise<TransactionReceipt>
-- approve transaction receipt. Promise will be resolved, when swap transaction gets to block.
crossChainTrade.from readonly field
readonly crossChainTrade.from: PriceTokenAmount
Token to sell with price in USD per 1 token unit and selling amount.
crossChainTrade.to readonly field
readonly crossChainTrade.to: PriceTokenAmount
Token to buy with price in USD per 1 token unit and estimated output amount.
crossChainTrade.toTokenAmountMin readonly field
readonly crossChainTrade.to: PriceTokenAmount
Is same as crossChainTrade.to
, but amount less than crossChainTrade.to
by (toSlippageTolerance * 100)
percent.
crossChainTrade.estimatedGas getter
crossChainTrade.estimateGas(): GasFeeInfo | null
Gets gasFee, that is gasLimit * gasPrice. Equals null
if gas couldn't be calculated.
Celer Cross Chain Trade and Rubic Cross Chain Trade
Extend CrossChainTrade
class.
crossChainTrade.priceImpactData getter
crossChainTrade.priceImpactData(): {
priceImpactFrom: number | null;
priceImpactTo: number | null;
}
Returns price impact in first and second blockchains, based on tokens usd prices, taken from coingecko api.
Symbiosis Cross Chain Trade
Extends CrossChainTrade
class.
crossChainTrade.priceImpact readonly field
crossChainTrade.priceImpact: number
Returns overall price impact, based on symbiosis api.
Cross Chain Symbiosis Manager
Contains methods to work with pending user trades and revert them.
crossChainSymbiosisManager.getUserTrades method
crossChainSymbiosisManager.getUserTrades(fromAddress?: string): Promise<PendingRequest[]>
Returns pending request for fromAddress
if provided, otherwise for connected wallet address.
crossChainSymbiosisManager.revertTrade method
crossChainSymbiosisManager.revertTrade(
revertTransactionHash: string,
options?: SwapTransactionOptions
): Promise<string | never>
Reverts trade, which transaction hash is revertTransactionHash
for connected wallet address.
SwapTransactionOptions description:
Option | Type | Description | Default |
---|---|---|---|
onConfirm? | (hash: string) => void |
Callback that will be called after the user signs swap transaction. | Not set. |
gasPrice? | string |
Specifies gas price in wei for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
gasLimit? | string |
Specifies gas limit for swap and approve transactions. Set this parameter only if you know exactly what you are doing. | The value obtained during the calculation of the trade. If value wasn't calculated, it will calculates automatically by user's wallet. |
Tokens Manager
tokensManager.createTokenFromStruct method
tokensManager.createTokenFromStruct(tokenStruct: TokenStruct): Token
Creates Token
instance by full token data struct.
tokensManager.createToken method
tokensManager.createToken(tokenBaseStruct: TokenBaseStruct): Promise<Token>
Fetches token data and creates Token
by token address and token blockchain.
tokensManager.createTokensFromStructs method
tokensManager.createTokensFromStructs(tokensStructs: TokenStruct[]): Token[]
Same as tokensManager.createTokenFromStruct
for multiple token structs.
tokensManager.createTokens method
tokensManager.createTokens(addresses: string[], blockchain: BLOCKCHAIN_NAME): Promise<Token[]>
Same as tokensManager.createToken
for multiple token structs. But using multicall for data fetching, so makes only one rpc request.
Use this method to crate tokens list instead of Promise.all
and tokensManager.createToken
.
tokensManager.createPriceTokenFromStruct method
tokensManager.createPriceTokenFromStruct(priceTokenStruct: PriceTokenStruct): PriceToken
Creates price token from full price token struct including price.
tokensManager.createPriceToken method
tokensManager.createPriceToken(token: TokenBaseStruct | TokenStruct): Promise<PriceToken>
Creates price token from full token struct (without price) or from token address and blockchain.
tokensManager.createPriceTokenAmountFromStruct method
tokensManager.createPriceTokenAmountFromStruct(priceTokenAmountStruct: PriceTokenAmountStruct): PriceTokenAmount
Creates price token amount from full price token amount struct.
tokensManager.createPriceTokenAmount method
tokensManager.createPriceTokenAmount(
priceTokenAmountStruct:
| PriceTokenAmountBaseStruct
| (TokenStruct & ({ weiAmount: BigNumber } | { tokenAmount: BigNumber }))
): Promise<PriceTokenAmount>
Creates price token amount from token struct (without price) and amount or from token address, blockchain and amount.
Token
token fields
readonly blockchain: BLOCKCHAIN_NAME;
readonly address: string;
readonly name: string;
readonly symbol: string;
readonly decimals: number;
token.isNative method
Use token.isNative
to detect native coins like ETH, BNB, MATIC, ... instead of comparing token address with 0x000...0.
token.isEqualTo method
token.isEqualTo(token: TokenBaseStruct): boolean
Use it to check that two tokens have equal blockchains and addresses (in any case: lower/upper/mixed).
Token is TokenBaseStruct so you can pass Token instance to token.isEqualTo
.
token.clone method
token.clone(replaceStruct?: Partial<TokenStruct>): Token
Use it to deep clone token object and replace some properties.
PriceToken
Extends Token
.
priceToken.price getter
Returns last set token price as BigNumber
.
priceToken.asStruct getter
Serializes priceToken and its price to struct object.
priceToken.getAndUpdateTokenPrice method
priceToken.getAndUpdateTokenPrice(): Promise<BigNumber>
Fetches current token price and saves it into token.
priceToken.cloneAndCreate
priceToken.cloneAndCreate(tokenStruct?: Partial<PriceTokenStruct>): Promise<PriceToken>
Same as token.clone
but fetches new price for new PriceToken
.
PriceTokenAmount
Extends PriceToken
.
priceTokenAmount.weiAmount getter
Returns saved token amount in wei as BigNumber
(weiAmount = tokenAmount * (10 ** token.decimals)).
priceTokenAmount.stringWeiAmount getter
Returns saved token amount in wei as string.
priceTokenAmount.tokenAmount getter
Returns saved token amount in human-readable token units as BigNumber
(tokenAmount = weiAmount / (10 ** token.decimals)).
priceTokenAmount.weiAmountMinusSlippage method
priceTokenAmount.weiAmountMinusSlippage(slippage: number): BigNumber
Returns wei amount decreased by (1 - slippage) times. Slippage is in range from 0 to 1.
priceTokenAmount.weiAmountPlusSlippage method
priceTokenAmount.weiAmountPlusSlippage(slippage: number): BigNumber
Returns wei amount increased by (1 - slippage) times. Slippage is in range from 0 to 1.
priceTokenAmount.calculatePriceImpactPercent method
calculatePriceImpactPercent(toToken: PriceTokenAmount): number | null
Calculates trade price impact percent if instance token is selling token, and parameter is buying token. If selling usd amount is less than buying usd amount, returns 0.