Gateway: EstimateAmt
Get estimation for the user's transfer request.
get
https://cbridge-prod2.celer.app
/v2/estimateAmt
Get estimation for the user's transfer request
// import estimateAmt request message
import {
EstimateAmtRequest,
EstimateAmtResponse
} from "../ts-proto/sgn/gateway/v1/gateway_pb";
// import grpc-web WebClient
import {
WebClient
} from "../ts-proto/sgn/gateway/v1/GatewayServiceClientPb";
const estimateRequest = new EstimateAmtRequest();
estimateRequest.setSrcChainId(1);
estimateRequest.setDstChainId(56);
estimateRequest.setTokenSymbol("USDT");
estimateRequest.setUsrAddr(0xaa47c83316edc05cf9ff7136296b026c5de7eccd);
estimateRequest.setSlippageTolerance(3000);
estimateRequest.setAmt("100000");
const client = new WebClient(`https://cbridge-prod2.celer.app`, null, null);
const res = await client.estimateAmt(estimateRequest, null);
Name | Type | Description |
|---|---|---|
src_chain_id | Number | Source Chain Id, given by transfer configs |
dst_chain_id | Number | Destination Chain Id, given by transfer configs |
token_symbol | String | Symbol of token to be transfered, given by transfer configs |
usr_addr | String | User's wallet address(Not required for multi-chain token transfer) |
slippage_tolerance | Number | Slippage for onchain transaction(User's input) |
amt | String | Token amount to be transfered. Token's decimal should be used here. For example, if the user wants to transfer 1 tokenA and A's decimal is 4, then amt should be 10000 |
is_pegged | | Used for pegged token transfer only |
Which value is suitable to set for slippage_tolerance?
cBridge gateway uses slippage_tolerance_rate to represent user's slippage for on-chain transaction. The range of slippage_tolerance_rate is from [0, 1)
The calculation formula between slippage_tolerance and slippage_tolerance_rate is
slippage_tolerance_rate = slippage_tolerance / 1M
Hence, if the user sets slippage_tolerance with 0.05%, slippage_tolerance in the request will be 0.05% * 1M = 500
Moreover, if the user sets slippage_tolerance with 0.050123%, the calculation will lead to 0.050123% * 1M = 501.23. However, gateway will only accept integer as slippage_tolerance. The final value should be 501
You need to find out whether this transfer is used for pegged token according to PeggedPairConfigs. Moreover, slippage will not be effective if is_pagged is true
Name | Type | Description |
|---|---|---|
eq_value_token_amt
| String | Token amount in destination chain |
bridge_rate | Number | |
perc_fee | String | |
base_fee | String | |
slippage_tolerance | Number | The same number as slippage_tolerance in request |
max_slippage | Number | slippage will be used to submit on-chain transaction, see below for calculation detail |
How to calculate max_slippage?
There are several factors influencing the final value for max_slippage, all of them are inside the response. Since we cannot guarantee user receiving more tokens on destination chain, there is slippage adjustment in the end.
- 1.estimate_dst_amt = user_transfer_amount_on_src_chain * bridge_rate
- 2.estimate_min_dst_amt = estimate_dst_amt * (1 - slippage_tolerance_rate) - base_fee - perc_fee
- 3.max_slippage_rate = 1 - estimate_min_dst_amt / user_transfer_amount_on_src_chain
- 4.max_slippage = max(max_slippage_rate * 1M, minimalMaxSlippage)
The on-chain send transaction failed mostly when slippage is too small to be processed by cBridge system.
To avoid the potential on-chain failure and waste of gas, we recommend you compare max_slippage with minimalMaxSlippage on cBridge contract before sending on-chain transaction. If max_slippage is less than minimalMaxSlippage, guide user increasing input value slippage_tolerance.
Moreover, since max_slippage, bridge_rate, perc_fee and base_fee may change when user interacting with your application, we should get the lastest estimation before final submit to avoid on-chain send failure.
The cross-chain transfer is accepted only. if src_chain_id is the same as dst_chain_id, it may lead to an error
- 1.ERROR_CODE_INBOUND_LIQUIDITY_LIMIT
The sending amount is beyond liquidity pool limit. It will happen only for liquidity pool-based transfer. The calculation for inbound liquidity limit of source chain token liquidity pool is TOTAL_LIQUIDITY_ADDED - TOTAL__LIQUIDITY_RELAYED - TOTAL__LIQUIDITY_WITHDRAWN. Once this error code is given, you have to let the users decrease their input sending amount.
2. ERROR_CODE_NO_ENOUGH_TOKEN_ON_DST_CHAIN
Destination chain doesn’t have enough token for this transfer. It may happen for pool based transfer which bridge rate is fixed to 1.
To provide a better user experience, cBridge has a request to indicate user how long it will take to finish a transfer. You may also use this to provide a better time estimation for the users.
get
https://cbridge-prod2.celer.network
/v2/getLatest7DayTransferLatencyForQuery
Request Sample
Last modified 2mo ago