Build first tgBTC dApp

👋 Introduction

The TONX API enables seamless interaction with tgBTC, allowing developers to retrieve tgBTC-related data and execute transactions. Built with React and TypeScript, this project provides web3 developers with a practical implementation for integrating tgBTC into their applications. In this guide, we will explore how to leverage the TONX API for tgBTC integration.

Please note that tgBTC only supports testnet environments, and this API was built by independent community developers, so keep this in mind during development.

💎 What is TON Teleport BTC?

TON Teleport BTC allows seamless and secure BTC transfers between the Bitcoin and TON networks, without the need for centralized issuers. Its decentralized design and strong security features ensure trust and convenience. You can mint your first tgBTC using TON Teleport and step-by-step guide.

🦄 What you will learn

• connect your TON testnet wallet using TON Connect

• check and manage your tgBTC balance with ease

• send tgBTC to any account with just a few clicks

• real-time transaction confirmation for full transparency and security using the TONX API​

💡 Prerequisites

Before you start, ensure you have the following:

• testnet wallet in TON (e.g., Tonkeeper, as shown in our previous guide)

• TONX API key (testnet). Get access to the TONX API for free

• basic knowledge of React and TypeScript to follow along with the code

• pnpm package manager installed on your machine

• Node.js (v16 or higher) for running the project

• some tgBTC for testing transfers

TONX API for tgBTC

In this project, we use the TONX API and @tonx/core SDK to perform tgBTC transactions. For more details on the SDK, refer to the SDK guide. In particular, we use the following methods to execute tgBTC transactions:

• getJettonWallets
• getJettonTransfers
• getTgBTCTransferPayload

⚙ Setup development environment​

1. Install dependencies

npm install -g pnpm

1. Install project dependencies

pnpm install

1. Create a .env file in the root directory

VITE_TONXAPI_KEY=your_api_key_here

Great! At the end of the setup, replace your_api_key_here with your TONX API key.

Integrate TON Connect

Update the src/App.tsx file to include TonConnectButton, useTonWallet, and useTonConnectUI:

import { TonConnectButton, useTonWallet, useTonConnectUI } from '@tonconnect/ui-react';

Network settings

Configure the TONX API for testnet:

const client = new TONXJsonRpcProvider({
  network: 'testnet',
  apiKey: import.meta.env.VITE_TONXAPI_KEY
});

Retrieve tgBTC balance

Use getJettonWallet to get the tgBTC balance:

const wallets = await client.getJettonWallets({ owner_address: wallet?.account.address });
const tgBTCWallet = wallets.find((wallet: { jetton: string; }) => wallet.jetton === TGBTC_ADDRESS);
setAmount(tgBTCWallet.balance / JETTON_QUANTITY);
setJettonWallet(tgBTCWallet.address);

Send tgBTC

Use getTgBTCTransferPayload API to generate a payload for the transaction message:

const getTransferPayload = async () => {
    const response = fetch(`https://testnet-rpc.tonxapi.com/v2/json-rpc/${import.meta.env.VITE_TONXAPI_KEY}`, {
      method: "POST",
      headers: {
        accept: "application/json",
        "content-type": "application/json",
      },
      body: JSON.stringify({
        id: 1,
        jsonrpc: "2.0",
        method: "getTgBTCTransferPayload",
        params: {
          amount: transferAmount * JETTON_QUANTITY,
          destination: recipientAddress,
          source: wallet?.account.address,
          comment: "From TONX API",
        },
      }),
    });

Retrieve tgBTC transactions

Use getJettonTransfers to check and confirm a tgBTC transaction after sending out an amount:

const transfers = await client.getJettonTransfers({
      address: wallet?.account.address,
      jetton_master: TGBTC_ADDRESS,
      direction: 'out',
    });

🚢 Run the application

1. Start the development server:

pnpm dev

1. Use your browser to try out the application (default: http://localhost:4000)

🖼 User interface

After connecting the TON wallet:

Now you've created your first working tgBTC dApp using the third-party API by TONX.

🧐 What's next?

For the full implementation and source code, visit the project's GitHub repository.

With your environment set up and the TONX API integrated, you're ready to start using your application to manage tgBTC transactions. Test sending tgBTC, check balances in real time, and explore advanced features as your project grows.

For more methods, you can go to the next page!