@tronweb3/tronwallet-adapter-binance

@tronweb3/tronwallet-adapter-binance

This package provides an adapter to enable TRON DApps to connect to the Binance Wallet.

Demo

import { BinanceWalletAdapter } from '@tronweb3/tronwallet-adapter-binance';

const adapter = new BinanceWalletAdapter();
// connect to BinanceWallet
await adapter.connect();

// then you can get address
console.log(adapter.address);

const tronWeb = new TronWeb({
    fullHost: 'https://api.trongrid.io',
});

// create a send TRX transaction
const unSignedTransaction = await tronWeb.transactionBuilder.sendTrx(targetAddress, 100, adapter.address);
// using adapter to sign the transaction
const signedTransaction = await adapter.signTransaction(unSignedTransaction);
// broadcast the transaction
await tronWeb.trx.sendRawTransaction(signedTransaction);

Documentation

API

• Constructor(config: BinanceWalletAdapterConfig)

interface BinanceWalletAdapterConfig {
    /**
     * Set if open Wallet's website when wallet is not installed.
     * Default is true.
     */
    openUrlWhenWalletNotFound?: boolean;
    /**
     * Timeout in millisecond for checking if Binance wallet is supported.
     * Default is 2 * 1000ms
     * Must be a finite number between 0 and 600000 (10 minutes);
     * anything else throws at construction.
     */
    checkTimeout?: number;
    /**
     * Whether to open the Binance app via deeplink on a mobile browser when the
     * Binance Wallet provider is not injected.
     * Default is true.
     *
     * This takes precedence on mobile: even when `useWalletConnectWhenWalletNotFound`
     * is enabled, a mobile browser will open the Binance app via deeplink instead of
     * showing the WalletConnect QR (desktop still falls back to WalletConnect). Set to
     * `false` to disable and keep the WalletConnect / download-page fallback on mobile.
     */
    openAppWithDeeplink?: boolean;
    /**
     * Set if use WalletConnect as fallback when Binance Wallet is not found.
     * Default is false.
     */
    useWalletConnectWhenWalletNotFound?: boolean;
    /**
     * WalletConnect configuration, required when useWalletConnectWhenWalletNotFound is true.
     */
    walletConnectConfig?: WalletConnectAdapterConfig;
    /**
     * Callback to receive the WalletConnect URI for custom QR code rendering.
     * When provided, the AppKit modal will be skipped.
     * Only used when falling back to WalletConnect.
     */
    onWalletConnectUri?: (uri: string) => void;
}

Example with WalletConnect fallback:

import { BinanceWalletAdapter } from '@tronweb3/tronwallet-adapter-binance';

const adapter = new BinanceWalletAdapter({
    useWalletConnectWhenWalletNotFound: true,
    walletConnectConfig: {
        network: 'Nile',
        options: {
            projectId: 'your_project_id',
            metadata: {
                name: 'Your DApp',
                description: 'Your DApp Description',
                url: 'https://your-dapp.com',
                icons: ['https://your-dapp.com/icon.png'],
            },
        },
    },
    // Optional: custom QR code rendering
    onWalletConnectUri: (uri) => {
        console.log('WalletConnect URI:', uri);
        // Display your custom QR code here
    },
});

• signAndSendTransaction(transaction: Transaction): Promise<{ signature: string; txHash: string; transaction: SignedTransaction }>

  Sign a transaction and broadcast it using the Binance Wallet's selected network in a single call.

  const unSignedTransaction = await tronWeb.transactionBuilder.sendTrx(targetAddress, 100, adapter.address);
  const { signature, txHash, transaction } = await adapter.signAndSendTransaction(unSignedTransaction);
  console.log('txHash:', txHash);

  Note: This method is not supported when connected via the WalletConnect fallback (useWalletConnectWhenWalletNotFound). In that case it throws a WalletSignTransactionError. Use signTransaction() and broadcast the signed transaction yourself instead.

• setOnWalletConnectUri(callback: ((uri: string) => void) | undefined): void

  Set the onWalletConnectUri callback for custom QR code rendering. This allows dynamic configuration of the URI handler after adapter initialization.

  adapter.setOnWalletConnectUri((uri) => {
      console.log('WalletConnect URI:', uri);
      // Display your custom QR code here
  });

• network() method is supported to get current network information. The type of returned value is Network as follows:

  export enum NetworkType {
      Mainnet = 'Mainnet',
      Shasta = 'Shasta',
      Nile = 'Nile',
      /**
       * When use custom node
       */
      Unknown = 'Unknown',
  }
  
  export type Network = {
      networkType: NetworkType;
      chainId: string;
      fullNode: string;
      solidityNode: string;
      eventServer: string;
  };

Deeplink and URL privacy

openAppWithDeeplink is enabled by default.

When it is on and the dApp runs in a mobile browser where Binance Wallet is not detected, the adapter opens the wallet through Binance's deeplink service. The entire current page URL — including its query string and hash — is embedded in the _dp parameter of https://app.binance.com/en/download. If the app is not installed, or the universal link does not resolve to it, the browser requests that HTTPS address, so the URL reaches Binance's servers.

Because of that:

• Do not put sensitive values in the page URL — access tokens, OAuth codes, session IDs, one-time credentials, and anything else that grants access. This is good practice regardless of this adapter (URLs end up in browser history, Referer headers and server logs), but the deeplink sends the URL somewhere it would otherwise never go.

• Base64 is not encryption. This adapter base64-encodes the deeplink payload before putting it in _dp, and percent-encoding is applied elsewhere. Neither hides anything: both are reversible with one function call.

• If the URL can contain sensitive data, act before connecting. Either strip it — move the value out of the URL, or clear it with history.replaceState() once it has been consumed — or turn the deeplink off:

  const adapter = new BinanceWalletAdapter({ openAppWithDeeplink: false });

  With openAppWithDeeplink: false the adapter never hands the URL to the deeplink service. The trade-off is that a mobile user without the wallet's in-app browser is no longer prompted to open the app, so guide them there yourself.

Security Check

BinanceWalletAdapter supports an optional securityOptions field for detecting wallet risks before connect(). When enabled, the adapter fetches a remote risk configuration and calls onRiskDetected if the wallet is flagged.

const adapter = new BinanceWalletAdapter({
    securityOptions: {
        enabled: true,
        configUrls: ['https://your-server.com/security-config.json'],
        onRiskDetected: async ({ risks }) => {
            // Throw to block the connection, or log a warning
            throw new Error(`Wallet risk detected: ${risks[0].title}`);
        },
    },
});

For the full SecurityOptions API reference, see walletadapter.org/docs.

Caveats

• Binance Wallet App doesn't implement multiSign() and switchChain().
• Binance Wallet App supports the following events:
  • connect
  • disconnect
  • accountsChanged
• Binance Wallet does not support auto-reconnect after a page reload.

For more information about tronwallet adapters, please refer to @tronweb3/tronwallet-adapters