Token Insight & Analytics API

Professional Node.js/Express backend service providing AI-powered cryptocurrency token insights via CoinGecko and HyperLiquid wallet PnL tracking.

🚀 Features

• Token Insight API: AI-powered market analysis combining CoinGecko data with GPT-4o-mini insights
• HyperLiquid PnL Tracking: Daily profit/loss calculation for wallet addresses
• Production-Ready: TypeScript, comprehensive error handling, logging, caching, and rate limiting
• Docker Support: Multi-stage builds for optimized deployment
• Comprehensive Testing: Unit and integration tests with Jest
• API Documentation: Postman collection included

📋 Prerequisites

• Node.js >= 18.0.0
• npm >= 9.0.0
• Docker (optional, for containerized deployment)
• OpenAI API key (for AI insights)

🛠️ Installation

Local Development

1. Clone the repository

   cd token-insight-api

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env

4. Edit .env and add your API keys

   OPENROUTER_FREE_API_KEY=your_OPENROUTER_FREE_API_KEY_here

5. Run in development mode

   npm run dev

   Server will start on http://localhost:3000

Docker Deployment

1. Build and run with Docker Compose

   docker-compose up --build

2. Or build manually

   docker build -t token-insight-api .
   docker run -p 3000:3000 --env-file .env token-insight-api

🔧 Configuration

All configuration is managed via environment variables. See .env.example for all available options:

Variable	Description	Default
PORT	Server port	3000
NODE_ENV	Environment (development/production)	development
OPENROUTER_FREE_API_KEY	OpenAI API key (required)	-
AI_MODEL	AI model to use	gpt-4o-mini
AI_BASE_URL	AI model base url to use	https://openrouter.ai/api/v1
AI_TEMPERATURE	AI response creativity (0-1)	0.7
COINGECKO_API_KEY	CoinGecko API key (optional)	-
RATE_LIMIT_MAX_REQUESTS	Max requests per window	100
CACHE_TTL_COINGECKO	CoinGecko cache TTL (ms)	300000

📡 API Endpoints

Health Check

GET /health

Response:

{
  "status": "ok",
  "timestamp": "2025-12-16T12:00:00.000Z",
  "uptime": 123.456
}

Token Insight API

POST /api/token/:id/insight

Parameters:

• id (path): Token ID from CoinGecko (e.g., bitcoin, ethereum, chainlink)

Request Body:

{
  "vs_currency": "usd",
  "history_days": 30
}

Response:

{
  "source": "coingecko",
  "token": {
    "id": "chainlink",
    "symbol": "link",
    "name": "Chainlink",
    "market_data": {
      "current_price_usd": 7.23,
      "market_cap_usd": 3500000000,
      "total_volume_usd": 120000000,
      "price_change_percentage_24h": -1.2
    }
  },
  "insight": {
    "reasoning": "Chainlink shows stable market position with moderate trading volume...",
    "sentiment": "Neutral"
  },
  "model": {
    "provider": "openai",
    "model": "gpt-4o-mini"
  }
}

Example:

curl -X POST http://localhost:3000/api/token/chainlink/insight \
  -H "Content-Type: application/json" \
  -d '{"vs_currency": "usd", "history_days": 30}'

HyperLiquid Wallet PnL API

GET /api/hyperliquid/:wallet/pnl?start=YYYY-MM-DD&end=YYYY-MM-DD

Parameters:

• wallet (path): Ethereum wallet address (0x...)
• start (query): Start date in YYYY-MM-DD format
• end (query): End date in YYYY-MM-DD format (max 90 days range)

Response:

{
  "wallet": "0xabc123...",
  "start": "2025-08-01",
  "end": "2025-08-03",
  "daily": [
    {
      "date": "2025-08-01",
      "realized_pnl_usd": 120.5,
      "unrealized_pnl_usd": -15.3,
      "fees_usd": 2.1,
      "funding_usd": -0.5,
      "net_pnl_usd": 102.6,
      "equity_usd": 10102.6
    }
  ],
  "summary": {
    "total_realized_usd": 120.5,
    "total_unrealized_usd": -25.3,
    "total_fees_usd": 3.3,
    "total_funding_usd": -0.8,
    "net_pnl_usd": 91.1
  },
  "diagnostics": {
    "data_source": "hyperliquid_api",
    "last_api_call": "2025-12-16T12:00:00Z",
    "notes": "PnL calculated using daily close prices"
  }
}

Example:

curl "http://localhost:3000/api/hyperliquid/0xabc123.../pnl?start=2025-08-01&end=2025-08-03"

🧪 Testing

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm test -- --coverage

📦 Build

# Build TypeScript
npm run build

# Run production build
npm start

🎯 Postman Collection

Import the Postman collection from postman/collection.json:

1. Open Postman
2. Click Import
3. Select postman/collection.json
4. Update the baseUrl variable if needed
5. Test all endpoints

🏗️ Project Structure

token-insight-api/
├── src/
│   ├── config/           # Configuration management
│   ├── controllers/      # Route controllers
│   ├── middleware/       # Express middleware
│   ├── routes/           # API routes
│   ├── services/         # Business logic
│   │   ├── ai.service.ts
│   │   ├── coingecko.service.ts
│   │   ├── hyperliquid.service.ts
│   │   └── pnl.service.ts
│   ├── types/            # TypeScript types
│   ├── utils/            # Utilities (cache, logger, errors)
│   ├── app.ts            # Express app setup
│   └── server.ts         # Server entry point
├── tests/
│   ├── unit/             # Unit tests
│   └── integration/      # Integration tests
├── postman/              # Postman collection
├── Dockerfile
├── docker-compose.yml
└── README.md

🔒 Security

• Helmet: Security headers
• CORS: Configurable cross-origin requests
• Rate Limiting: Prevents abuse
• Input Validation: Joi schema validation
• Error Handling: No sensitive data in error responses

📝 Development

# Run with auto-reload
npm run dev

# Lint code
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

🚢 Deployment

Docker (Recommended)

# Build production image
docker build -t token-insight-api:latest .

# Run container
docker run -d \
  -p 3000:3000 \
  --env-file .env \
  --name token-insight-api \
  token-insight-api:latest

Manual Deployment

# Build
npm run build

# Set environment
export NODE_ENV=production
export OPENROUTER_FREE_API_KEY=your_key

# Start
npm start

🐛 Troubleshooting

AI Service Not Working

• Ensure OPENROUTER_FREE_API_KEY is set in .env
• Check API key validity
• Verify you have API credits

CoinGecko Rate Limits

• Add COINGECKO_API_KEY for higher limits
• Increase CACHE_TTL_COINGECKO to reduce requests

HyperLiquid API Errors

• Verify wallet address format (0x...)
• Check date range (max 90 days)
• Ensure wallet has trading history

📄 License

MIT

👨‍💻 Author

Built with ❤️ using Node.js, TypeScript, and Express