Connect to Mobile Wallet
EVM-Compatible Chains

EVM-Compatible Chains#

EVM-compatible chains refer to blockchain networks that use Ethereum Virtual Machine (EVM) technology.

These chains share the same smart contract execution environment as Ethereum, allowing developers to easily deploy Ethereum-based applications on these networks.

This compatibility enables developers to use existing Ethereum tools and libraries, such as Solidity, Web3.js, and Truffle, to build and deploy decentralized applications (DApps).

Common EVM-compatible chains include Polygon, Avalanche, and Fantom. The emergence of these networks has enriched the blockchain ecosystem, providing users with more options while promoting the development of cross-chain interoperability.

Installation and Initialization#

Ensure you have updated to version 6.88.0 to start integration: You can integrate OKX Connect into your DApp using npm:

`npm install @okxconnect/universal-provider`

Before connecting the wallet, you need to create an object for subsequent wallet connections, transaction submissions, and other operations.

OKXUniversalProvider.init({metaData: {name, icon}})

Request Parameters

  • metaData - object
    • name - string: Application name, not unique identifier
    • icon - string: URL of the application icon. Must be in formats like PNG, ICO, etc. SVG icons are not supported. Preferably pass a URL pointing to a 180x180px PNG icon.

Return Value

  • OKXUniversalProvider

Example

import { OKXUniversalProvider } from "@okxconnect/universal-provider";

const okxUniversalProvider = await OKXUniversalProvider.init({
    dappMetaData: {
        name: "application name",
        icon: "application icon url"
    },
})

Connecting the Wallet#

Connect the wallet to obtain the wallet address, which serves as an identifier and is necessary for signing transactions.

okxUniversalProvider.connect(connectParams: ConnectParams);

Request Parameters

  • connectParams - ConnectParams
    • namespaces - [namespace: string]: ConnectNamespace; Information required for connection. The key for EVM systems is "eip155". If any chain requested is not supported by the wallet, the wallet will reject the connection.
      • chains: string[]; Chain ID information
      • rpcMap?: [chainId: string]: string; RPC information. The RPC URL must be configured to request RPC information on-chain.
      • defaultChain?: string; Default chain
    • optionalNamespaces - [namespace: string]: ConnectNamespace; Optional information for the connection. The key for EVM systems is "eip155". If any corresponding chain information is unsupported by the wallet, the connection can still be established.
      • chains: string[]; Chain ID information
      • rpcMap?: [chainId: string]: string; RPC information
      • defaultChain?: string; Default chain
    • sessionConfig: object
      • redirect: string; Redirection parameter after a successful connection. If in a Telegram Mini App, set this to the Telegram deeplink: "tg://resolve".

Return Value

  • Promise<SessionTypes.Struct | undefined>
    • topic: string; Session identifier;
    • namespaces: Record<string, Namespace>; Information on successfully connected namespaces;
      • chains: string[]; Connected chain information;
      • accounts: string[]; Connected account information;
      • methods: string[]; Wallet-supported methods under the current namespace;
      • rpcMap?: [chainId: string]: string; RPC information;
      • defaultChain?: string; Current session's default chain
    • sessionConfig?: SessionConfig
      • dappInfo: object DApp information;
        • name:string
        • icon:string
      • redirect?:string; Redirect parameter after successful connection

Example

var session = await okxUniversalProvider.connect({
    namespaces: {
        eip155: {
            chains: ["eip155:1", "eip155:66", "eip155:55"],
            rpcMap: {
                1: "https://rpc" // set your own rpc url
            },
            defaultChain: "1"
        }
    },
    optionalNamespaces: {
        eip155: {
            chains: ["eip155:43114"]
        }
    },
    sessionConfig: {
        redirect: "tg://resolve"
    }
})

Sending Signature and Transactions#

This method allows sending messages to the wallet, supporting signatures, transactions, and RPC requests.

okxUniversalProvider.request(requestArguments, chain);

Request Parameters

  • requestArguments - object
    • method: string; The name of the method to be requested.
    • params?: unknown[] | Record <string, unknown> | object | undefined; The parameters corresponding to the requested method.
  • chain: string; The chain where the request method will be executed. It is recommended to pass this parameter; if not provided, the current defaultChain will be used.

Return Values

Depending on the execution result of different methods, the return parameters vary. Refer to the following examples for specifics.

  • personal_sign

    • Promise - object
      • method: string; The requested method (personal_sign).
      • result: string; The signature result.
  • eth_signTypedData_v4

    • Promise - object
      • method: string; The requested method (eth_signTypedData_v4).
      • result: string; The signature result.
  • eth_sendTransaction

    • Promise - object
      • method: string; The requested method (eth_sendTransaction).
      • result: string; The transaction result.
  • eth_requestAccounts

    • Promise - string[]; Returns the address of the default chain ID.
  • eth_chainId

    • Promise - string; Returns the default chain ID.
  • wallet_switchEthereumChain

    • Promise - object
      • method: string; The requested method (wallet_switchEthereumChain).
      • result: string; The switched chain ID, e.g., "eip155:137".
  • wallet_addEthereumChain

    • Promise - object
      • method: string; The requested method (wallet_addEthereumChain).
      • result: string; Information of the added chain, e.g., "eip155:122:0xf2f3e73be57031114dd1f4e75c1dd87658be7f0e".
  • wallet_watchAsset

    • Promise - object
      • method: string; The requested method (wallet_watchAsset).
      • result: boolean; Whether the asset was successfully added.

Example

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

// Execute `personalSign` on the chain
data = {"method": "personal_sign", "params": {"message": "0x48656c6c6f204170704b697421"}};
var personalSignResult = await okxUniversalProvider.request(data, chain);
// personalSignResult:  
// "0xe8d34297c33a619321cef88e0f0373d13c75f66f35dc8157346d4720bb3e8071247a0cdcd155256197720a1eb1bcdc68aae333fbe6d972060ffde84833ceba151c"

// Execute `eth_signTypedData_v4` on the chain
data = {
    "method": "eth_signTypedData_v4",
    "params": {"typedDataJson": "{\"domain\":{\"name\":\"Ether Mail\",\"version\":\"1\",\"chainId\":1,\"verifyingContract\":\"0xcccccccccccccccccccccccccccccccccccccccc\"},\"message\":{\"from\":{\"name\":\"Cow\",\"wallet\":\"0xCD2a3d9F938E13CD947Ec05AbC7FE734Df8DD826\"},\"to\":{\"name\":\"Bob\",\"wallet\":\"0xbBbBBBBbbBBBbbbBbbBbbbbBBbBbbbbBbBbbBBbB\"},\"contents\":\"Hello, Bob!\"},\"primaryType\":\"Mail\",\"types\":{\"EIP712Domain\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"version\",\"type\":\"string\"},{\"name\":\"chainId\",\"type\":\"uint256\"},{\"name\":\"verifyingContract\",\"type\":\"address\"}],\"Person\":[{\"name\":\"name\",\"type\":\"string\"},{\"name\":\"wallet\",\"type\":\"address\"}],\"Mail\":[{\"name\":\"from\",\"type\":\"Person\"},{\"name\":\"to\",\"type\":\"Person\"},{\"name\":\"contents\",\"type\":\"string\"}]}}"}
};
var signTypeV4Result = await okxUniversalProvider.request(data, chain);
// signTypeV4Result:  
// "0xa8bb3c6b33a119d2d567c7632195c21988df778006082742125a591f5c633f716107883a37f7de6531a6312a5f69022135bf46fe5ab77905b62c82b3395f985e1b"

// Execute `eth_sendTransaction` on the chain
data = {
    "method": "eth_sendTransaction",
    "params": {"gasPrice": "0x17003f6530", "nonce": "0x0d30", "data": "0x", "value": "0x00", "gasLimit": "0x5208"}
};
var sendTransactionResult = await okxUniversalProvider.request(data, chain);
// {"method":"eth_sendTransaction","result":"0x1ccf2c4a3d689067fc2acac04749b3489eaa3eaaea8dfc37398edfec98fe24f4"}

// Get address information from the default chain
data = {"method": "eth_requestAccounts"};
var ethRequestAccountsResult = await okxUniversalProvider.request(data, chain);
// ethRequestAccountsResult: ["0xf2f3e73be57031114dd1f4e75c1dd87658be7f0e"]

// Get default chain information
data = {"method": "eth_chainId"};
var chainIdResult = await okxUniversalProvider.request(data, chain);
// chainIdResult: 1

// Switch chain
data = {"method": "wallet_switchEthereumChain", "params": {"chainId": "1"}};
var switchResult = await okxUniversalProvider.request(data, chain);
// {"method":"wallet_switchEthereumChain","result":"eip155:137"}

// Add a new chain
data = {
    "method": "wallet_addEthereumChain",
    "params": {
        "blockExplorerUrls": ["https://explorer.fuse.io"],
        "chainId": "0x7a",
        "chainName": "Fuse",
        "nativeCurrency": {"name": "Fuse", "symbol": "FUSE", "decimals": 18},
        "rpcUrls": ["https://rpc.fuse.io"]
    }
};
var addEthereumChainResult = await okxUniversalProvider.request(data, chain);
// addEthereumChainResult: {"requestId":"1727623372236","method":"wallet_addEthereumChain","result":"eip155:122:0xf2f3e73be57031114dd1f4e75c1dd87658be7f0e"}

// Add a new asset to the chain using `wallet_watchAsset`
data = {
    "method": "wallet_watchAsset",
    "params": {
        "type": "ERC20",
        "options": {
            "address": "0xeB51D9A39AD5EEF215dC0Bf39a8821ff804A0F01",
            "symbol": "LGNS",
            "image": "https://polygonscan.com/token/images/originlgns_32.png",
            "decimals": 9
        }
    }
};
var watchAssetResult = await okxUniversalProvider.request(data, chain);
// watchAssetResult: {"method":"wallet_watchAsset","result":"true"}

// Execute an RPC request on the chain
data = {"method": "eth_getBalance", "params": ["0x8D97689C9818892B700e27F316cc3E41e17fBeb9", "latest"]};
var getBalanceResult = await okxUniversalProvider.request(data, chain);
// getBalanceResult: "0xba862b54effa"

Set Default Network#

When multiple networks are connected and the developer doesn't explicitly specify which network to interact with, the default network will be used.

setDefaultChain(chain, rpcUrl?)

Example

okxUniversalProvider.setDefaultChain("eip155:1", "rpcurl");

Disconnect Wallet#

Disconnects the currently connected wallet and deletes the current session. If you wish to switch wallets, disconnect the current wallet first.

okxUniversalProvider.disconnect();