Skip to main content

Multichain API

Flask Only
This feature is experimental and only available in MetaMask Flask, the canary distribution of MetaMask.

Dapps can call Multichain API methods to create and manage CAIP-25 connections with MetaMask. The API also provides events that wallets can send to dapps to notify them of onchain or connection changes.

See also

Methods​

wallet_createSession​

Creates a multichain connection with a wallet, authorizing that wallet with the specified set of scopes and properties. This method is defined in CAIP-25.

Parameters​

  • optionalScopes: object - (Optional) CAIP-217 authorization scopes the wallet can support in order to be used with this dapp. If scopes are specified, only the following properties are supported:
    • references: array - (Optional) A list of references to specific blockchains for the namespace of this scope. This property is mainly used when there would otherwise be duplicate scopes.
    • methods: array - A list of JSON-RPC methods the wallet must support in order to be used with this dapp.
    • notifications: array - A list of JSON-RPC notifications the wallet must support in order to be used with this dapp.
    • accounts: array - (Optional) A list of CAIP-10 account IDs valid within this scope. Dapps should only supply this property when they know the set of accounts they would like the user to permit. When supplied, these accounts are preselected by default in the account selection process. Dapps typically omit this property for the user to select their own accounts.
  • sessionProperties: object - (Optional) Properties that the wallet can use to determine if the connection is valid.
  • requiredScopes: object - (Optional) CAIP-217 authorization scopes the wallet must support in order to be used with this dapp. We don't recommend using requiredScopes with MetaMask.

Returns​

The scopes and properties of the created connection.

Example​

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_createSession",
  "params": {
    "optionalScopes": {
      "eip155": {
        "references": ["1", "137"],
        "methods": ["eth_sendTransaction", "eth_signTransaction", "eth_sign", "get_balance", "personal_sign"],
        "notifications": ["accountsChanged", "chainChanged"]
      },
      "eip155:10": {
        "methods": ["get_balance"],
        "notifications": ["accountsChanged", "chainChanged"]
      },
      "eip155:0": {
        "methods": ["wallet_getPermissions", "wallet_creds_store", "wallet_creds_verify", "wallet_creds_issue", "wallet_creds_present"],
        "notifications": []
      },
      "eip155:42161": {
        "methods": ["eth_sendTransaction", "eth_signTransaction", "get_balance", "personal_sign"],
        "notifications": ["accountsChanged", "chainChanged"]
      }
    },
    "sessionProperties": {
      "expiry": "2022-12-24T17:07:31+00:00",
      "caip154-mandatory": "true"
    }
  }
}

wallet_getSession​

Gets the scopes and properties within the active connection. This method is defined in CAIP-312.

note

MetaMask doesn't support session IDs.

Parameters​

None.

Returns​

The scopes and properties of the connection.

Example​

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_getSession",
  "params": {}
}

wallet_invokeMethod​

Invokes the specified JSON-RPC API method on the specified network previously authorized to the dapp within a connection. This method is defined in CAIP-27.

note

MetaMask doesn't support session IDs.

Parameters​

  • scope: string - A CAIP-2 chain ID previously authorized to the dapp within a connection.
  • request: object - A request object containing:
    • method: string - The JSON-RPC API method to invoke, previously authorized to the dapp within a connection.
    • params: object - The RPC method parameters (can be empty).

Returns​

The response from the JSON-RPC method call.

Example​

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_invokeMethod",
  "params": {
    "scope": "eip155:1",
    "request": {
      "method": "eth_sendTransaction",
      "params": [
        {
          "to": "0x4B0897b0513FdBeEc7C469D9aF4fA6C0752aBea7",
          "from": "0xDeaDbeefdEAdbeefdEadbEEFdeadbeefDEADbEEF",
          "gas": "0x76c0",
          "value": "0x8ac7230489e80000",
          "data": "0x",
          "gasPrice": "0x4a817c800"
        }
      ]
    }
  }
}

wallet_revokeSession​

Revokes the active connection. This method is defined in CAIP-285.

note

MetaMask doesn't support session IDs.

Parameters​

None.

Returns​

true if the revocation was successful.

Example​

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "wallet_revokeSession",
  "params": {}
}

Events​

The Multichain API provides the following events that wallets can send to dapps to notify them of changes to a session.

wallet_notify​

Notifies the dapp of events or state changes related to a specific, previously authorized network. This event is defined in CAIP-319.

note

MetaMask doesn't support session IDs.

Parameters​

  • scope: string - A CAIP-2 chain ID previously authorized to the dapp within a connection.
  • notification: object - A notification object containing:
    • method: string - A JSON-RPC API notification method name previously authorized to the dapp within a connection.
    • params: object - The RPC notification method parameters.

Example​

{
  "jsonrpc": "2.0",
  "method": "wallet_notify",
  "params": {
    "scope": "eip155:1",
    "notification": {
      "method": "eth_subscription",
      "params": {
        "subscription": "0x12345678",
        "result": {
          "blockNumber": "0x1234",
          "transactionHash": "0x5678",
          "logIndex": "0x9abc"
        }
      }
    }
  }
}

wallet_sessionChanged​

Notifies the dapp of updates to the active connection's authorization scopes. This method is defined in CAIP-311.

note

MetaMask doesn't support session IDs.

Parameters​

sessionScopes: object - An object containing the full updated authorization scopes, each formatted according to CAIP-217.

Example​

{
  "jsonrpc": "2.0",
  "method": "wallet_sessionChanged",
  "params": {
    "sessionScopes": {
      "eip155:1": {
        "methods": ["eth_signTransaction", "eth_sendTransaction"],
        "notifications": ["message"],
        "accounts": ["eip155:1:0xabc123"]
      },
      "eip155:137": {
        "methods": ["eth_sendTransaction"],
        "notifications": [],
        "accounts": ["eip155:137:0xdef456"]
      }
    }
  }
}
On this page