主题

Provider API#

什么是 Injected provider API？#

欧易 Injected providers API 是一个 JavaScript API，欧易将其注入用户访问的网站。您的 DApp 可以使用此 API 请求用户帐户，从用户连接的区块链读取数据，帮助用户签署消息和交易。

连接账户#

eth_requestAccounts

EIP-1102

此方法由 EIP-1102 指定。在底层逻辑上，它调用 wallet_requestPermissions 以获得 eth_accounts 权限。由于目前来说 eth_accounts 是唯一的权限，所以你现在仅需此方法。

描述

此方法请求用户提供一个以太坊地址来识别。返回值为一个解析为单个以太坊地址字符串数组的 Promise。如果用户拒绝该请求，Promise 将被拒绝并返回 4001 错误。

该请求会导致一个欧易的弹窗出现。你应该只在响应用户操作时请求账户，比如一个用户在单击按钮的时候。在请求仍处于待处理状态时，你应该始终禁用导致请求被分派的按钮。

如果你无法检索用户的账户，你应该鼓励用户发起账户请求。

返回值

string[] - 单个十六进制以太坊地址字符串的数组。

例子

在 codeopen中打开。

HTML

JavaScript

<button class="connectEthereumButton">Connect Ethereum</button>

const connectEthereumButton = document.querySelector('.connectEthereumButton');

connectEthereumButton.addEventListener('click', () => {
  //Will Start the OKX extension
  okxwallet.request({ method: 'eth_requestAccounts' });
});

添加代币#

Note: 该功能仅在欧易 Web3 钱包插件端支持。

`wallet_watchAsset`#

EIP-747

此方法由 EIP-747 指定。

描述

此方法请求用户在欧易中关注某代币。返回一个布尔值，这个布尔值代表着代币是否已成功添加。

大多数以太坊钱包都支持关注一组代币，这些代币通常来自集中管理的代币注册表。 wallet_watchAsset 让 Web3 应用程序开发人员能够在运行时询问他们的用户去关注他们钱包中的代币。新添加的代币与通过原始方法（例如集中式注册表）添加的代币没有任何区别。

参数

WatchAssetParams - 要关注的资产的元数据。

interface WatchAssetParams {
  type: 'ERC20'; // In the future, other standards will be supported
  options: {
    address: string; // The address of the token contract
    'symbol': string; // A ticker symbol or shorthand, up to 11 characters
    decimals: number; // The number of token decimals
    image: string; // A string url of the token logo
  };
}

返回值

boolean - 如果添加了代币为 true，否则为 false。

例子

在 codeopen中打开。

HTML

JavaScript

<button class="connectEthereumButton btn">Connect Ethereum</button>
<button class="addTokenButton btn">Add Token</button>

const ethereumButton = document.querySelector('.connectEthereumButton');
const addTokenButton = document.querySelector('.addTokenButton');

addTokenButton.addEventListener('click', async () => {
  await okxwallet.request({ method: 'wallet_switchEthereumChain', params: [{ chainId: '0x1' }] });

  okxwallet
    .request({
      method: 'wallet_watchAsset',
      params: {
        type: 'ERC20',
        options: {
          address: '0xdac17f958d2ee523a2206206994597c13d831ec7',
          symbol: 'USDT',
          decimals: 6,
          image: 'https://foo.io/token-image.svg',
        },
      },
    })
    .then((success) => {
      if (success) {
        console.log('USDT successfully added to wallet!');
      } else {
        throw new Error('Something went wrong.');
      }
    })
    .catch(console.error);
});

ethereumButton.addEventListener('click', () => {
  getAccount();
});

function getAccount() {
  okxwallet.request({ method: 'eth_requestAccounts' }).catch((error)=>{
    console.log(error);
  });
}

支持 EIP-5792#

钱包支持批量发送多笔调用，查询交易结果等。

由 EIP-5792 规范定义。

wallet_sendCalls#

请求钱包批量发送多笔调用。

入参

type Capability = {
  [key: string]: unknown;
  optional?: boolean;
}

type SendCallsParams = {
  version: string;
  id?: string;
  from?: `0x${string}`;
  chainId: `0x${string}`;
  atomicRequired: boolean;
  calls: {
    to?: `0x${string}`;
    data?: `0x${string}`;
    value?: `0x${string}`;
    capabilities?: Record<string, Capability>;
  }[];
  capabilities?: Record<string, Capability>;
};

version：固定值， "2.0.0"
id：可选，请求的唯一标识，如果没有传入，钱包会自动生成 id
from：可选，发起请求的钱包地址，没有传入的话，则是当前连接的钱包
chainId：发起交易的链 id
atomicRequired：是否必须是原子交易，当前，通过 okx 发送的交易都是原子交易
calls：批量调用的列表
- to：调用的合约地址
- data：交易 data
- value：转移主币的数量
- capabilities：暂不支持
capabilities：暂不支持

返回值

type SendCallsResult = {
  id: string;
  capabilities?: Record<string, any>;
};

调用示例

window.okxwallet.request({
     "method": "wallet_sendCalls",
     "params": [
        {
          version: "2.0.0",
          from: "0x819d3f4c17d50004c165d06f22418c4f28010eda",
          chainId: "0x1",
          atomicRequired: true,
          calls: [
            {
              to: "0x54f1C1965B355e1AB9ec3465616136be35bb5Ff7",
              value: "0x0"
            },
            {
              to: "0x2D48e6f5Ae053e4E918d2be53570961D880905F2",
              value: "0x0"
            }
          ],
        }
      ],
})

wallet_getCallsStatus#

获取之前通过 wallet_sendCalls 发送的交易的状态。

入参

// 入参
type GetCallsParams = [string];

通过 id 查询交易。

返回值

type GetCallsResult = {
  version: string;
  id: `0x${string}`;
  chainId: `0x${string}`;
  status: number;
  atomic: boolean;
  receipts?: {
    logs: {
      address: `0x${string}`;
      data: `0x${string}`;
      topics: `0x${string}`[];
    }[];
    status: `0x${string}`;
    blockHash: `0x${string}`;
    blockNumber: `0x${string}`;
    gasUsed: `0x${string}`;
    transactionHash: `0x${string}`;
  }[];
  capabilities?: Record<string, any>;
};

version：发送交易的版本
id：唯一标识
chainId：发起交易的链 id
status：交易的状态，
- 100：确认中
- 200：已确认
- 400：链下失败
- 500：被拒绝
receipts：交易的详细信息
capabilities：暂不支持

调用示例

window.okxwallet.request({
     "method": "wallet_getCallsStatus",
     "params": [
       "0x123456"
     ],
})

wallet_getCapabilities#

返回钱包对相应atomic功能的支持信息。

入参

type GetCapabilitiesParams = [`0x${string}`, [`0x${string}`]];

第一个参数是要查询的地址
第二个参数是要查询的链的列表

返回值

type GetCapabilitiesResult = Record<`0x${string}`, <Record<string, any>>;

如果某条链不支持发送批量交易，则不会出现在查询结果中。

调用示例

window.okxwallet.request({
    "method": "wallet_getCapabilities",
    "params": [
        "0x00b909cefa36ab6bc26f5887a867e46ef162238f0a171b1c2974b665afd4237f",
        [
            "0x1",
            "0xaa36a7"
        ]
    ],
});

// 响应示例
{
    "0x1": {
        "atomic": {
            "status": "supported"
        }
    },
    "0xaa36a7": {
        "atomic": {
            "status": "ready"
        }
    }
}

事件#

欧易提供者实现了 Node.js EventEmitter API。本节详细介绍了通过该 API 发出的事件。网络上有其他各式各样的 EventEmitter 指南可供参考，本指南列出了如下一些事件：

okxwallet.on('accountsChanged', (accounts) => {
  // Handle the new accounts, or lack thereof.
  // "accounts" will always be an array, but it can be empty.
});

okxwallet.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();
});

另外，一旦你使用完监听器，请不要忘记将其删除（例如在 React 中卸载组件时）：

function handleAccountsChanged(accounts) {
  // ...
}

okxwallet.on('accountsChanged', handleAccountsChanged);

// Later
okxwallet.removeListener('accountsChanged', handleAccountsChanged);

okxwallet.removeListener 的第一个参数是事件名称，第二个参数是对已传递给第一个参数中提到的事件名称的 okxwallet.on 的同一函数的引用。

connect

interface ConnectInfo {
  chainId: string;
}

okxwallet.on('connect', handler: (connectInfo: ConnectInfo) => void);

欧易提供者会在第一次能够向链提交 RPC 请求时发出此事件。我们建议使用 connect 事件处理程序和 okxwallet.isConnected() 方法来确定欧易提供者的连接状态和连接时间。

disconnect

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

如果欧易提供者无法向任何链提交 RPC 请求，则会发出此事件。通常，这只会发生在网络连接问题或某些其他不可预见的错误状态下。

一旦发出 disconnect，提供者直到重新建立与链的连接之前将不会接受任何新请求，建立新连接需要重新加载页面。你还可以使用 okxwallet.isConnected() 方法来确定提供程序是否已断开连接。

accountsChanged

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

每当 eth_accounts RPC 方法的返回值发生变化时，欧易提供程序都会发出此事件。 eth_accounts 会返回一个为空或包含单个账户地址的数组。返回的地址（如果存在）即为允许调用者访问的最近使用的账户地址。由于调用者由其 URL origin 标识，所以具有相同来源(origin)的站点会持有相同的权限。

只要用户公开的账户地址发生变化，就会发出 accountsChanged.

提示

我们计划在不久的将来允许 eth_accounts 数组能够包含多个地址。

chainChanged

提示

欧易的默认链及其链 ID 请参见 Chain IDs section。

当前连接的链发生变化时，欧易提供者会发出此事件。

所有的 RPC 请求都提交到当前连接的链上。因此，通过侦听此事件来跟踪当前链 ID 是至关重要的。

我们强烈建议在链更改时重新加载页面，当然你也可以通过需求自行选择。

okxwallet.on('chainChanged', (_chainId) => window.location.reload());

message

interface ProviderMessage {
  type: string;
  data: unknown;
}

okxwallet.on('message', handler: (message: ProviderMessage) => void);

欧易提供者在有需要通知消费者的消息时发出此事件。消息的种类由 type 字符串标识。

RPC 订阅更新是 message 事件的常见用例。例如，如果你使用 eth_subscribe 创建订阅，则每个订阅更新都将作为 message 事件发出，其 type 为 eth_subscription。

例子

在 codeopen中打开。

HTML

JavaScript

<button class="connectEthereumButton btn">Connect Ethereum</button>
<button class="switchChainButton btn">Switch Chain</button>

const ethereumButton = document.querySelector(".connectEthereumButton");
const switchChainButton = document.querySelector(".switchChainButton");

window.okxwallet.on("chainChanged", (_chainId) => {
  console.log(`on chainChanged, current chainId: ${_chainId}`);
});

switchChainButton.addEventListener("click", async () => {
  try {
    await okxwallet.request({
      method: "wallet_switchEthereumChain",
      params: [{ chainId: okxwallet.chainId === "0x42" ? "0x38" : "0x42" }]
    });
  } catch (error) {
    // handle other "switch" errors
    console.log(error);
  }
});

ethereumButton.addEventListener("click", () => {
  getAccount();
});

async function getAccount() {
  await okxwallet.request({ method: "eth_requestAccounts" });
}