Developer Documentation

Everything you need to integrate Nebula Analytics into your applications

🚀 Getting Started

Welcome to Nebula Analytics! This guide will help you get started with our blockchain analytics platform in minutes.

Quick Start

📌 Note: You'll need an API key to get started. Sign up at nebulasolai.xyz to get your free key.

1. Installation

Install the Nebula SDK using npm or yarn:

# NPM
npm install @nebula/analytics-sdk

# Yarn
yarn add @nebula/analytics-sdk

# pnpm
pnpm add @nebula/analytics-sdk

2. Initialize the Client

Set up your Nebula client with your API key:

import { NebulaClient } from '@nebula/analytics-sdk';

const nebula = new NebulaClient({
    apiKey: 'YOUR_API_KEY',
    network: 'solana-mainnet' // or 'ethereum', 'polygon', etc.
});

// Test your connection
const status = await nebula.ping();
console.log('Connected:', status.ok);

3. Make Your First Request

Analyze a token to get comprehensive data:

const tokenAddress = 'So11111111111111111111111111111111111111112';
const analysis = await nebula.tokens.analyze(tokenAddress);

console.log('Token:', analysis.symbol);
console.log('Price:', analysis.price);
console.log('Market Cap:', analysis.marketCap);
console.log('Risk Score:', analysis.riskScore);

✅ Success! You're now ready to build with Nebula Analytics.

🔐 Authentication

All API requests require authentication using an API key. Include your key in the request headers.

API Key Authentication

// JavaScript/Node.js
const response = await fetch('https://api.nebulasolai.xyz/v1/tokens/analyze', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        address: 'TOKEN_ADDRESS'
    })
});

Python Example

import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(
    'https://api.nebulasolai.xyz/v1/tokens/analyze',
    headers=headers,
    json={'address': 'TOKEN_ADDRESS'}
)

data = response.json()
print(data)

⚠️ Security: Never expose your API key in client-side code. Use environment variables and keep keys secure.

Rate Limits by Tier

Plan	Requests/Minute	Daily Limit
Free	60	10,000
Pro	300	100,000
Enterprise	Unlimited	Unlimited

💎 Token Analysis

Get comprehensive analysis for any token including price, liquidity, holders, and risk assessment.

Analyze Token

POST /v1/tokens/analyze

Request Body

Parameter	Type	Required	Description
`address`	string	✓	Token contract address
`network`	string		Network (default: solana)
`includeHolders`	boolean		Include top holders data

Example Request

const analysis = await nebula.tokens.analyze({
    address: 'So11111111111111111111111111111111111111112',
    network: 'solana',
    includeHolders: true
});

console.log(analysis);

Response Example

{
    "success": true,
    "data": {
        "address": "So11111111111111111111111111111111111111112",
        "symbol": "SOL",
        "name": "Wrapped Solana",
        "price": 98.45,
        "priceChange24h": 5.2,
        "marketCap": 45000000000,
        "volume24h": 2500000000,
        "liquidity": 850000000,
        "holders": 1245000,
        "riskScore": 15,
        "riskLevel": "LOW",
        "securityChecks": {
            "mintable": false,
            "freezable": false,
            "renounced": true,
            "liquidityLocked": true
        },
        "topHolders": [
            {
                "address": "5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1",
                "balance": 1234567.89,
                "percentage": 2.5
            }
        ]
    }
}

💡 Tip: Use the riskScore (0-100) to quickly assess token safety. Lower is safer.

👛 Wallet Tracking

Track wallet activities, portfolio values, and transaction history in real-time.

Get Wallet Portfolio

GET /v1/wallets/{address}/portfolio

const wallet = await nebula.wallets.getPortfolio(
    '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1'
);

console.log('Total Value:', wallet.totalValue);
console.log('Tokens:', wallet.tokens.length);
console.log('PnL 24h:', wallet.pnl24h);

Track Wallet Transactions

GET /v1/wallets/{address}/transactions

const txs = await nebula.wallets.getTransactions(
    '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1',
    {
        limit: 50,
        type: 'all' // 'swap', 'transfer', 'all'
    }
);

txs.forEach(tx => {
    console.log(`${tx.type}: ${tx.amount} ${tx.symbol}`);
});

🤖 AI Insights

Get AI-powered insights and analysis for tokens, wallets, and market trends.

Ask AI Assistant

POST /v1/ai/query

const aiResponse = await nebula.ai.query({
    question: "Is SOL a good investment right now?",
    context: {
        includeMarketData: true,
        includeRiskAnalysis: true
    }
});

console.log(aiResponse.answer);
console.log('Confidence:', aiResponse.confidence);

Generate Token Report

const report = await nebula.ai.generateReport({
    tokenAddress: 'So11111111111111111111111111111111111111112',
    includeChart: true,
    format: 'markdown' // or 'html', 'pdf'
});

console.log(report.summary);
console.log(report.recommendations);

⚡ Real-time WebSockets

Subscribe to real-time updates for prices, transactions, and wallet activities.

Connect to WebSocket

const ws = nebula.ws.connect({
    apiKey: 'YOUR_API_KEY'
});

// Subscribe to token price updates
ws.subscribe('token.price', {
    address: 'So11111111111111111111111111111111111111112'
}, (data) => {
    console.log('New price:', data.price);
    console.log('Change:', data.priceChange);
});

// Subscribe to wallet transactions
ws.subscribe('wallet.transactions', {
    address: '5Q544fKrFoe6tsEbD7S8EmxGTJYAKtTVhAW5Q5pge4j1'
}, (tx) => {
    console.log('New transaction:', tx);
});

Available Channels

Channel	Description	Update Frequency
`token.price`	Real-time price updates	~1 second
`token.volume`	Volume changes	~5 seconds
`wallet.transactions`	New transactions	Instant
`market.trends`	Market-wide trends	~30 seconds

⚠️ Error Handling

Handle API errors gracefully with proper error codes and messages.

Error Response Format

{
    "success": false,
    "error": {
        "code": "INVALID_ADDRESS",
        "message": "The provided token address is invalid",
        "details": {
            "address": "invalid_address_format"
        }
    }
}

Common Error Codes

Code	HTTP Status	Description
`INVALID_API_KEY`	401	API key is missing or invalid
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INVALID_ADDRESS`	400	Invalid wallet or token address
`RESOURCE_NOT_FOUND`	404	Requested resource doesn't exist
`INTERNAL_ERROR`	500	Server error occurred

Error Handling Example

try {
    const analysis = await nebula.tokens.analyze(tokenAddress);
    console.log(analysis);
} catch (error) {
    if (error.code === 'RATE_LIMIT_EXCEEDED') {
        console.log('Rate limit hit, retrying in 60 seconds...');
        await new Promise(resolve => setTimeout(resolve, 60000));
        // Retry logic here
    } else if (error.code === 'INVALID_ADDRESS') {
        console.error('Invalid token address provided');
    } else {
        console.error('Unexpected error:', error.message);
    }
}