Premium Feature: Advanced analytics requires a Growth or Enterprise plan. Upgrade →

ssUSD Analytics API

Get comprehensive insights into ssUSD supply, velocity, usage patterns, and market dynamics with our Analytics API.

🎯 Overview

The Analytics API provides real-time and historical data about ssUSD, including:

Supply metrics and growth
Transaction velocity and patterns
User adoption and retention
Cross-chain activity
Market dynamics and liquidity

📊 Real-Time Metrics

GET /v1/stablecoin/analytics/realtime

Returns current ssUSD metrics updated every second.

curl https://api.stateset.com/v1/stablecoin/analytics/realtime \
  -H "Authorization: Bearer sk_test_..."

Response:

{
  "timestamp": "2024-06-25T12:00:00Z",
  "total_supply": 1234567890.50,
  "total_supply_formatted": "$1,234,567,890.50",
  "circulation": {
    "circulating_supply": 1200000000.00,
    "locked_supply": 34567890.50,
    "burned_supply": 0.00
  },
  "volume": {
    "volume_24h": 89012345.67,
    "volume_7d": 623456789.12,
    "volume_30d": 2345678901.23,
    "avg_transaction_size": 2345.67
  },
  "velocity": {
    "velocity_24h": 0.072,
    "velocity_7d": 0.519,
    "velocity_30d": 1.954
  },
  "activity": {
    "transactions_24h": 37984,
    "active_wallets_24h": 12567,
    "new_wallets_24h": 892,
    "unique_receivers_24h": 8934
  },
  "distribution": {
    "top_10_concentration": 0.234,
    "top_100_concentration": 0.567,
    "gini_coefficient": 0.72
  },
  "chains": {
    "stateset": 987654321.00,
    "base": 123456789.00,
    "solana": 98765432.00,
    "cosmos_ibc": 24691358.50
  }
}

📈 Historical Data

GET /v1/stablecoin/analytics/historical

Query historical ssUSD metrics with customizable time ranges and granularity. Query Parameters:

start_date

string

required

Start date in ISO 8601 formatExample: 2024-01-01T00:00:00Z

end_date

string

required

End date in ISO 8601 formatExample: 2024-06-25T23:59:59Z

granularity

string

default:"daily"

Data point frequencyOptions: hourly, daily, weekly, monthly

metrics

array

Specific metrics to includeDefault: All available metrics

Example Request:

const historical = await stateset.stablecoin.analytics.historical({
  start_date: '2024-01-01',
  end_date: '2024-06-25',
  granularity: 'daily',
  metrics: ['supply', 'volume', 'velocity', 'active_wallets']
});

// Plot supply growth
const supplyChart = historical.data.map(d => ({
  date: d.date,
  supply: d.metrics.supply
}));

🔍 Transaction Analytics

GET /v1/stablecoin/analytics/transactions

Analyze transaction patterns and behaviors. Query Parameters:

period

string

default:"24h"

Analysis periodOptions: 1h, 24h, 7d, 30d, 90d, 1y

breakdown_by

string

Group transactions by categoryOptions: size, type, chain, hour_of_day, day_of_week

Response Example:

{
  "period": "24h",
  "transaction_count": 37984,
  "total_volume": 89012345.67,
  "size_distribution": [
    { "range": "$0-100", "count": 12567, "percentage": 33.1 },
    { "range": "$100-1000", "count": 18934, "percentage": 49.8 },
    { "range": "$1000-10000", "count": 5892, "percentage": 15.5 },
    { "range": "$10000+", "count": 591, "percentage": 1.6 }
  ],
  "type_breakdown": {
    "transfers": { "count": 25678, "volume": 45678901.23 },
    "payments": { "count": 8901, "volume": 23456789.01 },
    "defi": { "count": 3405, "volume": 19876655.43 }
  },
  "peak_hours": [
    { "hour": 14, "timezone": "UTC", "transactions": 2134 },
    { "hour": 15, "timezone": "UTC", "transactions": 2098 },
    { "hour": 16, "timezone": "UTC", "transactions": 1987 }
  ],
  "average_confirmation_time": 0.8,
  "failed_transaction_rate": 0.0012
}

👥 User Analytics

GET /v1/stablecoin/analytics/users

Understand user behavior and adoption patterns.

const userAnalytics = await stateset.stablecoin.analytics.users({
  period: '30d',
  cohort_analysis: true
});

// Cohort retention data
console.log('30-day retention:', userAnalytics.cohort_retention.day_30);

Response:

{
  "total_users": 156789,
  "new_users_period": 12567,
  "active_users_period": 45678,
  "user_segments": {
    "retail": { "count": 145678, "percentage": 92.9 },
    "institutional": { "count": 8901, "percentage": 5.7 },
    "merchant": { "count": 2210, "percentage": 1.4 }
  },
  "balance_distribution": [
    { "range": "$0-100", "users": 78901, "percentage": 50.3 },
    { "range": "$100-1000", "users": 45678, "percentage": 29.1 },
    { "range": "$1000-10000", "users": 23456, "percentage": 15.0 },
    { "range": "$10000+", "users": 8754, "percentage": 5.6 }
  ],
  "cohort_retention": {
    "day_1": 0.85,
    "day_7": 0.67,
    "day_30": 0.52,
    "day_90": 0.41
  },
  "user_lifetime_value": {
    "average": 2345.67,
    "median": 567.89,
    "top_10_percent": 23456.78
  }
}

🌊 Liquidity Analytics

GET /v1/stablecoin/analytics/liquidity

Monitor ssUSD liquidity across venues and chains.

const liquidity = await stateset.stablecoin.analytics.liquidity();

// Find best liquidity sources
const bestVenues = liquidity.venues
  .sort((a, b) => b.depth_2_percent - a.depth_2_percent)
  .slice(0, 5);

Response:

{
  "total_liquidity": 456789012.34,
  "venues": [
    {
      "name": "StateSet Native",
      "chain": "stateset",
      "liquidity": 234567890.12,
      "depth_2_percent": 12345678.90,
      "spread": 0.0001,
      "volume_24h": 34567890.12
    },
    {
      "name": "Uniswap V3",
      "chain": "base",
      "liquidity": 123456789.01,
      "depth_2_percent": 6789012.34,
      "spread": 0.0003,
      "volume_24h": 23456789.01
    }
  ],
  "liquidity_score": 94.5,
  "market_depth": {
    "buy_1m": 0.0002,
    "sell_1m": 0.0002,
    "buy_10m": 0.0012,
    "sell_10m": 0.0013
  }
}

📊 Custom Reports

POST /v1/stablecoin/analytics/reports

Generate custom analytics reports with specific parameters.

// Create monthly treasury report
const report = await stateset.stablecoin.analytics.createReport({
  type: 'treasury_report',
  period: {
    start: '2024-06-01',
    end: '2024-06-30'
  },
  sections: [
    'balance_summary',
    'transaction_analysis',
    'yield_performance',
    'risk_metrics'
  ],
  format: 'pdf',
  email_to: 'cfo@company.com'
});

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

🔔 Analytics Webhooks

Subscribe to analytics events and thresholds.

// Alert when supply changes significantly
const webhook = await stateset.webhooks.create({
  url: 'https://yourapp.com/webhooks/analytics',
  events: ['analytics.supply_change'],
  filters: {
    change_percentage: 5, // Alert on 5% changes
    time_window: '1h'
  }
});

// Alert on unusual activity
const activityWebhook = await stateset.webhooks.create({
  url: 'https://yourapp.com/webhooks/activity',
  events: ['analytics.unusual_activity'],
  config: {
    volume_spike: 3, // 3x normal volume
    wallet_concentration: 0.7 // 70% concentration
  }
});

📈 Visualization Examples

Supply Growth Chart

// Fetch data for chart
const supplyData = await stateset.stablecoin.analytics.historical({
  start_date: '2024-01-01',
  end_date: new Date().toISOString(),
  granularity: 'daily',
  metrics: ['supply']
});

// Format for Chart.js
const chartData = {
  labels: supplyData.data.map(d => d.date),
  datasets: [{
    label: 'ssUSD Supply',
    data: supplyData.data.map(d => d.metrics.supply),
    borderColor: 'rgb(75, 192, 192)',
    tension: 0.1
  }]
};

Transaction Heatmap

// Get hourly transaction data
const heatmapData = await stateset.stablecoin.analytics.transactions({
  period: '7d',
  breakdown_by: 'hour_and_day'
});

// Format for heatmap visualization
const heatmap = heatmapData.hourly_pattern.map(h => ({
  day: h.day_of_week,
  hour: h.hour,
  value: h.transaction_count,
  intensity: h.transaction_count / heatmapData.max_hourly
}));

🎯 Use Cases

Risk Management Dashboard

class RiskDashboard {
  async getMetrics() {
    const [realtime, liquidity, users] = await Promise.all([
      stateset.stablecoin.analytics.realtime(),
      stateset.stablecoin.analytics.liquidity(),
      stateset.stablecoin.analytics.users({ period: '24h' })
    ]);
    
    return {
      concentration_risk: this.calculateConcentrationRisk(realtime),
      liquidity_risk: this.calculateLiquidityRisk(liquidity),
      velocity_risk: this.calculateVelocityRisk(realtime),
      overall_score: this.calculateOverallRisk(realtime, liquidity, users)
    };
  }
  
  calculateConcentrationRisk(data) {
    const gini = data.distribution.gini_coefficient;
    return {
      score: (1 - gini) * 100,
      level: gini > 0.8 ? 'high' : gini > 0.6 ? 'medium' : 'low',
      recommendation: gini > 0.8 ? 'Monitor large holder activities' : 'Healthy distribution'
    };
  }
}

Market Making Analytics

// Analyze spread and volume for market making
const marketAnalytics = await stateset.stablecoin.analytics.liquidity({
  include_orderbook: true,
  depth_levels: [100000, 1000000, 10000000]
});

const opportunities = marketAnalytics.venues
  .filter(v => v.spread > 0.0005 && v.volume_24h > 1000000)
  .map(v => ({
    venue: v.name,
    potential_profit: v.volume_24h * v.spread * 0.5,
    required_capital: v.depth_2_percent * 2
  }));

Reserves API

Real-time reserve composition

Transactions API

Detailed transaction data

Attestations

Monthly audit reports

Webhooks

Real-time notifications

StateSet Commerce

​ssUSD Analytics API

​🎯 Overview

​📊 Real-Time Metrics

​GET /v1/stablecoin/analytics/realtime

​📈 Historical Data

​GET /v1/stablecoin/analytics/historical

​🔍 Transaction Analytics

​GET /v1/stablecoin/analytics/transactions

​👥 User Analytics

​GET /v1/stablecoin/analytics/users

​🌊 Liquidity Analytics

​GET /v1/stablecoin/analytics/liquidity

​📊 Custom Reports

​POST /v1/stablecoin/analytics/reports

​🔔 Analytics Webhooks

​📈 Visualization Examples

​Supply Growth Chart

​Transaction Heatmap

​🎯 Use Cases

​Risk Management Dashboard

​Market Making Analytics

​🔗 Related Endpoints

Reserves API

Transactions API

Attestations

Webhooks

ssUSD Analytics API

🎯 Overview

📊 Real-Time Metrics

GET /v1/stablecoin/analytics/realtime

📈 Historical Data

GET /v1/stablecoin/analytics/historical

🔍 Transaction Analytics

GET /v1/stablecoin/analytics/transactions

👥 User Analytics

GET /v1/stablecoin/analytics/users

🌊 Liquidity Analytics

GET /v1/stablecoin/analytics/liquidity

📊 Custom Reports

POST /v1/stablecoin/analytics/reports

🔔 Analytics Webhooks

📈 Visualization Examples

Supply Growth Chart

Transaction Heatmap

🎯 Use Cases

Risk Management Dashboard

Market Making Analytics

🔗 Related Endpoints