Integrate the powerful OKX Widget into your product! With this widget, you can create an effective trading interface within 30 minutes.
yarn add @okxweb3/dex-widget
// or
npm install @okxweb3/dex-widget
// or
pnpm add @okxweb3/dex-widget
Here is an example which shows how to use @okxweb3/dex-widget in a React project. You can find more examples through this link.
Demo:https://okx.github.io/dex-widget/
import React, { useRef, useEffect } from 'react';
import ReactDOM from 'react-dom/client';
import { createOkxSwapWidget } from '@okxweb3/dex-widget';
function App() {
const widgetRef = useRef();
useEffect(() => {
const params = {
width: 375,
providerType: 'EVM',
};
const provider = window.ethereum;
const listeners = [
{
event: 'ON_CONNECT_WALLET',
handler: () => {
provider.enable();
},
},
];
const instance = createOkxSwapWidget(widgetRef.current, {
params,
provider,
listeners,
});
return () => {
instance.destroy();
};
}, []);
return <div ref={widgetRef} />;
}
const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
<React.StrictMode>
<App />
</React.StrictMode>
);
You should pass the wallet provider information from your application if you want to connect a wallet. Then add the ON_CONNECT_WALLET event to seamlessly use the widget as part of your application.
import { createOkxSwapWidget, ProviderType } from '@okxweb3/dex-widget';
const widgetEthInstance = createOkxSwapWidget(
document.getElementById('widget'),
{
params: {
providerType: ProviderType.EVM,
},
provider: window.ethereum, // e.g. window.okexchain
}
);
const widgetSolanaInstance = createOkxSwapWidget(
document.getElementById('widget'),
{
params: {
providerType: ProviderType.SOLANA,
},
provider: window.solana, // window.okexchain.solana
}
);
You can check out this link。 for an example of using the Rainbow kit to connect to a wallet.
The following sheet contains the descriptions of the params.
Parameter | Type | Default | Description |
---|---|---|---|
width | number | 450 | The width of the widget in css values (px). If the width is not set, the display style for the width will be: 450px when the screen width > 767px. 100% when the screen width < 768px. 375px when the screen width < 375px. |
theme | THEME | light | The swap widget provides a default light theme and a dark theme as options. You can change the theme of the widget by following the example below. |
lang | string | en_us | The widget language is adjustable. Check the Multilanguage section for more details. |
tradeType | TradeType | auto | The type of transaction. It can be “swap”, “bridge”, or “auto”.Note: “Auto” includes “swap” and “bridge”. |
chainIds | Array<string> | [] | The ID of the blockchain on which the single-chain swap will take place. Check the ChainId config section for all the networks that you can choose from. |
feeConfig | IFeeConfig | {} | You can enable a fee for all transactions in the widget. Check the Fee customization section for more details. |
tokenPair | ITokenPair | {} | In the case when you want to use tokens that are included in the default token lists, Check tokenPair config section for more details. |
providerType | ProviderType | ' ' | ProviderType represents the type of the provider and corresponds to it one-to-one. For example, if the provider is Solana, then the providerType would be SOLANA. |
interface IFeeConfig {
[key: string]: {
feePercent?: string | number;
referrerAddress?: {
[key: string]: {
feePercent: string | number;
};
};
};
}
interface ITokenPair {
fromChain: string | number;
toChain: string | number;
fromToken?: string;
toToken?: string;
}
enum ProviderType {
EVM = 'EVM',
SOLANA = 'SOLANA',
WALLET_CONNECT = 'WALLET_CONNECT',
}
enum TradeType {
SWAP = 'swap',
BRIDGE = 'bridge',
AUTO = 'auto',
}
enum THEME {
LIGHT = 'light',
DARK = 'dark',
}
lang | Description |
---|---|
en_us | English,Default |
zh_cn | 简体中文 |
zh_tw | 繁體中文 |
fr_fr | Français (Afrique) |
id_id | Bahasa Indonesia |
ru_ru | Русский |
tr_tr | Türkçe |
vi_vn | Tiếng Việt |
de_de | Deutsch |
it_it | Italiano |
pl_pl | Polski |
pt_pt | Português (Portugal) |
es_es | Español (España) |
pt_br | Português (Brasil) |
es_419 | Español (Latinoamérica) |
cs_cz | Čeština |
ro_ro | Română |
uk_ua | Українська |
ar_eh | العربية |
nl_nl | Nederlands |
Network | ChainId | Native token contract |
---|---|---|
Ethereum | 1 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
zkSync Era | 324 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Optimism | 10 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Polygon | 137 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Avalanche C | 43114 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Arbitrum | 42161 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Linea | 59144 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Base | 8453 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Mantle | 5000 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Scroll | 534352 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
X layer | 196 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Blast | 81457 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
BNB Chain | 56 | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE |
Solana | 501 | 11111111111111111111111111111111 |
If this isn’t configured, for single-chain swaps, the default network is set to Ethereum, with ETH as the fromToken and USDC as the toToken; For cross-chain swaps, the default bridge is from Ethereum to BNB Chain, with ETH as the fromToken and BNB as the toToken.
import React, { useEffect, useRef } from 'react';
import {
OkxSwapWidgetParams,
ProviderType,
TradeType,
} from '@okxweb3/dex-widget';
const provider = window.ethereum;
export function EvmWidget() {
const widgetRef = useRef();
const params = {
chainIds: ['1', '10'],
lang: 'zh_cn',
providerType: ProviderType.EVM,
theme: 'dark',
tradeType: TradeType.SWAP,
tokenPair: {
fromChain: 1, //ETH
toChain: 1, // ETH
fromToken: '0xdac17f958d2ee523a2206206994597c13d831ec7', // USDT
toToken: '0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee', // ETH
},
};
const initialConfig = {
params,
provider,
listeners: [
{
event: 'ON_CONNECT_WALLET',
handler: (token, preToken) => {
provider.enable();
},
},
],
};
useEffect(() => {
const widgetHandler = createOkxSwapWidget(widgetRef.current, initialConfig);
return () => {
widgetHandler?.destroy();
};
}, []);
return <div ref={widgetRef} />;
}
Parameter | Type | Default | Description |
---|---|---|---|
fromChain | String | 1 | The ID of the source network that the fromToken belongs to (e.g., 1: Ethereum. Check ChainId config for a full list of the supported networks and the corresponding chain IDs). |
fromToken | String | 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE | The contract address of the token to be sold. E.g., ETH: 0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE. If the fromToken is a blockchain’s native token, check the chain ID to get the contract address. |
toChain | String | 1 | The ID of the destination network that the toToken belongs to (e.g., 1: Ethereum. Check ChainId config for a full list of the supported networks and the corresponding chain IDs). |
toToken | String | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 | "The contract address of a token to be bought. E.g., USDC: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48. If the toToken is a blockchain’s native token, check the chain ID to get the contract address." |
You may enable feeConfig to collect fees on the transactions executed by your users on different networks through the widget by adding the following parameters:
You need to declare the chainId, feePercent, and referrerAddress.
For Ethereum or other EVM networks, you can set the feePercent and the referrerAddress to receive the fees.
For Solana, SOL and SPL-token commissions are different. SOL commissions use wallet addresses, and SPL-token commissions use token accounts.
You can adjust the fee rate of the commission received by the referrerAddress by adding feePercent:
// EVM feeConfig example
feeConfig: {
[chainId]: {
referrerAddress: 'xxx',
feePercent: [0-3],
}
}
// Solana feeConfig example
feeConfig: {
[chainId]: {
feePercent: [0-3],
referrerAddress: {
[tokenContractA]: {
referrerAccount: 'account/abc',
feePercent: '1',
},
[tokenContractB]: {
referrerAccount: 'account/abc',
feePercent: '2',
}
}
}
}
// Full Example
feeConfig: {
1: {// Ethereum chainId
feePercent: 3, // The percentage of Fee
referrerAddress: '0x38a3b108eb2b97c307bf5788909f8c12afd0cd6b', // eth address that receives the fee
},
56: { // Bnb Chain chainId
feePercent: 3, //
referrerAddress: '0x38a3b108eb2b97c307bf5788909f8c12afd0cd6b', // bnb address that receives the fee
},
501: { // solana chainId
referrerAddress: {
'11111111111111111111111111111111': { //solana SOL contract address
account: '6rocMMKG1DNg93RDfVL2xVdrA5nbAT8cFMbdvVTHUF4m',
feePercent: 1,
},
EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v: { //solana USDC contract address
account: 'C6XW7mFvCuVxYFTi9zTQrUcwkvhfGYAvuosXz6pLDZsa', //solana USDC token account that receives the fee
feePercent: 1,
},
JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN: { //solana JUP contract address
account: 'Ezq6jTC3CwnsXDSdtgy8Sa4xi1iA6fxuEeXxWFPLG9sc', //solana JUP token account that receives the fee
feePercent: 1,
},
},
},
8453: {
feePercent: 3,
referrerAddress: '0x38a3b108eb2b97c307bf5788909f8c12afd0cd6b',
},
}
The percentage of fromTokenAmount that will be sent to the referrer’s address. The rest of the token amount will be set as the input amount to be sold. The fee rate is in basis points (BPS). One basis point is equivalent to 0.01% (1/100th of a percent). The fee rate can’t exceed 3% (300 BPS).
The referrerAddress is the address that receives the fee.
Make sure that the fee recipient address exists on its respective network as defined in the parameters sheet.
Updateable attributes: theme, lang, width
// 1. Create and initialize the widget
const widgetHandler = createOkxSwapWidget(container, initialConfig);
// 2. Update the widget's parameters (e.g., change theme or size)
widgetHandler.updateParams({
width: 700,
theme: 'light',
lang: 'tr_tr',
});
The widget supports EVM and Solana. When switching from EVM to Solana, remember to update the corresponding widget’s provider, and vice versa.
If you don’t pass in provider information for the first rendering and want the widget to respond to a wallet connection, you need to call updateProvider.
// 3. Update the provider if the user connects a different wallet, EVM => SOLANA
widgetHandler.updateProvider(window.solana, ProviderType.SOLANA);
// SOLANA => EVM
// widgetHandler.updateProvider(window.ethereum, ProviderType.EVM);
You can update the events that the widget listens to.
// 4. Modify event listeners to handle new types of events
widgetHandler.updateListeners([
{
event: OkxEvents.ON_FROM_CHAIN_CHANGE,
handler: (payload) => {
//
},
},
]);
Call this method when removing the widget module.
const widgetHandler = createOkxSwapWidget(container, initialConfig);
widgetHandler.destory();
Widget provides event listeners for ON_CONNECT_WALLET and ON_FROM_CHAIN_CHANGE.
Here’s how to use them:
import {createOkxSwapWidget, OkxSwapWidgetParams, OkxEventListeners, OkxEvents} from '@cowprotocol/widget-lib'
const params: OkxSwapWidgetParams = {
// ...
}
const listeners: OkxEventListeners = [
{
event: OkxEvents.ON_CONNECT_WALLET,
handler: () => {
// open connect wallet method, eg openConnectModal of the rainbow kit.
window.ethereum.enable()
}
},
{
event: OkxEvents.ON_FROM_CHAIN_CHANGE,
handler: (token) => {
//
}
},
]
const { updateListeners } = createCowSwapWidget(container, { params, listeners, provider })