# Nebula Public API

Base URL: https://nebula-api.hiddensystems.ai/api/v1/public
Reference index: https://docs.hiddensystems.ai/nebula/reference/
OpenAPI JSON: https://docs.hiddensystems.ai/nebula/openapi.json

This file concatenates the main endpoint reference pages in Markdown so AI agents can read the whole public API without rendering JavaScript.

# Nebula Agent chat completions

- Method: `POST`
- Path: `/chat/completions`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/post-chat-completions/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=post-chat-completions

## 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.

## cURL Example

```bash
curl --request POST \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/chat/completions' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {
      "content": "What narratives are heating up around Solana?",
      "role": "user"
    }
  ],
  "stream": true,
  "thinking_mode": "auto"
}'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

No query parameters for this endpoint.

## Request Body

Media type: `application/json`

```json
{
  "messages": [
    {
      "content": "What narratives are heating up around Solana?",
      "role": "user"
    }
  ],
  "stream": true,
  "thinking_mode": "auto"
}
```

## Response

OK. When stream=true, the response is text/event-stream with OpenAI-style chat.completion.chunk data frames.

- `choices` (array<object>): No description provided.
- `choices[].delta` (object): No description provided.
- `choices[].delta.content` (string): No description provided.
- `choices[].delta.role` (string): No description provided.
- `choices[].finish_reason` (string): No description provided.
- `choices[].index` (integer): No description provided.
- `choices[].message` (object): No description provided.
- `choices[].message.content` (string): No description provided.
- `choices[].message.role` (string): No description provided.
- `created` (integer (int64)): No description provided.
- `id` (string): No description provided.
- `model` (string): No description provided.
- `object` (string): No description provided.
- `usage` (object): No description provided.
- `usage.credits_used` (integer (int64)): No description provided.

Media type: `application/json`

## JSON Response

```json
{
  "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
  }
}
```


# Token market cap vs BTC

- Method: `GET`
- Path: `/token/{id}/btc-dominance`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-btc-dominance/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-btc-dominance

## Description

Token market cap as a percentage of Bitcoin market cap over time.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/btc-dominance' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `change` (object): Current period-over-period change metrics.
- `change.pct` (number (double)): No description provided.
- `current` (object): Latest token market cap vs Bitcoin market cap snapshot.
- `current.btc_market_cap` (number (double)): Bitcoin market capitalization in USD for this bucket.
- `current.market_cap_vs_btc_pct` (number (double)): Token market cap as a percentage of Bitcoin market cap.
- `current.token_market_cap` (number (double)): Token market capitalization in USD for this bucket.
- `data` (array<object>): Token market cap vs Bitcoin market cap time series.
- `data[].btc_market_cap` (number (double)): Bitcoin market capitalization in USD for this bucket.
- `data[].market_cap_vs_btc_pct` (number (double)): Token market cap as a percentage of Bitcoin market cap.
- `data[].time` (string (date-time)): UTC timestamp for the data point.
- `data[].token_market_cap` (number (double)): Token market capitalization in USD for this bucket.

Media type: `application/json`

## JSON Response

```json
{
  "change": {
    "pct": 0
  },
  "current": {
    "btc_market_cap": 0,
    "market_cap_vs_btc_pct": 0,
    "token_market_cap": 0
  },
  "data": [
    {
      "btc_market_cap": 0,
      "market_cap_vs_btc_pct": 0,
      "time": "2026-01-15T12:00:00Z",
      "token_market_cap": 0
    }
  ]
}
```


# Token cultiness index

- Method: `GET`
- Path: `/token/{id}/cultiness-index`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-cultiness-index/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-cultiness-index

## Description

Cultiness index time-series for the token.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/cultiness-index' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `series` (array<object>): Cultiness index time series.
- `series[].index` (number (double)): Index value (typically 0-100 scale).
- `series[].time` (string (date-time)): UTC timestamp for the data point.

Media type: `application/json`

## JSON Response

```json
{
  "series": [
    {
      "index": 0,
      "time": "2026-01-15T12:00:00Z"
    }
  ]
}
```


# Token dumb money sentiment

- Method: `GET`
- Path: `/token/{id}/dumb-money-sentiment`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-dumb-money-sentiment/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-dumb-money-sentiment

## Description

Sentiment time-series from dumb money cohort only.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/dumb-money-sentiment' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `data` (array<object>): Dumb-money sentiment series only.
- `data[].bearish_posts` (number (double)): Count of bearish posts included in the computed window.
- `data[].bucket_start` (string (date-time)): UTC bucket start timestamp.
- `data[].bullish_posts` (number (double)): Count of bullish posts included in the computed window.
- `data[].interval_bearish_posts` (number (double)): Bearish posts in the current emitted interval bucket.
- `data[].interval_bullish_posts` (number (double)): Bullish posts in the current emitted interval bucket.
- `data[].interval_neutral_posts` (number (double)): Neutral posts in the current emitted interval bucket.
- `data[].interval_posts` (number (double)): Posts in the current emitted interval bucket.
- `data[].neutral_posts` (number (double)): Count of neutral posts included in the computed window.
- `data[].sentiment_score` (number (double)): Sentiment score on a 0-100 scale (higher is more bullish).
- `data[].sentiment_score_smoothed` (number (double)): Smoothed sentiment score (0-100) when available.
- `data[].sentiment_score_z` (number (double)): Z-score normalized sentiment where available.
- `data[].sentiment_signal` (number (double)): Model-level sentiment signal used for downstream ranking when available.
- `data[].total_posts` (number (double)): Total posts included in the computed window.
- `data[].total_posts_smoothed` (number (double)): Smoothed total-posts series where available.

Media type: `application/json`

## JSON Response

```json
{
  "data": [
    {
      "bearish_posts": 0,
      "bucket_start": "2026-01-15T12:00:00Z",
      "bullish_posts": 0,
      "interval_bearish_posts": 0,
      "interval_bullish_posts": 0,
      "interval_neutral_posts": 0,
      "interval_posts": 0,
      "neutral_posts": 0,
      "sentiment_score": 0,
      "sentiment_score_smoothed": 0,
      "sentiment_score_z": 0,
      "sentiment_signal": 0,
      "total_posts": 0,
      "total_posts_smoothed": 0
    }
  ]
}
```


# Token emotions series

- Method: `GET`
- Path: `/token/{id}/emotions-series`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-emotions-series/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-emotions-series

## Description

Emotion distribution (joy, fear, etc.) over time for the token.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/emotions-series' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `metadata` (object): Computation metadata and model context.
- `metadata.empty_bucket_policy` (string): How empty emotion buckets are represented in the series.
- `metadata.empty_buckets` (integer): Number of returned time buckets with no observed posts.
- `metadata.granularity` (string): No description provided.
- `metadata.hours` (integer): Lookback window in hours used to compute the metric.
- `metadata.latest_empty_bucket` (string (date-time)): Most recent returned bucket with no observed posts, if any.
- `series` (object, allowed keys: anger, anticipation, boredom, confidence, disgust, distrust, fear, greed, joy, love, optimism, pessimism, sadness, surprise, trust): Per-emotion time series keyed by emotion label.

Media type: `application/json`

## JSON Response

```json
{
  "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"
      }
    ]
  }
}
```


# Token Fear and Greed index

- Method: `GET`
- Path: `/token/{id}/fear-greed-index`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-fear-greed-index/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-fear-greed-index

## 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.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/fear-greed-index' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.
- `debug` (boolean, optional): Set true to include diagnostic fields in the response.

## Response

OK

- `current` (object): Latest Fear and Greed index value.
- `current.index` (number (double)): Index value (typically 0-100 scale).
- `current.label` (string): Human-readable label for the index regime.
- `debug` (object): Optional diagnostics included only when debug=true.
- `metadata` (object): Model metadata and component weights.
- `metadata.components` (array<object>): Model components contributing to the index.
- `metadata.components[].description` (string): No description provided.
- `metadata.components[].name` (string): Display name.
- `metadata.components[].weight` (number (double)): No description provided.
- `metadata.hours` (integer): Lookback window in hours used to compute the metric.
- `metadata.labels` (array<string>): Human-readable labels for index regimes.
- `metadata.scale` (string): No description provided.
- `metadata.token_id` (integer (int64)): Internal token identifier.
- `series` (array<object>): Fear and Greed index time series.
- `series[].absolute_momentum` (number (double)): Composite absolute momentum component.
- `series[].debug_mom_long` (integer): No description provided.
- `series[].debug_mom_short` (integer): No description provided.
- `series[].debug_sent_long` (integer): No description provided.
- `series[].debug_sent_short` (integer): No description provided.
- `series[].debug_vol_long` (integer): No description provided.
- `series[].debug_vol_short` (integer): No description provided.
- `series[].emotions` (number (double)): No description provided.
- `series[].immediate_momentum` (number (double)): Momentum contribution from the most recent window.
- `series[].immediate_sentiment` (number (double)): Sentiment contribution from the most recent window.
- `series[].immediate_volume` (number (double)): Volume contribution from the most recent window.
- `series[].index` (number (double)): Index value (typically 0-100 scale).
- `series[].label` (string): Human-readable label for the index regime.
- `series[].long_abs_momentum` (number (double)): Long-horizon absolute momentum component.
- `series[].long_rel_momentum` (number (double)): Long-horizon relative momentum component.
- `series[].momentum` (number (double)): No description provided.
- `series[].post_volume` (number (double)): Post volume used in the Fear and Greed index calculation.
- `series[].relative_momentum` (number (double)): Composite relative momentum component.
- `series[].relative_volume` (number (double)): Relative social or trading volume vs baseline.
- `series[].sentiment` (number (double)): No description provided.
- `series[].short_abs_momentum` (number (double)): Short-horizon absolute momentum component.
- `series[].short_rel_momentum` (number (double)): Short-horizon relative momentum component.
- `series[].social_volume_multiplier` (number (double)): Multiplier capturing how elevated social volume is vs baseline.
- `series[].time` (string (date-time)): UTC timestamp for the data point.
- `series[].volatility` (number (double)): No description provided.

Media type: `application/json`

## JSON Response

```json
{
  "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"
    }
  ]
}
```


# Token follower history

- Method: `GET`
- Path: `/token/{id}/follower-history`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-follower-history/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-follower-history

## Description

Total follower counts over time for the token. Query by days.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/follower-history' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `days` (integer, optional): Lookback window in days.

## Response

OK

- `data` (array<object>): Follower history points for tracked project/handle accounts.
- `data[].followers_count` (integer (int64)): Total followers at the snapshot timestamp.
- `data[].snapshot_at` (string (date-time)): UTC timestamp of the follower snapshot.

Media type: `application/json`

## JSON Response

```json
{
  "data": [
    {
      "followers_count": 0,
      "snapshot_at": "2026-01-15T12:00:00Z"
    }
  ]
}
```


# Token intelligence

- Method: `GET`
- Path: `/token/{id}/intelligence`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-intelligence/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-intelligence

## Description

Paginated curated intelligence for the token. Filter by time range, tags, and order.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/intelligence' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `limit` (integer, optional): Maximum number of items to return (default and max may vary by endpoint).
- `offset` (integer, optional): Number of items to skip for pagination (use with limit).
- `startTimeAfter` (string (date-time), optional): Return insights that start after this ISO 8601 date-time.
- `startTimeBefore` (string (date-time), optional): Return insights that start before this ISO 8601 date-time.
- `updatedAtAfter` (string (date-time), optional): Return insights last updated after this ISO 8601 date-time.
- `updatedAtBefore` (string (date-time), optional): Return insights last updated before this ISO 8601 date-time.
- `tags` (string, optional): Filter insights by tags (comma-separated; include only insights with any of these tags).
- `excludeTags` (string, optional): Exclude insights that have any of these tags (comma-separated).
- `orderBy` (string, optional): Sort order for insights.

## Response

OK

- `insights` (array<object>): Paginated intelligence records related to the token.
- `insights[].accounts` (array<object>): No description provided.
- `insights[].accounts[].author_id` (integer (int64)): Internal Nebula author identifier for this account.
- `insights[].accounts[].avatar_url` (string): URL of the account’s avatar image.
- `insights[].accounts[].display_name` (string): Display name of the author account.
- `insights[].accounts[].handle` (string): No description provided.
- `insights[].accounts[].screen_name` (string): Screen name or handle on the source platform.
- `insights[].accounts[].source` (string): Origin/source of the insight data.
- `insights[].accounts[].source_user_id` (string): Identifier for the author on the source platform.
- `insights[].category` (string): No description provided.
- `insights[].headline` (string): No description provided.
- `insights[].id` (integer (int64)): No description provided.
- `insights[].importance_score` (integer): Relative importance score for the insight (higher is more important).
- `insights[].primary_subject` (object): No description provided.
- `insights[].primary_subject.account` (object): No description provided.
- `insights[].primary_subject.account.author_id` (integer (int64)): Internal Nebula author identifier for this account.
- `insights[].primary_subject.account.avatar_url` (string): URL of the account’s avatar image.
- `insights[].primary_subject.account.display_name` (string): Display name of the author account.
- `insights[].primary_subject.account.handle` (string): No description provided.
- `insights[].primary_subject.account.screen_name` (string): Screen name or handle on the source platform.
- `insights[].primary_subject.account.source` (string): Origin/source of the insight data.
- `insights[].primary_subject.account.source_user_id` (string): Identifier for the author on the source platform.
- `insights[].primary_subject.project` (object): No description provided.
- `insights[].primary_subject.project.handle` (string): No description provided.
- `insights[].primary_subject.project.image_url` (string): Project or token logo URL.
- `insights[].primary_subject.project.internal_id` (integer (int64)): Internal Nebula identifier for the account or project.
- `insights[].primary_subject.project.name` (string): Display name.
- `insights[].primary_subject.project.symbol` (string): Token symbol.
- `insights[].primary_subject.type` (string): No description provided.
- `insights[].projects` (array<object>): No description provided.
- `insights[].projects[].handle` (string): No description provided.
- `insights[].projects[].image_url` (string): Project or token logo URL.
- `insights[].projects[].internal_id` (integer (int64)): Internal Nebula identifier for the account or project.
- `insights[].projects[].name` (string): Display name.
- `insights[].projects[].symbol` (string): Token symbol.
- `insights[].sentiment` (integer): No description provided.
- `insights[].start_time` (string (date-time)): When the insight became active or relevant (UTC).
- `insights[].summary` (string): Summary output for the endpoint.
- `insights[].tags` (array<string>): Tag selectors applied to the request.
- `insights[].updated_at` (string (date-time)): Last time the insight record was updated (UTC).

Media type: `application/json`

## JSON Response

```json
{
  "insights": [
    {
      "accounts": [
        {
          "author_id": 0,
          "avatar_url": "string",
          "display_name": "string",
          "handle": "string",
          "screen_name": "string",
          "source": "string",
          "source_user_id": "string"
        }
      ],
      "category": "string",
      "headline": "string",
      "id": 0,
      "importance_score": 0,
      "primary_subject": {
        "account": {
          "author_id": 0,
          "avatar_url": "string",
          "display_name": "string",
          "handle": "string",
          "screen_name": "string",
          "source": "string",
          "source_user_id": "string"
        },
        "project": {
          "handle": "string",
          "image_url": "string",
          "internal_id": 0,
          "name": "string",
          "symbol": "string"
        },
        "type": "string"
      },
      "projects": [
        {
          "handle": "string",
          "image_url": "string",
          "internal_id": 0,
          "name": "string",
          "symbol": "string"
        }
      ],
      "sentiment": 0,
      "start_time": "2026-01-15T12:00:00Z",
      "summary": "string",
      "tags": [
        "string"
      ],
      "updated_at": "2026-01-15T12:00:00Z"
    }
  ]
}
```


# Token long/short ratio

- Method: `GET`
- Path: `/token/{id}/long-short-ratio`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-long-short-ratio/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-long-short-ratio

## Description

Counts of unique long vs short callers over time for the token.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/long-short-ratio' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `data` (array<object>): Time series of long/short caller counts.
- `data[].long_callers` (integer (int64)): Unique callers with bullish/long stance in the bucket.
- `data[].short_callers` (integer (int64)): Unique callers with bearish/short stance in the bucket.
- `data[].time` (string (date-time)): UTC timestamp for the data point.

Media type: `application/json`

## JSON Response

```json
{
  "data": [
    {
      "long_callers": 0,
      "short_callers": 0,
      "time": "2026-01-15T12:00:00Z"
    }
  ]
}
```


# Token mindshare

- Method: `GET`
- Path: `/token/{id}/mindshare`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-mindshare/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-mindshare

## 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.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/mindshare' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.
- `clusters` (array<string>, optional): 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).

## Response

OK

- `mindshare` (array<object>): Token social mindshare series.
- `mindshare[].time` (string (date-time)): UTC timestamp for the data point.
- `mindshare[].value` (number (double)): Numeric metric value for the timestamp.

Media type: `application/json`

## JSON Response

```json
{
  "mindshare": [
    {
      "time": "2026-01-15T12:00:00Z",
      "value": 0
    }
  ]
}
```


# Token post volume

- Method: `GET`
- Path: `/token/{id}/post-volume`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-post-volume/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-post-volume

## Description

Post volume time-series for the token (all authors).

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/post-volume' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `post_volume` (array<object>): Token social post-volume series (all tracked authors).
- `post_volume[].tag_breakdown` (array<object>): Per-bucket post-tag counts.
- `post_volume[].tag_breakdown[].count` (integer (int64)): Posts carrying the tag in the bucket.
- `post_volume[].tag_breakdown[].tag` (string, 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): Normalized post tag.
- `post_volume[].time` (string (date-time)): UTC timestamp for the data point.
- `post_volume[].value` (number (double)): Numeric metric value for the timestamp.

Media type: `application/json`

## JSON Response

```json
{
  "post_volume": [
    {
      "tag_breakdown": [
        {
          "count": 0,
          "tag": "technical_analysis"
        }
      ],
      "time": "2026-01-15T12:00:00Z",
      "value": 0
    }
  ]
}
```


# Token sentiment timeframes

- Method: `GET`
- Path: `/token/{id}/sentiment-timeframes`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-sentiment-timeframes/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-sentiment-timeframes

## Description

Sentiment broken down by short/medium/long timeframes.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/sentiment-timeframes' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `metadata` (object): Computation metadata for timeframe sentiment output.
- `metadata.as_of` (string (date-time)): No description provided.
- `metadata.calculation` (string): No description provided.
- `metadata.formula` (string): No description provided.
- `metadata.half_life_h` (number (double)): No description provided.
- `metadata.handle` (string): No description provided.
- `metadata.handles` (array<string>): Normalized handles used by the query.
- `metadata.lookback_days` (integer): No description provided.
- `metadata.scale` (string): No description provided.
- `metadata.token_id` (integer (int64)): Internal token identifier.
- `series` (object): Sentiment time series split by timeframe buckets (short, medium, long).
- `summary` (object): Current summary sentiment by timeframe key.

Media type: `application/json`

## JSON Response

```json
{
  "metadata": {
    "as_of": "2026-01-15T12:00:00Z",
    "calculation": "string",
    "formula": "string",
    "half_life_h": 0,
    "handle": "string",
    "handles": [
      "string"
    ],
    "lookback_days": 0,
    "scale": "string",
    "token_id": 0
  },
  "series": {},
  "summary": {}
}
```


# Token simple sentiment

- Method: `GET`
- Path: `/token/{id}/simple-sentiment`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-simple-sentiment/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-simple-sentiment

## 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.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/simple-sentiment' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.
- `clusters` (array<string>, optional): 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).

## Response

OK

- `cohorts` (object): Sentiment series by author-cohort id. Keys are strings "0" through "5"; higher ids represent higher-confidence/smart-money author buckets.
- `summary` (array<object>): Aggregate sentiment series across non-baseline cohorts.
- `summary[].bearish_posts` (number (double)): Count of bearish posts included in the computed window.
- `summary[].bucket_start` (string (date-time)): UTC bucket start timestamp.
- `summary[].bullish_posts` (number (double)): Count of bullish posts included in the computed window.
- `summary[].interval_bearish_posts` (number (double)): Bearish posts in the current emitted interval bucket.
- `summary[].interval_bullish_posts` (number (double)): Bullish posts in the current emitted interval bucket.
- `summary[].interval_neutral_posts` (number (double)): Neutral posts in the current emitted interval bucket.
- `summary[].interval_posts` (number (double)): Posts in the current emitted interval bucket.
- `summary[].neutral_posts` (number (double)): Count of neutral posts included in the computed window.
- `summary[].sentiment_score` (number (double)): Sentiment score on a 0-100 scale (higher is more bullish).
- `summary[].sentiment_score_smoothed` (number (double)): Smoothed sentiment score (0-100) when available.
- `summary[].sentiment_score_z` (number (double)): Z-score normalized sentiment where available.
- `summary[].sentiment_signal` (number (double)): Model-level sentiment signal used for downstream ranking when available.
- `summary[].total_posts` (number (double)): Total posts included in the computed window.
- `summary[].total_posts_smoothed` (number (double)): Smoothed total-posts series where available.

Media type: `application/json`

## JSON Response

```json
{
  "cohorts": {},
  "summary": [
    {
      "bearish_posts": 0,
      "bucket_start": "2026-01-15T12:00:00Z",
      "bullish_posts": 0,
      "interval_bearish_posts": 0,
      "interval_bullish_posts": 0,
      "interval_neutral_posts": 0,
      "interval_posts": 0,
      "neutral_posts": 0,
      "sentiment_score": 0,
      "sentiment_score_smoothed": 0,
      "sentiment_score_z": 0,
      "sentiment_signal": 0,
      "total_posts": 0,
      "total_posts_smoothed": 0
    }
  ]
}
```


# Token smart money bias

- Method: `GET`
- Path: `/token/{id}/smart-money-bias`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-smart-money-bias/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-smart-money-bias

## Description

Current bias (smart money sentiment minus overall sentiment) in basis points.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/smart-money-bias' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `current` (object): Latest point-in-time smart-money bias metrics.
- `current.bucket_start` (string (date-time)): UTC bucket start timestamp.
- `current.overall_sentiment_score` (number (double)): Overall sentiment score (0-100).
- `current.sentiment_bias_bps` (number (double)): Difference between smart-money and overall sentiment, in basis points.
- `current.smart_money_sentiment_score` (number (double)): Smart-money cohort sentiment score (0-100).

Media type: `application/json`

## JSON Response

```json
{
  "current": {
    "bucket_start": "2026-01-15T12:00:00Z",
    "overall_sentiment_score": 0,
    "sentiment_bias_bps": 0,
    "smart_money_sentiment_score": 0
  }
}
```


# Token smart money post volume

- Method: `GET`
- Path: `/token/{id}/smart-money-post-volume`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-smart-money-post-volume/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-smart-money-post-volume

## 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.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/smart-money-post-volume' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `giga_brain_volume` (array<object>): Token social post-volume series for smart-money cohort.
- `giga_brain_volume[].tag_breakdown` (array<object>): Per-bucket post-tag counts for smart-money posts.
- `giga_brain_volume[].tag_breakdown[].count` (integer (int64)): Smart-money posts carrying the tag in the bucket.
- `giga_brain_volume[].tag_breakdown[].tag` (string, 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): Normalized post tag.
- `giga_brain_volume[].time` (string (date-time)): UTC timestamp for the data point.
- `giga_brain_volume[].value` (number (double)): Numeric metric value for the timestamp.

Media type: `application/json`

## JSON Response

```json
{
  "giga_brain_volume": [
    {
      "tag_breakdown": [
        {
          "count": 0,
          "tag": "technical_analysis"
        }
      ],
      "time": "2026-01-15T12:00:00Z",
      "value": 0
    }
  ]
}
```


# Token smart money sentiment

- Method: `GET`
- Path: `/token/{id}/smart-money-sentiment`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-smart-money-sentiment/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-smart-money-sentiment

## Description

Deprecated / redundant: prefer /token/{id}/simple-sentiment?clusters=smart_money. Sentiment time-series from smart money cohort only. Retained for backward compatibility.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/smart-money-sentiment' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `data` (array<object>): Smart-money sentiment series only.
- `data[].bearish_posts` (number (double)): Count of bearish posts included in the computed window.
- `data[].bucket_start` (string (date-time)): UTC bucket start timestamp.
- `data[].bullish_posts` (number (double)): Count of bullish posts included in the computed window.
- `data[].interval_bearish_posts` (number (double)): Bearish posts in the current emitted interval bucket.
- `data[].interval_bullish_posts` (number (double)): Bullish posts in the current emitted interval bucket.
- `data[].interval_neutral_posts` (number (double)): Neutral posts in the current emitted interval bucket.
- `data[].interval_posts` (number (double)): Posts in the current emitted interval bucket.
- `data[].neutral_posts` (number (double)): Count of neutral posts included in the computed window.
- `data[].sentiment_score` (number (double)): Sentiment score on a 0-100 scale (higher is more bullish).
- `data[].sentiment_score_smoothed` (number (double)): Smoothed sentiment score (0-100) when available.
- `data[].sentiment_score_z` (number (double)): Z-score normalized sentiment where available.
- `data[].sentiment_signal` (number (double)): Model-level sentiment signal used for downstream ranking when available.
- `data[].total_posts` (number (double)): Total posts included in the computed window.
- `data[].total_posts_smoothed` (number (double)): Smoothed total-posts series where available.

Media type: `application/json`

## JSON Response

```json
{
  "data": [
    {
      "bearish_posts": 0,
      "bucket_start": "2026-01-15T12:00:00Z",
      "bullish_posts": 0,
      "interval_bearish_posts": 0,
      "interval_bullish_posts": 0,
      "interval_neutral_posts": 0,
      "interval_posts": 0,
      "neutral_posts": 0,
      "sentiment_score": 0,
      "sentiment_score_smoothed": 0,
      "sentiment_score_z": 0,
      "sentiment_signal": 0,
      "total_posts": 0,
      "total_posts_smoothed": 0
    }
  ]
}
```


# Token social momentum

- Method: `GET`
- Path: `/token/{id}/social-momentum`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-social-momentum/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-social-momentum

## 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.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/social-momentum' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `clusters` (object): Momentum series keyed by author-cluster id (e.g. day_trader, bots, vcs, media). Sparse: empty buckets are omitted.

Media type: `application/json`

## JSON Response

```json
{
  "clusters": {}
}
```


# Token top degens sentiment

- Method: `GET`
- Path: `/token/{id}/top-degens-sentiment`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-top-degens-sentiment/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-top-degens-sentiment

## Description

Sentiment time-series from top degens cohort only.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/top-degens-sentiment' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `data` (array<object>): Top-degens sentiment series only.
- `data[].bearish_posts` (number (double)): Count of bearish posts included in the computed window.
- `data[].bucket_start` (string (date-time)): UTC bucket start timestamp.
- `data[].bullish_posts` (number (double)): Count of bullish posts included in the computed window.
- `data[].interval_bearish_posts` (number (double)): Bearish posts in the current emitted interval bucket.
- `data[].interval_bullish_posts` (number (double)): Bullish posts in the current emitted interval bucket.
- `data[].interval_neutral_posts` (number (double)): Neutral posts in the current emitted interval bucket.
- `data[].interval_posts` (number (double)): Posts in the current emitted interval bucket.
- `data[].neutral_posts` (number (double)): Count of neutral posts included in the computed window.
- `data[].sentiment_score` (number (double)): Sentiment score on a 0-100 scale (higher is more bullish).
- `data[].sentiment_score_smoothed` (number (double)): Smoothed sentiment score (0-100) when available.
- `data[].sentiment_score_z` (number (double)): Z-score normalized sentiment where available.
- `data[].sentiment_signal` (number (double)): Model-level sentiment signal used for downstream ranking when available.
- `data[].total_posts` (number (double)): Total posts included in the computed window.
- `data[].total_posts_smoothed` (number (double)): Smoothed total-posts series where available.

Media type: `application/json`

## JSON Response

```json
{
  "data": [
    {
      "bearish_posts": 0,
      "bucket_start": "2026-01-15T12:00:00Z",
      "bullish_posts": 0,
      "interval_bearish_posts": 0,
      "interval_bullish_posts": 0,
      "interval_neutral_posts": 0,
      "interval_posts": 0,
      "neutral_posts": 0,
      "sentiment_score": 0,
      "sentiment_score_smoothed": 0,
      "sentiment_score_z": 0,
      "sentiment_signal": 0,
      "total_posts": 0,
      "total_posts_smoothed": 0
    }
  ]
}
```


# Token volatility index

- Method: `GET`
- Path: `/token/{id}/volatility-index`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-volatility-index/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-volatility-index

## Description

Volatility index time-series for the token.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/volatility-index' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. Only `1d` is supported for this endpoint.

## Response

OK

- `volatility` (array<object>): Token volatility index series.
- `volatility[].time` (string (date-time)): UTC timestamp for the data point.
- `volatility[].value` (number (double)): Numeric metric value for the timestamp.

Media type: `application/json`

## JSON Response

```json
{
  "volatility": [
    {
      "time": "2026-01-15T12:00:00Z",
      "value": 0
    }
  ]
}
```


# Token volume series

- Method: `GET`
- Path: `/token/{id}/volume-series`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-token-id-volume-series/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-token-id-volume-series

## Description

Trading volume time-series for the token over the lookback window.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/token/bitcoin/volume-series' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

- `id` (string, required): Token identifier. Accepts internal token_id (integer) or coingecko_id (string, e.g. bitcoin).

## Query Parameters

- `hours` (integer, optional): Lookback window in hours.
- `granularity` (string, optional): Optional bucket size override. If provided, response is aggregated at this interval regardless of lookback window.

## Response

OK

- `volume` (array<object>): Token trading volume series.
- `volume[].time` (string (date-time)): UTC timestamp for the data point.
- `volume[].value` (number (double)): Numeric metric value for the timestamp.

Media type: `application/json`

## JSON Response

```json
{
  "volume": [
    {
      "time": "2026-01-15T12:00:00Z",
      "value": 0
    }
  ]
}
```


# Token list (paged)

- Method: `GET`
- Path: `/tokens`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-tokens/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-tokens

## 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.

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/tokens' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `limit` (integer, optional): Maximum number of items to return (default and max may vary by endpoint).
- `offset` (integer, optional): Number of items to skip for pagination (use with limit).

## Response

OK

- `limit` (integer): Applied response size limit.
- `offset` (integer): Applied page offset (always 0 for non-paginated token snapshots).
- `tokens` (array<object>): Paged token rows. One entry per indexed token.
- `tokens[].address` (string): Canonical contract address when available; null for native assets or unknown contracts.
- `tokens[].coingecko_id` (string): CoinGecko asset identifier when available; null otherwise.
- `tokens[].market_cap_usd` (number (double)): Latest known market capitalization in USD; null when unavailable.
- `tokens[].mindshare_24h` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].mindshare_change` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].mindshare_change_pct` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].name` (string): Human-readable token name.
- `tokens[].price_usd` (number (double)): Latest known USD price; null when unavailable.
- `tokens[].symbol` (string): Primary trading symbol.
- `tokens[].token_id` (integer (int64)): Internal Nebula token identifier.
- `tokens[].volume_usd` (number (double)): Latest known 24h volume in USD; null when unavailable.
- `total` (integer): Total number of tokens in this response set.

Media type: `application/json`

## JSON Response

```json
{
  "limit": 0,
  "offset": 0,
  "tokens": [
    {
      "address": "string",
      "coingecko_id": "string",
      "market_cap_usd": 0,
      "mindshare_24h": 0,
      "mindshare_change": 0,
      "mindshare_change_pct": 0,
      "name": "string",
      "price_usd": 0,
      "symbol": "string",
      "token_id": 0,
      "volume_usd": 0
    }
  ],
  "total": 0
}
```


# Token search

- Method: `GET`
- Path: `/tokens/search`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-tokens-search/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-tokens-search

## 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.

## cURL Example

```bash
curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/tokens/search' \
  --data-urlencode 'q=string' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `q` (string, required): Search query. For tokens this matches symbol, name, or contract address; for accounts it matches display name or handle.
- `limit` (integer, optional): Maximum number of results to return (default 10, max 50).

## Response

OK

- `query` (string): Normalized query string that was searched.
- `tokens` (array<object>): Matching tokens ordered by relevance.
- `tokens[].coingecko_id` (string): CoinGecko asset identifier when available; null otherwise.
- `tokens[].followers` (integer (int64)): Project follower count when available; null otherwise.
- `tokens[].handle` (string): Primary social handle for the token's project; null when unknown.
- `tokens[].image_url` (string): Token logo URL.
- `tokens[].market_cap_usd` (number (double)): Latest known market capitalization in USD; null when unavailable.
- `tokens[].name` (string): Human-readable token name.
- `tokens[].price_change_24h_pct` (number (double)): 24h price change percentage; null when unavailable.
- `tokens[].price_usd` (number (double)): Latest known USD price; null when unavailable.
- `tokens[].symbol` (string): Primary trading symbol.
- `tokens[].token_id` (integer (int64)): Internal Nebula token identifier.
- `total` (integer): Number of tokens returned in this response.

Media type: `application/json`

## JSON Response

```json
{
  "query": "string",
  "tokens": [
    {
      "coingecko_id": "string",
      "followers": 0,
      "handle": "string",
      "image_url": "string",
      "market_cap_usd": 0,
      "name": "string",
      "price_change_24h_pct": 0,
      "price_usd": 0,
      "symbol": "string",
      "token_id": 0
    }
  ],
  "total": 0
}
```


# Trending token list

- Method: `GET`
- Path: `/tokens/trending`
- Tier: Pro
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-tokens-trending/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-tokens-trending

## 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).

## cURL Example

```bash
curl --request GET \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/tokens/trending' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `limit` (integer, optional): Maximum number of trending tokens to return (default 10, max 50).

## Response

OK

- `limit` (integer): Applied response size limit.
- `offset` (integer): Applied page offset (always 0 for non-paginated token snapshots).
- `tokens` (array<object>): Paged token rows. One entry per indexed token.
- `tokens[].address` (string): Canonical contract address when available; null for native assets or unknown contracts.
- `tokens[].coingecko_id` (string): CoinGecko asset identifier when available; null otherwise.
- `tokens[].market_cap_usd` (number (double)): Latest known market capitalization in USD; null when unavailable.
- `tokens[].mindshare_24h` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].mindshare_change` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].mindshare_change_pct` (number (double)): Percent change in mindshare over the latest comparison window when available.
- `tokens[].name` (string): Human-readable token name.
- `tokens[].price_usd` (number (double)): Latest known USD price; null when unavailable.
- `tokens[].symbol` (string): Primary trading symbol.
- `tokens[].token_id` (integer (int64)): Internal Nebula token identifier.
- `tokens[].volume_usd` (number (double)): Latest known 24h volume in USD; null when unavailable.
- `total` (integer): Total number of tokens in this response set.

Media type: `application/json`

## JSON Response

```json
{
  "limit": 0,
  "offset": 0,
  "tokens": [
    {
      "address": "string",
      "coingecko_id": "string",
      "market_cap_usd": 0,
      "mindshare_24h": 0,
      "mindshare_change": 0,
      "mindshare_change_pct": 0,
      "name": "string",
      "price_usd": 0,
      "symbol": "string",
      "token_id": 0,
      "volume_usd": 0
    }
  ],
  "total": 0
}
```


# Account search

- Method: `GET`
- Path: `/users/search`
- Tier: Basic
- HTML docs: https://docs.hiddensystems.ai/nebula/reference/get-users-search/
- Interactive docs: https://docs.hiddensystems.ai/nebula/#endpoint=get-users-search

## 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.

## cURL Example

```bash
curl --get \
  --url 'https://nebula-api.hiddensystems.ai/api/v1/public/users/search' \
  --data-urlencode 'q=string' \
  --header 'X-API-Key: YOUR_API_KEY'
```

## Path Parameters

No path parameters for this endpoint.

## Query Parameters

- `q` (string, required): Search query. For tokens this matches symbol, name, or contract address; for accounts it matches display name or handle.
- `limit` (integer, optional): Maximum number of results to return (default 10, max 50).

## Response

OK

- `query` (string): Normalized query string that was searched.
- `total` (integer): Number of accounts returned in this response.
- `users` (array<object>): Matching accounts ordered by relevance.
- `users[].author_id` (integer (int64)): Internal Nebula author identifier.
- `users[].avatar_url` (string): URL of the account's avatar image.
- `users[].bot_score` (number (double)): Model score based on the quality of the account's smart-money followers.
- `users[].cohort` (integer): Cohort classification id for the account.
- `users[].display_name` (string): Display name of the account.
- `users[].followers` (integer (int64)): Total follower count for the account.
- `users[].name` (string): Account name.
- `users[].profile_url` (string): Normalized query string that was searched.
- `users[].screen_name` (string): Screen name or handle on the source platform.
- `users[].smart_followers_score` (number (double)): Model score based on the quality of the account's smart-money followers.
- `users[].smart_money_score` (number (double)): Model score based on the quality of the account's smart-money followers.
- `users[].source` (string): Source platform for the account (e.g. twitter).
- `users[].source_user_id` (string): Identifier for the account on the source platform.
- `users[].verified` (boolean): Whether the account is verified on the source platform.

Media type: `application/json`

## JSON Response

```json
{
  "query": "string",
  "total": 0,
  "users": [
    {
      "author_id": 0,
      "avatar_url": "string",
      "bot_score": 0,
      "cohort": 0,
      "display_name": "string",
      "followers": 0,
      "name": "string",
      "profile_url": "string",
      "screen_name": "string",
      "smart_followers_score": 0,
      "smart_money_score": 0,
      "source": "string",
      "source_user_id": "string",
      "verified": false
    }
  ]
}
```