API Reference

This page describes XPay methods, components and types

Methods

openTransactionModal

const openTransactionModal = async (payload: ModalIntegrationPayload): Promise<Transactions | undefined>

Description: This method opens an XPay modal for selecting tokens and communicating with the XSwap backend to get the routes and required transactions calldata to make the cross-chain transaction possible. The modal implements transaction execution by default.

For a detailed description of parameters check ModalIntegrationPayload

Example:

const transactions = await openTransactionModal({
      integratorId: "YOUR_INTEGRATOR_ID",
      dstChain: "8453", // Base
      dstToken: "0x8fe815417913a93ea99049fc0718ee1647a2a07c", // XSWAP Token
});

If needed, the modal will execute the approval for the user's tokens and send the cross-chain swap transaction. For a more detailed example please check the example project on Github

Components

TxWidget

The TxWidget component offers the same swap functionality as openTransactionModal but is embedded directly into your website as a widget without opening a modal. It’s ideal for seamless integration of cross-chain swaps on your site.

<TxWidget
  integratorId="YOUR_INTEGRATOR_ID"
  dstChain="8453"
  dstToken="0x8fe815417913a93ea99049fc0718ee1647a2a07c"
  lightTheme={true}
  defaultWalletPicker={true}
/>

Parameters: The parameters are very similar to openTransactionModal, they utilize WidgetIntegrationPayload type

Usage of TxWidget as a Web Component

In addition to the React-based example, the TxWidget can also be embedded into any HTML page by including it as a web component using a simple <script> tag. This method is ideal for projects that are not using React or any other JavaScript framework and just need to add cross-chain swap functionality to their website.

Including the widget script

To include the widget as a web component, make sure to load the script using the following URL:

<script src="https://unpkg.com/@xswap-link/sdk"></script>

HTML Example

Here’s an example of how to use the TxWidget as a web component within a plain HTML page:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>XPay Widget Example</title>
  <script src="https://unpkg.com/@xswap-link/sdk"></script>
</head>
<body>
  <h1>XPay Cross-Chain Swap</h1>
  <xpay-widget
    integrator-id="YOUR_INTEGRATOR_ID"
    dst-chain="8453"
    dst-token="0x8fe815417913a93ea99049fc0718ee1647a2a07c"
  ></xpay-widget>
</body>
</html>

NOTE: All parameter names passed to the web component widget must be in the kebab-case format, as shown in the examples above.

Types

ModalIntegrationPayload

type ModalIntegrationPayload = {
  integratorId: string;
  dstChain: string;
  dstToken: string;
  srcChain?: string;
  srcToken?: string;
  customContractCalls?: ContractCall[];
  desc?: string;
  dstDisplayToken?: string;
  lightTheme?: boolean;
  defaultWalletPicker?: boolean;
  styles: ModalIntegrationStyles
};

Properties:

  • integratorId (string): The ID of the integrator using the SDK. Apply Here

  • dstChain (string, optional): The destination chain ID.

  • dstToken (string, optional): The destination token address to which the user funds will be swapped.

  • srcChain (string, optional): The source chain ID where the initial token swap will occur.

  • srcToken (string, optional): The source token address that the user wishes to swap.

  • customContractCalls (ContractCall[], optional): An array of custom contract calls to be executed during the transaction on the destination chain after the swap.

  • desc (string, optional): A description of the transaction displayed for the user.

  • lightTheme (boolean, optional): If set to true, the modal will use a light theme interface.

  • defaultWalletPicker (boolean, optional): When set to true, the SDK handles connecting SDK to user's wallet. Do not use this option if your app already can be connected to wallets.

  • styles (ModalIntegrationStyles, optional): Custom styling options for the modal. These styles extend the base theme while allowing overrides for specific UI components.

ModalIntegrationStyles

type ModalIntegrationStyles = {
    mainAccentLight?: string;
    mainAccentDark?: string;
    textSecondary?: string;
    width?: string;
}

Properties:

  • mainAccentLight (string, optional): Defines the primary accent color used in the theme. This color is typically used for icons and accent backgrounds. The value should be provided in hex format. Example: "#3681C6"

  • mainAccentDark (string, optional): Supplementary accent color to create gradient color with mainAccentLight. If you prefer a single-color design, set this to the same value as mainAccentLight. The value should be provided in hex format. Example: "#2B4A9D"

  • textSecondary (string, optional): The color used for secondary text elements. It is recommended to align this color with mainAccentLight for visual consistency. The value should be provided in hex format. Example: "#3681C6"

  • width (string, optional) : Sets the width of the modal, allowing for responsive or fixed-width designs. The value should be a valid CSS width string. Example: "400px"

WidgetIntegrationPayload

type ModalIntegrationPayload = {
  integratorId: string;
  dstChain: string;
  dstToken: string;
  srcChain?: string;
  srcToken?: string;
  customContractCalls?: ContractCall[];
  desc?: string;
  dstDisplayToken?: string;
  lightTheme?: boolean;
  defaultWalletPicker?: boolean;
  styles?: string;
};

Properties:

  • integratorId (string): The ID of the integrator using the SDK. Apply Here

  • dstChain (string, optional): The destination chain ID.

  • dstToken (string, optional): The destination token address to which the user funds will be swapped.

  • srcChain (string, optional): The source chain ID where the initial token swap will occur.

  • srcToken (string, optional): The source token address that the user wishes to swap.

  • customContractCalls (ContractCall[], optional): An array of custom contract calls to be executed during the transaction on the destination chain after the swap.

  • desc (string, optional): A description of the transaction displayed for the user.

  • lightTheme (boolean, optional): If set to true, the modal will use a light theme interface.

  • defaultWalletPicker (boolean, optional): When set to true, the SDK handles connecting SDK to user's wallet. Do not use this option if your app already can be connected to wallets.

  • styles (string, optional): Custom styling options for the modal, provided as JSON string. These styles extend the base theme while allowing overrides for specific UI components. The structure of the styles should follow the same format as the ModalIntegrationStyles type. You must pass the styles as a stringified object using JSON.stringify(). Example usage:

    styles={JSON.stringify({
      mainAccentLight: '#ff69b4',
    })}

Last updated