/tmai-api-sdk-typescript

Token Metrics API and SDK: Empowering developers to build AI-driven crypto trading agents.

Primary LanguageTypeScriptMIT LicenseMIT

Token Metrics AI API TypeScript SDK

npm version

The official TypeScript SDK for Token Metrics AI API - providing professional investors and traders with comprehensive cryptocurrency analysis, AI-powered trading signals, market data, and advanced insights.

Features

  • Comprehensive Market Data: Access detailed information on thousands of cryptocurrencies
  • AI-Powered Analysis: Get trading and investment grades based on advanced AI models
  • Technical Indicators: Access technical analysis grades and quantitative metrics
  • Price Data: Retrieve historical OHLCV (Open, High, Low, Close, Volume) data
  • Trading Signals: Receive AI-generated long and short trading signals
  • AI Agent: Interact with Token Metrics' AI chatbot for market insights
  • AI Reports: Access detailed technical, fundamental, and trading reports
  • Simple Interface: Intuitive API with Express.js integration
  • JavaScript & TypeScript Compatible: Works with both JavaScript and TypeScript projects

Installation

npm install tmai-api

You can find the package on npm at: tmai-api

Quick Start

TypeScript Usage

import { TokenMetricsClient } from 'tmai-api';

// Initialize the client with your API key
const client = new TokenMetricsClient('your-api-key');

// Get information for top cryptocurrencies
client.tokens.get({ symbol: 'BTC,ETH' })
  .then(tokens => {
    console.log(tokens);
  });

// Ask the AI agent a question (simplified method)
client.aiAgent.ask('What is your analysis of Bitcoin?')
  .then(response => {
    console.log(response);
  });

// Get just the answer text
client.aiAgent.getAnswerText('What is your Bitcoin forecast?')
  .then(answerText => {
    console.log(answerText);
  });

// Use chat method for conversation with multiple messages
client.aiAgent.chat([
  { user: 'What is Bitcoin?' },
  { user: 'What are its current market trends?' }
])
  .then(response => {
    console.log(response);
  });

// Get hourly trading signals
client.hourlyTradingSignals.get({
  token_id: '3375', // Bitcoin token ID
  limit: 10,
  page: 1
})
  .then(signals => {
    console.log(signals);
  });

// Get indices overview
client.indices.get({ indices_type: 'active' })
  .then(indices => {
    console.log(indices);
  });

// Get indices holdings
client.indicesHoldings.get({ id: 1 })
  .then(holdings => {
    console.log(holdings);
  });

// Get indices performance
client.indicesPerformance.get({
  id: 1,
  start_date: '2023-10-01',
  end_date: '2023-10-10'
})
  .then(performance => {
    console.log(performance);
  });

// Get TM Grades (multiple filter options)
client.tmGrades.get({ token_id: '3375' })
  .then(grades => {
    console.log(grades);
  });

// Get TM Grades by symbol
client.tmGrades.get({ symbol: 'BTC' })
  .then(grades => {
    console.log(grades);
  });

// Get TM Grades by token name
client.tmGrades.get({ token_name: 'Bitcoin' })
  .then(grades => {
    console.log(grades);
  });

// Get TM Grades Historical
client.tmGrades.getHistorical({ 
  token_id: '3375',
  start_date: '2025-07-01',
  end_date: '2025-07-05',
  limit: 100,
  page: 1
})
  .then(historicalGrades => {
    console.log(historicalGrades);
  });

// Get Technology Grades (multiple filter options)
client.technologyGrades.get({ token_id: '3306' })
  .then(techGrades => {
    console.log(techGrades);
  });

// Get Technology Grades by symbol
client.technologyGrades.get({ symbol: 'ETH' })
  .then(techGrades => {
    console.log(techGrades);
  });

// Get Technology Grades by token name
client.technologyGrades.get({ token_name: 'Ethereum' })
  .then(techGrades => {
    console.log(techGrades);
  });

// Get Technology Grades Historical
client.technologyGrades.getHistorical({ 
  symbol: 'BTC',
  start_date: '2025-07-01',
  end_date: '2025-07-05',
  limit: 50,
  page: 1
})
  .then(historicalTechGrades => {
    console.log(historicalTechGrades);
  });

// Get Fundamental Grades (multiple filter options)
client.fundamentalGrades.get({ token_id: '3375' })
  .then(fundamentalGrades => {
    console.log(fundamentalGrades);
  });

// Get Fundamental Grades by symbol
client.fundamentalGrades.get({ symbol: 'BTC' })
  .then(fundamentalGrades => {
    console.log(fundamentalGrades);
  });

// Get Fundamental Grades by token name
client.fundamentalGrades.get({ token_name: 'Bitcoin' })
  .then(fundamentalGrades => {
    console.log(fundamentalGrades);
  });

// Get Fundamental Grades Historical
client.fundamentalGrades.getHistorical({ 
  symbol: 'ETH',
  start_date: '2025-07-01',
  end_date: '2025-07-05',
  limit: 50,
  page: 1
})
  .then(historicalFundamentalGrades => {
    console.log(historicalFundamentalGrades);
  });

// Get moonshot tokens (AI-curated high potential picks)
client.moonshotTokens.get({ 
  type: 'active',
  sort_by: 'roi_pct',
  limit: 10 
})
  .then(moonshotTokens => {
    console.log(moonshotTokens);
  });

// Using async/await with type annotations
async function getTokenData(): Promise<void> {
  const tokens = await client.tokens.get({ symbol: 'BTC,ETH' });
  console.log(tokens);
}

JavaScript Usage

// ES Modules
import { TokenMetricsClient } from 'tmai-api';

// OR CommonJS
// const { TokenMetricsClient } = require('tmai-api');

// Initialize the client with your API key
const client = new TokenMetricsClient('your-api-key');

// Get information for top cryptocurrencies
client.tokens.get({ symbol: 'BTC,ETH' })
  .then(tokens => {
    console.log(tokens);
  });

// Get hourly trading signals
client.hourlyTradingSignals.get({
  token_id: '3375', 
  limit: 20
})
  .then(signals => {
    console.log(signals);
  });

// Using async/await
async function getTokenData() {
  const tokens = await client.tokens.get({ symbol: 'BTC,ETH' });
  console.log(tokens);
}

Available Endpoints

Endpoint Description Example
tokens Information about all supported tokens client.tokens.get({ symbol: 'BTC,ETH' })
hourlyOhlcv Hourly price and volume data client.hourlyOhlcv.get({ symbol: 'BTC', start_date: '2023-10-01', end_date: '2023-10-10' })
dailyOhlcv Daily price and volume data client.dailyOhlcv.get({ symbol: 'BTC', start_date: '2023-10-01', end_date: '2023-10-10' })
marketMetrics Market analytics with Bullish/Bearish indicator client.marketMetrics.get({ start_date: '2023-10-01', end_date: '2023-10-10' })
aiAgent Interact with Token Metrics AI chatbot client.aiAgent.ask('What is your Bitcoin forecast?') or client.aiAgent.getAnswerText('Question') or client.aiAgent.chat([{user: 'Question'}])
aiReports AI-generated comprehensive analyses including deep dives and investment analyses client.aiReports.get({ symbol: 'BTC,ETH' })
tradingSignals AI-generated trading signals client.tradingSignals.get({ symbol: 'BTC,ETH', start_date: '2023-10-01', end_date: '2023-10-10', signal: '1' })
hourlyTradingSignals Hourly AI-generated trading signals client.hourlyTradingSignals.get({ token_id: '3375'})
cryptoInvestors Latest list of crypto investors and their scores client.cryptoInvestors.get()
topMarketCapTokens Top tokens by market capitalization client.topMarketCapTokens.get({ top_k: 100 })
resistanceSupport Historical resistance and support levels for tokens client.resistanceSupport.get({ symbol: 'BTC' })
price Current token prices client.price.get({ symbol: 'BTC' })
quantmetrics Latest quantitative metrics for tokens client.quantmetrics.get({ symbol: 'BTC' })
pricePrediction Crypto price predictions under different market scenarios client.pricePrediction.get({ symbol: 'BTC' })
correlation Top 10 and Bottom 10 correlated tokens from top 100 market cap client.correlation.get({ symbol: 'BTC,ETH' })
indices Overview of active/passive indices with performance metrics client.indices.get({ indices_type: 'active' })
indicesHoldings Current holdings of an index with weight percentages, performance data, and trading grades client.indicesHoldings.get({ id: 1 })
indicesPerformance Historical performance data with cumulative ROI over time client.indicesPerformance.get({ id: 1, start_date: '2023-10-01', end_date: '2023-10-10' })
moonshotTokens Get AI-curated token picks with high breakout potential client.moonshotTokens.get({ type: 'active', sort_by: 'roi_pct' })
tmGrades Latest TM Grade and Fundamental Grade insights with signals and momentum client.tmGrades.get({ token_id: '3375' }) or client.tmGrades.get({ symbol: 'BTC' }) or client.tmGrades.get({ token_name: 'Bitcoin' })
tmGrades.getHistorical Historical TM Grade and Fundamental Grade data over a date range client.tmGrades.getHistorical({ token_id: '3375', start_date: '2023-10-01', end_date: '2023-10-10', limit: 100, page: 1 })
technologyGrades Technology Grade insights including activity, security, repository, collaboration, and DeFi scanner scores client.technologyGrades.get({ token_id: '3306' }) or client.technologyGrades.get({ symbol: 'ETH' }) or client.technologyGrades.get({ token_name: 'Ethereum' })
technologyGrades.getHistorical Historical Technology Grade data over a date range with all scoring metrics client.technologyGrades.getHistorical({ symbol: 'BTC', start_date: '2023-10-01', end_date: '2023-10-10', limit: 50, page: 1 })
fundamentalGrades Fundamental Grade insights including grade class, community score, exchange score, VC score, tokenomics score, and DeFi scanner score client.fundamentalGrades.get({ token_id: '3375' }) or client.fundamentalGrades.get({ symbol: 'BTC' }) or client.fundamentalGrades.get({ token_name: 'Bitcoin' })
fundamentalGrades.getHistorical Historical Fundamental Grade data over a date range with all scoring metrics client.fundamentalGrades.getHistorical({ symbol: 'ETH', start_date: '2023-10-01', end_date: '2023-10-10', limit: 50, page: 1 })

Authentication

All API requests require an API key. You can get your API key by signing up at Token Metrics.

// Initialize with your API key
const client = new TokenMetricsClient('your-api-key');

Error Handling

The SDK provides built-in error handling for API requests:

client.tokens.get({ symbol: 'INVALID_SYMBOL' })
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error('Error:', error.message);
    // Handle the error appropriately
  });

// Using async/await with try/catch
async function getTokenData(): Promise<void> {
  try {
    const data = await client.tokens.get({ symbol: 'INVALID_SYMBOL' });
    console.log(data);
  } catch (error: unknown) {
    if (error instanceof Error) {
      console.error('Error:', error.message);
    } else {
      console.error('Unknown error:', error);
    }
    // Handle the error appropriately
  }
}

Requirements

  • Node.js 14+
  • axios package
  • express package

Express.js Integration

This SDK can be easily integrated with Express.js to create your own API endpoints that leverage Token Metrics data:

import express from 'express';
import cors from 'cors';
import { TokenMetricsClient } from 'tmai-api';

// Initialize the Token Metrics client
const tmClient = new TokenMetricsClient('your-api-key');

// Create Express app
const app = express();
const port = 3000;

// Middleware
app.use(cors());
app.use(express.json());

// Get tokens endpoint
app.get('/api/tokens/:symbol', async (req, res) => {
  try {
    const { symbol } = req.params;
    const result = await tmClient.tokens.get({ symbol });
    res.json(result);
  } catch (error) {
    if (error instanceof Error) {
      res.status(500).json({ error: error.message });
    } else {
      res.status(500).json({ error: 'Unknown error occurred' });
    }
  }
});

// Get trading signals endpoint
app.get('/api/trading-signals/:symbol', async (req, res) => {
  try {
    const { symbol } = req.params;
    const { start_date, end_date, signal } = req.query;
    
    const result = await tmClient.tradingSignals.get({
      symbol,
      start_date: start_date as string | undefined,
      end_date: end_date as string | undefined,
      signal: signal as string | undefined
    });
    
    res.json(result);
  } catch (error) {
    if (error instanceof Error) {
      res.status(500).json({ error: error.message });
    } else {
      res.status(500).json({ error: 'Unknown error occurred' });
    }
  }
});

// Start the server
app.listen(port, () => {
  console.log(`Server running at http://localhost:${port}`);
});

For a complete Express.js server example, see the examples/express-server.js file.

Documentation

For complete API documentation, visit:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This SDK is distributed under the MIT License. See the LICENSE file for details.

Token Metrics Logo

Empowering investors with AI-powered crypto insights