UI#

On top of the Ton SDK, we also provide the UI interface.

Install via npm#

npm install @okxconnect/ui

Initialization#

Before connecting to a wallet, you need to create an object for subsequent operations such as connecting to the wallet and sending transactions.

new OKXTonConnectUI(metaData, buttonRootId, actionsConfiguration, uiPreferences, language, restoreConnection)

Request Parameters

• metaData - object
  • name - string: The name of the application, will not be used as a unique representation.
  • icon - string: URL of the application icon, must be in PNG, ICO, etc. SVG icons are not supported. SVG icons are not supported. It is better to pass a url pointing to a 180x180px PNG icon.
• buttonRootId - string: the HTML element ID of the button used to attach the wallet connection. if not passed, the button will not appear;.
• actionsConfiguration - object
  • modals - ('before' | 'success' | 'error')[] | 'all' The modals for displaying the alert screen during a transaction.
  • returnStrategy -string 'none' | ${string}://${string}; Specify the return strategy for deep links when the user signs/rejects the request, if in tg, configure tg://resolve
• uiPreferences -object
  • theme - Theme can be: THEME.DARK, THEME.LIGHT, “SYSTEM”
• language - 'en_US' | 'ru_RU' | 'zh-CN', currently supports English/Russian/Simplified Chinese, default is en_US
• restoreConnection?: boolean - Whether to automatically restore the previous connection;

Return Value

• OKXTonConnectUI

Example

import { OKXTonConnectUI } from "@okxconnect/ui";

const okxTonConnectUI = new OKXTonConnectUI({
    dappMetaData: {
        name: "application name",
        icon: "application icon url"
    },
    buttonRootId: 'button-root',
    actionsConfiguration:{
        returnStrategy:'none'
    },
    uiPreferences: {
        theme: THEME.LIGHT
    },
    language: 'en_US',
    restoreConnection: true
});

Connect to Wallet#

Connecting to a wallet goes to get the wallet address, which serves as the identifier and the necessary parameters used to sign the transaction. The “Connect Button” (added to buttonRootId) automatically handles the click and invokes the connection. If no buttonRootId is added, this method needs to be called.

await okxTonConnectUI.openModal();

Example

okxTonConnectUI.openModal();

Set the tonProof#

Add the connection signature parameter. If you need to set tonProof, set state:'loading', before the tonProof parameter is ready. When ready, set state to 'ready' and add value;. You can also remove the loading state by setting setConnectRequestParameters(null);

Example

okxtonConnectUI.setConnectRequestParameters({ state: 'loading' });

const tonProofPayload: string | null = await fetchTonProofPayloadFromBackend();

if (!tonProofPayload) {
  okxtonConnectUI.setConnectRequestParameters(null);
} else {
  okxtonConnectUI.setConnectRequestParameters({
    state: "ready",
    value: { tonProof: tonProofPayload }
  });
}

Close connection popup#

Example

okxTonConnectUI.closeModal();

Get the currently connected Wallet and WalletInfo#

Get information about whether there is a currently connected wallet, and the connected wallet;

Example

const currentWallet  = okxTonConnectUI.wallet;
const currentAccount = okxTonConnectUI.account;
const isConnected    = okxTonConnectUI.connected;

Disconnect#

Example

okxTonConnectUI.disconnect();

Monitor wallet state changes#

Wallet statuses are: connected successfully, reconnected successfully, disconnected, etc. You can use this method to get the status. Method details same as OKXTonConnect.onStatusChange

Example

import { Wallet } from "@okxconnect/ui";

const unsubscribe = okxTonConnectUI.onStatusChange((walletInfo: Wallet | null) => {
        console.log('Connection status:', walletInfo);
    }, (err: OKXConnectError) => {
        console.log('Connection status:', err);
    }
)
unsubscribe()

Send transaction#

Method for sending a message to a wallet:

sendTransaction(transaction, actionConfigurationRequest): Promise<SendTransactionResponse>

Request parameters

• transaction - object, parameters same as transaction of OKXTonConnect.sendTransaction

• actionConfigurationRequest - object

  • modals : ('before' | 'success' | 'error')[] | 'all' Mode of displaying the alert screen during the transaction, defaults to 'before'

Return Value

• Promise - {boc: string}: Signature Result

import { OKXConnectError, OKX_CONNECT_ERROR_CODES } from "@okxconnect/core";

let transactionRequest = {
    "validUntil": Date.now() / 1000 + 360,
    "from": "0:348bcf827469c5fc38541c77fdd91d4e347eac200f6f2d9fd62dc08885f0415f",
    "messages": [
        {
            "address": "0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F",
            "amount": "20000000",
            "stateInit": "base64bocblahblahblah==" //deploy contract
        }, 
        {
            "address": "0:E69F10CC84877ABF539F83F879291E5CA169451BA7BCE91A37A5CED3AB8080D3",
            "amount": "60000000",
            "payload": "base64bocblahblahblah==" //transfer nft to new deployed account 0:412410771DA82CBA306A55FA9E0D43C9D245E38133CB58F1457DFB8D5CD8892F
        }
    ]
}

okxTonConnectUI.sendTransaction(transactionRequest, {
    modals: 'all'
}).then((result) => {
    let boc = result.boc
}).catch((error) => {
    if (error instanceof OKXConnectError && error.code == OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR) {
        //userReject;
    } else {
        //other error;
    }
})

Setting up UI configuration items#

Support to modify the theme, text language settings, you can also add these configurations during initialization;

Example

okxTonConnectUI.uiOptions = {
  language: 'zh_CN',
  uiPreferences: {
    theme: THEME.DARK
  }
};

Listening to Events#

When the following events occur, a notification of the corresponding event will be sent, and the Dapp can add listeners as needed to handle the corresponding logic;

event

Example

import { OKX_UI_CONNECTION_AND_TRANSACTION_EVENT } from "@okxconnect/ui";

window.addEventListener(OKX_UI_CONNECTION_AND_TRANSACTION_EVENT.OKX_UI_CONNECTION_STARTED, (event) => {
    if (event instanceof CustomEvent) {
        console.log('Transaction init', event.detail);
    }
});