QACC Tokens API

A comprehensive TypeScript API server for calculating token circulating supply using Polygon smart contract data.

Features

• 🚀 Express.js server with TypeScript
• 🔒 Security middleware (Helmet, CORS)
• 📊 Real-time circulating supply calculation
• 🌐 Polygon network integration with ethers.js
• 🛡️ Input validation and error handling
• 🔧 Flexible token configuration management
• 📝 Comprehensive logging and monitoring

API Endpoints

Health Check

• GET /health - Server health status

Token Supply Information

• GET /api/tokens/supply/:tokenTicker - Get token supply in wei format (Giveth-style)
• GET /api/tokens/detailed/:tokenTicker - Get detailed token supply in decimal format for debugging

Getting Started

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Installation

1. Clone the repository:

git clone <repository-url>
cd qacc-tokens

2. Install dependencies:

npm install

3. Set up environment variables:

cp env.example .env
# Edit .env with your configuration

4. Start the development server:

npm run dev

The server will start on http://localhost:3000

Available Scripts

• npm run dev - Start development server with hot reload
• npm run dev:watch - Start development server with nodemon
• npm run build - Build the project for production
• npm start - Start production server
• npm run clean - Clean build directory

Environment Variables

Variable	Description	Default
PORT	Server port	3000
NODE_ENV	Environment	development
POLYGON_RPC_URL	Polygon RPC URL	https://polygon-rpc.com
POLYGON_API_KEY	API key for Polygon access	(empty)

Polygon Network Setup

This API is specifically designed for Polygon network tokens. For detailed setup instructions, see POLYGON_SETUP.md.

Quick Start with Polygon

1. Configure RPC: Update your .env file with a Polygon RPC URL:

   POLYGON_RPC_URL=https://polygon-rpc.com
   # Or use premium providers:
   # POLYGON_RPC_URL=https://polygon-mainnet.infura.io/v3/YOUR_PROJECT_ID
   # POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/YOUR_API_KEY

2. Test the API: Run the test script:

   node test-api.js

Project Structure

src/
├── controllers/     # Request handlers
├── middleware/      # Custom middleware
├── routes/         # API routes
├── services/       # Business logic
└── index.ts        # Application entry point

Development

The project uses TypeScript with strict type checking. Make sure to:

1. Run npm run build before committing
2. Fix any TypeScript errors
3. Follow the existing code structure

Production Deployment

1. Build the project:

npm run build

2. Start the production server:

npm start

API Examples

Token Supply API

This API returns token supply data in wei format, similar to the Giveth circulating supply API.

Get Token Supply

curl http://localhost:3000/api/tokens/supply/AKA

Response:

{
  "totalSupply": "1000000000000000000000000000",
  "circulating": "377638543168219876216648485"
}

Get Detailed Token Supply (Debug)

curl http://localhost:3000/api/tokens/detailed/AKA

Response:

{
  "tokenTicker": "AKA",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "amounts": {
    "totalSupply": {
      "wei": "6722276701385420072755012",
      "decimal": "6722276.701385420072755012"
    },
    "circulatingSupply": {
      "wei": "1327871899751580675096060",
      "decimal": "1327871.899751580675096060"
    },
    "teamAmount": {
      "wei": "6400000000000000000000000",
      "decimal": "6400000.000000000000000000"
    },
    "arbBotAmount": {
      "wei": "1013333000000000000000000",
      "decimal": "1013333.000000000000000000"
    },
    "streamBasedLockedAmount": {
      "wei": "3995000000000000000000000",
      "decimal": "3995000.000000000000000000"
    }
  },
  "calculation": {
    "totalExcluded": {
      "wei": "10395000000000000000000000",
      "decimal": "10395000.000000000000000000"
    },
    "totalAdded": {
      "wei": "1013333000000000000000000",
      "decimal": "1013333.000000000000000000"
    },
    "circulatingPercentage": 19.75,
    "excludedPercentage": 80.25
  },
  "unlockStreams": [
    {
      "totalAmount": {
        "wei": "44899321099999990000000",
        "decimal": "44899.321099999990000000"
      },
      "lockedAmount": {
        "wei": "3995000000000000000000000",
        "decimal": "3995000.000000000000000000"
      },
      "unlockedAmount": {
        "wei": "4949321099999990000000",
        "decimal": "4949.321099999990000000"
      },
      "startDate": "2025-04-29",
      "endDate": "2025-10-29",
      "description": "Season 1 Batch 4"
    }
  ]
}

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and build
5. Submit a pull request

License

MIT