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

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

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 [email protected]

Change /route from GET to POST

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

Our SDK handles this behind the scenes. No changes needed


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


// 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

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


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

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!

Last updated 8 months ago

Overview of Breaking Changes

New SDK Version

New Widget Version

Base URLs

Route Request Endpoint

Status Endpoint

Ethers version (Squid SDK integrations only)

Change /route from GET to POST

Importing types

integrator-id is required on all requests in v2

V2 Parameters

API Migration

Route Request

Status Check

API Parameter Changes

API Response Handling

SDK Migration

SDK Initialization

Get Route

Execute Route

Check Status

Hook, Previously customContractCalls, Implementation (API and SDK)

PreHook Example

PostHook Example

Breaking Changes: Details And Examples

Request Params Modification Example for API

Hook Implementations

Modified Hook Implementation API

Response Shape Change Example

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

`integrator-id` is required on all requests in v2