Google Sheets USDT Tracker

A Google Apps Script project for tracking USDT transactions and wallet balances across multiple blockchain networks, all within a Google Spreadsheet.

Features

• Multi-network support -- track USDT on TRC20 (TRON), BEP20 (BSC), and TON networks from a single spreadsheet
• Precision string arithmetic -- raw blockchain values are divided using string-based math (not parseFloat, not BigInt), which prevents JavaScript floating-point errors for large integers (critical for BEP20 with 18 decimals)
• Adapter pattern -- each network implements a uniform adapter interface, making it straightforward to add new networks
• Automatic deduplication -- transactions are deduplicated by hash + wallet_name before writing
• Safe balance updates -- balance functions return null on API errors so that a valid balance is never overwritten with zero
• Built-in TON address parsing -- no external TonWeb dependency required
• Dust filtering -- BEP20 transfers under 0.5 USDT and zero-amount transfers are ignored
• Cooldown logic -- enforces a minimum interval (default 5 min) between update cycles

Supported Networks

Network	Token	Decimals	API Provider
TRC20	USDT (TRON)	6	TronGrid v1
BEP20	USDT (BSC)	18	NodeReal MegaNode API (free tier)
TON	USDT (TON)	6	Toncenter v3

Google Sheets Structure

The spreadsheet uses two sheets. Their names are configurable in config.gs.

Wallets sheet (default name: "Wallets")

Column	Content
A	Wallet address
B	Name / description
C	Network (TRC20 / BEP20 / TON)
D	USDT balance (updated automatically)
G1	Timestamp of the last balance update

Transactions sheet (default name: "Transactions")

Column	Content
A	Date
B	Income
C	Expense
D	Wallet
E	Network
F	Hash

Note: Sheet names and column headers are configurable in config.gs.

Setup / Installation

1. Open a Google Spreadsheet.
2. Go to Extensions > Apps Script.
3. Create the script files listed below, preserving the exact load order (the order matters in GAS):

   1. config.gs
   2. utils.gs
   3. trc20.gs
   4. bep20.gs
   5. ton.gs
   6. network_tracker.gs
   7. wallets.gs
   8. main.gs
   

4. Copy the corresponding source code into each file.
5. Fill in your API keys in config.gs (see the Configuration section).
6. Create the two sheets ("Wallets" and "Transactions") or update the names in config.gs.
7. Populate the Wallets sheet with your addresses, names, and networks.
8. Run trackAllTransactions() manually or set up a time-driven trigger.

Available Functions

Function	Description
trackAllTransactions()	Full cycle: update balances, then track all networks
runTRC20Tracking()	Track TRC20 transactions only
runBEP20Tracking()	Track BEP20 transactions only
runTONTracking()	Track TON transactions only
runBalanceUpdate()	Update wallet balances only

Configuration

All settings live in config.gs.

API Keys

Key	Service
TRONGRID_API_KEY	TronGrid API (TRC20)
TONCENTER_API_KEY	Toncenter API (TON)
NODEREAL_API_KEY	NodeReal MegaNode API (BEP20)

Parameters

Parameter	Default	Description
TIME_THRESHOLD_DAYS	90	Transactions older than this are ignored
TRON_GRID_LIMIT	50	Max TRC20 transactions per API request
TON_CENTER_LIMIT	100	Max TON events per API request
Cooldown	5 min	Minimum interval between balance update cycles

How It Works

Adapter Pattern

Each network module (trc20.gs, bep20.gs, ton.gs) exports an adapter object with two methods:

• fetchTransactions(address) -- retrieves raw transactions from the blockchain API.
• processTransaction(tx, address, name, cutoffDate) -- converts a raw transaction into a spreadsheet row: [Date, Incoming, Outgoing, Wallet, Network, Hash].

The universal handler in network_tracker.gs (trackNetworkTransactions) reads wallets from the Wallets sheet, filters by network, calls the adapter for each wallet, deduplicates by hash + wallet_name, and appends new rows to the Transactions sheet.

String Arithmetic

The toTokenAmount(rawValue, decimals) function in utils.gs performs string-based division of raw blockchain integers by 10^decimals. This avoids JavaScript's loss of precision for integers larger than 2^53, which is especially important for BEP20 USDT where raw values have 18 decimal places.

Transaction Filtering

• TRC20: only Transfer type events; filtered by the USDT contract address.
• BEP20: hex-to-decimal conversion (NodeReal returns hex); dust filter (< 0.5 USDT) and zero-amount filter.
• TON: event types jetton_transfer and jetton_swap; filtered by USDT master address.
• All networks: deduplication by hash + wallet_name; cutoff by date (configurable, default 90 days).

Limitations

• TRC20 API returns a maximum of 50 recent transactions per request (TronGrid limit).
• TON API returns a maximum of 100 recent events per request (Toncenter limit).
• Google Apps Script has a 6-minute execution time limit for consumer (non-Workspace) accounts.

License

MIT