Make sure to update the OKX App to version 6.90.1 or later to start accessing:
To integrate OKX Connect into your DApp, you can use npm:
``
npm install @okxconnect/ui
`
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;${string}://${string}
- tmaReturnUrl -string'back' |'none' | ; 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
`typescript
import { OKXUniversalConnectUI } from "@okxconnect/ui";
const universalUi = await OKXUniversalConnectUI.init({
DAppMetaData: {
icon: "https://static.okx.com/cdn/assets/imgs/247/58E63FEA47A2B7D7.png",
name: "OKX Connect Demo"
},
actionsConfiguration: {
returnStrategy:'tg://resolve',
modals:'all',
tmaReturnUrl:'back'
},
language: "en_US",
uiPreferences: {
theme: THEME.LIGHT
},
});
`
await universalUi.openModal(connectParams: ConnectParams);
Request Parameters
- connectParams - ConnectParams
- namespaces - [namespace: string]: ConnectNamespace; The necessary information for requesting a connection. The key for the EVM system is "eip155". If any chain in the request is not supported by a wallet, the connection will be rejected.
- chains: string[]; Chain ID information, defined as decimal numbers in EIP155, for example, Ethereum is eip155:1.
- defaultChain?: string; The default chain.
- rpcMap?: [chainId: string]: string; rpc information, configure rpc url to request rpc information on the chain, only support EVM system, the chain configured for RPC must be included in the chains;
- optionalNamespaces - [namespace: string]: ConnectNamespace; optional information for requesting connection, the key of EVM system is ‘eip155’, if the corresponding chain information is not supported by the wallet, it can still be connected; if you need to connect to a custom network, you can add the request of the custom network to this parameter, if the wallet does not support it, you can add the request of the custom network to this parameter. If you need to connect to a custom network, you can add the request for the custom network to this parameter, if the wallet already has the custom network, the information of the custom chain will be returned in the request result session; if the wallet doesn't support it, and there is no information of the custom chain in the request result session, you can add the custom chain by calling the request method again, with the method set to wallet_addEthereumChain. Add the custom chain.
- chains: string[]; chain id information, rpcMap?
- rpcMap?: [chainId: string]: string; rpc information, configure rpc url to request rpc information on the chain, only support EVM system, the chain configured with RPC must be included in the chains;
Return value
- Promise
- topic: string; the session identifier;
- namespaces: ; 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;
- defaultChain?: string; The default chain for the current session.
- sessionConfig?: SessionConfig
- DAppInfo: object DApp information;
- name:string
- Info: object DApp info; name:string
Example
`typescript`
var session = await universalUi.openModal({
namespaces: {
eip155: {
// Please pass in as many chain ids as you need.
chains: ["eip155:1","eip155:137"],
defaultChain: "1",
rpcMap: {
"137":"https://polygon.drpc.org"
}
}
},
optionalNamespaces: {
eip155: {
chains: ["eip155:43114"]
}
}
})
Connect to the wallet to get the wallet address and sign the data; the result will be called back in the event ‘connect_signResponse’;
`
await universalUi.openModalAndSign(connectParams: ConnectParams,signRequest: RequestParams[]);
Request parameters
- connectParams - ConnectParams
- namespaces - [namespace: string]: ConnectNamespace ; Necessary information for requesting a connection, the EVM system key 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, decimal number defined in EIP155, e.g. ether is eip155:1, defaultChain?
- defaultChain?: string; default chain
- rpcMap?: [chainId: string]: string; rpc information, configure rpc url to request rpc information on the chain, only support EVM system, the chain configured for RPC must be included in the chains;
- optionalNamespaces - [namespace: string]: ConnectNamespace; optional information for requesting connection, the key of EVM system is ‘eip155’, if the corresponding chain information is not supported by the wallet, it can still be connected; if you need to connect to a custom network, you can add the request of the custom network to this parameter, if the wallet does not support it, you can add the request of the custom network to this parameter. If you need to connect to a custom network, you can add the request for the custom network to this parameter, if the wallet already has the custom network, the information of the custom chain will be returned in the request result session; if the wallet doesn't support it, and there is no information of the custom chain in the request result session, you can add the custom chain by calling the request method again, with the method set to wallet_addEthereumChain. Add the custom chain.
- chains: string[]; chain id information, rpcMap?
- rpcMap?: [chainId: string]: string; rpc information, configure rpc url to request rpc information on the chain, only support EVM system, configure RPC chain must be included in chains;
- signRequest - RequestParams[]; the method to request the connection and sign, only up to one method is supported at a time;
- method: string; the name of the requested method, EVM systems support methods such as ‘personal_sign’;
- chainId: string; the ID of the chain in which the method is executed, this chainId must be included in the namespaces above;
- params: unknown[] | Record | object | undefined; Parameters for the requested method;
Return Value
- Promise
- topic: string; The session identifier;
- namespaces: ; 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 in the current namespace;
- defaultChain?: string; The default chain for the current session.
- sessionConfig?: SessionConfig
- dappInfo: object DApp information;
- name: string
- icon:string
Example
`typescript`
// Add the signature result listener first
universalUi.on("connect_signResponse", (signResponse) => {
console.log(signResponse);
});
var session = await universalUi.openModalAndSign({
namespaces: {
eip155: {
// Please pass in as many chain ids as you need, more than one for more than one chain.
chains: ["eip155:1","eip155:137"],
defaultChain: "1",
rpcMap: {
"137":"https://polygon.drpc.org"
}
}
},
optionalNamespaces: {
eip155: {
chains: ["eip155:43114"]
}
},
sessionConfig: {
redirect: "tg://resolve"
}
},[{
method: "personal_sign",
chainId: "eip155:1",
params: [
"0x4d7920656d61696c206973206a6f686e40646f652e636f6d202d2031373237353937343537313336",
],
}])
Gets whether the wallet is currently connected.
Return Value
- boolean
Example
`typescript`
universalUi.connected();
Methods for sending messages to the wallet, supporting signatures, transactions.
`
universalUi.request(requestArguments, chain, actionConfigurationRequest);
requestArguments
- requestArguments - object
- method: string; the name of the requested method.
- params?: unknown[] | Record | object | undefined; The parameters corresponding to the requested method;${string}://${string}
- returnStrategy -string'none’ | ; The return strategy for the deep link in the App wallet when the user signs or rejects the request, if it is a Mini App in Telegram, it can be configured with tg://resolve, and if it's not configured here, the will take the returnStrategy passed by the init method, default is'none’${string}://${string}
- 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' | ; 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
`typescript
let chain ='eip155:1'
var data = {}
data = {
"method": "personal_sign",
"params": [
"0x506c65617365207369676e2074686973206d65737361676520746f20636f6e6669726d20796f7572206964656e746974792e",
"0x4B0897b0513FdBeEc7C469D9aF4fA6C0752aBea7"
]
}
var personalSignResult = await universalUi.request(data, chain,'all')
//personalSignResult: 0xe8d34297c33a61"
`Using RPC
When EVM request method can not meet the demand, you can configure RPC to achieve more functions, in the connection wallet openModal or openModalAndSign, RPC configuration in the rpcMap.
**Example
`typescript`
//Query the details of the transaction hash
let rpcData = {
method: "eth_getTransactionByHash",
params: ["0xd62fa4ea3cf7ee3bf6f5302b764490730186ed6a567c283517e8cb3c36142e1a"],
};
let result = await universalUi.request(rpcData,"eip155:137")
Example
`typescript`
universalUi.closeModal();
Example
`typescript`
const unsubscribe = universalUi.onModalStateChange((state)=>{
})
Remove the monitor when it's not needed typescript const unsubscribe = universalUi.onModalStateChange(state) => { }`
unsubscribe()
Get information about whether there is a currently connected wallet, and the connected wallets;
Example
` typescript`
universalUi.session.
Example
`typescript`
universalUi.uiOptions = {
language:'zh_CN',
uiPreferences: {
theme: THEME.DARK
}
};
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)'
Example
`typescript`
universalUi.setDefaultChain('eip155:1')
Example
`typescript`
universalUi.disconnect();
`typescript
// Generate universalLink
universalUi.on("display_uri", (uri) => {
console.log(uri);
}).
// Session information changes (e.g. adding a custom chain) will trigger this event;
universalUi.on("session_update", (session) => {
console.log(JSON.stringify(session));
});
// Disconnecting triggers this event;
universalUi.on("session_delete", ({topic}) => {
console.log(topic);
});
// This event is triggered when a connection is made and the signature is signed.
universalUi.on("connect_signResponse", (signResponse) => {
console.log(signResponse);
});
// This event is triggered when connected to OKX Extension wallet and switch wallet
universalUi.on("accountChanged", (session) => {
if (session){
console.log(accountChanged , JSON.stringify(session));
}
});
`
Exceptions that may be thrown during connection, transaction, and disconnection.
Exception
| Error Code | Description |
|----------------------------------------------|-------------------------|
| OKX_CONNECT_ERROR_CODES.UNKNOWN_ERROR | Unknown Error |
| OKX_CONNECT_ERROR_CODES.ALREADY_CONNECTED_ERROR | Wallet Already Connected |
| OKX_CONNECT_ERROR_CODES.NOT_CONNECTED_ERROR | Wallet Not Connected |
| OKX_CONNECT_ERROR_CODES.USER_REJECTS_ERROR | User Rejected |
| OKX_CONNECT_ERROR_CODES.METHOD_NOT_SUPPORTED | Method Not Supported |
| OKX_CONNECT_ERROR_CODES.CHAIN_NOT_SUPPORTED | Chain Not Supported |
| OKX_CONNECT_ERROR_CODES.WALLET_NOT_SUPPORTED | Wallet Not Supported |
| OKX_CONNECT_ERROR_CODES.CONNECTION_ERROR | Connection Error |
`typescript``
export enum OKX_CONNECT_ERROR_CODES {
UNKNOWN_ERROR = 0,
ALREADY_CONNECTED_ERROR = 11,
NOT_CONNECTED_ERROR = 12,
USER_REJECTS_ERROR = 300,
METHOD_NOT_SUPPORTED = 400,
CHAIN_NOT_SUPPORTED = 500,
WALLET_NOT_SUPPORTED = 600,
CONNECTION_ERROR = 700
}