Provider API
OneKey Browser Extension injects a global API into websites visited by its users at window.$onekey.ethereum
. This API allows websites to request users' Ethereum accounts, read data from blockchains the user is connected to, and suggest that the user sign messages and transactions. The presence of the provider object indicates an Ethereum user.
We recommend using typeof window !== 'undefined' && window.$onekey.ethereum
to detect our provider in browser.
The Ethereum JavaScript provider API is specified by EIP-1193.
Basic Usage
For any non-trivial Ethereum web application — a.k.a. dapp, web3 site etc. — to work, you will have to:
Detect the OneKey provider (
window.$onekey.ethereum
)Detect which Ethereum network the user is connected to
Get the user's Ethereum account(s)
The snippet at the top of this page is sufficient for detecting the provider. You can learn how to accomplish the other two by reviewing the snippet in the Using the Provider section.
The provider API is all you need to create a full-featured web3 application.
That said, many developers use a convenience library, such as ethers, instead of using the provider directly. If you are in need of higher-level abstractions than those provided by this API, we recommend that you use a convenience library.
Chain IDs
These are the IDs of the Ethereum chains that OneKey supports by default. Visit chainlist for more.
Methods
window.$onekey.ethereum.isConnected()
window.$onekey.ethereum.isConnected()
Tip
Note that this method has nothing to do with the user's accounts.
You may often encounter the word "connected" in reference to whether a web3 site can access the user's accounts. In the provider interface, however, "connected" and "disconnected" refer to whether the provider can make RPC requests to the current chain.
Returns true
if the provider is connected to the current chain, and false
otherwise.
If the provider is not connected, the page will have to be reloaded in order for connection to be re-established. Please see the connect
and disconnect
events for more information.
window.$onekey.ethereum.request(args)
window.$onekey.ethereum.request(args)
Use request
to submit RPC requests to Ethereum via OneKey Browser Extension. It returns a Promise
that resolves to the result of the RPC method call.
The params
and return value will vary by RPC method. In practice, if a method has any params
, they are almost always of type Array<any>
.
If the request fails for any reason, the Promise will reject with an Ethereum RPC Error.
OneKey Browser Extension supports most standardized Ethereum RPC methods, in addition to a number of methods that may not be supported by other wallets.
See the OneKey Browser Extension RPC API documentation for details.
Example
Events
The OneKey Browser Extension provider implements the Node.js EventEmitter
API.
This sections details the events emitted via that API.
There are innumerable EventEmitter
guides elsewhere, but you can listen for events like this:
connect
The OneKey Browser Extension provider emits this event when it first becomes able to submit RPC requests to a chain.
We recommend using a connect
event handler and the window.$onekey.ethereum.isConnected()
method in order to determine when/if the provider is connected.
disconnect
The OneKey provider emits this event if it becomes unable to submit RPC requests to any chain. In general, this will only happen due to network connectivity issues or some unforeseen error.
Once disconnect
has been emitted, the provider will not accept any new requests until the connection to the chain has been re-restablished, which requires reloading the page. You can also use the window.$onekey.ethereum.isConnected()
method to determine if the provider is disconnected.
accountsChanged
The OneKey provider emits this event whenever the return value of the eth_accounts
RPC method changes. eth_accounts
returns an array that is either empty or contains a single account address. The returned address, if any, is the address of the most recently used account that the caller is permitted to access. Callers are identified by their URL origin, which means that all sites with the same origin share the same permissions.
This means that accountsChanged
will be emitted whenever the user's exposed account address changes.
Tip
We plan to allow the eth_accounts
array to be able to contain multiple addresses in the near future.
chainChanged
Tip
See the Chain IDs section for OneKey Browser Extension's default chains and their chain IDs.
The OneKey Browser Extension provider emits this event when the currently connected chain changes.
All RPC requests are submitted to the currently connected chain. Therefore, it's critical to keep track of the current chain ID by listening for this event.
message
The OneKey provider emits this event when it receives some message that the consumer should be notified of.
The kind of message is identified by the type
string.
RPC subscription updates are a common use case for the message
event.
For example, if you create a subscription using eth_subscribe
, each subscription update will be emitted as a message
event with a type
of eth_subscription
.
Errors
All errors thrown or returned by the OneKey Browser Extension provider follow this interface:
The window.$onekey.ethereum.request(args)
method throws errors eagerly.
You can often use the error code
property to determine why the request failed.
Common codes and their meaning include:
4001
The request was rejected by the user
-32602
The parameters were invalid
-32603
Internal error
For the complete list of errors, please see EIP-1193 and EIP-1474.
Last updated