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
Error Code | Error Number | Description |
|---|---|---|
ERROR_CODE_UNDEFINED | 0 | Error code placeholder |
ERROR_CODE_COMMON | 500 | Chain is disabled |
ERROR_NO_TOKEN_ON_DST_CHAIN | 1001 | Token not supported on destination chain |
ERROR_NO_TOKEN_ON_SRC_CHAIN | 1002 | Token not supported on source chain |
ERROR_CODE_NO_ENOUGH_TOKEN_ON_DST_CHAIN | 1004 | Destination chain token is not enough for transfer |
ERROR_CODE_INBOUND_LIQUIDITY_LIMIT | 1005 | Token pool epoch volume cap reached |
ERROR_CODE_TRANSFER_DISABLED | 1009 | Token transfer between source chain and destination(both direction) is disabled |
ERROR_CODE_BAD_LIQ_SLIPPAGE | 1012 | Bad slippage |
ERROR_CODE_ADDRESS_BLOCKED | 1015 | This address is blocked due to potential security risks, which is alerted by third party organization. Those risks include hacker's address, money laundering and etc. |
ERROR_CODE_BLOCK_BRIDGE_DIRECT | 1016 | Token transfer from source chain to destination(one direction) is disabled |
ERROR_CODE_LIQ_OVER_CAP | 1017 | Token pool total cap reached |
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.
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 17d ago