Data Querying Solution

Access comprehensive blockchain data with NUVA Labs' powerful querying APIs. This solution covers everything from real-time data access to historical analysis and custom query building.

Overview

The Data Querying solution provides APIs for:

• Real-time Data: Live blockchain data and market information
• Historical Analysis: Access to historical blockchain data
• Custom Queries: Build complex queries for specific use cases
• Data Export: Export data for external analysis
• Analytics: Built-in analytics and reporting tools

Key Features

📊 Real-time Data

• Live blockchain status and metrics
• Real-time market data and prices
• Transaction monitoring and alerts
• Network health and performance

📈 Historical Analysis

• Historical price and volume data
• Transaction history and patterns
• Network growth and adoption metrics
• Custom time range analysis

🔍 Advanced Querying

• Custom query builder
• Complex filtering and sorting
• Aggregation and grouping
• Export to multiple formats

📋 Analytics & Reporting

• Built-in analytics dashboards
• Custom report generation
• Performance metrics
• Compliance reporting

Quick Start

1. Get Real-time Data

import { NUClient } from '@nu/sdk';

const client = new NUClient({
  clientId: process.env.NU_CLIENT_ID,
  clientSecret: process.env.NU_CLIENT_SECRET,
  environment: 'production',
});

await client.authenticate();

// Get current blockchain status
const status = await client.getBlockchainStatus();
console.log('Current block:', status.latestBlockHeight);

// Get market data
const marketData = await client.getMarketData('asset_1234567890');
console.log('Current price:', marketData.price);

2. Query Historical Data

// Get historical prices
const historicalData = await client.getHistoricalData('asset_1234567890', {
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  interval: '1d',
});

console.log('Historical data points:', historicalData.length);

3. Build Custom Query

// Custom query for large transactions
const largeTransactions = await client.query({
  table: 'transactions',
  filters: {
    amount: { $gte: 1000000 },
    date: { $gte: '2024-01-01' },
  },
  sort: { amount: -1 },
  limit: 100,
});

console.log('Large transactions:', largeTransactions.length);

API Reference

Data Querying Endpoints

Endpoint	Method	Description
/data/status	GET	Get blockchain status
/data/market	GET	Get market data
/data/historical	GET	Get historical data
/data/query	POST	Execute custom query
/data/export	POST	Export data
/data/analytics	GET	Get analytics

Real-time Data

Blockchain Status

const status = await client.getBlockchainStatus();
console.log('Network:', status.network);
console.log('Block height:', status.latestBlockHeight);
console.log('Chain ID:', status.chainId);
console.log('Node info:', status.nodeInfo);

Market Data

const marketData = await client.getMarketData('asset_1234567890');
console.log('Price:', marketData.price);
console.log('Volume:', marketData.volume);
console.log('Change 24h:', marketData.change24h);
console.log('Market cap:', marketData.marketCap);

Network Metrics

const metrics = await client.getNetworkMetrics();
console.log('Active validators:', metrics.activeValidators);
console.log('Total stake:', metrics.totalStake);
console.log('Network uptime:', metrics.uptime);

Historical Data

Price History

const priceHistory = await client.getHistoricalData('asset_1234567890', {
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  interval: '1h',
});

priceHistory.forEach((point) => {
  console.log(`${point.timestamp}: $${point.price}`);
});

Transaction History

const txHistory = await client.getTransactionHistory({
  accountId: 'acc_1234567890',
  startDate: '2024-01-01',
  endDate: '2024-01-31',
  limit: 1000,
});

console.log('Transactions:', txHistory.length);

Volume Analysis

const volumeData = await client.getVolumeAnalysis('asset_1234567890', {
  period: '30d',
  groupBy: 'day',
});

volumeData.forEach((day) => {
  console.log(`${day.date}: ${day.volume} volume`);
});

Custom Queries

Simple Query

const result = await client.query({
  table: 'transactions',
  filters: {
    amount: { $gte: 1000 },
    status: 'completed',
  },
  sort: { timestamp: -1 },
  limit: 100,
});

Complex Query

const result = await client.query({
  table: 'transactions',
  filters: {
    $and: [
      { amount: { $gte: 1000 } },
      { status: 'completed' },
      { timestamp: { $gte: '2024-01-01' } },
    ],
  },
  groupBy: ['assetId'],
  aggregation: {
    totalVolume: { $sum: 'amount' },
    count: { $count: '*' },
  },
  sort: { totalVolume: -1 },
});

Aggregation Queries

const analytics = await client.query({
  table: 'transactions',
  filters: {
    timestamp: { $gte: '2024-01-01' },
  },
  aggregation: {
    totalVolume: { $sum: 'amount' },
    averageAmount: { $avg: 'amount' },
    maxAmount: { $max: 'amount' },
    minAmount: { $min: 'amount' },
    count: { $count: '*' },
  },
});

Data Export

Export to CSV

const exportResult = await client.exportData({
  query: {
    table: 'transactions',
    filters: {
      timestamp: { $gte: '2024-01-01' },
    },
  },
  format: 'csv',
  filename: 'transactions_2024.csv',
});

console.log('Export URL:', exportResult.downloadUrl);

Export to JSON

const exportResult = await client.exportData({
  query: {
    table: 'market_data',
    filters: {
      assetId: 'asset_1234567890',
    },
  },
  format: 'json',
  filename: 'market_data.json',
});

Export to Excel

const exportResult = await client.exportData({
  query: {
    table: 'portfolio_performance',
    filters: {
      accountId: 'acc_1234567890',
    },
  },
  format: 'excel',
  filename: 'portfolio_performance.xlsx',
});

Analytics & Reporting

Built-in Analytics

const analytics = await client.getAnalytics('asset_1234567890', {
  period: '30d',
  metrics: ['price', 'volume', 'transactions'],
});

console.log('Price trend:', analytics.priceTrend);
console.log('Volume trend:', analytics.volumeTrend);
console.log('Transaction count:', analytics.transactionCount);

Custom Reports

const report = await client.generateReport({
  type: 'portfolio_performance',
  accountId: 'acc_1234567890',
  period: '30d',
  format: 'pdf',
});

console.log('Report URL:', report.downloadUrl);

Performance Metrics

const performance = await client.getPerformanceMetrics('acc_1234567890', {
  period: '30d',
  includeFees: true,
});

console.log('Total return:', performance.totalReturn);
console.log('Sharpe ratio:', performance.sharpeRatio);
console.log('Max drawdown:', performance.maxDrawdown);

Real-time Updates

WebSocket Connection

const ws = client.createWebSocket();

ws.on('blockUpdate', (block) => {
  console.log('New block:', block.height);
});

ws.on('priceUpdate', (price) => {
  console.log('Price update:', price.assetId, price.price);
});

ws.on('transactionUpdate', (tx) => {
  console.log('New transaction:', tx.id);
});

Event Subscriptions

// Subscribe to price updates
await client.subscribeToPriceUpdates('asset_1234567890');

// Subscribe to transaction updates
await client.subscribeToTransactions('acc_1234567890');

// Subscribe to block updates
await client.subscribeToBlocks();

Use Cases

1. Trading Dashboard

class TradingDashboard {
  constructor(client) {
    this.client = client;
  }

  async getDashboardData(assetId) {
    const [marketData, historicalData, analytics] = await Promise.all([
      this.client.getMarketData(assetId),
      this.client.getHistoricalData(assetId, { period: '7d' }),
      this.client.getAnalytics(assetId, { period: '7d' }),
    ]);

    return {
      currentPrice: marketData.price,
      priceChange: marketData.change24h,
      volume: marketData.volume,
      historicalData,
      analytics,
    };
  }
}

2. Portfolio Analyzer

class PortfolioAnalyzer {
  constructor(client) {
    this.client = client;
  }

  async analyzePortfolio(accountId) {
    const [portfolio, performance, transactions] = await Promise.all([
      this.client.getPortfolio(accountId),
      this.client.getPerformanceMetrics(accountId, { period: '30d' }),
      this.client.getTransactionHistory({ accountId, limit: 1000 }),
    ]);

    return {
      totalValue: portfolio.totalValue,
      performance,
      transactionCount: transactions.length,
      topAssets: portfolio.positions
        .sort((a, b) => b.value - a.value)
        .slice(0, 5),
    };
  }
}

3. Market Research Tool

class MarketResearchTool {
  constructor(client) {
    this.client = client;
  }

  async researchAsset(assetId) {
    const [marketData, historicalData, analytics, transactions] =
      await Promise.all([
        this.client.getMarketData(assetId),
        this.client.getHistoricalData(assetId, { period: '90d' }),
        this.client.getAnalytics(assetId, { period: '90d' }),
        this.client.query({
          table: 'transactions',
          filters: { assetId },
          limit: 1000,
        }),
      ]);

    return {
      marketData,
      historicalData,
      analytics,
      transactionCount: transactions.length,
      averageTransactionSize:
        transactions.reduce((sum, tx) => sum + tx.amount, 0) /
        transactions.length,
    };
  }
}

Best Practices

1. Query Optimization

• Use appropriate filters to limit results
• Implement pagination for large datasets
• Cache frequently accessed data
• Use aggregation for summary data

2. Real-time Updates

• Use WebSocket for real-time data
• Implement proper error handling
• Handle connection drops gracefully
• Monitor subscription limits

3. Data Export

• Use appropriate formats for your use case
• Implement proper error handling
• Monitor export limits
• Clean up temporary files

4. Performance

• Use batch operations when possible
• Implement proper caching
• Monitor API usage
• Use compression for large datasets

Error Handling

Common Errors

try {
  const data = await client.getHistoricalData('asset_1234567890');
} catch (error) {
  switch (error.code) {
    case 'INVALID_DATE_RANGE':
      console.error('Invalid date range provided');
      break;
    case 'RATE_LIMITED':
      console.error('Rate limited, please wait');
      break;
    case 'INSUFFICIENT_DATA':
      console.error('Insufficient data for requested period');
      break;
    case 'QUERY_TIMEOUT':
      console.error('Query timeout, try with smaller date range');
      break;
    default:
      console.error('Unexpected error:', error.message);
  }
}

Integration Examples

React Data Dashboard

import React, { useState, useEffect } from 'react';
import { NUClient } from '@nu/sdk';

function DataDashboard() {
  const [data, setData] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const client = new NUClient({
      clientId: process.env.REACT_APP_NU_CLIENT_ID,
      clientSecret: process.env.REACT_APP_NU_CLIENT_SECRET,
      environment: 'production',
    });

    const loadData = async () => {
      try {
        await client.authenticate();
        const [status, marketData] = await Promise.all([
          client.getBlockchainStatus(),
          client.getMarketData('asset_1234567890'),
        ]);
        setData({ status, marketData });
      } catch (error) {
        console.error('Failed to load data:', error);
      } finally {
        setLoading(false);
      }
    };

    loadData();
  }, []);

  if (loading) return <div>Loading data...</div>;

  return (
    <div>
      <h2>Data Dashboard</h2>
      <div>
        <h3>Blockchain Status</h3>
        <p>Block Height: {data?.status.latestBlockHeight}</p>
        <p>Network: {data?.status.network}</p>
      </div>
      <div>
        <h3>Market Data</h3>
        <p>Price: ${data?.marketData.price}</p>
        <p>Volume: {data?.marketData.volume}</p>
      </div>
    </div>
  );
}

Next Steps

• Explore Blockchain Integration for direct blockchain access
• Learn about Asset Management for asset operations
• Check out our API Reference for detailed endpoint documentation
• Review Best Practices for production deployment

---

Ready to start building? Let's explore Blockchain Integration for direct blockchain access!