UI#

In addition to SDK, we also provide a UI interface. If using the UI connection, and the DApp is operating in Telegram, users can choose to open the mobile App Wallet or stay in Telegram and launch the OKX Mini Wallet.

Install via npm#

npm install @okxconnect/ui

Initialisation#

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

OKXUniversalConnectUI.init(dappMetaData, actionsConfiguration, uiPreferences, language, restoreConnection)

Request parameters

• dappMetaData - 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.
• actionsConfiguration - object
  • modals - (‘before’ | ‘success’ | ‘error’)[] | ‘all’ The modes of displaying alerts during transaction, defaults to ‘before’.
  • returnStrategy -string ‘none’ | ${string}://${string}; For app wallet, specify the return strategy for the deep link when the user signs/rejects the request, or configure tg://resolve if it's in tg;
  • tmaReturnUrl -string ‘back’ | ‘none’ | ${string}://${string}; for Telegram Mini Wallet, specify the return policy for the deep link when the user signs/rejects the request, generally configure back, which means that after signing and closing the wallet, it will automatically display the dapp; none means no processing after signing; the default is back;
• uiPreferences -object
  • theme - Theme can be: THEME.DARK, THEME.LIGHT, ‘SYSTEM’.
• language - ‘en_US’ | ‘ru_RU’ | ‘zh_CN’ | ‘ar_AE’ | ‘cs_CZ’ | ‘de_DE’ | ‘es_ES’ | ‘es_LAT’ | ‘fr_FR’ | ‘id_ID’ | ‘it_IT’ | ‘nl_NL’ | ‘pl_PL’ | ‘pt_BR’ | ‘pt_PT’ | ‘ro_RO’ | ‘tr_TR’ | ‘uk_UA’ | ‘vi_VN’. , defaults to en_US
• restoreConnection?: boolean - Whether to automatically restore the previous connection;

Return Value.

• OKXUniversalConnectUI

Examples

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

const universalUi = await OKXUniversalConnectUI.init({
  dappMetaData: {
    icon: "https://static.okx.com/cdn/assets/imgs/247/58E63FEA47A2B7D7.png",
    name: "OKX WalletConnect UI Demo"
  },
  actionsConfiguration: {
    returnStrategy: 'tg://resolve',
    modals:"all",
    tmaReturnUrl:'back'
  },
  language: "en_US",
  uiPreferences: {
    theme: THEME.LIGHT
  },
});

Connecting to a wallet#

Connecting to a wallet goes to get the wallet address as an identifier and the necessary parameters used to sign the transaction, the

await universalUi.openModal(connectParams: ConnectParams);

Request Parameters

• connectParams - ConnectParams
  • namespaces - [namespace: string]: ConnectNamespace ; necessary information for the requested connection, the key for EVM system is ‘eip155’. If any of the requested chains are not supported by the wallet, the wallet will reject the connection;
    • chains: string[]; chain id information, the chain's key is ‘eip155’.
    • rpcMap?: [chainId: string]: string; rpc information, configure the rpc url to request rpc information on the chain;
    • defaultChain?: string; default chain
  • optionalNamespaces - [namespace: string]: ConnectNamespace; optional information for requesting connection, the key for EVM system is ‘eip155’. If the corresponding chain information is not supported by the wallet, the connection can still be made;
    • chains: string[]; chain id information, if the corresponding chain is not supported by the wallet, it can still be connected.
      • rpcMap?: [chainId: string]: string; rpc info;
      • defaultChain?: string; default chain
  • sessionConfig: object
    • redirect: string Jump parameter after successful connection, if it is Mini App in Telegram, here can be set to Telegram's deeplink: ‘tg://resolve’

Return value

• Promise <SessionTypes.Struct | undefined>
  • topic: string; the session identifier;
  • namespaces: Record<string, Namespace>; namespace information for a successful connection;
    • chains: string[]; Chain information for the connection;
    • accounts: string[]; accounts information for the connection;
    • methods: string[]; methods supported by the wallet under the current namespace;
    • rpcMap?: [chainId: string]: string; rpc info;
    • defaultChain?: string; The default chain for the current session.
  • sessionConfig?: SessionConfig
    • dappInfo: object DApp information;
      • name:string
      • dappInfo: object DApp info; name:string

Example

var session = await universalUi.openModal({
  namespaces: {
    eip155: {
      chains: ["eip155:1", "eip155:xxx"],
      rpcMap: {
        1: "https://rpc" // set your own rpc url
      },
      defaultChain: "1"
    }
  },
  optionalNamespaces: {
    eip155: {
      chains: ["eip155:43114"]
    }
  }
})

Send signatures and transactions#

Methods for sending messages to the wallet, supporting signatures, transactions, rpc requests.

universalUi.request(requestArguments, chain, actionConfigurationRequest);

requestArguments

• requestArguments - object
  • method: string; the name of the requested method.
  • params?: unknown[] | Record<string, unknown> | object | undefined; The parameters corresponding to the requested method;
• chain: string; the chain in which the requested method will be executed, it is recommended to pass this parameter, if not it will be set to the current defaultChain;
• actionConfigurationRequest - object
  • modals : (‘before’ | ‘success’ | ‘error’)[] | ‘all’ The modals of the alert display during the transaction, if request does not have this parameter set, take the parameter added during init, if init does not have this parameter set as well, then take the default value: ‘before’,
  • tmaReturnUrl -string ‘back’ | ‘none’ | ${string}://${string}; Telegram Mini Wallet wallet, when the user signs/rejects the request, the deep link return strategy, generally configure back, that is to say, after signing and closing the wallet, it will show the dapp; none means that after signing and closing the wallet, it will show the dapp automatically. dapp; none means no processing after signing; default is back;

** return value **

return parameter details same as EVM-compatible chain for sending signatures and transactions

Examples

Example same EVM-compatible chain for sending signatures and transactions

let chain = 'eip155:1'
var data = {}

data = {
    "method": "personal_sign",
    "params": [
        "0x506c65617365207369676e2074686973206d65737361676520746f20636f6e6669726d20796f7572206964656e746974792e",
        "0x4B0897b0513FdBeEc7C469D9aF4fA6C0752aBea7"
    ]
}
var personalSignResult = await universalUi.request(data, chain,'all')
//personalSignResult:   0xe8d34297c33a61"

Close connection popup#

Example

universalUi.closeModal();

Get information about the currently connected session#

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

Example

universalUi.session.

Set ui configuration items#

Support to change the theme, text language setting, also can add these configurations during initialisation;

example

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

Setting the default network#

In the case of multiple networks, if the developer does not specify the network where the current operation is taking place, the interaction will take place through the default network.

‘setDefaultChain(chain, rpcUrl?)’

Example

universalUi.setDefaultChain(‘eip155:1’, ‘rpcurl’)

Disconnect the wallet#

Example

universalUi.disconnect();

Event#

// Generate universalLink  
okxUniversalProvider.on(‘display_uri’, (uri) => {
    console.log(uri);
}).
// Session information changes (e.g. adding a custom chain) will trigger this event;
okxUniversalProvider.on(‘session_update’, (session) => {
    console.log(JSON.stringify(session)); }); // Session information changes (e.g., adding a custom chain).
;
// Disconnecting triggers this event;
okxUniversalProvider.on(‘session_delete’, ({topic}) => {
    console.log(topic);
});

Error code#

Same details as EVM compatibility chain