# Developer documentation

Introduction

MetaX injects a global API into websites visited by its users at window.okexchain to connect to MetaX.

This API specification borrows heavily from API MetaMask provided, so Web3 site developers can easily connect their dApps with the MetaX. The APIs allow websites to request users' MetaX addresses, read data from the blockchain the user is connected to, prompt the users to sign messages and transactions, and allow the website to add or switch networks.

The API this extension wallet provides includes API specified by EIP-1193 (opens new window) and API defined by MetaMask (opens new window).

# Basic usage

For any web3 applications to work, you will have to:

  1. Detect the MetaX provider (window.okexchain)
  2. Detect which network the user is connected to
  3. Get the user's MetaX accounts

You can learn how to accomplish the 2 and 3 from the code:

/**********************************************************/
/* Handle chain (network) and chainChanged (per EIP-1193) */
/**********************************************************/
// Normally, we would recommend the 'eth_chainId' RPC method, but it currently
// returns incorrectly formatted chain ID values.
let currentChainId = okexchain.chainId;
okexchain.on('chainChanged', handleChainChanged);
function handleChainChanged(_chainId) {
  // We recommend reloading the page, unless you must do otherwise
  window.location.reload();
}
/***********************************************************/
/* Handle user accounts and accountsChanged (per EIP-1193) */
/***********************************************************/
let currentAccount = null;
okexchain
  .request({ method: 'eth_accounts' })
  .then(handleAccountsChanged)
  .catch((err) => {
    // Some unexpected error.
    // For backwards compatibility reasons, if no accounts are available,
    // eth_accounts will return an empty array.
    console.error(err);
  });
// Note that this event is emitted on page load.
// If the array of accounts is non-empty, you're already
// connected.
okexchain.on('accountsChanged', handleAccountsChanged);
// For now, 'eth_accounts' will continue to always return an array
function handleAccountsChanged(accounts) {
  if (accounts.length === 0) {
    // MetaX is locked or the user has not connected any accounts
    console.log('Please connect to MetaX.');
  } else if (accounts[0] !== currentAccount) {
    currentAccount = accounts[0];
    // Do any other work!
  }
}
/*********************************************/
/* Access the user's accounts (per EIP-1102) */
/*********************************************/
// You should only attempt to request the user's accounts in response to user
// interaction, such as a button click.
// Otherwise, you popup-spam the user like it's 1999.
// If you fail to retrieve the user's account(s), you should encourage the user
// to initiate the attempt.
document.getElementById('connectButton', connect);
function connect() {
  okexchain
    .request({ method: 'eth_requestAccounts' })
    .then(handleAccountsChanged)
    .catch((err) => {
      if (err.code === 4001) {
        // EIP-1193 userRejectedRequest error
        // If this happens, the user rejected the connection request.
        console.log('Please connect to MetaX.');
      } else {
        console.error(err);
      }
    });
}

# Properties

# okexchain.isOKExWallet

WARNING

This property is non-standard. Non MetaX providers may also set this property to true.

true if the user has MetaX installed.

# okexchain.isWhitelist

WARNING

This property is non-standard. Non MetaX providers may also set this property to true.

# Why needs whitelist

The MetaX provides a unique injection method to avoid conflicting with other extension wallets. If your website provides MetaX connection and other extension wallet connection, and if it is a whitelisted website, MetaX will not inject the Ethereum object to prevent this website from connecting to MetaX while users trying to connect to other extension wallets (such as MetaMask), which can give a bad user experience to users.

# How to add to Whitelist

Send an email to [email protected], submit website information, and this website will be added to the Whitelist after approval.

The submitted information is as follows:

  1. Official website.
  2. All first-level domain names that interact with the extension wallet. (e.g., Please provide xxx.com if it is xxx.xxx.com)
  3. A screenshot of connecting to OKX on-chain wallet.
  4. Other information. (If there is no screenshot, please describe the process of connecting to MetaX)

It is expected that the review will be completed within 3-5 working days after submission, and result will be sent by email.

# How to verify

You need to install MetaX in your broswer, and open your website and use the broswer developer tools and enter okexchain.isWhiteList in the console mode to verify.

true means the website has been added to the Whitelist, false means it has not been added.

# Methods

# okexchain.isConnected()

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

okexchain.isConnected(): boolean;

# okexchain.request(args)

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

interface RequestArguments {
  method: string;
  params?: unknown[] | object;
}
okexchain.request(args: RequestArguments): Promise<unknown>;

# wallet_switchEthereumChain

If it needs to switch to Ethereum chain, please use this method. For more information, please refer to MetaMask Doc (opens new window)

try {
  await okexchain.request({
    method: 'wallet_switchEthereumChain',
    params: [{ chainId: '0xf00' }],
  });
} catch (switchError) {
  // This error code indicates that the chain has not been added to MetaX.
  if (error.code === 4902) {
    try {
      await okexchain.request({
        method: 'wallet_addEthereumChain',
        params: [{ chainId: '0xf00', rpcUrl: 'https://...' /* ... */ }],
      });
    } catch (addError) {
      // handle "add" error
    }
  }
  // handle other "switch" errors
}

# okexchain.requestChainId()

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

okexchain.requestChainId(): Promise<string>;

# okexchain.requestAccounts()

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

okexchain.requestAccounts(): Promise<string[]>;

# Events

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

okexchain.on('accountsChanged', (accounts) => {
  // Handle the new accounts, or lack thereof.
  // "accounts" will always be an array, but it can be empty.
});
okexchain.on('chainChanged', (chainId) => {
  // Handle the new chain.
  // Correctly handling chain changes can be complicated.
  // We recommend reloading the page unless you have a very good reason not to.
  window.location.reload();
});

# connect

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

interface ConnectInfo {
  chainId: string;
}
okexchain.on('connect', handler: (connectInfo: ConnectInfo) => void);

# disconnect

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

okexchain.on('disconnect', handler: (error: ProviderRpcError) => void);

# accountsChanged

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

okexchain.on('accountsChanged', handler: (accounts: Array<string>) => void);

# chainChanged

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

okexchain.on('chainChanged', handler: (chainId: string) => void);
okexchain.on('chainChanged', (_chainId) => window.location.reload());

# message

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

interface ProviderMessage {
  type: string;
  data: unknown;
}
okexchain.on('message', handler: (message: ProviderMessage) => void);

# Errors

Please refer toMetaMask Doc (opens new window), the only difference is that we inject different objects.

# Else

# Material

When guiding users to connect to the MetaX, the following materials can be used for configuration if website developers intend to display the wallet logo and name to users.

Click to download MetaX Logo
Recommended name: MetaX

# Download guide

If website developers need to guide users to download MetaX, they can use the following link:

Chrome:
https://chrome.google.com/webstore/detail/okex-wallet/mcohilncbfahbmgdjkbpemcciiolgcge (opens new window)

Firefox:
https://addons.mozilla.org/zh-CN/firefox/addon/okexwallet (opens new window)

Strategies recommended by MetaX

If it is the Firefox browser, guide users to Firefox Marketplace.
If not, guide users to Chrome Web Store.