๐ŸŒ‰
Celer cBridge
  • ๐Ÿ‘‹Welcome to cBridge
  • Introduction
    • Architectural Benefits
    • State Guardian Network
    • SGN and cBridge
      • The SGN as a cBridge node gateway and Service Level Agreement (SLA) arbitrator
      • The SGN as a Shared Liquidity Pool Manager
    • Fungible Token Bridging Models
    • cBridge Security
  • Tutorial
    • Cross-chain Transfer
    • LP Guide
    • SGN V2 Staking Guide
    • SGN V1 Unbonding Guide
    • Smart Contract as LP
    • Aptos Bridging Guide
    • Ape Chain Bridging Guide
    • Flow Cadence Bridging Guide
    • Flow EVM Bridging Guide
  • Developer
    • Circle Cross-chain USDC Transfer Protocol(CCTP)
    • cBridge SDK
    • cBridge Pool-Based Transfer (xLiquidity)
      • Transfer
      • Transfer Refund
    • cBridge Canonical Mapping Transfer (xAsset)
      • Mint
      • Mint Refund
      • Burn
      • Burn Refund
    • cBridge Transfer Web Widget
    • cBridge Aptos Transfer (xAsset Only)
    • Custom Transfer URL Schemes
    • cBridge APIs for Sui
    • Referral Specific Transfer
    • cBridge Limit Parameters
    • API Reference
      • Gateway: GetTransferConfigsForAll
      • Gateway: EstimateAmt
      • Contract: Pool-Based Transfer
      • Gateway: GetTransferStatus
      • Contract: Pool-Based Transfer Refund
      • Gateway: TransferHistory
      • Contract: Mint Canonical Token(OriginalTokenVault)
      • Contract: Mint Canonical Token(OriginalTokenVaultV2)
      • Contract: Mint Canonical Token Transfer Refund
      • Contract: Burn Canonical Token(PeggedTokenBridge)
      • Contract: Burn Canonical Token (PeggedTokenBridgeV2)
      • Contract: Burn Canonical Token Transfer Refund
      • Gateway: MarkRefRelation
      • Contract: TransferAgent Mint Token Submission
      • Contract: TransferAgent Burn Token Submission
      • Contract: Aptos Vault Mint Token Submission
      • Contract: Aptos PegBridge Burn Token Submission
  • NFT Bridge
    • Introduction
    • NFT Bridge Fee
  • List Your Tokens
    • Simple Listing Process
  • Reference
    • FAQ
    • Audit Reports
    • Contract Addresses
Powered by GitBook
On this page
  • REST API
  • Get estimation for the user's transfer request
  • GRPC-Web API
  • Request Parameters
  • Response Parameters
  • Error handling
  • Error Code Description
  • Error with high frequency
  • Estimated Time of Arrival for Transfer
  • Request Sample
  1. Developer
  2. API Reference

Gateway: EstimateAmt

Get estimation for the user's transfer request.

PreviousGateway: GetTransferConfigsForAllNextContract: Pool-Based Transfer

Last updated 6 months ago

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:

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

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.

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

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
}

You need to find out whether this transfer is used for pegged token according to . Moreover, slippage will not be effective if is_pagged is true

between source chain and destination chain

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

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
on-chain send
https://cbridge-prod2.celer.app/v2/getLatest7DayTransferLatencyForQuery?src_chain_id=1&dst_chain_id=56
Bridge rate
Protocol fee
Base fee
PeggedPairConfigs