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.

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;
};