Analytics API Overview

The TokenOps Analytics API provides comprehensive insights, real-time monitoring, and data analytics for all TokenOps contracts. It offers RESTful endpoints, WebSocket connections, webhook notifications, and advanced querying capabilities for vesting, staking, airdrops, and token distribution contracts.

What is the Analytics API?

The Analytics API is a RESTful service that provides insights and data for TokenOps vesting contracts and token analytics, offering:

• Multi-Chain Support: Ethereum mainnet, testnets, and compatible chains
• Advanced Filtering: Query grants by recipient, token, event type, and more
• Pagination Support: Efficient data retrieval for large datasets
• RESTful Design: Standard HTTP methods with JSON responses

To learn more take a look into our Swagger API

API Architecture

API Client Setup

Installation and Configuration

import { TokenOpsApi } from 'tokenops-sdk';

// Initialize API client
const api = new TokenOpsApi('your-api-key-here');

// Test connection
const pingResponse = await api.ping();
console.log('API Status:', pingResponse.message);

Authentication

The API uses bearer token authentication. Your API key is included in the Authorization header for all requests:

// API key is automatically included in all requests
const api = new TokenOpsApi(process.env.TOKENOPS_API_KEY!);

// Test authentication with ping
try {
  const response = await api.ping();
  console.log('Authentication successful:', response);
} catch (error) {
  console.error('Authentication failed:', error);
}

Core API Endpoints

1. Vesting Analytics

Comprehensive vesting contract insights and data:

// Get vesting contract overview
const vestingInfo = await api.vesting(chainId, contractAddress, tokenAddress);
console.log('Vesting info:', {
  address: vestingInfo.data.address,
  chainId: vestingInfo.data.chainId,
  token: vestingInfo.data.token,
  totalAllocated: vestingInfo.data.totalAllocated,
  totalWithdrawn: vestingInfo.data.totalWithdrawn,
  totalClaimable: vestingInfo.data.totalClaimable,
  totalVested: vestingInfo.data.totalVested,
  grantsCount: vestingInfo.data.grantsCount,
  latestBlockUpdate: vestingInfo.data.latestBlockUpdate
});

// Get specific vesting grants with filtering
const grants = await api.vestingGrants(
  chainId,
  contractAddress,
  tokenAddress,        // Optional: filter by token
  recipientAddress,    // Optional: filter by recipient
  eventType,          // Optional: filter by event type
  page,               // Optional: page number (default: 1)
  size                // Optional: page size (default: 10)
);

console.log('Grants:', {
  total: grants.total,
  page: grants.page,
  size: grants.size,
  pages: grants.pages,
  items: grants.items
});

// Get vesting insights and analytics
const insights = await api.vestingInsights(
  chainId,
  contractAddress,
  tokenAddress,        // Optional: filter by token
  recipientAddress,    // Optional: filter by recipient
  page,               // Optional: page number
  size                // Optional: page size
);

console.log('Insights:', insights.items);

// Get vesting events
const events = await api.vestingEvents(
  chainId,
  contractAddress,
  tokenAddress,        // Optional: filter by token
  recipientAddress,    // Optional: filter by recipient
  eventType,          // Optional: filter by event type
  page,               // Optional: page number
  size                // Optional: page size
);

console.log('Events:', events.items);

2. Token Supply Analytics

Track token supply and distribution:

// Get total supply for a token
const totalSupply = await api.totalSupply(tokenAddress);
console.log('Total supply:', totalSupply.total_supply);

// Get vested supply for a token
const vestedSupply = await api.vestedSupply(tokenAddress);
console.log('Vested supply:', vestedSupply.vested_supply);

// Calculate supply analytics
const supplyAnalytics = {
  totalSupply: totalSupply.total_supply,
  vestedSupply: vestedSupply.vested_supply,
  vestedPercentage: Number(vestedSupply.vested_supply) / Number(totalSupply.total_supply) * 100,
  circulatingSupply: totalSupply.total_supply - vestedSupply.vested_supply
};

console.log('Supply analytics:', supplyAnalytics);

3. Contract Analytics

Get vesting contract count for multiple wallets:

// Get contract count for multiple wallets
const walletAddresses = [
  '0x742d35Cc6632C0532c718F4D8c2b1D1f8a1B9F36',
  '0x123...',
  '0x456...'
];

const contractCounts = await api.vestingContractCount(walletAddresses);
console.log('Contract counts:', contractCounts.results);

// Process results
contractCounts.results.forEach(result => {
  console.log(`Wallet ${result.recipient}: ${result.countract_count} contracts`);
});

Real-time Event Monitoring

Webhook Subscriptions

The API provides webhook subscriptions for real-time vesting event notifications:

// Subscribe to vesting events via webhook
async function subscribeToVestingEvents() {
  const subscription = await api.vestingSubscribe(
    chainId,
    contractAddress,
    ['Claim', 'Revoke'], // Desired events
    'https://your-app.com/webhooks/vesting' // Your webhook URL
  );

  console.log('Webhook subscription response:', subscription);
  // Response: { status_code: 200, response_type: 'success', description: 'Subscription created' }
}

// Example with error handling
async function setupVestingWebhook() {
  try {
    const result = await api.vestingSubscribe(
      11155111, // Sepolia testnet
      '0x742d35Cc6632C0532c718F4D8c2b1D1f8a1B9F36',
      ['Claim', 'Revoke'],
      'https://your-app.com/webhooks/vesting' // Your webhook URL
    );

    if (result.status_code === 200) {
      console.log('✅ Webhook subscription successful');
    }
  } catch (error) {
    console.error('❌ Webhook subscription failed:', error);
  }
}

Error Handling

Basic Error Handling

// Handle API errors properly
async function safeApiCall() {
  try {
    const vestingData = await api.vesting(1, contractAddress);
    console.log('Success:', vestingData);
  } catch (error) {
    if (error.response) {
      // API returned an error response
      console.error('API Error:', {
        status: error.response.status,
        message: error.response.data?.message || error.message
      });
    } else if (error.request) {
      // Network error
      console.error('Network Error:', error.message);
    } else {
      // Other error
      console.error('Error:', error.message);
    }
  }
}

Next Steps

Now that you understand the Analytics API:

1. Get API Key - Sign up for API access at the TokenOps dashboard
2. Test Integration - Try the code examples provided in this documentation
3. Set up Webhooks - Configure real-time notifications using the webhook methods
4. Explore SDK - Use the full TokenOps SDK

Resources

• API Base URL: https://api.tokenops.xyz/v1/
• Authentication: Bearer token (API key required)
• Rate Limits: Contact Tokenops for current limits
• SDK Documentation: Quick Start