search

Aggregator Widget

The @minswap/aggregator-widget is for token swapping at the best prices across all Cardano DEXes.

hashtag
Installation

hashtag
React Setup

npm install @minswap/aggregator-widget

or

yarn add @minswap/aggregator-widget

or

pnpm install @minswap/aggregator-widget

hashtag
HTML Setup

You can also use the widget directly in HTML without a React build setup. Add the following to your HTML file:

<!DOCTYPE html>
<html>
  <head>
    <!-- Add this part to <head> -->
    <link
      rel="stylesheet"
      href="https://esm.sh/@minswap/aggregator-widget/dist/index.css"
    />
  </head>
  <body>
    <!-- Add this part to <body> -->
    <div id="minswap-widget"></div>
    <script type="importmap">
      {
        "imports": {
          "react": "https://esm.sh/react",
          "react-dom": "https://esm.sh/react-dom",
          "react-dom/": "https://esm.sh/react-dom/",
          "react/jsx-runtime": "https://esm.sh/react/jsx-runtime",
          "@minswap/aggregator-widget": "https://esm.sh/@minswap/aggregator-widget?external=react,react-dom"
        }
      }
    </script>
    <script type="module" src="https://esm.sh/tsx"></script>
    <script type="text/babel">
      import React from "react";
      import ReactDOMClient from "react-dom/client";
      import { Widget } from "@minswap/aggregator-widget";

      ReactDOMClient.createRoot(
        document.getElementById("minswap-widget")
      ).render(<Widget displayMode="full" partnerCode="your-partner-code" />);
    </script>
  </body>
</html>

hashtag
Basic Usage

hashtag
Props

Here's a quick overview of all available props:

Prop
Type
Required
Default
Description

wallet

WalletApi

No

-

Wallet instance for integration. If not provided, widget handles wallet connection internally

partnerCode

string

No

-

Your unique partner identification code

defaultAsset

string

No

-

Pre-selected asset (cannot be ADA)

selectableAssets

string[]

No

All assets

List of allowed assets for selection (ADA always included)

allowedProtocols

Protocol[]

No

All protocols

List of permitted DEX protocols (Minswap protocols always included)

displayMode

"button" | "full"

No

"full"

Widget display mode

trigger

ReactNode

No

-

Custom trigger element for button mode

Detailed description of each prop:

hashtag
wallet

  • Type: WalletApi

  • Optional: Yes

  • Description: An instance of WalletApi for wallet integration. This enables wallet connectivity and transaction functionality within the widget. If not provided, the widget will handle wallet connection internally with its own UI and connection flow. The WalletApi type is defined as:

    Where:

    • getUnusedAddresses: Function to get unused addresses from the wallet

    • getUsedAddresses: Function to get previously used addresses from the wallet

    • signTx: Function to sign transactions

    • id: A unique identifier for the wallet instance. This is crucial for wallet updates within the Widget.

    The interface follows the CIP-30 Cardano Wallet Standardarrow-up-right, which is the standard specification for Cardano wallet integration.

hashtag
partnerCode

  • Type: string

  • Optional: Yes

  • Description: A unique code that identifies the partner integrating the widget. To obtain your partnerCode:

    1. Visit minswap.org/partnersarrow-up-right

    2. Create a new application

    3. Get your unique partner code from the dashboard

    4. Use this code in the widget integration

    The partnerCode enables tracking of your application's usage, revenue sharing, and other partnership benefits.

hashtag
defaultAsset

  • Type: string

  • Optional: Yes

  • Description: The asset that will be pre-selected when the widget initially loads. The string must follow the format <policyId><tokenName>, where:

    • policyId: The Cardano policy ID of the token (hex string)

    • tokenName: The token name in hex format

    Example:

    Important: ADA (lovelace) cannot be used as a defaultAsset. You must specify a native token.

hashtag
selectableAssets

  • Type: string[]

  • Optional: Yes

  • Description: An array of assets that users can choose from within the widget. If not provided, all supported assets will be available. Each string in the array must follow the format <policyId><tokenName>.

    Example:

    Note:

    • For ADA (lovelace), you can use the special string "lovelace" instead of a policy ID and token name

    • ADA (lovelace) is always included in the selectable assets by default, even if not explicitly specified in the array

hashtag
allowedProtocols

  • Type: Protocol[]

  • Optional: Yes

  • Description: An array of protocol identifiers that are permitted for use in the widget. This can be used to restrict which protocols are available for swapping. Available protocols include:

    Example:

    Important Notes:

    • Minswap protocols ("Minswap", "MinswapV2", "MinswapStable") are always included in the available protocols, regardless of this setting

    • If this prop is not provided, all protocols will be available for routing

hashtag
displayMode

  • Type: "button" | "full"

  • Optional: Yes

  • Default: "full"

  • Description: Determines how the widget is displayed:

    • "button": The widget appears as a button that, when clicked, opens the full interface

    • "full": The widget is displayed in its complete form directly in the page

hashtag
trigger

  • Type: ReactNode

  • Optional: Yes

  • Description: A custom trigger element for the "button" display mode. This allows you to customize the appearance of the button that opens the widget.

hashtag
Examples

hashtag
Basic Usage with Full Display Mode

hashtag
Custom Button Trigger

hashtag
Theming Customization

The widget supports two methods of theme customization: preset themes and custom CSS variables.

hashtag
Preset Themes

We provide six predefined themes that you can use out of the box:

  • default-light

  • default-dark

  • green-light

  • green-dark

  • violet-light

  • violet-dark

To use a preset theme, add the data-ms-theme attribute to your HTML tag:

hashtag
Custom CSS Variables

For more granular control over the widget's appearance, you can override the default CSS variables. Create a CSS file with your custom variables:

Then include your CSS file in your HTML, making sure to place it at the end of the head tag to properly override the default styles:

Note: The variables shown above are just common examples. You can customize many more CSS variables than those listed. To see the complete list of available CSS variables:

  1. Open your browser's DevTools

  2. Inspect any element within the widget

  3. Look for :root or elements with --ms- prefixed CSS variables

  4. Override any of these variables in your custom CSS file to achieve your desired styling

PreviousMinswap APIsNextAggregator API

Last updated