v1 -> v2 Migration

Squid is launching v2! With this upgrade Squid delivers:

• Lightning fast response times, always <1 sec, down to 300ms

• Long term scaling improvements, we’re ready to handle hundreds of RPS

  • Each partner has an RPS limit in place, so please let us know if you need more!

Overview of Breaking Changes

As a part of this upgrade there are breaking changes you must implement to get access to the improved Squid v2

1. Change your endpoint fromhttps://api.squidrouter.com to https://v2.api.squidrouter.com

   1. Route Request Endpoint: https://v2.api.squidrouter.com/v2/route

   2. Transaction Status Endpoint:https://v2.api.squidrouter.com/v2/status

2. Acquiring a v2 Integrator ID. Connect with the Squid team and we will enable your existing integratorID from a v1 Integrator ID to a v2Integrator ID.

   1. If you do not have a V1 Integrator ID to upgrade, you can apply for a v2 Integrator ID here and it will be sent to your email.

3. Modify your hook implementations

   1. Including a fundAmount and fundToken to preHooks

   2. Include provider, description , and logoURI in both the preHook and postHook call

New SDK Version

npm install @0xsquid/sdk@^2.8.23

New Widget Version

npm install @0xsquid/widget@^2.0.0

Base URLs

v1: https://api.squidrouter.com

v2: https://v2.api.squidrouter.com

Route Request Endpoint

v1: https://api.squidrouter.com

v2: https://v2.api.squidrouter.com/v2/route

Status Endpoint

v1: https://api.squidrouter.com/v1/status?transactionId=

v2: https://v2.api.squidrouter.com/v2/status

Ethers version (Squid SDK integrations only)

• V1: Ethers V5

• V2: Ethers V5 or V6 up to v6.7.1

  • npm i ethers@6.7.1

Change /route from GET to POST

• The /route endpoint is now POST. /status is still a /GET request.

SDK

Our SDK handles this behind the scenes. No changes needed

  // Get the swap route using Squid SDK
  const { route, requestId } = await squid.getRoute(params);

API

// Function to get the optimal route for the swap using Squid API
const getRoute = async (params: any) => {
  try {
    const result = await axios.post(
      "https://apiplus.squidrouter.com/v2/route",
      params,
      {
        headers: {
          "x-integrator-id": integratorId,
          "Content-Type": "application/json",
        },
      }
    );
    const requestId = result.headers["x-request-id"]; // Retrieve request ID from response headers
    return { data: result.data, requestId: requestId };
  } catch (error) {
    if (error.response) {
      console.error("API error:", error.response.data);
    }
    console.error("Error with parameters:", params);
    throw error;
  }
};

Importing types

• v1:

  • import { ChainType, RouteResponse, SquidCallType } from "@0xsquid/sdk";
• v2: Slightly different import path

  • import { ChainType, RouteResponse, SquidCallType } from "@0xsquid/sdk/dist/types";

integrator-id is required on all requests in v2

SDK

v1

const getSquidSDK = async () => {
  const squid = new Squid({
    baseUrl: "https://api.squidrouter.com",
  });
  await squid.init();
  return squid;
};

v2

// Function to get Squid SDK instance
const getSDK = (): Squid => {
  const squid = new Squid({
    baseUrl: "https://v2.api.squidrouter.com",
    integratorId: integratorId,
  });
  return squid;
};

API

Add integrator-id to headers of every GET and POST request:

const getChains = async () => {
	const result = await axios.get('https://v2.api.squidrouter.com/v2/chains', {
		headers: {
			'x-integrator-id': integratorId,
		},
	});
	return result.data;
};

// Function to get the optimal route for the swap using Squid API
const getRoute = async (params: any) => {
  try {
    const result = await axios.post(
      "https://v2.api.squidrouter.com/v2/route",
      params,
      {
        headers: {
          "x-integrator-id": integratorId,
          "Content-Type": "application/json",
        },
      }
    );
    const requestId = result.headers["x-request-id"]; // Retrieve request ID from response headers
    return { data: result.data, requestId: requestId };
  } catch (error) {
    if (error.response) {
      console.error("API error:", error.response.data);
    }
    console.error("Error with parameters:", params);
    throw error;
  }
};

V2 Parameters

const params = {
  fromChain: number | string; //the chainID assets are being bridged FROM
  toChain: number | string; //the chainID assets are being bridged TO
  fromToken: string;  //the asset address being swapped FROM, "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" for native assets
  toToken: string;  // The asset address being swapped TO, "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE" for native assets
  fromAmount: string; // The unadjusted decimal amount assets 
  fromAddress: string; // The address FROM which assets are being sent to be bridged
  toAddress: string; // The address TO which bridged assets will be sent to
  slippage?: number; //OPTIONAL, If set it determines the max slippage across the route (0.01-99.99) 1 = 1% slippage.
  quoteOnly?: boolean; //OPTIONAL, If true, returns only a quote for the route. Omits transaction data needed for execution. Defaults to false
};

API Migration

Migrating from v1 to v2, enables route requests under 1 second and sustainability scalability.. You can find out-of-the-box examples to implement Squid v2 in our github examples repo.

Route Request

The route request now uses the new endpoint and requires the updated Integrator ID in the headers.

const getRoute = async (params) => {
  const result = await axios.post(
    "<https://apiplus.squidrouter.com/v2/route>",
    params,
    {
      headers: {
        "x-integrator-id": integratorId,
        "Content-Type": "application/json",
      },
    }
  );
  return {
    data: result.data,
    requestId: result.headers["x-request-id"]
  };
};

Note the extraction of requestId from the response headers, which is now required for status checks.

Status Check

The status check endpoint has also been updated:

const getStatus = async (params) => {
  return await axios.get("<https://v2.api.squidrouter.com/v2/status>", {
    params: {
      transactionId: params.transactionId,
      requestId: params.requestId,
      fromChainId: params.fromChainId,
      toChainId: params.toChainId,
    },
    headers: {
      "x-integrator-id": integratorId,
    },
  });
};

Ensure you're passing the requestId obtained from the route request.

API Parameter Changes

• Include slippage as a number instead of an object

API Response Handling

• Extract requestId from response headers for status checks

• Use route.transactionRequest for transaction execution

SDK Migration

If you're using the Squid SDK, you can find the key changes to implement below. You can find out-of-the-box examples to implement Squid v2 and our SDK in our Github examples repo.

SDK Initialization

Initialize the SDK with the new base URL and your updated Integrator ID:

import { Squid } from "@0xsquid/sdk";

const squid = new Squid({
  baseUrl: "<https://v2.api.squidrouter.com>",
  integratorId: "YOUR_INTEGRATOR_ID",
});
await squid.init();

Get Route

The getRoute method now returns a requestId along with the route:

const { route, requestId } = await squid.getRoute({
  fromChain: fromChainId,
  fromToken: fromToken,
  fromAmount: amount,
  toChain: toChainId,
  toToken: toToken,
  toAddress: signer.address,
  slippage: 1,// Now a number

Execute Route

Use the transactionRequest object from the route to execute the transaction:

const tx = await signer.sendTransaction({
  to: route.transactionRequest.target,
  data: route.transactionRequest.data,
  value: route.transactionRequest.value,
  gasLimit: route.transactionRequest.gasLimit,
});
const txReceipt = await tx.wait();

Check Status

Include the requestId when checking the transaction status:

const status = await squid.getStatus({
  transactionId: txReceipt.transactionHash,
  requestId: requestId,
  fromChainId: fromChainId,
  toChainId: toChainId,
});

Hook, Previously customContractCalls, Implementation (API and SDK)

customContractCalls have been renamed to postHook and postHook

Hooks now require additional parameters. Here are examples for both pre and postHooks:

PreHook Example

You can use a preHook to execute an action before a cross-chain swap.

preHook: {
  chainType: "evm",
  fundAmount: "10000",
  fundToken: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  provider: "Your App",
  description: "Wrap native token",
  logoURI: "<http://your-logo-url.com>",
  calls: [
    {
      chainType: "evm",
      callType: 2,
      target: WETH_ADDRESS,
      value: "10000",
      callData: wrapEncodedData,
      payload: {
        tokenAddress: "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
        inputPos: 0,
      },
      estimatedGas: "500000",
    },
  ],
},

PostHook Example

You can use a preHook to execute an action after a cross-chain swap.

postHook: {
  chainType: "evm",
  provider: "Your App",
  description: "Approve and Deposit",
  logoURI: "<http://your-logo-url.com>",
  calls: [
    {
      chainType: "evm",
      callType: 1,
      target: usdcAddress,
      value: "0",
      callData: approveEncoded,
      payload: {
        tokenAddress: usdcAddress,
        inputPos: "1",
      },
      estimatedGas: "50000",
    },
    {
      chainType: "evm",
      callType: 1,
      target: lendingPoolAddress,
      value: "0",
      callData: depositEncoded,
      payload: {
        tokenAddress: usdcAddress,
        inputPos: "1",
      },
      estimatedGas: "50000",
    },
  ],
},

Breaking Changes: Details And Examples

There are two required modifications to Request Params

• slippage: NUMBER(0.01-99.99); this number can be 0.01 to 99.99 and represents the associated slippage with a transaction. This parameter is now optional and will be dynamically set by Squid if not included.

  • Recommendation: Slippage is an optional parameter. We recommend you don’t set the slippage value so it is dynamically set by Squid during the route request

    Request Params Modification Example for API

v1 Implementation

//Previous Implementation
const params = {
    fromAddress: signer.address,
    fromChain: fromChainId,
    fromToken: fromToken,
    fromAmount: amount,
    toChain: toChainId,
    toToken: toToken,
    toAddress: signer.address,
    slippage:1,
  };

v2 Implementation

//New Implementation

const params = {
    fromAddress: signer.address,
    fromChain: fromChainId,
    fromToken: fromToken,
    fromAmount: amount,
    toAddress: signer.address,
    toChain: toChainId,
    toToken: toToken,
    slippage: 1, //add slippage optional
  };

Request Params Modification Example for SDK

v1 Implementation

//Previous Implementation
const params = {
    fromAddress: signer.address,
    fromChain: fromChainID,
    fromToken: fromToken,
    fromAmount: amount,
    toChain: toChainId,
    toToken: toToken,
    toAddress: signer.address,
    slippage: 1, 
    quoteOnly: false,
  };

v2 Implementation

const params = {
    fromAddress: signer.address,
    fromChain: fromChainID,
    fromToken: fromToken,
    fromAmount: amount,
    toChain: toChainId,
    toToken: toToken,
    toAddress: signer.address,
    slippage: 1, //add slippage optional
    quoteOnly: false,
  };

Hook Implementations

we have added a fundAmount and fundToken to preHooks. We have also added a provider, description , and logoURI to the both the preHook and postHook call.

"provider": "Integration Test",
"description": "Wrap native",
"logoURI": "http://",

Modified Hook Implementation API

v1 Implementation

//Previous Implementation

postHook: {
      chainType: ChainType.EVM,
      //fundAmount: "10000", // for prehooks only
      //fundToken: "TOKEN ADDRESS, //for prehooks only
      calls: [
        {
          chainType: ChainType.EVM,
          callType: 1, // SquidCallType.FULL_TOKEN_BALANCE
          target: radiantLendingPoolAddress,
          value: "0",
          callData: depositEncodedData,
          payload: {
            tokenAddress: usdcArbitrumAddress,
            inputPos: 1,
          },
          estimatedGas: "50000",
        },
        
      ],
    },
  };

v2 Implementation

//New Implementation

postHook: {
      chainType: ChainType.EVM,
      //fundAmount: "10000", //for prehooks only
      //fundToken: "TOKEN ADDRESS, //for prehooks only
      calls: [
        {
          chainType: ChainType.EVM,
          callType: 1, // SquidCallType.FULL_TOKEN_BALANCE
          target: radiantLendingPoolAddress,
          value: "0",
          callData: depositEncodedData,
          payload: {
            tokenAddress: usdcArbitrumAddress,
            inputPos: 1,
          },
          estimatedGas: "50000",
        },
        
      ],
			//add provider, description, logoURI
      description: "Lend USD To Radiant",
      logoURI: "<https://radiant.svg>",
      provider: "Radiant",
    },
  };

Modified Hook Implementation SDK

v1 Implementation

//Previous Implementation

postHook: {
      chainType: ChainType.EVM,
      //fundAmount: "10000", // for prehooks only
      //fundToken: "TOKEN ADDRESS, //for prehooks only
      calls: [
        {
          chainType: ChainType.EVM,
          callType: 1, // SquidCallType.FULL_TOKEN_BALANCE
          target: radiantLendingPoolAddress,
          value: "0",
          callData: depositEncodedData,
          payload: {
            tokenAddress: usdcArbitrumAddress,
            inputPos: 1,
          },
          estimatedGas: "50000",
        },
        
      ],
    },
  };
  

v2 Implementation

  /New Implementation

postHook: {
      chainType: ChainType.EVM,
      //fundAmount: "10000", //for prehooks only
      //fundToken: "TOKEN ADDRESS, //for prehooks only
      calls: [
        {
          chainType: ChainType.EVM,
          callType: 1, // SquidCallType.FULL_TOKEN_BALANCE
          target: radiantLendingPoolAddress,
          value: "0",
          callData: depositEncodedData,
          payload: {
            tokenAddress: usdcArbitrumAddress,
            inputPos: 1,
          },
          estimatedGas: "50000",
        },
        
      ],
			//add provider, description, logoURI
      description: "Lend USD To Radiant",
      logoURI: "<https://radiant.svg>",
      provider: "Radiant",
    },
  };

Response Shape Change Example

Lastly, the request response shape has changed inside the actions steps. This is for integrators that utilize the request response.

• Wrappers, bridges, and DEXes will now have an associated Provider: and logoURI: within the json response.

v1 Example Response

//Previous Response

{
    "route": {
        "estimate": {
            "actions": [
                {
                    "type": "wrap",
                    "chainType": "evm",
                    "data": {
                        "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
                        "chainId": "42161",
                        "type": "WrappedNative",
                        "path": [
                            "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                            "0x82af49447d8a07e3bd95bd0d56f35241523fbab1"
                        ],
                        "target": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
                        "direction": "wrap"
                    },
                    "fromChain": "42161",
                    "toChain": "42161",
                    "fromToken": {
                        "type": "evm",
                        "chainId": "42161",
                        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
                        "name": "Ethereum",
                        "symbol": "ETH",
                        "decimals": 18,
                        "logoURI": "<https://raw.githubusercontent.com/0xsquid/assets/main/images/tokens/eth.svg>",
                        "coingeckoId": "ethereum",
                        "usdPrice": 3726.560765050724
                    },
                    "toToken": {
                        "type": "evm",
                        "chainId": "42161",
                        "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
                        "name": "Wrapped ETH",
                        "symbol": "WETH",
                        "decimals": 18,
                        "logoURI": "<https://raw.githubusercontent.com/0xsquid/assets/main/images/tokens/weth.svg>",
                        "coingeckoId": "weth",
                        "usdPrice": 3727.7391068116112
                    },
                    "fromAmount": "1000000000000000000",
                    "toAmount": "1000000000000000000",
                    "toAmountMin": "1000000000000000000",
                    "exchangeRate": "1.0",
                    "priceImpact": "0.00",
                    "stage": 0,
                    "description": "Wrap ETH to WETH"
                    
                }]}}}

v2 Example Response

//New Implementation

{
    "route": {
        "estimate": {
            "actions": [
                {
                    "type": "wrap",
                    "chainType": "evm",
                    "data": {
                        "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
                        "chainId": "42161",
                        "type": "WrappedNative",
                        "path": [
                            "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
                            "0x82af49447d8a07e3bd95bd0d56f35241523fbab1"
                        ],
                        "target": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
                        "direction": "wrap"
                    },
                    "fromChain": "42161",
                    "toChain": "42161",
                    "fromToken": {
                        "type": "evm",
                        "chainId": "42161",
                        "address": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
                        "name": "Ethereum",
                        "symbol": "ETH",
                        "decimals": 18,
                        "logoURI": "<https://raw.githubusercontent.com/0xsquid/assets/main/images/tokens/eth.svg>",
                        "coingeckoId": "ethereum",
                        "usdPrice": 3726.560765050724
                    },
                    "toToken": {
                        "type": "evm",
                        "chainId": "42161",
                        "address": "0x82af49447d8a07e3bd95bd0d56f35241523fbab1",
                        "name": "Wrapped ETH",
                        "symbol": "WETH",
                        "decimals": 18,
                        "logoURI": "<https://raw.githubusercontent.com/0xsquid/assets/main/images/tokens/weth.svg>",
                        "coingeckoId": "weth",
                        "usdPrice": 3727.7391068116112
                    },
                    "fromAmount": "1000000000000000000",
                    "toAmount": "1000000000000000000",
                    "toAmountMin": "1000000000000000000",
                    "exchangeRate": "1.0",
                    "priceImpact": "0.00",
                    "stage": 0,
                    "description": "Wrap ETH to WETH",
                    // Now contains Provider & logoURI
                    "Provider": "Provider Name",
                    "logoURI": "https://"
                }]}}}

For more examples, you can explore our Github Examples Repo. Please reach out to us if you have any questions, thank you!