Quote & Swap

Find the potential quote for user's input and target output

Every swap starts with a call to /quote, then the caller can decide whether they want to proceed. If the price/path looks good, the caller should proceed to call /swap with a selected path to build the calldata for the contract call.

Quote

POST/chainhop/quote

Body

application/json

srcTokenfield names matches the tokenlist standard

dstTokenfield names matches the tokenlist standard

amountInstring

slippageTolerancestring (int64)

nativeOutmost bridges would only output native token when the desired output is either native/wrapped so if the user specifically wants wrapped native token as output, some direct bridge route will not be included

onlySwapsarray of string

onlyBridgesarray of string

noncestring (uint64)

a number that is used to both dedup quote results and prevent replay at the cbridge contracts the same nonce is returned in QuoteResponse.

Response

200default

A successful response.

Body

application/json

errchainhopErrMsg (object)

srcTokenUsdPricenumber (double)

dstTokenUsdPricenumber (double)

pathsarray of chainhopPath (object)

noncestring (uint64)

Request

JavaScriptCurl

const response = await fetch('/chainhop/quote', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "err": {
    "code": "ERROR_CODE_UNDEFINED",
    "msg": "text",
    "errMinMaxSend": {
      "amountIn": "text",
      "minSend": "text",
      "maxSend": "text"
    }
  },
  "srcTokenUsdPrice": 0,
  "dstTokenUsdPrice": 0,
  "paths": [
    {
      "steps": [
        {
          "type": "STEP_UNKNOWN",
          "tokenIn": {
            "chainId": "text",
            "symbol": "text",
            "address": "text",
            "name": "text",
            "logoUri": "text"
          },
          "tokenOut": {
            "chainId": "text",
            "symbol": "text",
            "address": "text",
            "name": "text",
            "logoUri": "text"
          },
          "providerName": "text",
          "providerIconUrl": "text"
        }
      ],
      "amountOut": "text",
      "amountOutRaw": "text",
      "amountOutMin": "text",
      "returnAmount": "text",
      "bridgeFee": "text",
      "priceImpact": "text",
      "etaSeconds": "text",
      "srcGasFee": "text",
      "srcGasFeeUsd": 0,
      "pathType": "text",
      "mmId": "text",
      "rfqPrice": {
        "srcToken": {
          "chainId": "text",
          "symbol": "text",
          "address": "text",
          "name": "text",
          "logoUri": "text"
        },
        "srcAmount": "text",
        "dstToken": {
          "chainId": "text",
          "symbol": "text",
          "address": "text",
          "name": "text",
          "logoUri": "text"
        },
        "srcReleaseAmount": "text",
        "dstAmount": "text",
        "validThru": "text",
        "mmAddr": "text",
        "sig": "text",
        "srcDeadlinePeriod": "text",
        "dstDeadlinePeriod": "text"
      }
    }
  ],
  "nonce": "text"
}

Request Fields

Name	Type	Description
src_token	Token	User's assets which will be used by ExecutionNode contract deployed on source chain
dst_token	Token	Assets will be moved to user's account on destination chain
amount_in	String	Amount with token's decimals
slippage_tolerance	Number	In basis points, 100% is 1000000(1M)
native_out	Boolean	Whether the user wants native token as output (only applicable if the dst_token is set to a native wrap)
only_swaps	Array<String>	Swap will be executed only at these dexes if there are specific swap array. Dexes supported are SushiSwap, UniswapV2/V3, Curve, Platypus, 1inch, more will be added
only_bridges	Array<String>	Bridge selection filter. 'cbridge', 'stargate', 'anyswap', 'hop', 'hyphen', 'across'.
nonce	Number	Nonce is used for uniquely tracking a swap on a per user per swap basis. Typically this is set to a unix timestamp

Token

Name	Type	Description
symbol	String	Token symbol
chain_id	Number	Id of chain on which token is deployed
address	String	Token Address
decimals	Number	Token decimals
name	String	Token name
logo_uri	String	Token logo's URI

logo_uri and name are not required for token

Response Fields

Name	Type	Description
err	Optional Error Message
src_token_usd_price	Number	Source token's usd price
dst_token_usd_price	Number	Destination token's usd price
swap_id	String
paths	Array<Path>	Quote paths

Path

Name	Type	Description
steps	Array<Step>
amount_out	String	Estimated receiving amount. All non-native fees for destination chain swap will be deducted.
amount_out_raw	String	amount_out plus non-native fees
amount_out_min	String	The minium destination token value that the receiver will receive
return_amount	String	The return estimation for user's swap, which is denominated in destination token
bridge_fee	String	All fees that are charged through the token bridge. Native token fees charged up front in the source chain transaction will not be included. It is denominated in source token
tx_data	String	Abi encoded transaction data field.
tx_value	String	Abi encoded transaction value field. If the path involves sending message through cBridge, it will be set to a non-zero value to facilitate the message fee. If the bridge has native gas requirement, such as stargate, it will be also a positive value. Otherwise, the fee will be "0"
price_impact	Number	Calculation below
eta_seconds	Number	ETA of the path. It will include bridge time and message execution time if there is any
src_gas_fee	String	Gas token amount with decimals
src_gas_fee_usd	Number	Gas token value in USD, no decimals included

price_impact = (amount_in / amount_out) / (token_out_usd_price / token_in_usd_price) - 1

Step

Name	Type	Description
type	StepType	Step type indication
token_in	Token	Input token for this step
token_out	Token	Token output for this step
provider_name	String	Provider's name
provider_icon_url	String	Provider's icon url

StepType

Value	Description
STEP_UNKNOWN(0)	Unknown Step
STEP_DEX(1)	Step fulfilled by a DEX
STEP_BRIDGE(2)	Step fulfilled by a Bridge

Since the step type is enum, ChainHop will return a number to represent the type.

Swap

Swap() should only be called when the user selects a path and wants to commit a swap

POST/chainhop/swap

Body

application/json

stepsuse the same steps field from QuoteResponse's paths

amountInstring

slippageTolerancestring (int64)

nativeInboolean

nativeOutboolean

receiverreceiver is an eth address that 1. receives the output token and 2. receives the refund token if swap/bridge goes wrong. caller need to ensure that they have control over this receiver address on any chain supported by chainhop

noncestring (uint64)

senderstring

Response

200default

A successful response.

Body

application/json

errchainhopErrMsg (object)

txDataabi encoded transaction "data" field

txValuetransaction "value" field. if a path involves sending message through cBridge, this field will be set to a non-zero value to facilitate the message fee. otherwise it's always set to "0"

pathchainhopPath (object)

noncestring (uint64)

swapIdswap_id = keccak256(abi.encodePacked(sender, receiver, nonce))

Request

JavaScriptCurl

const response = await fetch('/chainhop/swap', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "err": {
    "code": "ERROR_CODE_UNDEFINED",
    "msg": "text",
    "errMinMaxSend": {
      "amountIn": "text",
      "minSend": "text",
      "maxSend": "text"
    }
  },
  "txData": "text",
  "txValue": "text",
  "path": {
    "steps": [
      {
        "type": "STEP_UNKNOWN",
        "tokenIn": {
          "chainId": "text",
          "symbol": "text",
          "address": "text",
          "name": "text",
          "logoUri": "text"
        },
        "tokenOut": {
          "chainId": "text",
          "symbol": "text",
          "address": "text",
          "name": "text",
          "logoUri": "text"
        },
        "providerName": "text",
        "providerIconUrl": "text"
      }
    ],
    "amountOut": "text",
    "amountOutRaw": "text",
    "amountOutMin": "text",
    "returnAmount": "text",
    "bridgeFee": "text",
    "priceImpact": "text",
    "etaSeconds": "text",
    "srcGasFee": "text",
    "srcGasFeeUsd": 0,
    "pathType": "text",
    "mmId": "text",
    "rfqPrice": {
      "srcToken": {
        "chainId": "text",
        "symbol": "text",
        "address": "text",
        "name": "text",
        "logoUri": "text"
      },
      "srcAmount": "text",
      "dstToken": {
        "chainId": "text",
        "symbol": "text",
        "address": "text",
        "name": "text",
        "logoUri": "text"
      },
      "srcReleaseAmount": "text",
      "dstAmount": "text",
      "validThru": "text",
      "mmAddr": "text",
      "sig": "text",
      "srcDeadlinePeriod": "text",
      "dstDeadlinePeriod": "text"
    }
  },
  "nonce": "text",
  "swapId": "text"
}