{ "components": { "schemas": { "ErrorResponse": { "properties": { "error": { "type": "boolean" }, "message": { "type": "string" } }, "required": [ "error", "message" ], "type": "object" } }, "securitySchemes": { "ApiKeyAuth": { "description": "API key via X-API-Key header (or Authorization: ApiKey \u003ckey\u003e).", "in": "header", "name": "X-API-Key", "type": "apiKey" } } }, "info": { "description": "Public, read-only API endpoints under /api/v1/public/*.", "title": "Nebula Public API", "version": "1.0.2" }, "openapi": "3.0.3", "paths": { "/chat/completions": { "post": { "description": "Stateless Nebula Agent inference over Nebula's market intelligence layer. Pass a messages array; the latest user message is answered and up to six preceding messages are used as caller-managed conversation context. Set stream=true for OpenAI-style SSE text deltas. thinking_mode is optional and defaults to auto; use deep for deeper reasoning.", "requestBody": { "content": { "application/json": { "example": { "messages": [ { "content": "What narratives are heating up around Solana?", "role": "user" } ], "stream": true, "thinking_mode": "auto" }, "schema": { "properties": { "messages": { "items": { "properties": { "content": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "type": "array" }, "stream": { "type": "boolean" }, "thinking_mode": { "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "choices": [ { "finish_reason": "stop", "index": 0, "message": { "content": "Solana attention is being driven by renewed DEX volume, app-token speculation, and smart-money accumulation in adjacent ecosystem names.", "role": "assistant" } } ], "created": 1780934400, "id": "chatcmpl_example", "model": "nebula-agent", "object": "chat.completion", "usage": { "credits_used": 42 } }, "schema": { "properties": { "choices": { "items": { "properties": { "delta": { "nullable": true, "properties": { "content": { "type": "string" }, "role": { "type": "string" } }, "type": "object" }, "finish_reason": { "nullable": true, "type": "string" }, "index": { "type": "integer" }, "message": { "nullable": true, "properties": { "content": { "type": "string" }, "role": { "type": "string" } }, "type": "object" } }, "type": "object" }, "type": "array" }, "created": { "format": "int64", "type": "integer" }, "id": { "type": "string" }, "model": { "type": "string" }, "object": { "type": "string" }, "usage": { "nullable": true, "properties": { "credits_used": { "format": "int64", "type": "integer" } }, "type": "object" } }, "type": "object" } } }, "description": "OK. When stream=true, the response is text/event-stream with OpenAI-style chat.completion.chunk data frames." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Nebula Agent chat completions" } }, "/token/{id}/btc-dominance": { "get": { "description": "Token market cap as a percentage of Bitcoin market cap over time.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "change": { "description": "Current period-over-period change metrics.", "properties": { "pct": { "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "current": { "description": "Latest token market cap vs Bitcoin market cap snapshot.", "properties": { "btc_market_cap": { "description": "Bitcoin market capitalization in USD for this bucket.", "format": "double", "nullable": true, "type": "number" }, "market_cap_vs_btc_pct": { "description": "Token market cap as a percentage of Bitcoin market cap.", "format": "double", "nullable": true, "type": "number" }, "token_market_cap": { "description": "Token market capitalization in USD for this bucket.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "data": { "description": "Token market cap vs Bitcoin market cap time series.", "items": { "properties": { "btc_market_cap": { "description": "Bitcoin market capitalization in USD for this bucket.", "format": "double", "type": "number" }, "market_cap_vs_btc_pct": { "description": "Token market cap as a percentage of Bitcoin market cap.", "format": "double", "type": "number" }, "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" }, "token_market_cap": { "description": "Token market capitalization in USD for this bucket.", "format": "double", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token market cap vs BTC" } }, "/token/{id}/cultiness-index": { "get": { "description": "Cultiness index time-series for the token.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "series": { "description": "Cultiness index time series.", "items": { "properties": { "index": { "description": "Index value (typically 0-100 scale).", "format": "double", "type": "number" }, "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token cultiness index" } }, "/token/{id}/dumb-money-sentiment": { "get": { "description": "Sentiment time-series from dumb money cohort only.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Dumb-money sentiment series only.", "items": { "properties": { "bearish_posts": { "description": "Count of bearish posts included in the computed window.", "format": "double", "type": "number" }, "bucket_start": { "description": "UTC bucket start timestamp.", "format": "date-time", "type": "string" }, "bullish_posts": { "description": "Count of bullish posts included in the computed window.", "format": "double", "type": "number" }, "interval_bearish_posts": { "description": "Bearish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_bullish_posts": { "description": "Bullish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_neutral_posts": { "description": "Neutral posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_posts": { "description": "Posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "neutral_posts": { "description": "Count of neutral posts included in the computed window.", "format": "double", "type": "number" }, "sentiment_score": { "description": "Sentiment score on a 0-100 scale (higher is more bullish).", "format": "double", "type": "number" }, "sentiment_score_smoothed": { "description": "Smoothed sentiment score (0-100) when available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_score_z": { "description": "Z-score normalized sentiment where available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_signal": { "description": "Model-level sentiment signal used for downstream ranking when available.", "format": "double", "nullable": true, "type": "number" }, "total_posts": { "description": "Total posts included in the computed window.", "format": "double", "type": "number" }, "total_posts_smoothed": { "description": "Smoothed total-posts series where available.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token dumb money sentiment" } }, "/token/{id}/emotions-series": { "get": { "description": "Emotion distribution (joy, fear, etc.) over time for the token.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "series": { "anger": [ { "proportion": 0.08, "time": "2026-01-15T12:00:00Z" } ], "anticipation": [ { "proportion": 0.04, "time": "2026-01-15T12:00:00Z" } ], "boredom": [ { "proportion": 0.01, "time": "2026-01-15T12:00:00Z" } ], "confidence": [ { "proportion": 0.07, "time": "2026-01-15T12:00:00Z" } ], "disgust": [ { "proportion": 0.01, "time": "2026-01-15T12:00:00Z" } ], "distrust": [ { "proportion": 0.02, "time": "2026-01-15T12:00:00Z" } ], "fear": [ { "proportion": 0.15, "time": "2026-01-15T12:00:00Z" } ], "greed": [ { "proportion": 0.2, "time": "2026-01-15T12:00:00Z" } ], "joy": [ { "proportion": 0.25, "time": "2026-01-15T12:00:00Z" } ], "love": [ { "proportion": 0.03, "time": "2026-01-15T12:00:00Z" } ], "optimism": [ { "proportion": 0.06, "time": "2026-01-15T12:00:00Z" } ], "pessimism": [ { "proportion": 0.03, "time": "2026-01-15T12:00:00Z" } ], "sadness": [ { "proportion": 0.02, "time": "2026-01-15T12:00:00Z" } ], "surprise": [ { "proportion": 0.01, "time": "2026-01-15T12:00:00Z" } ], "trust": [ { "proportion": 0.02, "time": "2026-01-15T12:00:00Z" } ] } }, "schema": { "properties": { "metadata": { "description": "Computation metadata and model context.", "nullable": true, "properties": { "empty_bucket_policy": { "description": "How empty emotion buckets are represented in the series.", "type": "string" }, "empty_buckets": { "description": "Number of returned time buckets with no observed posts.", "type": "integer" }, "granularity": { "type": "string" }, "hours": { "description": "Lookback window in hours used to compute the metric.", "type": "integer" }, "latest_empty_bucket": { "description": "Most recent returned bucket with no observed posts, if any.", "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "series": { "additionalProperties": { "description": "Time series for a single emotion label.", "items": { "properties": { "proportion": { "description": "Proportion of posts or volume attributed to the emotion in this bucket.", "format": "double", "type": "number" }, "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" }, "description": "Per-emotion time series keyed by emotion label.", "type": "object", "x-allowed-keys": [ "anger", "anticipation", "boredom", "confidence", "disgust", "distrust", "fear", "greed", "joy", "love", "optimism", "pessimism", "sadness", "surprise", "trust" ] } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token emotions series" } }, "/token/{id}/fear-greed-index": { "get": { "description": "Fear and Greed index time-series for the token (0–100 scale). Diagnostics are omitted by default; pass debug=true to include model diagnostic fields.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } }, { "description": "Set true to include diagnostic fields in the response.", "in": "query", "name": "debug", "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "example": { "current": { "index": 42.7, "label": "Fear" }, "metadata": { "components": [ { "description": "Volatility component on a 0-100 greed scale.", "name": "volatility", "weight": 0.16 } ], "hours": 168, "labels": [ "Extreme Fear (0-24)", "Fear (25-49)", "Greed (50-74)", "Extreme Greed (75-100)" ], "scale": "0-100", "token_id": 1 }, "series": [ { "index": 42.7, "label": "Fear", "time": "2026-01-15T00:00:00Z" } ] }, "schema": { "properties": { "current": { "description": "Latest Fear and Greed index value.", "properties": { "index": { "description": "Index value (typically 0-100 scale).", "format": "double", "type": "number" }, "label": { "description": "Human-readable label for the index regime.", "type": "string" } }, "type": "object" }, "debug": { "additionalProperties": {}, "description": "Optional diagnostics included only when debug=true.", "type": "object" }, "metadata": { "description": "Model metadata and component weights.", "nullable": true, "properties": { "components": { "description": "Model components contributing to the index.", "items": { "properties": { "description": { "type": "string" }, "name": { "description": "Display name.", "type": "string" }, "weight": { "format": "double", "type": "number" } }, "type": "object" }, "type": "array" }, "hours": { "description": "Lookback window in hours used to compute the metric.", "type": "integer" }, "labels": { "description": "Human-readable labels for index regimes.", "items": { "type": "string" }, "type": "array" }, "scale": { "type": "string" }, "token_id": { "description": "Internal token identifier.", "format": "int64", "type": "integer" } }, "type": "object" }, "series": { "description": "Fear and Greed index time series.", "items": { "properties": { "absolute_momentum": { "description": "Composite absolute momentum component.", "format": "double", "type": "number" }, "debug_mom_long": { "type": "integer" }, "debug_mom_short": { "type": "integer" }, "debug_sent_long": { "type": "integer" }, "debug_sent_short": { "type": "integer" }, "debug_vol_long": { "type": "integer" }, "debug_vol_short": { "type": "integer" }, "emotions": { "format": "double", "type": "number" }, "immediate_momentum": { "description": "Momentum contribution from the most recent window.", "format": "double", "type": "number" }, "immediate_sentiment": { "description": "Sentiment contribution from the most recent window.", "format": "double", "type": "number" }, "immediate_volume": { "description": "Volume contribution from the most recent window.", "format": "double", "type": "number" }, "index": { "description": "Index value (typically 0-100 scale).", "format": "double", "type": "number" }, "label": { "description": "Human-readable label for the index regime.", "type": "string" }, "long_abs_momentum": { "description": "Long-horizon absolute momentum component.", "format": "double", "type": "number" }, "long_rel_momentum": { "description": "Long-horizon relative momentum component.", "format": "double", "type": "number" }, "momentum": { "format": "double", "type": "number" }, "post_volume": { "description": "Post volume used in the Fear and Greed index calculation.", "format": "double", "type": "number" }, "relative_momentum": { "description": "Composite relative momentum component.", "format": "double", "type": "number" }, "relative_volume": { "description": "Relative social or trading volume vs baseline.", "format": "double", "type": "number" }, "sentiment": { "format": "double", "type": "number" }, "short_abs_momentum": { "description": "Short-horizon absolute momentum component.", "format": "double", "type": "number" }, "short_rel_momentum": { "description": "Short-horizon relative momentum component.", "format": "double", "type": "number" }, "social_volume_multiplier": { "description": "Multiplier capturing how elevated social volume is vs baseline.", "format": "double", "type": "number" }, "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" }, "volatility": { "format": "double", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token Fear and Greed index" } }, "/token/{id}/follower-history": { "get": { "description": "Total follower counts over time for the token. Query by days.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in days.", "in": "query", "name": "days", "schema": { "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Follower history points for tracked project/handle accounts.", "items": { "properties": { "followers_count": { "description": "Total followers at the snapshot timestamp.", "format": "int64", "type": "integer" }, "snapshot_at": { "description": "UTC timestamp of the follower snapshot.", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token follower history" } }, "/token/{id}/intelligence": { "get": { "description": "Paginated curated intelligence for the token. Filter by time range, tags, and order.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of items to return (default and max may vary by endpoint).", "in": "query", "name": "limit", "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Number of items to skip for pagination (use with limit).", "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } }, { "description": "Return insights that start after this ISO 8601 date-time.", "in": "query", "name": "startTimeAfter", "schema": { "format": "date-time", "type": "string" } }, { "description": "Return insights that start before this ISO 8601 date-time.", "in": "query", "name": "startTimeBefore", "schema": { "format": "date-time", "type": "string" } }, { "description": "Return insights last updated after this ISO 8601 date-time.", "in": "query", "name": "updatedAtAfter", "schema": { "format": "date-time", "type": "string" } }, { "description": "Return insights last updated before this ISO 8601 date-time.", "in": "query", "name": "updatedAtBefore", "schema": { "format": "date-time", "type": "string" } }, { "description": "Filter insights by tags (comma-separated; include only insights with any of these tags).", "in": "query", "name": "tags", "schema": { "type": "string" } }, { "description": "Exclude insights that have any of these tags (comma-separated).", "in": "query", "name": "excludeTags", "schema": { "type": "string" } }, { "description": "Sort order for insights.", "in": "query", "name": "orderBy", "schema": { "enum": [ "start_time_asc", "start_time_desc", "updated_at_asc", "updated_at_desc", "created_at_asc", "created_at_desc", "importance_score_asc", "importance_score_desc" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "insights": { "description": "Paginated intelligence records related to the token.", "items": { "properties": { "accounts": { "items": { "properties": { "author_id": { "description": "Internal Nebula author identifier for this account.", "format": "int64", "type": "integer" }, "avatar_url": { "description": "URL of the account’s avatar image.", "nullable": true, "type": "string" }, "display_name": { "description": "Display name of the author account.", "nullable": true, "type": "string" }, "handle": { "nullable": true, "type": "string" }, "screen_name": { "description": "Screen name or handle on the source platform.", "type": "string" }, "source": { "description": "Origin/source of the insight data.", "type": "string" }, "source_user_id": { "description": "Identifier for the author on the source platform.", "type": "string" } }, "type": "object" }, "type": "array" }, "category": { "type": "string" }, "headline": { "type": "string" }, "id": { "format": "int64", "type": "integer" }, "importance_score": { "description": "Relative importance score for the insight (higher is more important).", "type": "integer" }, "primary_subject": { "nullable": true, "properties": { "account": { "nullable": true, "properties": { "author_id": { "description": "Internal Nebula author identifier for this account.", "format": "int64", "type": "integer" }, "avatar_url": { "description": "URL of the account’s avatar image.", "nullable": true, "type": "string" }, "display_name": { "description": "Display name of the author account.", "nullable": true, "type": "string" }, "handle": { "nullable": true, "type": "string" }, "screen_name": { "description": "Screen name or handle on the source platform.", "type": "string" }, "source": { "description": "Origin/source of the insight data.", "type": "string" }, "source_user_id": { "description": "Identifier for the author on the source platform.", "type": "string" } }, "type": "object" }, "project": { "nullable": true, "properties": { "handle": { "nullable": true, "type": "string" }, "image_url": { "description": "Project or token logo URL.", "type": "string" }, "internal_id": { "description": "Internal Nebula identifier for the account or project.", "format": "int64", "type": "integer" }, "name": { "description": "Display name.", "type": "string" }, "symbol": { "description": "Token symbol.", "type": "string" } }, "type": "object" }, "type": { "type": "string" } }, "type": "object" }, "projects": { "items": { "properties": { "handle": { "nullable": true, "type": "string" }, "image_url": { "description": "Project or token logo URL.", "type": "string" }, "internal_id": { "description": "Internal Nebula identifier for the account or project.", "format": "int64", "type": "integer" }, "name": { "description": "Display name.", "type": "string" }, "symbol": { "description": "Token symbol.", "type": "string" } }, "type": "object" }, "type": "array" }, "sentiment": { "type": "integer" }, "start_time": { "description": "When the insight became active or relevant (UTC).", "format": "date-time", "nullable": true, "type": "string" }, "summary": { "description": "Summary output for the endpoint.", "type": "string" }, "tags": { "description": "Tag selectors applied to the request.", "items": { "type": "string" }, "type": "array" }, "updated_at": { "description": "Last time the insight record was updated (UTC).", "format": "date-time", "nullable": true, "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token intelligence" } }, "/token/{id}/long-short-ratio": { "get": { "description": "Counts of unique long vs short callers over time for the token.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Time series of long/short caller counts.", "items": { "properties": { "long_callers": { "description": "Unique callers with bullish/long stance in the bucket.", "format": "int64", "type": "integer" }, "short_callers": { "description": "Unique callers with bearish/short stance in the bucket.", "format": "int64", "type": "integer" }, "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token long/short ratio" } }, "/token/{id}/mindshare": { "get": { "description": "Mindshare (social attention) time-series for the token. Optionally scope to a subset of social clusters via `clusters` (repeatable): with no clusters it's the token's share of all crypto attention; with clusters it's the token's share of attention within those clusters.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } }, { "description": "Optional. Repeatable. Scope the metric to a subset of social clusters (the union of the ids). Omit for ALL. Ids: smart_money, dumb_money, top_degens (caller-list, token-only), plus author clusters (developers, founders, team_leaders, project_accounts, vcs, asset_managers, dao_guild_funds, incubators, exchanges, kols, celebrities, media, marketer, shiller, ta_analyst, fa_analyst, macro_analyst, onchain_analyst, investigators, position_trader, swing_trader, day_trader, tribalist, perma_bull, doomer, political, nft, bots, automated_ai).", "explode": true, "in": "query", "name": "clusters", "schema": { "items": { "type": "string" }, "type": "array" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "mindshare": { "description": "Token social mindshare series.", "items": { "properties": { "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" }, "value": { "description": "Numeric metric value for the timestamp.", "format": "double", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token mindshare" } }, "/token/{id}/post-volume": { "get": { "description": "Post volume time-series for the token (all authors).", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "post_volume": { "description": "Token social post-volume series (all tracked authors).", "items": { "properties": { "tag_breakdown": { "description": "Per-bucket post-tag counts.", "items": { "properties": { "count": { "description": "Posts carrying the tag in the bucket.", "format": "int64", "type": "integer" }, "tag": { "description": "Normalized post tag.", "enum": [ "technical_analysis", "fundamental_analysis", "onchain", "macro", "fomo", "fud", "shilling", "news_report", "project_update", "alpha_leak", "prediction_market", "ipo", "etf", "listing", "delisting", "hack", "scam_warning", "airdrop", "whale", "breaking_news", "potential_catalyst", "mindshare", "fundraising", "rumour", "long_call", "short_call" ], "type": "string" } }, "type": "object" }, "type": "array" }, "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" }, "value": { "description": "Numeric metric value for the timestamp.", "format": "double", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token post volume" } }, "/token/{id}/sentiment-timeframes": { "get": { "description": "Sentiment broken down by short/medium/long timeframes.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "metadata": { "description": "Computation metadata for timeframe sentiment output.", "nullable": true, "properties": { "as_of": { "format": "date-time", "nullable": true, "type": "string" }, "calculation": { "type": "string" }, "formula": { "type": "string" }, "half_life_h": { "format": "double", "type": "number" }, "handle": { "nullable": true, "type": "string" }, "handles": { "description": "Normalized handles used by the query.", "items": { "type": "string" }, "type": "array" }, "lookback_days": { "type": "integer" }, "scale": { "type": "string" }, "token_id": { "description": "Internal token identifier.", "format": "int64", "nullable": true, "type": "integer" } }, "type": "object" }, "series": { "additionalProperties": { "items": { "properties": { "bucket_start": { "description": "UTC bucket start timestamp.", "format": "date-time", "type": "string" }, "interval_posts": { "description": "Posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "sentiment_score": { "description": "Sentiment score on a 0-100 scale (higher is more bullish).", "format": "double", "type": "number" }, "total_posts": { "description": "Total posts included in the computed window.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" }, "description": "Sentiment time series split by timeframe buckets (short, medium, long).", "type": "object" }, "summary": { "additionalProperties": { "format": "double", "type": "number" }, "description": "Current summary sentiment by timeframe key.", "type": "object" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token sentiment timeframes" } }, "/token/{id}/simple-sentiment": { "get": { "description": "Smoothed sentiment series (summary and cohorts). Optionally scope to a subset of social clusters via `clusters` (repeatable); the merged series is returned in `summary`. `clusters=smart_money` supersedes the dedicated smart-money-sentiment endpoint.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } }, { "description": "Optional. Repeatable. Scope the metric to a subset of social clusters (the union of the ids). Omit for ALL. Ids: smart_money, dumb_money, top_degens (caller-list, token-only), plus author clusters (developers, founders, team_leaders, project_accounts, vcs, asset_managers, dao_guild_funds, incubators, exchanges, kols, celebrities, media, marketer, shiller, ta_analyst, fa_analyst, macro_analyst, onchain_analyst, investigators, position_trader, swing_trader, day_trader, tribalist, perma_bull, doomer, political, nft, bots, automated_ai).", "explode": true, "in": "query", "name": "clusters", "schema": { "items": { "type": "string" }, "type": "array" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "cohorts": { "additionalProperties": { "items": { "properties": { "bearish_posts": { "description": "Count of bearish posts included in the computed window.", "format": "double", "type": "number" }, "bucket_start": { "description": "UTC bucket start timestamp.", "format": "date-time", "type": "string" }, "bullish_posts": { "description": "Count of bullish posts included in the computed window.", "format": "double", "type": "number" }, "interval_bearish_posts": { "description": "Bearish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_bullish_posts": { "description": "Bullish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_neutral_posts": { "description": "Neutral posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_posts": { "description": "Posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "neutral_posts": { "description": "Count of neutral posts included in the computed window.", "format": "double", "type": "number" }, "sentiment_score": { "description": "Sentiment score on a 0-100 scale (higher is more bullish).", "format": "double", "type": "number" }, "sentiment_score_smoothed": { "description": "Smoothed sentiment score (0-100) when available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_score_z": { "description": "Z-score normalized sentiment where available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_signal": { "description": "Model-level sentiment signal used for downstream ranking when available.", "format": "double", "nullable": true, "type": "number" }, "total_posts": { "description": "Total posts included in the computed window.", "format": "double", "type": "number" }, "total_posts_smoothed": { "description": "Smoothed total-posts series where available.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" }, "description": "Sentiment series by author-cohort id. Keys are strings \"0\" through \"5\"; higher ids represent higher-confidence/smart-money author buckets.", "type": "object" }, "summary": { "description": "Aggregate sentiment series across non-baseline cohorts.", "items": { "properties": { "bearish_posts": { "description": "Count of bearish posts included in the computed window.", "format": "double", "type": "number" }, "bucket_start": { "description": "UTC bucket start timestamp.", "format": "date-time", "type": "string" }, "bullish_posts": { "description": "Count of bullish posts included in the computed window.", "format": "double", "type": "number" }, "interval_bearish_posts": { "description": "Bearish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_bullish_posts": { "description": "Bullish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_neutral_posts": { "description": "Neutral posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_posts": { "description": "Posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "neutral_posts": { "description": "Count of neutral posts included in the computed window.", "format": "double", "type": "number" }, "sentiment_score": { "description": "Sentiment score on a 0-100 scale (higher is more bullish).", "format": "double", "type": "number" }, "sentiment_score_smoothed": { "description": "Smoothed sentiment score (0-100) when available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_score_z": { "description": "Z-score normalized sentiment where available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_signal": { "description": "Model-level sentiment signal used for downstream ranking when available.", "format": "double", "nullable": true, "type": "number" }, "total_posts": { "description": "Total posts included in the computed window.", "format": "double", "type": "number" }, "total_posts_smoothed": { "description": "Smoothed total-posts series where available.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token simple sentiment" } }, "/token/{id}/smart-money-bias": { "get": { "description": "Current bias (smart money sentiment minus overall sentiment) in basis points.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "current": { "description": "Latest point-in-time smart-money bias metrics.", "nullable": true, "properties": { "bucket_start": { "description": "UTC bucket start timestamp.", "format": "date-time", "type": "string" }, "overall_sentiment_score": { "description": "Overall sentiment score (0-100).", "format": "double", "type": "number" }, "sentiment_bias_bps": { "description": "Difference between smart-money and overall sentiment, in basis points.", "format": "double", "type": "number" }, "smart_money_sentiment_score": { "description": "Smart-money cohort sentiment score (0-100).", "format": "double", "type": "number" } }, "type": "object" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token smart money bias" } }, "/token/{id}/smart-money-post-volume": { "get": { "description": "Post volume time-series from smart money (giga brain) cohort only. Note: /token/{id}/smartmoney-post-volume is a deprecated alias and will be removed after 30 days.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "giga_brain_volume": { "description": "Token social post-volume series for smart-money cohort.", "items": { "properties": { "tag_breakdown": { "description": "Per-bucket post-tag counts for smart-money posts.", "items": { "properties": { "count": { "description": "Smart-money posts carrying the tag in the bucket.", "format": "int64", "type": "integer" }, "tag": { "description": "Normalized post tag.", "enum": [ "technical_analysis", "fundamental_analysis", "onchain", "macro", "fomo", "fud", "shilling", "news_report", "project_update", "alpha_leak", "prediction_market", "ipo", "etf", "listing", "delisting", "hack", "scam_warning", "airdrop", "whale", "breaking_news", "potential_catalyst", "mindshare", "fundraising", "rumour", "long_call", "short_call" ], "type": "string" } }, "type": "object" }, "type": "array" }, "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" }, "value": { "description": "Numeric metric value for the timestamp.", "format": "double", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token smart money post volume" } }, "/token/{id}/smart-money-sentiment": { "get": { "description": "Deprecated / redundant: prefer /token/{id}/simple-sentiment?clusters=smart_money. Sentiment time-series from smart money cohort only. Retained for backward compatibility.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Smart-money sentiment series only.", "items": { "properties": { "bearish_posts": { "description": "Count of bearish posts included in the computed window.", "format": "double", "type": "number" }, "bucket_start": { "description": "UTC bucket start timestamp.", "format": "date-time", "type": "string" }, "bullish_posts": { "description": "Count of bullish posts included in the computed window.", "format": "double", "type": "number" }, "interval_bearish_posts": { "description": "Bearish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_bullish_posts": { "description": "Bullish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_neutral_posts": { "description": "Neutral posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_posts": { "description": "Posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "neutral_posts": { "description": "Count of neutral posts included in the computed window.", "format": "double", "type": "number" }, "sentiment_score": { "description": "Sentiment score on a 0-100 scale (higher is more bullish).", "format": "double", "type": "number" }, "sentiment_score_smoothed": { "description": "Smoothed sentiment score (0-100) when available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_score_z": { "description": "Z-score normalized sentiment where available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_signal": { "description": "Model-level sentiment signal used for downstream ranking when available.", "format": "double", "nullable": true, "type": "number" }, "total_posts": { "description": "Total posts included in the computed window.", "format": "double", "type": "number" }, "total_posts_smoothed": { "description": "Smoothed total-posts series where available.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token smart money sentiment" } }, "/token/{id}/social-momentum": { "get": { "description": "Per-cluster social momentum: post volume, sentiment split (bullish/bearish/neutral) and unique posters over time, broken out by author cluster (e.g. day_trader, bots, vcs, media). Shows how broadly a token's chatter is spreading across social space and which cohorts drive it. The series is sparse — buckets in which a cluster had no posts are omitted.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "clusters": { "additionalProperties": { "description": "Time-bucketed post activity for a single author cluster.", "items": { "properties": { "avg_sentiment_score": { "description": "Post-weighted average sentiment for the cluster in the bucket (-100..100).", "format": "double", "type": "number" }, "bearish_posts": { "description": "Bearish posts in the bucket.", "format": "int64", "type": "integer" }, "bucket_start": { "description": "UTC start of the time bucket.", "format": "date-time", "type": "string" }, "bullish_posts": { "description": "Bullish posts in the bucket.", "format": "int64", "type": "integer" }, "neutral_posts": { "description": "Neutral posts in the bucket.", "format": "int64", "type": "integer" }, "total_posts": { "description": "Posts from this cluster in the bucket.", "format": "int64", "type": "integer" }, "unique_posters": { "description": "Distinct authors from this cluster in the bucket (upper bound above 1h granularity).", "format": "int64", "type": "integer" } }, "type": "object" }, "type": "array" }, "description": "Momentum series keyed by author-cluster id (e.g. day_trader, bots, vcs, media). Sparse: empty buckets are omitted.", "type": "object" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token social momentum" } }, "/token/{id}/top-degens-sentiment": { "get": { "description": "Sentiment time-series from top degens cohort only.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "description": "Top-degens sentiment series only.", "items": { "properties": { "bearish_posts": { "description": "Count of bearish posts included in the computed window.", "format": "double", "type": "number" }, "bucket_start": { "description": "UTC bucket start timestamp.", "format": "date-time", "type": "string" }, "bullish_posts": { "description": "Count of bullish posts included in the computed window.", "format": "double", "type": "number" }, "interval_bearish_posts": { "description": "Bearish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_bullish_posts": { "description": "Bullish posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_neutral_posts": { "description": "Neutral posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "interval_posts": { "description": "Posts in the current emitted interval bucket.", "format": "double", "nullable": true, "type": "number" }, "neutral_posts": { "description": "Count of neutral posts included in the computed window.", "format": "double", "type": "number" }, "sentiment_score": { "description": "Sentiment score on a 0-100 scale (higher is more bullish).", "format": "double", "type": "number" }, "sentiment_score_smoothed": { "description": "Smoothed sentiment score (0-100) when available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_score_z": { "description": "Z-score normalized sentiment where available.", "format": "double", "nullable": true, "type": "number" }, "sentiment_signal": { "description": "Model-level sentiment signal used for downstream ranking when available.", "format": "double", "nullable": true, "type": "number" }, "total_posts": { "description": "Total posts included in the computed window.", "format": "double", "type": "number" }, "total_posts_smoothed": { "description": "Smoothed total-posts series where available.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token top degens sentiment" } }, "/token/{id}/volatility-index": { "get": { "description": "Volatility index time-series for the token.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. Only `1d` is supported for this endpoint.", "in": "query", "name": "granularity", "schema": { "enum": [ "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "volatility": { "description": "Token volatility index series.", "items": { "properties": { "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" }, "value": { "description": "Numeric metric value for the timestamp.", "format": "double", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token volatility index" } }, "/token/{id}/volume-series": { "get": { "description": "Trading volume time-series for the token over the lookback window.", "parameters": [ { "description": "Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).", "in": "path", "name": "id", "required": true, "schema": { "type": "string" } }, { "description": "Lookback window in hours.", "in": "query", "name": "hours", "schema": { "minimum": 1, "type": "integer" } }, { "description": "Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.", "in": "query", "name": "granularity", "schema": { "enum": [ "1h", "2h", "4h", "12h", "1d" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "volume": { "description": "Token trading volume series.", "items": { "properties": { "time": { "description": "UTC timestamp for the data point.", "format": "date-time", "type": "string" }, "value": { "description": "Numeric metric value for the timestamp.", "format": "double", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token volume series" } }, "/tokens": { "get": { "description": "Paginated list of tokens with token_id, coingecko_id, symbol, name, price_usd, market_cap_usd, volume_usd, and address. Sorted by market_cap_usd DESC NULLS LAST by default. Use limit (max 500) and offset for paging.", "parameters": [ { "description": "Maximum number of items to return (default and max may vary by endpoint).", "in": "query", "name": "limit", "schema": { "maximum": 500, "minimum": 1, "type": "integer" } }, { "description": "Number of items to skip for pagination (use with limit).", "in": "query", "name": "offset", "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "limit": { "description": "Applied response size limit.", "type": "integer" }, "offset": { "description": "Applied page offset (always 0 for non-paginated token snapshots).", "type": "integer" }, "tokens": { "description": "Paged token rows. One entry per indexed token.", "items": { "properties": { "address": { "description": "Canonical contract address when available; null for native assets or unknown contracts.", "nullable": true, "type": "string" }, "coingecko_id": { "description": "CoinGecko asset identifier when available; null otherwise.", "nullable": true, "type": "string" }, "market_cap_usd": { "description": "Latest known market capitalization in USD; null when unavailable.", "format": "double", "nullable": true, "type": "number" }, "mindshare_24h": { "description": "Percent change in mindshare over the latest comparison window when available.", "format": "double", "nullable": true, "type": "number" }, "mindshare_change": { "description": "Percent change in mindshare over the latest comparison window when available.", "format": "double", "nullable": true, "type": "number" }, "mindshare_change_pct": { "description": "Percent change in mindshare over the latest comparison window when available.", "format": "double", "nullable": true, "type": "number" }, "name": { "description": "Human-readable token name.", "type": "string" }, "price_usd": { "description": "Latest known USD price; null when unavailable.", "format": "double", "nullable": true, "type": "number" }, "symbol": { "description": "Primary trading symbol.", "type": "string" }, "token_id": { "description": "Internal Nebula token identifier.", "format": "int64", "type": "integer" }, "volume_usd": { "description": "Latest known 24h volume in USD; null when unavailable.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" }, "total": { "description": "Total number of tokens in this response set.", "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token list (paged)" } }, "/tokens/search": { "get": { "description": "Search tokens by symbol, name, or contract address. Returns matching tokens ordered by relevance. Use q for the query string and limit (max 50) to cap results.", "parameters": [ { "description": "Search query. For tokens this matches symbol, name, or contract address; for accounts it matches display name or handle.", "in": "query", "name": "q", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of results to return (default 10, max 50).", "in": "query", "name": "limit", "schema": { "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "Normalized query string that was searched.", "type": "string" }, "tokens": { "description": "Matching tokens ordered by relevance.", "items": { "properties": { "coingecko_id": { "description": "CoinGecko asset identifier when available; null otherwise.", "nullable": true, "type": "string" }, "followers": { "description": "Project follower count when available; null otherwise.", "format": "int64", "nullable": true, "type": "integer" }, "handle": { "description": "Primary social handle for the token's project; null when unknown.", "nullable": true, "type": "string" }, "image_url": { "description": "Token logo URL.", "type": "string" }, "market_cap_usd": { "description": "Latest known market capitalization in USD; null when unavailable.", "format": "double", "nullable": true, "type": "number" }, "name": { "description": "Human-readable token name.", "type": "string" }, "price_change_24h_pct": { "description": "24h price change percentage; null when unavailable.", "format": "double", "nullable": true, "type": "number" }, "price_usd": { "description": "Latest known USD price; null when unavailable.", "format": "double", "nullable": true, "type": "number" }, "symbol": { "description": "Primary trading symbol.", "type": "string" }, "token_id": { "description": "Internal Nebula token identifier.", "format": "int64", "type": "integer" } }, "type": "object" }, "type": "array" }, "total": { "description": "Number of tokens returned in this response.", "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Token search" } }, "/tokens/trending": { "get": { "description": "Trending token snapshot sorted by mindshare_change DESC. Returns the same response shape as /tokens, with optional trend metrics (mindshare_24h, mindshare_change, mindshare_change_pct). Use limit (max 50).", "parameters": [ { "description": "Maximum number of trending tokens to return (default 10, max 50).", "in": "query", "name": "limit", "schema": { "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "limit": { "description": "Applied response size limit.", "type": "integer" }, "offset": { "description": "Applied page offset (always 0 for non-paginated token snapshots).", "type": "integer" }, "tokens": { "description": "Paged token rows. One entry per indexed token.", "items": { "properties": { "address": { "description": "Canonical contract address when available; null for native assets or unknown contracts.", "nullable": true, "type": "string" }, "coingecko_id": { "description": "CoinGecko asset identifier when available; null otherwise.", "nullable": true, "type": "string" }, "market_cap_usd": { "description": "Latest known market capitalization in USD; null when unavailable.", "format": "double", "nullable": true, "type": "number" }, "mindshare_24h": { "description": "Percent change in mindshare over the latest comparison window when available.", "format": "double", "nullable": true, "type": "number" }, "mindshare_change": { "description": "Percent change in mindshare over the latest comparison window when available.", "format": "double", "nullable": true, "type": "number" }, "mindshare_change_pct": { "description": "Percent change in mindshare over the latest comparison window when available.", "format": "double", "nullable": true, "type": "number" }, "name": { "description": "Human-readable token name.", "type": "string" }, "price_usd": { "description": "Latest known USD price; null when unavailable.", "format": "double", "nullable": true, "type": "number" }, "symbol": { "description": "Primary trading symbol.", "type": "string" }, "token_id": { "description": "Internal Nebula token identifier.", "format": "int64", "type": "integer" }, "volume_usd": { "description": "Latest known 24h volume in USD; null when unavailable.", "format": "double", "nullable": true, "type": "number" } }, "type": "object" }, "type": "array" }, "total": { "description": "Total number of tokens in this response set.", "type": "integer" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Trending token list" } }, "/users/search": { "get": { "description": "Search tracked accounts by display name or handle. Returns matching accounts ordered by relevance. Use q for the query string and limit (max 50) to cap results.", "parameters": [ { "description": "Search query. For tokens this matches symbol, name, or contract address; for accounts it matches display name or handle.", "in": "query", "name": "q", "required": true, "schema": { "type": "string" } }, { "description": "Maximum number of results to return (default 10, max 50).", "in": "query", "name": "limit", "schema": { "maximum": 50, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "query": { "description": "Normalized query string that was searched.", "type": "string" }, "total": { "description": "Number of accounts returned in this response.", "type": "integer" }, "users": { "description": "Matching accounts ordered by relevance.", "items": { "properties": { "author_id": { "description": "Internal Nebula author identifier.", "format": "int64", "type": "integer" }, "avatar_url": { "description": "URL of the account's avatar image.", "type": "string" }, "bot_score": { "description": "Model score based on the quality of the account's smart-money followers.", "format": "double", "type": "number" }, "cohort": { "description": "Cohort classification id for the account.", "type": "integer" }, "display_name": { "description": "Display name of the account.", "type": "string" }, "followers": { "description": "Total follower count for the account.", "format": "int64", "type": "integer" }, "name": { "description": "Account name.", "type": "string" }, "profile_url": { "description": "Normalized query string that was searched.", "type": "string" }, "screen_name": { "description": "Screen name or handle on the source platform.", "type": "string" }, "smart_followers_score": { "description": "Model score based on the quality of the account's smart-money followers.", "format": "double", "type": "number" }, "smart_money_score": { "description": "Model score based on the quality of the account's smart-money followers.", "format": "double", "type": "number" }, "source": { "description": "Source platform for the account (e.g. twitter).", "type": "string" }, "source_user_id": { "description": "Identifier for the account on the source platform.", "type": "string" }, "verified": { "description": "Whether the account is verified on the source platform.", "type": "boolean" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } }, "description": "Bad Request" } }, "summary": "Account search" } } }, "security": [ { "ApiKeyAuth": [] } ], "servers": [ { "url": "/api/v1/public" } ] }