API Reference

TONX API SDK Sample Project

TON Balance and Transaction Viewer

This is a React application that displays TON balances and transfer history using the TONX SDK. Refer to this sample project's GitHub repository.

Prerequisites

  • Node.js (v16 or higher recommended)
  • pnpm package manager
  • Fundamental TypeScript knowledge

Environment Setup

  1. Install pnpm globally:
npm install -g pnpm
  1. Install project dependencies:
pnpm install

Configurations

API Key Setup

  1. Get your API key from dashboard.tonxapi.com.
  2. Important: Use a Testnet API key.
  3. Define VITE_TONXAPI_KEY with the testnet API key in the .env file.

Network Configuration

  1. Set up the application for the testnet environment. Ensure correct network setting as follows:
const client = new TONXJsonRpcProvider({
  network: "testnet", // Keep this as testnet for development
  apiKey: import.meta.env.VITE_TONXAPI_KEY,
});

Wallet Address Configuration

The application uses a default wallet address for tracking:

const myTonAddress = "EQDi1eWU3HWWst8owY8OMq2Dz9nJJEHUROza8R-_wEGb8yu6";

To track a different wallet:

  1. Replace the myTonAddressconstant with your own address.
  2. Ensure the address is valid and exists on the TON testnet.

Features

  • View wallet balance in TON
  • Display the latest transaction details
  • Direct link to transaction explorer
  • Loading state handling
  • Error state handling

Running the Application

Start the development server:

pnpm dev

Access the application (usually at http://localhost:4000)

Component Functionality

The application provides several key features:

Balance Display

  • Shows current wallet balance
  • Updates on refresh
  • Handles error states gracefully

Transaction Viewing

  • Displays the latest transaction hash
  • Provides clickable links to TON Explorer
  • Shows appropriate messages for different states

Error States

The application handles multiple states:

  • "No connection" - Initial state
  • "Error fetching balance" - Balance fetch failure
  • "Error fetching transaction" - Transaction fetch failure
  • "No transaction found" - When no transactions exist
  • Valid transaction hash - Displays with explorer link

Security Best Practices

  1. Never commit API keys to version control
  2. Validate wallet addresses before querying
  3. Handle API errors appropriately

Troubleshooting

  1. API Key Issues

    • Verify you're using a testnet API key
    • Ensure the environment variable is correctly accessed

  2. Balance Not Showing

    • Verify the wallet address is correct
    • Check if the wallet exists on testnet
    • Ensure you have proper network connectivity

  3. Transactions Not Loading

    • Verify the wallet has a recent transaction history in the last 30 days.
    • Check network connection
    • Confirm API key permissions