Skip to main content

Swap

To perform a swap, a swap transaction needs to be generated by calling the Swap endpoint in the Rest API and then broadcast to a chain.

The swap parameters are the following:

asset_in
amount_in
slippage
timeout
swaps
cross_chain_addresses
partner_fee

We will go through all the steps needed to get each of the parameters.

Steps​

The following steps describe the workflow to perform a swap using the Euclid Layer:

1. Get all available tokens​

The first step will be getting all the available tokens and selecting the input and output tokens. This ensures that the tokens involved in the swap are supported by the Euclid Layer. This can be done using the All Tokens query:

query Router {
  router {
    all_tokens {
      tokens
    }
  }
}

This will return a response similar to the following:

{
  "data": {
    "router": {
      "all_tokens": {
        "tokens": [
          "axs",
          "bera",
          "bnb",
          "chog",
          "coin50",
          "const",
          "eth",
          "euclid",
          "inj",
          "mon",
          "nibi",
          "ntrn",
          "orai",
          "osmo",
          "pol",
          "ron",
          "slp",
          "sp500",
          "stars",
          "testcore",
          "usdc",
          "usdt",
          "xau"
        ]
      }
    }
  }
}

Once fetched, they can be displayed for the user who can select the desired tokens for the swap.

2. Get all the chains for token_in​

Get the chains that have escrows for token in and then select the one to use. This can be done using the Escrows query:

tip
  • The connected wallet needs to be the same as the selected chain.
  • For the $token parameter, use the token_in selected in the previous step.
query Router($token: String!) {
  router {
    escrows(token: $token) {
      balance
      chain_id
      chain_uid
    }
  }
}

Here is a response for a "usdt" token in:

{
  "data": {
    "router": {
      "escrows": [
        {
          "balance": "3979277138184",
          "chain_id": "injective-888",
          "chain_uid": "injective"
        },
        {
          "balance": "52723595",
          "chain_id": "10143",
          "chain_uid": "monad"
        }
      ]
    }
  }
}

You can then prompt the user to select the chain of their choice.

3. Retrieve the allowed denoms​

Check the allowed denoms for the token in. This can be done using the Escrow query:

tip

Use the Chain UID and token Id from previous steps for the chain selected.

query Factory($chainUid: String!, $tokenId: String) {
  factory(chain_uid: $chainUid) {
    escrow(token_id: $tokenId) {
      denoms {
        ... on NativeTokenType {
          native {
            denom
          }
        }
        ... on SmartTokenType {
          smart {
            contract_address
          }
        }
      }
    }
  }
}

This will return the denom to be used in the swap based on the parameters passed by the user (usdt on ethereum in this example):

{
  "data": {
    "factory": {
      "escrow": {
        "denoms": [
          {
            "native": {
              "denom": "peggy0x87aB3B4C8661e07D6372361211B96ed4Dc36B1B5"
            }
          }
        ]
      }
    }
  }
}

4. Specify token in amount​

Next, we need to select the amount of token_in to swap. This would be specified by the user.

5. Get swap routes​

In many cases, multiple routes can be taken to perform the desired swap. In this step, we will fetch these routes and select the one we want to use. This can be done using the Get Routes query:

curl -X 'POST' \
  'https://testnet.api.euclidprotocol.com/api/v1/routes' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount_in": "100",
  "token_in": "usdt",
  "token_out": "eth"
}'

Here is a result for usdt in and eth out:

{
  "paths": [
    {
      "path": [
        {
          "route": [
            "usdt",
            "eth"
          ],
          "dex": "euclid",
          "amount_in": "100",
          "amount_out": "6343813458",
          "chain_uid": "vsl",
          "amount_out_for_hops": [
            "eth: 6343813458"
          ]
        }
      ],
      "total_price_impact": "0.00"
    },
    {
      "path": [
        {
          "route": [
            "usdt",
            "usdc",
            "eth"
          ],
          "dex": "euclid",
          "amount_in": "100",
          "amount_out": "6350391690",
          "chain_uid": "vsl",
          "amount_out_for_hops": [
            "usdc: 138",
            "eth: 6350391690"
          ]
        }
      ],
      "total_price_impact": "0.00"
    }
  ]
}
note

In addition to specifying the swap route, you can optionally include detailed execution parameters for each hop:

  • dex: The decentralized exchange to use for this segment of the swap (e.g., "euclid", "osmosis", "astroport").
  • amount_in: The input amount for this hop.
  • amount_out: The expected output amount after this hop.
  • chain_uid: The chain where this hop should be executed.

Providing these fields can offer more precise control over the routing behavior when constructing the swap message.

Example:

"swap_path": {
  "path": [
    {
      "route": ["nibi", "euclid"],
      "dex": "euclid",
      "amount_in": "1000000",
      "amount_out": "950000",
      "chain_uid": "nibiru"
    }
  ]
}

6. Simulate the swap​

Now that we have all the parameters required, we can simulate the swap. This can be done using the Simulate Swap query:

tip

For simulate swap, specify the min_amount_out as 1. We are only interested in getting the expected amount out and do not care about slippage here.

query Simulate_swap($assetIn: String!, $amountIn: String!, $assetOut: String!, $minAmountOut: String!, $swaps: [String!]) {
  router {
    simulate_swap(asset_in: $assetIn, amount_in: $amountIn, asset_out: $assetOut, min_amount_out: $minAmountOut, swaps: $swaps) {
      amount_out
      asset_out
    }
  }
}

The following parameters are used in the above example:

  "assetIn": "usdt",
  "amountIn": "100",
  "assetOut": "eth",
  "minAmountOut": "1",
  "swaps": ["usdt","eth"]

The response will return the expected amount_out for the swap:

{
  "data": {
    "router": {
      "simulate_swap": {
        "amount_out": "6347047297",
        "asset_out": "eth"
      }
    }
  }
}

7. Set slippage Value​

The slippage field specifies the maximum allowed slippage for the swap, expressed in basis points (bps):

  • 100 = 1%
  • 500 = 5%
  • 1000 = 10%

This value is used to protect the swap from executing at a worse rate than expected.

Example

To allow up to 5% slippage, set:

"slippage": "500"

8. Generate swap transaction​

note
  • Use the responses we got in all the previous steps for the swap fields.
  • For sender address and chain_uid use the ones from the connected chain.
  • You can include a specific timeout. Excluding it will take the default of 60 seconds.
  • You can include a partner_fee if you wish to include a fee for your application.
  • The cross_chain_addresses are taken as an input from the user. The addresses for different chains can be fetched from the wallet using the chain Id.

We now have everything needed to generate the swap transaction message:

const msg = await axios.post("https://testnet.api.euclidprotocol.com/api/v1/execute/swap", {
  amount_in: data.amountIn, // amount of asset in being swapped 
  asset_in: data.assetIn, // the type of asset in
  asset_out: data.assetOut, // the type of asset out
  cross_chain_addresses: data.crossChainAddresses, // the chains and addresses to release asset out
  slippage: data.slippage, // Used to specify max slippage tolerated.
  sender: {
    address: wallet!.bech32Address,
    chain_uid: chain!.chain_uid,
  },
  swaps: data.swaps,
}).then((res) => res.data as TxResult);
const msg = await axios.post("https://testnet.api.euclidprotocol.com/api/v1/execute/swap", {
  amount_in: data.amountIn,
  asset_in: data.assetIn,
  asset_out: data.assetOut,
  cross_chain_addresses: data.crossChainAddresses,
  slippage: data.slippage,
  sender: {
    address: walletAddress, // EVM address
    chain_uid: chainUid
  },
  swaps: data.swaps
}).then((res) => res.data);

9. Broadcast the transaction to chain​

The final step will be broadcasting this transaction to the chain and signing it with the connected wallet:

const tx = await client!.executeMultiple(
  wallet!.bech32Address,
  msg.msgs,
  "auto",
  "Swap"
);
return tx;
const provider = new ethers.providers.Web3Provider(window.ethereum);
const signer = provider.getSigner();

// Construct the transaction data
const tx = {
  to: msg.msgs[0].to, // Contract address
  data: msg.msgs[0].data, // Encoded calldata
  value: msg.msgs[0].value || "0x0" 
};

// Send transaction using signer (e.g. MetaMask)
const receipt = await signer.sendTransaction(tx);

// Optional: Wait for confirmation
const confirmed = await receipt.wait();
return confirmed;