Gateway: EstimateAmt

Get estimation for the user's transfer request.

REST API

Get estimation for the user's transfer request

GET https://cbridge-prod2.celer.app/v2/estimateAmt

Here is a sample request for estimateAmt:

https://cbridge-prod2.celer.app/v2/estimateAmt?src_chain_id=1&dst_chain_id=56&token_symbol=USDT&amt=1000000&usr_addr=0xaa47c83316edc05cf9ff7136296b026c5de7eccd&slippage_tolerance=3000

Path Parameters

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

amt*

String

Token amount to be transfered. It should contain token's decimal. For example, if the user wants to transfer 1 tokenA and A's decimal is 4, then amt should be 10000

slippage_tolerance*

Number

value between 1 and 1M - 1, see details below

is_pegged

Bool

set true if transfer pegged token

{
  "err": null,
  "eq_value_token_amt": "1000000999999999872",
  "bridge_rate": 1.000001,
  "perc_fee": "0",
  "base_fee": "605437528092011966",
  "slippage_tolerance": 3000,
  "max_slippage": 608436,
  "estimated_receive_amt": "394563471907987906",
  "drop_gas_amt": "0"
}

GRPC-Web API

// 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);

Request Parameters

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

Response Parameters

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. used for xLiquidity transfer only

estimated_receive_amt

String

receiving amount estimation on destination chain

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)

Minimum receiving amount calculation

amount = eq_value_token_amt * (1 - max_slippage/1M)

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 handling

Error Code Description

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

ErrCode_ERROR_CODE_VPN_BLOCK

1018

VPN is not allowed when getting transfer estimation

Error with high frequency

ERROR_CODE_INBOUND_LIQUIDITY_LIMIT & ERROR_CODE_LIQ_OVER_CAP

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.

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.

Estimated Time of Arrival for Transfer

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.

Request Sample

GET https://cbridge-prod2.celer.app/v2/getLatest7DayTransferLatencyForQuery

https://cbridge-prod2.celer.app/v2/getLatest7DayTransferLatencyForQuery?src_chain_id=1&dst_chain_id=56

Path Parameters

Name
Type
Description

src_chain_id*

Number

source chain id

dst_chain_id*

Number

destination chain id

{
  "err": null,
  "median_transfer_latency_in_second": 325.818221
}
PreviousGateway: GetTransferConfigsForAllNextContract: Pool-Based Transfer

Last updated