Ton Provider

Ton Provider API

Binance Web3 Wallet's TON API is fully compliant with the Ton Connect protocol.

Dapps can use the TON Connect SDK to integrate with Binance Web3 Wallet.

JS Bridge API

When the dapp is opened in the Binance Web3 Wallet browser, the window.binancew3w object will be injected into the global scope. The object contains the tonconnect object, which is the bridge object for the TON Connect protocol.

Provider Detection

window.binancew3w.tonconnect

The data structure of the object it points to is as follows:

interface TonConnectBridge {
  deviceInfo: DeviceInfo
  walletInfo?: WalletInfo
  protocolVersion: number
  connect(protocolVersion: number, message: ConnectRequest): Promise<ConnectEvent>
  restoreConnection(): Promise<ConnectEvent>
  send(message: AppRequest): Promise<WalletResponse>
  listen(callback: (event: WalletEvent) => void): () => void
}

The version of Ton Connect supported by Binance Web3 Wallet is currently 2. For more information, see ton-connect bridge api and ton-connect requests and responses

Example

const result = await window.binancew3w.tonconnect.connect(2, {
  manifestUrl: 'https://example.com/manifest.json',
  items: [{ name: 'ton_addr' }],
})

if (result.event === 'connect') {
  console.log(result.payload.items, result.payload.device)
}
if (result.event === 'connect_error') {
  console.error(result.payload.error.code, result.payload.error.message)
}

HTTP Bridge API

The Binance Web3 Wallet browser also provides an HTTP bridge API for dapps to interact with the wallet. The HTTP bridge API is compatible with the HTTP Bridge Protocol.

If the dapp is not opened in the Binance Web3 Wallet browser, the window.binancew3w object will not be injected into the global scope. In this case, the dapp can use the HTTP bridge API to interact with the wallet.

Provider Detection

Let say dapp with ID A connects to the bridge to listen to incoming requests from wallet with ID B.

request
    GET https://bridge.tonapi.io/bridge/events?client_id=<to_hex_str(A)>

    Accept: text/event-stream

Sending message from client A to client B. Bridge returns error if ttl is too high.

request
    POST https://bridge.tonapi.io/bridge/message?client_id=<to_hex_str(A)>?to=<to_hex_str(B)>&ttl=300&topic=sendTransaction

    body: <base64_encoded_message>

Dapp need to encrypt the message before sending it to the bridge with id of client B as public key. And client B will decrypt the message with its private key.

When the bridge receives a message base64_encoded_message from client A addressed to client B, it generates a message BridgeMessage:

{
  "from": <to_hex_str(A)>,
  "message": <base64_encoded_message>
}

Client B send a message to client A. Client A will receive a message from the bridge.

Dapp need to decrypt the message with its private key(id of client A).

{
  "from": <to_hex_str(B)>,
  "message": <base64_encoded_message>
}

Binance Web3 Connect

If you want to open binance web3 wallet directly without the user selecting a wallet, you can follow the steps below:

1. Add a button with the text Binance Web3 Connect

2. Add the following code.

Assume the id of the button above is binance-w3w-connect.

import TonConnectUI from "@tonconnect/ui";

// create an instance of TonConnectUI
const tonConnectUI = new TonConnectUI({
  manifestUrl: "https://ton-connect.github.io/demo-dapp-with-react-ui/tonconnect-manifest.json",
  buttonRootId: "your-button-root-id",
});

// add event listener to the button
document.querySelector('#binance-w3w-connect').addEventListener('click', async () => {
    await tonConnectUI.openSingleWalletModal("binanceWeb3TonWallet");
});

After that, when the user clicks the Binance Web3 Connect button, the binance wallet app will be opened directly.

Conclusion

The Binance Web3 Wallet browser provides both JS bridge API and HTTP bridge API for dapps to interact with the wallet. Dapps can use the JS bridge API when the dapp is opened in the Binance Web3 Wallet browser, and use the HTTP bridge API when the dapp is not opened in the Binance Web3 Wallet browser.

We strongly recommend that dapps use ton-connect to integrate with Binance Web3 Wallet, as it provides a more secure and reliable way to interact with the wallet. You don't need to care about which bridge API to use, ton-connect will automatically choose the appropriate bridge API based on the environment. Also you don't need to care about the encryption and decryption of messages, ton-connect will handle it for you.