API Documentation

Metamask Snap API

setConfiguration

setConfiguration(configuration: SnapConfig):Promise<void>

Configures snap for the specific network. It is possible to send custom configuration or select one from a set of predefined configurations by defining specific networkName.

Currently, there are two predefined configurations for kusama and westend networks. If selecting a predefined configuration only networkName field is required.

interface SnapConfig {
  networkName: string; // predefined: "kusama" and "westend"
  wsRpcUrl?: string;
  addressPrefix?: number;
  unit?: UnitConfiguration;
}

It is also possible to choose a predefined configuration and only change some specific properties. In the example SnapConfig below we selected predefined configuration for kusama network and only changed URL for RPC endpoint (wsRpcUrl), all other properties will be same as in predefined configuration for kusama network.

{
  networkName: "kusama",
  wsRpcUrl: "custom.rpc.url"
}

---

getLatestBlock

  getLatestBlock(): Promise<BlockInfo>

Returns basic info on the latest included block. Info contains block hash and block number, as BlockInfo.

interface BlockInfo {
  hash: string;
  number: string;
}

---

Account

getPublicKey

getPublicKey(): Promise<string>

Returns the public key for the generated account.

---

getBalance

getBalance(): Promise<string>

Returns balance for the generated account.

---

exportSeed

exportSeed(): Promise<string>

Returns seed used for generating an account.

This method will invoke Metamask prompt to confirm action

---

Transaction

Sending transaction is a three-step process (generate payload, generate signature and send transaction). InjectedSigner is used to generate a signature for payload as shown in Architecture overview. For a showcase of sending a transaction, see example code

generateTransactionPayload

generateTransactionPayload(amount: string | number, to: string): Promise<TxPayload>

Generates transaction payload for sending amount of units to address to.

Unit is always defined with current configuration (e.g. if kusama predefined configuration is selected then amount defines the quantity of KSM tokens that are being sent).

---

send

send(signature: string, txPayload: TxPayload): Promise<string>

Sends transaction defined with txPayload and signature. See example code for creating and sending transaction

---

getAllTransactions

getAllTransactions(address?: string): Promise<unknown>

Returns historic data about transactions for provided address or for a generated account if address is omitted. Data is retrieved from Polkascan.

---

Event API

To use event API, first, it must be fetched by calling and awaiting async function getEventApi.

getEventApi

  getEventApi(): Promise<PolkadotApi>

Resolved PolkadotApi defines methods for subscribing on specific Polkadot events as described below:

---

Event API

subscribeToBalance(callback: PolkadotEventCallback): void

Subscribe to balance changes for the generated account. Provided callback will be called on balance change with string argument representing new balance.

---

unsubscribeFromBalance(callback: PolkadotEventCallback): void

Unsubscribe specific callback, provided as an argument, from listening on balance change for the generated account.

---

unsubscribeAllFromBalance(): void

Unsubscribe all registered callbacks listening on balance change for the generated account.

---

subscribeToTxStatus(hash: HexHash, onIncluded: TxEventCallback, onFinalized?: TxEventCallback): void

Subscribe callbacks to transaction statuses inBlock ( onIncluded ) and onFinalized ( onFinalized ). Transaction hash is provided as a hex string.

The second callback for onFinalized status can be omitted.

Metamask snap API usage examples

Send transaction

const amount = "1000000000";
const recipient = "5DW5CXHWbM13Az7aetLQVUEviNq8WeXFQanHNPVMmzyRYKvX";

// get injected extension
const provider = await getInjectedMetamaskExtension();
if(provider) {
  // fetch metamask polkadot snap API
  const api = await provider.getMetamaskSnapApi();

  // send transaction
  const txPayload = await api.generateTransactionPayload(amount, recipient);
  const signedTx = await provider.signer.signPayload(txPayload.payload);
  const txHash = await api.send(signedTx.signature, txPayload);

  // subscribe to transaction events
  const polkadotEventApi = await api.getEventApi();
  // handleTransactionIncluded and handleTransactionFinalized are callbacks defined somewhare outside this code
  polkadotEventApi.subscribeToTxStatus(txHash, handleTransactionIncluded, handleTransactionFinalized);
}