Initial Multichain API docs

[alexandratran]

Description

Initial Multichain API docs.

Issue(s) fixed

Fixes #1566

Preview

(Links updated Mar 5)

• Interact with multiple networks
• About the Multichain API
• Multichain API reference

Checklist

Complete this checklist before merging your PR:

• [x] If this PR contains a major change to the documentation content, I have added an entry to the top of the "What's new?" page.
• [ ] The proposed changes have been reviewed and approved by a member of the documentation team.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
metamask-docs	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	May 28, 2025 5:41pm

[vandan]

For MetaMask, I do not believe we need to document the scenario where wallet_createSession is used with sessionIds.

[vandan]

The CAIP standards extensively use the term "session", which insinuates a transient connection. MetaMask predominantly establishes persistent connections so we could consider using alternative terminology such as "connection". But I'm not sure if it's more confusing to diverge from the names used in the Multichain API methods.

[alexandratran]

@vandan

The CAIP standards extensively use the term "session", which insinuates a transient connection. MetaMask predominantly establishes persistent connections so we could consider using alternative terminology such as "connection". But I'm not sure if it's more confusing to diverge from the names used in the Multichain API methods.

I went ahead and updated "session" to "connection" throughout the docs. I think this is fine, but let me know if you prefer one way or the other.

[vandan]

One new request came up. In wallet_createSession requests. When CAIP-217 scopeObjects are specified under optionalScopes, only the following parameters are supported:

• references
• methods
• notifications
• accounts

Note: The references parameter is mainly included as a shorthand when there would otherwise be repetitive scopeObjects with the only difference being the reference portion of the scopeString.

Note: Supplying an accounts parameter is also a special case where the requesting app already knows a set of account it would like the user to permission. When supplied, the account selection process may include the requested accounts as defaults when supplied in the accounts parameter. Typically, applications are expected to leave this parameter off for the user to make their own selections.

[vandan]

See also: https://github.com/MetaMask/metamask-improvement-proposals/pull/60

[vandan]

Sorry to change this, but the multichain API will essentially be rolling directly to production (vs Flask). We will still need to describe it as "experimental" in the API reference though. We could also reference the following MIPs, which will include a little more detail: https://github.com/MetaMask/metamask-improvement-proposals/blob/main/MIPs/mip-5.md (Multichain API) https://github.com/MetaMask/metamask-improvement-proposals/blob/main/MIPs/mip-6.md (Ethereum-specific use of the Multichain API)

[alexandratran]

@bgravenorst We use the term "experimental" for other features throughout the Wallet and Snaps docs (for example here and here), so we want to keep it consistent for now.