Use Imported TON Wallets

Learn how to work with imported TON wallets for common operations like checking balances and signing transactions

Overview

This guide shows you how to work with imported TON wallets for common operations. Once you’ve imported a private key, you can perform various wallet operations directly.

Prerequisites

• Imported a TON private key
• Set up your authenticated client
• Installed TON dependencies

Step 1: Check Wallet Balance

Check the TON balance of your imported wallet using the TON HTTP API:

const address = 'YourImportedTonWalletAddress';

const response = await fetch(
  `https://toncenter.com/api/v2/getAddressBalance?address=${address}`
);
const data = await response.json();

const balanceNanotons = BigInt(data.result);
const balanceTon = Number(balanceNanotons) / 1_000_000_000;

console.log('Balance:', balanceNanotons.toString(), 'nanotons');
console.log('Balance in TON:', balanceTon);

Step 2: Sign Transactions with Imported Wallet

Use your imported wallet to sign TON transactions. Serialize your cell to base64 before passing it to signTransaction():

import { beginCell, toNano } from '@ton/ton';

const tonClient = await authenticatedTonClient();

// Build the transfer body and serialize to base64
const transferBody = beginCell()
  .storeUint(0, 32)
  .storeStringTail('Hello!')
  .endCell();
const transactionString = transferBody.toBoc().toString('base64');

// Sign with imported wallet — returns base64 signature
const signature = await tonClient.signTransaction({
  walletMetadata,
  transaction: transactionString,
});

console.log('Signature (base64):', signature);

Step 3: Sign Messages with Imported Wallet

Sign messages for authentication or data integrity:

const message = 'Hello from my imported TON wallet!';
const signature = await tonClient.signMessage({
  message,
  walletMetadata,
});

// Returns base64-encoded Ed25519 signature
console.log('Message signed (base64):', signature);

Step 4: Check Jetton Balances

Check Jetton (TON fungible token) balances in your imported wallet:

// Get all Jetton wallets for the address via TON HTTP API
const response = await fetch(
  `https://toncenter.com/api/v2/getTokenData?address=${jettonWalletAddress}`
);
const data = await response.json();

console.log('Jetton data:', data.result);

Complete Example: Sign and Send from Imported Wallet

import { beginCell, toNano } from '@ton/ton';

export const signAndSendFromImportedWallet = async ({
  walletAddress,
  comment,
}: {
  walletAddress: string;
  comment?: string;
}) => {
  const tonClient = await authenticatedTonClient();

  // Build transfer body
  const body = comment
    ? beginCell().storeUint(0, 32).storeStringTail(comment).endCell()
    : beginCell().endCell();

  // Serialize to base64 string
  const transactionString = body.toBoc().toString('base64');

  // Sign — returns base64 Ed25519 signature
  const signature = await tonClient.signTransaction({
    walletMetadata,
    transaction: transactionString,
  });

  console.log('Signature (base64):', signature);
  return signature;
};

Best Practices

1. Balance Checking: Verify sufficient balance before sending transactions
2. Error Handling: Implement proper error handling for all wallet operations
3. Security: Never expose sensitive information in server-side code
4. Network Selection: The SDK currently supports TON Mainnet only

Next Steps

• Sign TON transactions
• Sign TON messages