4️⃣Build Swap Transaction

Get Build Tx

get

Query parameters

srcChainIdintegerRequired

Source chain ID.

srcQuoteTokenAddressstringRequired

Source chain quote token address.

srcQuoteTokenAmountstringRequired

Source chain quote token amount.

dstChainIdintegerRequired

Destination chain ID.

dstQuoteTokenAddressstringRequired

Destination chain quote token address.

slippagenumberRequired

Percentage of slippage tolerance.

receiverstringRequired

Destination chain quote token receiver.

affiliatestringOptional

Source chain affiliate address.

commissionRateintegerOptional

Commission rate of affiliate, denominator is 1000000. Affiliate must be provided when passing commissionRate.

bridgeProviderstringOptional

Provider of bridge operation.

srcBridgeTokenAddressstringOptional

Source chain bridge token address

dstBridgeTokenAddressstringOptional

Destination chain bridge token address

srcSwapProviderstringOptional

Provider of source chain swap.

dstSwapProviderstringOptional

Provider of destination chain swap.

Responses

200

Successful Response

application/json

Responseany of

or

get

/buildTx

HTTPcURLJavaScriptPython

GET /v1/buildTx?srcChainId=1&srcQuoteTokenAddress=text&srcQuoteTokenAmount=text&dstChainId=1&dstQuoteTokenAddress=text&slippage=1&receiver=text HTTP/1.1
Host: aggregator-api.xy.finance
Accept: */*

200

Successful Response

{
  "success": true,
  "route": {
    "srcChainId": 324,
    "srcQuoteTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "srcQuoteTokenAmount": "10000000000000000",
    "dstChainId": 59144,
    "dstQuoteTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
    "slippage": 1,
    "bridgeDescription": {
      "provider": "yBridge",
      "srcChainId": 324,
      "srcBridgeTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "dstChainId": 59144,
      "dstBridgeTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "srcBridgeTokenAmount": "9990000000000000",
      "dstBridgeTokenAmount": "9190000000000000",
      "bridgeContractAddress": "0xe4e156167cc9C7AC4AbD8d39d203a5495F775547",
      "bridgeFeeAmount": "800000000000000",
      "bridgeFeeToken": {
        "chainId": 324,
        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "decimals": 18,
        "symbol": "ETH"
      },
      "srcBridgeToken": {
        "chainId": 324,
        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "decimals": 18,
        "symbol": "ETH"
      },
      "dstBridgeToken": {
        "chainId": 59144,
        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        "decimals": 18,
        "symbol": "ETH"
      }
    },
    "dstQuoteTokenAmount": "9190000000000000",
    "minReceiveAmount": "9098100000000000",
    "affiliateFeeAmount": "10000000000000",
    "withholdingFeeAmount": "0",
    "routeType": "xy_router_cross_chain",
    "tags": [],
    "contractAddress": "0xB790c2970463F2C7678048f3932A28fdc3Cccf8F",
    "withholdingFeeToken": {
      "chainId": 324,
      "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "decimals": 18,
      "symbol": "ETH"
    },
    "srcQuoteToken": {
      "chainId": 324,
      "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "decimals": 18,
      "symbol": "ETH"
    },
    "dstQuoteToken": {
      "chainId": 59144,
      "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
      "decimals": 18,
      "symbol": "ETH"
    },
    "srcQuoteTokenUsdValue": "16.3805",
    "dstQuoteTokenUsdValue": "15.0536795",
    "transactionCounts": 2,
    "estimatedGas": "400000",
    "estimatedTransferTime": 180
  },
  "tx": {
    "to": "0xB790c2970463F2C7678048f3932A28fdc3Cccf8F",
    "data": "0xd99a86ec000000000000000000000000000000000000000000000000002386f26fc10000000000000000000000000000314c71ff355f9f525334526f339d84a57e664a1f00000000000000000000000000000000000000000000000000000000000000c00000000000000000000000000000000000000000000000000000000000000240000000000000000000000000bf5d9213bf083cf6ccc0e811c9bc43c700f0236200000000000000000000000000000000000000000000000000000000000003e8000000000000000000000000000000000000000000000000000000000000e708000000000000000000000000e4e156167cc9c7ac4abd8d39d203a5495f775547000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee00000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000014314c71ff355f9f525334526f339d84a57e664a1f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000080000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee0000000000000000000000000000000000000000000000000020a6419d7c6000000000000000000000000000bf5d9213bf083cf6ccc0e811c9bc43c700f02362000000000000000000000000000000000000000000000000000000000000006400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000001e00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000004000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000000000000000000000000000000000000140000000000000000000000000000000000000000000000000000000000000000",
    "value": "0x2386f26fc10000"
  }
}

When building transaction, there are 6 additional parameters along with quote input.

Field name	Requirement
receiver	Required
srcSwapProvider	Required when srcSwapDescription is presented in quote result
dstSwapProvider	Required when dstSwapDescription is presented in quote result
bridgeProvider	Required when bridgeDescription is presented in quote result
srcBridgeTokenAddress	Required when bridgeDescription is presented in quote result
dstBridgeTokenAddress	Required when bridgeDescription is presented in quote result

To build transaction, please fill the corresponding fields (srcSwapDescription, bridgeDescription and dstSwapDescription) from quote response's route to buildTx input . If parameters are not filled properly, it may not return the desired routing result. You can review the transaction calldata route by checking route field in buildTx response.

For example, following response is quote result of Arbitrum USDT to KCC native token.

// quote response
{
    "success": true,
    "routes": [
        {
            "srcChainId": 42161,
            "srcQuoteTokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
            "srcQuoteTokenAmount": "10000000",
            "dstChainId": 321,
            "dstQuoteTokenAddress": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
            "srcSwapDescription": null,
            "bridgeDescription": {
                "provider": "yBridge",
                // ...
            },
            "dstSwapDescription": {
                "provider": "XY DexAggregator",
                // ...
            },
            // ...
        }
    ],
}

• srcSwapDescription is null because these is no source chain swap needed in this route, so we don't have to fill srcSwapProvider when calling buildTx.

• We have a non-empty bridgeDescription because it's a cross-chain quote. We need to fill corresponding bridgeProvider, srcBridgeTokenAddress and dstBridgeTokenAddress when calling buildTx. For single chain quote, we can skip these parameters.

• dstSwapDescription is needed in this route. So we need to fill dstSwapProvider when calling buildTx.

Therefore, we can create the following buildTx request from above information:

// buildTx request
curl -G \
  -d 'srcChainId=42161' \
  -d 'srcQuoteTokenAddress=0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9' \
  -d 'srcQuoteTokenAmount=10000000' \
  -d 'dstChainId=321' \
  -d 'dstQuoteTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE' \
  -d 'slippage=1' \
  -d 'receiver=YOUR_DESTINATION_CHAIN_RECEIVER_ADDRESS' \
  -d 'bridgeProvider=yBridge' \
  -d 'srcBridgeTokenAddress=0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9' \
  -d 'dstBridgeTokenAddress=0x0039f574eE5cC39bdD162E9A88e3EB1f111bAF48' \
  -d 'dstSwapProvider=XY%20DexAggregator' \
  https://aggregator-api.xy.finance/v1/buildTx

Parameter/Response Details

• Use 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE as the address for the native token in your parameter.

• If you would like to know more about commissionRate fields and fee collection function, please refer to Monetization / Take Fees

• If you would like to know latest supported bridge provider and swap provider, please refer to Supported Blockchains/Bridges/DEXs

• The estimatedGas field in the API response is an estimated value. For now, please use a method similar to RPC, such as eth_estimateGas, to re-estimate the actual gas limit. You can refer to the following sample code to do that:

from web3 import Web3
import requests
​
if __name__ == "__main__":
    # 1st: get tx data from xy aggregator api
    endpoint = 'https://aggregator-api.xy.finance/v1/buildTx?srcChainId=137&srcQuoteTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&srcQuoteTokenAmount=9000000000000000000&dstChainId=56&dstQuoteTokenAddress=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d&slippage=1&receiver=0x9cEEEbdF49cF5DEa891C9D74f8ea03af2aCf284F&bridgeProvider=yBridge&srcBridgeTokenAddress=0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174&dstBridgeTokenAddress=0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d&srcSwapProvider=OneInch%20V4%20DexAggregator&affiliate=0x512E00f66217714BAee5F0736428b026e8c30AF5'
    resp = requests.get(endpoint)
    resp_json = resp.json()
​
    # 2nd: get estimateGas by calling web3 rpc
    rpc_endpoint = 'https://polygon.llamarpc.com'
    w3 = Web3(Web3.HTTPProvider(rpc_endpoint))
    estimate_gas = w3.eth.estimate_gas(resp_json["tx"])
​
    # 3rd: Combine the estimateGas with the tx data
    tx = resp_json["tx"]
    tx["gas"] = estimate_gas
​
    # 4th: sign the tx & send it
    priv_key = "0x"
    tx_signed = w3.eth.account.sign_transaction(tx, priv_key)
    tx_hash = w3.eth.send_raw_transaction(tx_signed.rawTransaction)

Example Request

$ curl https://aggregator-api.xy.finance/v1/buildTx?srcChainId=10&srcQuoteTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&srcQuoteTokenAmount=1000000000000000000&dstChainId=56&dstQuoteTokenAddress=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&slippage=1&receiver=0xb6EFA1C3679f1943f8aC4Fc9463Cc492435c6C92&bridgeProvider=yBridge&srcBridgeTokenAddress=0x94b008aA00579c1307B0EF2c499aD98a8ce58e58&dstBridgeTokenAddress=0x55d398326f99059fF775485246999027B3197955&affiliate=0x90d67a9eaC7324A1a2942D6Dea9f6174Ad6048c9&commissionRate=100000&srcSwapProvider=OKX+DEX&dstSwapProvider=OKX+DEX

This request is asking to bridge 1 ETH from Optimism for ETH on the BNB Chain

IMPORTANT: Note that the amount parameter should be padded with zeroes. For example, pass 100000000 instead of 100 if the decimals of the token is 6.

Here you can find our full API reference