@tronweb3/walletconnect-tron

@tronweb3/walletconnect-tron helps dApps connect to the TRON network via WalletConnect.

Get Started

Installation

You can install @tronweb3/walletconnect-tron with npm, yarn, or pnpm:

npm i @tronweb3/walletconnect-tron

yarn add @tronweb3/walletconnect-tron

pnpm add @tronweb3/walletconnect-tron

Create a WalletConnect wallet

Request Parameters

interface WalletConnectAdapterConfig {
  network: WalletConnectChainID;
  options: SignClientTypes.Options;
  /**
   * Theme mode configuration flag. By default, `themeMode` follows the user's system setting.
   * @type `dark` | `light`
   * @see https://docs.reown.com/appkit/react/core/theming
   */
  themeMode?: 'dark' | 'light';
  /**
   * Theme variable configuration object.
   * @default undefined
   * @see https://docs.reown.com/appkit/react/core/theming#themevariables
   */
  themeVariables?: ThemeVariables;
}

Example

import { WalletConnectWallet, WalletConnectChainID } from '@tronweb3/walletconnect-tron';
const wallet = new WalletConnectWallet({
  network: WalletConnectChainID.Mainnet,
  options: {
    relayUrl: 'wss://relay.walletconnect.com',
    projectId: '....',
    metadata: {
      name: 'Your dApp name',
      description: 'Your dApp description',
      url: 'Your dApp url',
      icons: ['Your dApp icon']
    }
  },
  // Theming (optional)
  themeMode: 'dark',
  themeVariables: {
    '--w3m-z-index': 1000
    // More variables: https://docs.reown.com/appkit/react/core/theming#themevariables
  }
});

Connect to the Wallet

Use wallet.connect() to establish a connection. If the dApp has previously connected, it will reconnect automatically; otherwise, a WalletConnect QR code will be displayed.

Response

Returns an object containing the wallet address when connected (e.g., { address: string }).

Example

const { address } = await wallet.connect();

Disconnect from the Wallet

Use wallet.disconnect() to disconnect the wallet.

Example

try {
  await wallet.disconnect();
} catch (error) {
  console.log('disconnect:' + error);
}

Sign Transaction

Signs the provided transaction object.

Request Parameters

Response

Returns a signed transaction object.

Examples

• TRX transfer (native TRX)

import { TronWeb } from 'tronweb';

const tronWeb = new TronWeb({ fullHost: 'https://nile.trongrid.io' }); // Nile Testnet
const from = '<yourAddress>';
const to = '<recipientAddress>';
const amountSun = 1_000_000; // 1 TRX

// build
const tx = await tronWeb.transactionBuilder.sendTrx(to, amountSun, from);

// sign
const signedTransaction = await wallet.signTransaction(tx);

// optional: broadcast
// const receipt = await tronWeb.trx.sendRawTransaction(signedTransaction)

• Contract call (USDT approve)

import { TronWeb } from 'tronweb';

const tronWeb = new TronWeb({ fullHost: 'https://nile.trongrid.io' }); // Nile Testnet
const from = '<yourAddress>';
const usdt = '<usdtContract>';
const spender = '<spenderAddress>';
const amount = 100n * 1_000_000n; // 100 USDT, 6 decimals

// triggerSmartContract returns { transaction }
const { transaction } = await tronWeb.transactionBuilder.triggerSmartContract(
  usdt,
  'approve(address,uint256)',
  { feeLimit: 200000000 },
  [
    { type: 'address', value: spender },
    { type: 'uint256', value: amount.toString() }
  ],
  from
);

const signedTransaction = await wallet.signTransaction(transaction);
// optional: broadcast
// const receipt = await tronWeb.trx.sendRawTransaction(signedTransaction)

Note

• For triggerSmartContract, pass the transaction field from its response, not the whole response object.
• sendTrx returns the transaction object directly; pass it to wallet.signTransaction.
• Some wallets auto-broadcast, others do not. If not, call tronWeb.trx.sendRawTransaction(signedTransaction) yourself.

Sign Message

Signs a string message.

Request Parameters

Example

try {
  const signature = await wallet.signMessage('hello world');
} catch (error) {
  console.log('signMessage:' + error);
}

Check Connection Status

Checks the connection status.

Response

Returns { address: string }. If not connected, returns { address: '' }.

Example

const { address } = await wallet.checkConnectStatus();

Event Listeners

The wallet supports event listeners to monitor connection state and account changes.

Note: The on() method returns a function that can be called to unsubscribe from the event. This is why the returned value is typically named unsubscribe.

accountsChanged Event

Triggered when the connected account address changes (e.g., user switches accounts in the wallet).

Parameters

The first address in the array is the primary account address.

Example

// on() returns a function that can be called to unsubscribe
const unsubscribe = wallet.on('accountsChanged', accounts => {
  const primaryAddress = accounts[0];
  console.log('Primary address:', primaryAddress);
  console.log('All addresses:', accounts);
});

// Call the returned function to unsubscribe when done
unsubscribe();

disconnect Event

Triggered when the wallet connection is disconnected (either by user action or network issues).

Example

// on() returns a function that can be called to unsubscribe
const unsubscribe = wallet.on('disconnect', () => {
  console.log('Wallet disconnected');
  // Clean up your app state
});

// Call the returned function to unsubscribe when done
unsubscribe();

Remove Event Listeners

Recommended: use the unsubscribe function returned by on(). To remove a specific listener with off(), pass the same function reference:

// Preferred
const fn = accounts => {
  /* ... */
};
const unsubscribe = wallet.on('accountsChanged', fn);
unsubscribe();

// Or remove by function reference
wallet.off('accountsChanged', fn);

// Cleanup
wallet.removeAllListeners('accountsChanged');
// wallet.removeAllListeners();

AppKit Control Methods

The SDK exposes AppKit control methods for advanced use cases. These methods allow you to control the AppKit modal and subscribe to its state changes.

Note: AppKit is initialized during the first connect() call. Most methods require AppKit to be initialized first.

closeModal()

Programmatically close the AppKit modal.

Example

// Close the modal programmatically
await wallet.closeModal();

Use Cases

• Auto-close modal after a timeout
• Close modal based on custom business logic
• Integrate with your own UI flow

setThemeMode()

Dynamically change the AppKit theme mode after initialization.

Parameters

Example

// Switch to light theme
wallet.setThemeMode('light');

// Switch to dark theme
wallet.setThemeMode('dark');

Note: This method can be called after connect() to dynamically change the theme. The initial theme is set via the themeMode config option when creating the wallet instance.

subscribeModalState()

Subscribe to AppKit modal state changes (e.g., modal open/close events).

Parameters

Returns

Returns an unsubscribe function that can be called to stop receiving updates.

Example

// Subscribe to modal state changes
const unsubscribe = wallet.subscribeModalState(state => {
  console.log('Modal open:', state.open);
  console.log('Selected network:', state.selectedNetworkId);

  if (state.open) {
    console.log('Modal opened');
  } else {
    console.log('Modal closed');
  }
});

// Later: unsubscribe when done
unsubscribe();

Note: This method can be called before connect(). The subscription will become active after AppKit is initialized.

subscribeEvents()

Subscribe to all AppKit events for analytics and tracking purposes.

Parameters

Returns

Returns an unsubscribe function that can be called to stop receiving events.

Example

// Subscribe to all AppKit events
const unsubscribe = wallet.subscribeEvents(event => {
  const { data } = event;
  if (data) {
    console.log('Event type:', data.event);
    console.log('Event data:', data.properties);

    // Track specific events
    if (data.event === 'MODAL_OPEN') {
      console.log('User opened wallet selection modal');
    } else if (data.event === 'MODAL_CLOSE') {
      console.log('User closed wallet selection modal');
    } else if (data.event === 'CONNECT_SUCCESS') {
      console.log('User successfully connected wallet');
    }
  }
});

// Later: unsubscribe when done
unsubscribe();

Common Events

• MODAL_OPEN - Modal opened
• MODAL_CLOSE - Modal closed
• SELECT_WALLET - User selected a wallet
• CONNECT_SUCCESS - Connection successful
• CONNECT_ERROR - Connection failed

Note: This method can be called before connect(). The subscription will become active after AppKit is initialized.

Note

The connection uses the WalletConnect relay service specified by relayUrl. Network errors may occur occasionally, so dApp developers should handle network errors, connection errors, and timeout errors appropriately.

Refer to the WalletConnect Error Definitions for all error messages and codes.

License

MIT

4.0.1

• Add AppKit control methods: closeModal(), setThemeMode(), subscribeModalState(), and subscribeEvents().
• Support dynamic theme mode switching after connection.
• Add modal state and event tracking capabilities.

4.0.0

• Update QR code modal from @walletconnect/modal to @reown/appkit.
• Change signing response structure to be compatible with both old and new wallets.
• Switch connection flow to use WalletConnect Universal Provider.
• Add event listeners support: accountsChanged and disconnect events.

3.0.0

• Replace @web3modal/standalone with @walletconnect/modal.

2.0.0

• Replace the original QRCodeModal with Web3Modal.
• Support web3ModalConfig when creating the WalletConnect Tron instance to customize the displayed wallet list for both desktop and mobile.

1.0.1

• Support qrcodeModalOptions when creating the WalletConnect Tron instance to customize the displayed wallet list for both desktop and mobile.

1.0.0

• Initial release: WalletConnect Tron SDK providing connect, disconnect, signTransaction, signMessage, and checkConnectStatus APIs.