Token Holder Tracking API

🔄 Real-time blockchain token holder tracking and analytics system built with NestJS

📜 About

A robust NestJS application that synchronizes with the Fraxtal blockchain to track token holders and their balances in real-time. Features automatic synchronization, high-precision balance tracking, and holder analytics.

⚡ Key Features

• Real-time blockchain synchronization
• High-precision balance tracking
• Automatic periodic updates (10-second intervals)
• Paginated holder data access
• Flexible sorting and filtering
• Percentage holdings calculation
• RESTful API endpoints
• Swagger API documentation

🏗 Architecture

The system is built around two core modules:

🔄 Sync Module

• Blockchain event synchronization
• Balance management
• Progress tracking (CLI)
• Automated updates

📊 Holders Module

• Paginated data access
• Percentage analytics
• Sorting capabilities

🛠 Tech Stack

• Framework: NestJS
• Database: PostgreSQL
• ORM: TypeORM
• RPC: Fraxtal RPC
• Libraries:
  • BigNumber.js (precision calculations)
  • Ethers (blockchain querying)
  • class-validator (input validation)
  • Swagger (API documentation)

🚀 Getting Started

1. Clone the repository

git clone https://github.com/omzi/token-holder-tracking-api.git
cd token-holder-tracking-api

2. Install dependencies

npm install

3. Configure environment variables Create a .env file in the root directory (or rename the .env.example file to .env):

DATABASE_URL = # Your PostgreSQL connection string
TOKEN_ADDRESS = # The token's contact address
FRAXTAL_RPC_URL = https://rpc.frax.com
PORT = 3000

4. Start the application

# Development
npm run start:dev

# Production
npm run start:prod

🔌 API Endpoints

GET /holders

Retrieve paginated list of token holders

• Query Parameters:
  • page (default: 1)
  • limit (default: 10, max: 100)
  • sortBy (options: balance, address, percentage)
  • order (options: asc, desc)

POST /sync

Manually trigger blockchain synchronization

📚 API Documentation

Access the Swagger API documentation at /api when running the application.

🧪 Testing

# Unit tests
npm run test

# E2E tests
npm run test:e2e

# Test coverage
npm run test:cov

📦 Project Structure

src/
├── sync/              # Blockchain synchronization module
├── holders/           # Holder management module
├── entities/          # Database entities
└── dto/               # Data transfer objects

👥 Contributors

• Omezibe Obioha (@0xOmzi)

📄 License

This project is licensed under the MIT License. See the LICENSE file for more details.

❌ Disclaimer

You may experience rate limits, errors and/or bugs while testing out the application. Feel free to reach to me on Twitter/X (@0xOmzi) regarding any issue you might be facing.

---

Back to Top ⬆️