API Reference

This page describes XPay methods, components and types

Components

TxWidget

The TxWidget component offers the swap functionality 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"
  defaultWalletPicker={true}
/>

Parameters: for the full list of properties check the WidgetIntegrationPayload

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.

Methods

openTransactionModal

const openTransactionModal = async (payload: ModalIntegrationPayload): Promise<void>

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

Types

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;
  dstTokenLocked?: boolean;
  dstChainLocked?: boolean;
  srcTokenLocked?: boolean;
  srcChainLocked?: boolean;
  bridge?: boolean;
  integratorFee?: number;
  integratorFeeReceiverAddress?: 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',
})}
```
dstTokenLocked(boolean, optional): If true, the destination token cannot be changed.
dstChainLocked(boolean, optional): If true, the destination chain cannot be changed.
srcTokenLocked(boolean, optional): If true, the source token cannot be changed.
srcChainLocked(boolean, optional): If true, the source chain cannot be changed.
bridge (boolean, optional): If true, enables bridge UI and enforces the bridge rules.
integratorFee (number, optional): Fee percentage for the integrator in a range from 1 to 1000 where the max value of 1000 represents 1% fee.
integratorFeeReceiverAddress (string, optional): Address to receive the integrator fee.

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;
  dstTokenLocked?: boolean;
  dstChainLocked?: boolean;
  srcTokenLocked?: boolean;
  srcChainLocked?: boolean;
  bridge?: boolean;
  integratorFee?: number;
  integratorFeeReceiverAddress?: 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 (ModalIntegrationStyles, optional): Custom styling options for the modal. These styles extend the base theme while allowing overrides for specific UI components.
dstChainLocked(boolean, optional): If true, the destination chain cannot be changed.
srcTokenLocked(boolean, optional): If true, the source token cannot be changed.
srcChainLocked(boolean, optional): If true, the source chain cannot be changed.
bridge (boolean, optional): If true, enables bridge UI and enforces the bridge rules.
integratorFee (number, optional): Fee percentage for the integrator in a range from 1 to 1000 where the max value of 1000 represents 1% fee.
integratorFeeReceiverAddress (string, optional): Address to receive the integrator fee.

ModalIntegrationStyles

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