Aggregator Widget
The @minswap/aggregator-widget
is for token swapping at the best prices across all Cardano DEXes.
Installation
React Setup
npm install @minswap/aggregator-widget
or
yarn add @minswap/aggregator-widget
or
pnpm install @minswap/aggregator-widget
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>
Basic Usage
import { Widget } from "@minswap/aggregator-widget";
function App() {
return <Widget partnerCode="your-partner-code" displayMode="full" />;
}
Props
Here's a quick overview of all available props:
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:
wallet
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:type WalletApi = Pick< Cip30WalletApi, "getUnusedAddresses" | "getUsedAddresses" | "signTx" > & { id: string; };
Where:
getUnusedAddresses
: Function to get unused addresses from the walletgetUsedAddresses
: Function to get previously used addresses from the walletsignTx
: Function to sign transactionsid
: A unique identifier for the wallet instance. This is crucial for wallet updates within the Widget.
The interface follows the CIP-30 Cardano Wallet Standard, which is the standard specification for Cardano wallet integration.
partnerCode
partnerCode
Type:
string
Optional: Yes
Description: A unique code that identifies the partner integrating the widget. To obtain your
partnerCode
:Visit minswap.org/partners
Create a new application
Get your unique partner code from the dashboard
Use this code in the widget integration
The
partnerCode
enables tracking of your application's usage, revenue sharing, and other partnership benefits.
defaultAsset
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:
// For MIN token const minToken = "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e"; // policyId + "MIN" in hex
Important: ADA (lovelace) cannot be used as a
defaultAsset
. You must specify a native token.
selectableAssets
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:
const assets = [ "29d222ce763455e3d7a09a665ce554f00ac89d2e99a1a83d267170c64d494e", // MIN token "af65a4734e8a22f43128913567566d2dde30d3b3298306d6317570f60014df104d494e20496e7465726e", // Minswap Intern token ];
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
allowedProtocols
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:
type Protocol = | "MinswapV2" | "Minswap" | "MinswapStable" | "MuesliSwap" | "Splash" | "SundaeSwapV3" | "SundaeSwap" | "VyFinance" | "WingRidersV2" | "WingRiders" | "WingRidersStableV2" | "Spectrum" | "SplashStable";
Example:
const protocols = ["MuesliSwap", "SundaeSwap", "VyFinance"];
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
displayMode
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
trigger
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.
Examples
Basic Usage with Full Display Mode
import { Widget } from "@minswap/aggregator-widget";
function SwapInterface() {
return <Widget partnerCode="your-partner-code" displayMode="full" />;
}
Custom Button Trigger
import { Widget } from "@minswap/aggregator-widget";
function SwapButton() {
return (
<Widget
partnerCode="your-partner-code"
displayMode="button"
trigger={<button className="custom-button">Open Swap</button>}
/>
);
}
Theming Customization
The widget supports two methods of theme customization: preset themes and custom CSS variables.
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:
<html data-ms-theme="<preset-theme-here>">
<!-- Your content -->
</html>
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:
:root {
/* Primary interaction tone */
--ms-itr-tone-pri: #c4e1bc;
/* Highlight tone */
--ms-itr-tone-hl: #4c7f3a;
/* Subtle tone */
--ms-itr-tone-sub: #2f5025;
/* Border highlight default */
--ms-bd-hl-df: #2f5025;
/* Secondary interaction tent default and subtle */
--ms-itr-tentSec-df: #2f5025;
--ms-itr-tentSec-sub: #2f5025;
}
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:
<head>
<!-- Other stylesheets and meta tags -->
...
<!-- Your custom theme should be last to ensure it overrides default styles -->
<link rel="stylesheet" href="your-custom-theme.css">
</head>
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:
Open your browser's DevTools
Inspect any element within the widget
Look for
:root
or elements with--ms-
prefixed CSS variablesOverride any of these variables in your custom CSS file to achieve your desired styling
Last updated
Was this helpful?