Analytics & Events API

Analytics & Events API

Overview

Endpoints for retrieving NFT analytics, tracking events, and monitoring collection statistics.

Get Collection Stats

Retrieve statistical data for a collection.

GET api.bloclabs.com/v1/nfts/collections/{collection_id}/stats

Response

{
    "status": "success",
    "data": {
        "collection_address": "0x789...def",
        "stats": {
            "total_supply": 10000,
            "num_owners": 5000,
            "floor_price": {
                "value": "0.5",
                "currency": "ETH",
                "usd_value": "1000.00"
            },
            "total_volume": {
                "value": "1000",
                "currency": "ETH",
                "usd_value": "2000000.00"
            },
            "average_price": {
                "value": "0.8",
                "currency": "ETH",
                "usd_value": "1600.00"
            },
            "market_cap": {
                "value": "5000",
                "currency": "ETH",
                "usd_value": "10000000.00"
            }
        },
        "time_series": {
            "daily_volume": [
                {
                    "date": "2024-03-15",
                    "volume": "100",
                    "transactions": 50
                }
            ],
            "floor_price_history": [
                {
                    "date": "2024-03-15",
                    "price": "0.5"
                }
            ]
        }
    }
}

Get NFT Activity

Retrieve activity history for a specific NFT.

GET api.bloclabs.com/v1/nfts/{token_id}/activity

Query Parameters

{
    "event_type": "all",    // all, transfer, sale, listing, offer
    "from_date": "2024-01-01",
    "to_date": "2024-03-15",
    "limit": 10,
    "offset": 0
}

Response

{
    "status": "success",
    "data": {
        "activities": [
            {
                "event_type": "SALE",
                "from_address": "0x123...abc",
                "to_address": "0x789...def",
                "price": {
                    "value": "0.5",
                    "currency": "ETH",
                    "usd_value": "1000.00"
                },
                "transaction_hash": "0xabc...123",
                "timestamp": "2024-03-15T10:00:00Z",
                "marketplace": "OpenSea"
            }
        ],
        "pagination": {
            "total": 50,
            "limit": 10,
            "offset": 0
        }
    }
}

Get Market Trends

Retrieve market trends and analytics.

GET api.bloclabs.com/v1/nfts/market/trends

Query Parameters

{
    "time_range": "24h",    // 24h, 7d, 30d, all
    "sort_by": "volume"     // volume, sales, floor_price
}

Response

{
    "status": "success",
    "data": {
        "trending_collections": [
            {
                "collection_address": "0x789...def",
                "name": "Popular Collection",
                "volume_24h": {
                    "value": "100",
                    "currency": "ETH",
                    "change_percentage": 25.5
                },
                "floor_price": {
                    "value": "0.5",
                    "currency": "ETH",
                    "change_percentage": 10.2
                },
                "sales_count": 50
            }
        ],
        "market_overview": {
            "total_volume_24h": {
                "value": "10000",
                "currency": "ETH"
            },
            "total_sales_24h": 5000,
            "average_price_24h": {
                "value": "2",
                "currency": "ETH"
            }
        }
    }
}

Get Ownership Distribution

Analyze ownership distribution for a collection.

GET api.bloclabs.com/v1/nfts/collections/{collection_id}/distribution

Response

{
    "status": "success",
    "data": {
        "unique_holders": 5000,
        "concentration": {
            "top_10_holders": 25.5,    // Percentage owned by top 10
            "top_50_holders": 45.2,
            "top_100_holders": 60.1
        },
        "holding_periods": {
            "less_than_30d": 20.5,     // Percentage of total supply
            "30d_to_90d": 30.2,
            "90d_to_180d": 25.1,
            "more_than_180d": 24.2
        }
    }
}

Error Responses

Invalid Date Range

{
    "status": "error",
    "message": "Invalid date range",
    "code": "INVALID_DATE_RANGE",
    "data": {
        "max_range": "365 days"
    }
}

Data Not Available

{
    "status": "error",
    "message": "Analytics data not available",
    "code": "DATA_NOT_AVAILABLE",
    "data": {
        "reason": "Insufficient trading history"
    }
}

Rate Limit Exceeded

{
    "status": "error",
    "message": "Rate limit exceeded for analytics",
    "code": "RATE_LIMIT_EXCEEDED",
    "data": {
        "retry_after": 60
    }
}

Notes

• Analytics data is updated every 5 minutes

• Historical data may be limited for new collections

• Price data includes all major marketplaces

• Volume calculations exclude wash trading

• Trend data may have slight delays

• Rate limits apply to analytics endpoints