Skip to content
Documentation
API Reference
TON Provider

TON Provider API

OpenMask injects a global API into websites visited by its users at window.ton. This API allows websites to request users' TON 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 TON user.


// get injected provider from window
if (window.ton) {
    onTonReady();
} else {
    window.addEventListener('tonready', () => onTonReady(), false);
}

function onTonReady() {
  const provider = window.ton;

  console.log('isOpenMask=', provider.isOpenMask);

  startApp(provider); // initialize your app
}

Basic Usage

For any non-trivial TON web application — a.k.a. dapp, web3 site etc. — to work, you will have to:

  • Detect the TON provider (window.ton)
  • Detect which TON network the user is connected to
  • Get the user's TON account(s)

The provider API is all you need to create a full-featured web3 application.

Properties

ton.isOpenMask

💡
This property is non-standard. Non-OpenMask providers may also set this property to true.

true if the user has OpenMask installed.

Methods

ton.isConnected()

ton.isConnected(): Promise<boolean>;

This method returns a Promise that resolves to a true if the provider is connected to the current chain, or throw Error otherwise.

If the provider is not connected, the page will have to be reloaded in order for connection to be re-established.

ton.isLocked()

ton.isLocked(): Promise<boolean>;

This method returns a Promise that resolves to a boolean indicating if OpenMask is unlocked by the user. OpenMask must be unlocked in order to perform any operation involving user accounts. Note that this method does not indicate if the user has exposed any accounts to the caller.

ton.send(args)

ton.send(method: string, params?: unknown[] | object): Promise<unknown>;

Use request to submit RPC requests to TON via OpenMask. 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 Error.

OpenMask Provider support 2 ways to pass parameters, there are both request would return the same result:

ton.send(method, param1, param2): Promise<unknown>;
ton.send(method, [param1, param2]): Promise<unknown>;

The second way is implemented to be backward compatible with wallet.ton.

See the OpenMask RPC API documentation for learn move about possible methods.

Events

The OpenMask 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:

ton.on('accountsChanged', (accounts) => {
  // Handle the new accounts, or lack thereof.
  // "accounts" will always be an array, but it can be empty.
});

ton.on('chainChanged', (chainId) => {
  // Handle the new chain.
  // Correctly handling chain changes can be complicated.
  // We recommend reloading the page unless you have good reason not to.
  window.location.reload();
});

Also, don't forget to remove listeners once you are done listening to them (for example on component unmount in React):

function handleAccountsChanged(accounts) {
  // ...
}

ton.on('accountsChanged', handleAccountsChanged);

// Later

ton.removeListener('accountsChanged', handleAccountsChanged);

The first argument of the ton.removeListener is the event name and the second argument is the reference to the same function which has passed to ethereum.on for the event name mentioned in the first argument.

accountsChanged

ton.on('accountsChanged', handler: (accounts: Array<string>) => void);

The OpenMask provider emits this event whenever the return value of the ton_requestAccounts RPC method changes. ton_requestAccounts 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.

chainChanged

ton.on('chainChanged', handler: (chainId: string) => void);

The OpenMask provider emits this event when the currently connected network changes.

All RPC requests are submitted to the currently connected chain. Therefore, it's critical to keep track of the current network by listening for this event.

Errors

interface ProviderRpcError extends Error {
  message: string;
  code: number;
}

The ton.send(args) method throws errors eagerly.

Using the Provider


const provider = window.ton;

const connect = async () => {
    try {
        const accounts = await provider.send('ton_requestAccounts');
        const account = accounts[0];
        setAddress(account);
    } catch (e) {
        console.error(e);
    }
}

document
    .getElementById('connectButton')
    .addEventListener('click', connect);
Switch Network
RPC API