metamask/api-specs

MetaMask API Specs

API Playground: https://metamask.github.io/api-playground/api-documentation API Reference Docs: https://docs.metamask.io/wallet/reference/json-rpc-api/

Latest build: https://metamask.github.io/api-specs/latest/openrpc.json

JSON-RPC API provided by MetaMask.

MetaMask dapp developers lack a formal RPC specification. This attempts to document which methods MetaMask supports in a way that's versionable, human-readable and machine-readable. It will improve the accuracy of documentation, API, and clients.

MetaMasks effectiveness as an enterprise-grade application platform depends on its ability to provide a reliable and predictable developer experience.

Contributing

Edit the openrpc.yaml file.

You can then run yarn run build to generate the output file again.

To test the result, you can paste the resulting file from dist/build/openrpc.json into the OpenRPC playground and view the result.

Build Process

• filter out methods that are not supported/implemented by metamask
• merge wallet methods with execution api methods
• output to build

Deploy

• On release uploads to npm at @metamask/api-specs
• On release uploads to github pages at https://metamask.github.io/api-specs/latest/metamask-openrpc.json

api-specs's Issues

methods that are inherited from execution-apis should have a tag to distinguish them

Add specs for API method to allow self-revokation of a permission

As a convience, a dapp may want to allow their users easy (e.g. single click) revocation of permissions that have been granted to themselves. We can expose an API that just allows the dapp to remove any permissions it has been granted.

type object and no properties makes the json-schema-form show up with nothing (wallet_requestPermissions)

Fix example for wallet_addEthereumChain

Looks like https://dai.poa.network is no longer responding.
We can resolve by replacing it with:
https://rpc.gnosischain.com/

How to recover some tokens from one network to another via MetaMask API.

Hello:
I have an issue which I want to solve it by MetaMask API, but before I spend more time on this topic, please provide some advice.
A few weeks ago, I sent some cryptocurrency tokens (Ruff Chain) from one exchange to another exchange. Unfortunately, even the sender’s exchange shows the successful sending, but the only network for sending this token on the sender’s exchange is on HECO network, but the receiver’s deposit address can receive the same token using only ERC20 network.
So those sent tokens stayed in the network for more than one month. The receiver’s exchange has recently released some kind of token recovery tools, so I can recover those tokens sent to my deposit address using ERC20 network. But I have to pay 100USDT each time if I use their tools.
I want to know if I can write some code (JavaScript) to do the similar job?
Or, if it is not easy to do this, then, can I use MetaMask wallet to receive similar tokens, which the sending network and the receiving network don’t match, thus cause the tokens not reaching their deposit addresses forever. If I can use MetaMask wallet to receive those tokens first, then change their network, then send them again from MetaMask wallet using the same network as the receiver’s deposits address network. That is changing from HECO network to REC20 network.
If not possible, then let me know, I will pay the fee to use the receiver’s exchange tools to recover my tokens.
If possible, please give some general ideas on how I can do this or provide some further readings on this topic. I can do this by hand for a few times, if possible, but I wish to be able to do this more via API, since there could be more chances to use this API functions.
Thanks,

Add subscription methods

The eth_subscribe and eth_unsubscribe methods are not documented, yet they are supported by our provider.

EIP: https://eips.ethereum.org/EIPS/eip-758

Related section of provider EIP: https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1193.md#subscriptions

Add specs for API methods for more user preferences (identicon type, dark mode preference, metrics opt-in)

Dapps may want to have the following MetaMask preferences accessible via API:

• identicon type (jazzicon vs blockie)
• dark mode preference
• metrics opt-in

This would allow dapps to ensure config of their UX is consistent with the wallet config.

Add a note about MIPs in the readme for this repo

We should mention that making significant API spec changes requires submitting a MIP and following the associated workflow there.

personal_sign spec and docs are incorrect about signature length

Spec and docs say:

api-specs/openrpc.yaml

Line 250 in 6d6ba82

description: A hex-encoded 129-byte array starting with `0x`.

But personal_sign signatures are 65-bytes long, e.g.:

• 0x587c03f5289ecc735901934bd7c60266848212bb6609e7865885963e9884b2ac68c05b61307aca7ad3fffb62ff9f37eab85f93e8bf4fb84c720d99c8598086871b
• 0x6449b69d356d6cded96ae3d0a30ad041b2a070a21d9b88047a4c377a1fe655646bb0b69e17201203e1131b0f7103db242c1bd87b0c72fa57f5782e7f7ec127451c

fix deploy for `latest/`

Description

Allow for sub directories of gh page builds for deploy

Depends on MetaMask/action-publish-gh-pages#20

Missing Specs Audit

Missing MetaMask Methods

• eth_requestAccounts [https://eips.ethereum.org/EIPS/eip-1102] (issue: #101)

Missing Client methods

• eth_getUncleByBlockHashAndIndex, eth_getUncleByBlockNumberAndIndex, (not in ethereum/execution-apis but supported by major infra nodes including infura)
• eth_protocolVersion (removed from ethereum/execution-apis? but infura supports)
• eth_subscribe / eth_unsubscribe [https://eips.ethereum.org/EIPS/eip-758] (issue: #89)
• eth_sign [we've semi deprecated so maybe not?]

WIP

• eth_signTypedData [https://github.com//pull/123]

MetaMask specific methods that are complete:

• wallet_addEthereumChain
• wallet_switchEthereumChain
• wallet_requestPermissions
• wallet_getPermissions
• wallet_registerOnboarding
• wallet_watchAsset
• eth_decrypt
• eth_getEncryptionPublicKey
• eth_accounts
• personal_sign

Add deprecated and rarely used methods into the spec for sake of completeness

Add missing methods:

• personal_ecRecover
• • parity_* (with deprecated: true, so that at least we still have them documented)

wallet_watchAsset constrain the number for decimals to "must be between 0 and 36"

eth_accounts example is malformed

Add a watch command that rebuilds the document when changes are made

should be yarn watch

Add EIP-4844 support to eth_sendTransaction definition

eth_signTransaction is not supported, and so without this update it will not be possible for application layer clients to submit blob-carrying tx's to MetaMask.

Tag methods that have confirmation dialogs associated with them

Many times we find ourselves wanting to know which set of methods will require a confirmation method. As such, we should just add a tag to make it really obivous and create a single source of truth for this expectation.

Use ethereum execution api spec

should be reffing https://raw.githubusercontent.com/ethereum/execution-apis/assembled-spec/refs-openrpc.json as the base spec for Ethereum

all methods should have at least one examplePairing

wallet_watchAsset address should ref the address schema (which should include a regex and length requirements, etc)

Publish builds to NPM via CI

Add npm publish step to our publish action

When this repo was made we hadn't really figured out the npm publish part. but we should be able to use whats in the metamask-module-template now since it has support for npm publishing.

add this at the bottom of .github/workflows/publish-release.yml. and follow the instructions in the comment below to set up the token.

      - name: Publish NPM
        uses: MetaMask/action-npm-publish@v2
        with:
          # This `NPM_TOKEN` needs to be manually set per-repository.
          # Look in the repository settings under "Environments", and set this token in the `npm-publish` environment.
          npm-token: ${{ secrets.NPM_TOKEN }}
        env:
          SKIP_PREPACK: true

source: https://github.com/MetaMask/metamask-module-template/blob/c2b55bce243483c4edcc3c454bba415ff996335b/.github/workflows/publish-release.yml#L64-L86

Maybe move this into the /specifications repository

IFF we choose to start using the /specifications repository as a shared cross-platform place to coordinate product strategy (as proposed in MetaMask/specifications#3 ) then it could make sense to move the contents of this repository into the /api folder there.

wallet_watchAsset image should have the format: 'uri'

Increase consistency in API Specs to cover all method-specifiic errors, descriptions/summaries, etc.

Error on `invokeSnap`

looks like it needs to be paramStructure: "by-name"

https://docs.metamask.io/wallet/reference/wallet_invokesnap/

Add yaml support to to provide a better contributor experience for markdown

We would like to implement this change in order to unify:
JSON-RPC API (manually maintained and mostly redundant now)
with JSON-RPC API Playground (interactive version that's generated from OpenRPC API specs)

Guidance from @shanejonas :

change api-specs repo to yaml to provide a better contributor experience for markdown

Invalid `wallet_requestSnaps` and `wallet_invokeSnap` specs

wallet_requestSnaps and wallet_invokeSnap use an object as params, but on the docs, the params are currently being wrapped in an array.

The spec and examples should be updated to use this format:

wallet_requestSnaps

type Request = {
  method: 'wallet_requestSnaps';
  params: Record<SnapId, { version?: SemVerVersion; }>;
}

wallet_invokeSnap

type Request = {
  method: 'wallet_invokeSnap',
  params: {
    snapId: SnapId;
    request: {
      method: string;
      params: Json;
    }
  }
}

Setup preview builds

We want to be able to have a preview link to the built openrpc document so that metamask-docs's previews will work with un-merged changes to api-specs.

add signTypedData method

method content descriptors should have descriptions (and summary where applicable).

Releases should contain a static openrpc.json

Having a link to the post-processed openrpc.json makes it a lot easier to use.

Add specs for API methods to retrieve the users nicknames of their own accounts

Dapps may wish retrieve a user's nicknames for their own accounts, so that they can represent those accounts in the same way that the wallet does

filter out execution api methods we dont support in MM dapp api (eth_createAccessList for example)

Add getLocale rpc method

Create a new rpc API endpoint to get current language

Mirko's notes:

• Implementation should live inside Lib/rpc-method-middleware
• Look for other methods implementation (e.g. addCustomChain)
• Look into createMethodMiddleware
• Test on the test dapp and/or playground

the open-rpc document should be paste-able into playground

At the moment, the document is using local refs to a schema that doesnt exist until you bundle it. This ticket is to make the document more easy to work on by only using remote refs when the underlying ref is from execution-apis document.

add requestAccounts

Add error codes for methods

Each method has a common set of error codes but also in some cases unique error codes we need to document

Gatleaa

Hello
H

wallet_watchAsset has a link in the description that is not clickable.

Error on wallet_requestSnaps

Looks like there is an issue with the wallet_requestSnaps method (possibly with the format of the example)

From @Montoya

It’s this one: https://docs.metamask.io/wallet/reference/wallet_requestsnaps/
If you click Send Request you get an error, I think because the parameters are formatted wrong

type array and no items makes the json-schema-form show up with an error (eth_subscribe)