Getting Started

Overview

TRC20 Monitor is a professional Python library for monitoring TRC20 token transactions on the Tron blockchain. It provides real-time transaction tracking with flexible storage and notification options.

Prerequisites

  • Python 3.8 or higher

  • Basic understanding of blockchain concepts

  • A Tron wallet address to monitor

Installation

Using pip

pip install trc20-monitor

Using Poetry

poetry add trc20-monitor

From Source

git clone https://github.com/kun-g/trc20-monitor.git
cd trc20-monitor
pip install -e .

Basic Concepts

Components

The library is built around three main components:

  1. Database Adapter: Stores transaction history

    • MemoryDB: In-memory storage (default)

    • SQLiteDB: Persistent SQLite storage

    • Custom implementations via DatabaseAdapter interface

  2. Notification Adapter: Handles transaction alerts

    • ConsoleNotifier: Prints to console

    • FileNotifier: Writes to file

    • WebhookNotifier: Sends to webhook URL

    • Custom implementations via NotificationAdapter interface

  3. Monitor: The main orchestrator that:

    • Fetches transactions from Tron network

    • Filters and processes new transactions

    • Stores transaction history

    • Triggers notifications

Transaction Flow

  1. Monitor queries the Tron network for transactions

  2. New transactions are identified by comparing with stored history

  3. Transactions are saved to the database

  4. Notifications are sent for each new transaction

  5. Process repeats at specified intervals

Your First Monitor

Here’s a simple example to get you started:

import asyncio
from trc20_monitor import TRC20Monitor, MemoryDB, ConsoleNotifier

async def main():
    # Create monitor with in-memory storage and console output
    monitor = TRC20Monitor(
        database=MemoryDB(),
        notifier=ConsoleNotifier()
    )
    
    # Monitor incoming USDT transactions
    await monitor.monitor_address(
        address="TYourTronAddressHere",
        contract="TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",  # USDT contract
        direction="in",  # Monitor incoming transactions
        interval=30,     # Check every 30 seconds
        min_amount=1.0   # Only notify for amounts >= 1 USDT
    )

# Run the monitor
asyncio.run(main())

Using the CLI

The library also provides a command-line interface:

# Monitor incoming USDT transactions
trc20-monitor monitor TYourAddressHere TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t --direction in

# Monitor with SQLite storage
trc20-monitor monitor TYourAddressHere TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t \\
    --db-type sqlite --db-path transactions.db

# Monitor with webhook notifications
trc20-monitor monitor TYourAddressHere TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t \\
    --notifier webhook --webhook-url https://your-webhook.com/endpoint

Common TRC20 Contracts

Here are some commonly monitored TRC20 contracts on Tron:

  • USDT: TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t

  • USDC: TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8

  • TUSD: TUpMhErZL2fhh4sVNULAbNKLokS4GjC1F4

Next Steps

Getting Help