# Introduction



AIXBT monitors public social sources and market activity to surface developments
across crypto projects and topics.

<IntroductionCards>
  <IntroductionCard icon="chatgpt" title="Chat with AIXBT" description="Research crypto in ChatGPT with the AIXBT connector and skill." href="/chatgpt" />

  <IntroductionCard icon="projects" title="Projects" description="Durable crypto entities ranked and tracked across time." href="/projects" />

  <IntroductionCard icon="topics" title="Topics" description="Live narratives showing how public attention is changing." href="/topics" />

  <IntroductionCard icon="chatter" title="Chatter" description="Public mention activity around a project or topic over time." href="/chatter" />

  <IntroductionCard icon="clusters" title="Clusters" description="Overlapping account archetypes carrying a conversation." href="/clusters" />

  <IntroductionCard icon="intel" title="Intel" description="Time-stamped developments on projects, graded by evidence." href="/intel" />

  <IntroductionCard icon="reports" title="Reports" description="Synthesized evidence for a topic." href="/reports" />

  <IntroductionCard icon="alerts" title="Alerts" description="Intel, project, topic, and report deliveries to your channels." href="/alerts" />

  <IntroductionCard icon="build" title="Build & automate" description="Connect workflows through REST and MCP integrations." href="/developers/v3" />
</IntroductionCards>


---

## Developers

---

# Overview



API v3 is the primary AIXBT API: one consistent view of Projects, Topics,
Intel, Reports, and Clusters, available over REST and
[MCP](/developers/mcp) with identical data. The base URL is
`https://api.aixbt.tech/v3`; the OpenAPI document is served at
[`/v3/openapi.yaml`](https://api.aixbt.tech/v3/openapi.yaml), with
interactive docs at `https://api.aixbt.tech/v3/docs`.

## Authentication [#authentication]

Current Topic list and detail are the keyless free tier:

```bash
curl --fail-with-body "https://api.aixbt.tech/v3/topics"
```

Everything else requires a key from [Developer
access](https://aixbt.tech/profile#developer-access), sent in the `x-api-key` header:

```bash
curl --fail-with-body "https://api.aixbt.tech/v3/projects?limit=5" \
  -H "x-api-key: YOUR_API_KEY"
```

Call [`GET /v3/me`](/developers/v3/reference/get-v3-me) to see your
account, plan, rate limits, and history window.

## Responses [#responses]

Every success body is `{data, meta}`. Failures return one typed error object.
List endpoints use `cursor` and `limit`; follow `meta.nextCursor` until it is
`null`.

```json
{
  "data": [],
  "meta": { "nextCursor": null }
}
```

## Find data [#find-data]

`GET /v3/intel?search=...` runs deep search across project identity
and Intel text. Use
[`GET /v3/vocabulary`](/developers/v3/reference/get-v3-vocabulary) for valid
filter values, and the [Reference](/developers/v3/reference) for exact
parameters, schemas, and examples.

## Migrating from v2 [#migrating-from-v2]

The [migration guide](/developers/v3/migration) maps every v2 route and
field to its v3 equivalent.


# Migrating from v2



API v3 is a redesign: consistent resources, one response envelope, clear
error codes, and cursor pagination. v2 remains available while you migrate;
new integrations should target v3. Trend is the sole current ranking in both
versions.

## Routes [#routes]

| v2                                            | v3                                                                                                                                                      |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /v2/projects`                            | [`GET /v3/projects`](/developers/v3/reference/get-v3-projects): cursor pagination, slug locators, typed `assets`                                        |
| `GET /v2/projects/:id`                        | [`GET /v3/projects/{idOrSlug}`](/developers/v3/reference/get-v3-projects-idorslug): accepts id or slug                                                  |
| `GET /v2/projects/:id/momentum`, `/rank`      | [`GET /v3/projects/{idOrSlug}/series/{measure}`](/developers/v3/reference/get-v3-projects-idorslug-series-measure): one series shape, `trend` or `rank` |
| `GET /v2/projects/:id/candles`, `/metrics`    | Removed: price and market-cap data are no longer part of the API                                                                                        |
| `GET /v2/projects/:id/neighbors`              | `relatedProjects` on Project detail                                                                                                                     |
| `GET /v2/projects/chains`                     | Moved into [`GET /v3/vocabulary`](/developers/v3/reference/get-v3-vocabulary)                                                                           |
| `GET /v2/topics`                              | [`GET /v3/topics`](/developers/v3/reference/get-v3-topics): free tier, keyless                                                                          |
| `GET /v2/topics/:id/report`                   | [`GET /v3/reports/{id}`](/developers/v3/reference/get-v3-reports-id): top-level Reports with revision history                                           |
| `GET /v2/grounding`                           | Replaced by [`GET /v3/topics`](/developers/v3/reference/get-v3-topics)                                                                                  |
| `GET /v2/intel` (and the `/v2/signals` alias) | [`GET /v3/intel`](/developers/v3/reference/get-v3-intel): graded, filterable, searchable                                                                |
| `GET /v2/intel/:id`                           | [`GET /v3/intel/{id}`](/developers/v3/reference/get-v3-intel-id): detail with cluster composition                                                       |
| `GET /v2/intel-categories`                    | Moved into [`GET /v3/vocabulary`](/developers/v3/reference/get-v3-vocabulary)                                                                           |
| `GET /v2/clusters`                            | [`GET /v3/clusters`](/developers/v3/reference/get-v3-clusters)                                                                                          |
| `GET /v2/api-keys/info`                       | [`GET /v3/me`](/developers/v3/reference/get-v3-me): account, plan, limits, history window                                                               |
| `POST /v2/agents/indigo`                      | Removed: use Ask at [aixbt.tech](https://aixbt.tech)                                                                                                    |
| `/v2/recipes/*`                               | Removed: recipes have been discontinued                                                                                                                 |
| all `/v1/*`                                   | Migrate to v3                                                                                                                                           |

## Envelope [#envelope]

| v2                                              | v3                                                                                                           |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Body `status` integer + `data`                  | `{data, meta}`; the HTTP status is the status                                                                |
| `pagination {page, limit, totalCount, hasMore}` | Opaque `cursor` + `limit`; follow `meta.nextCursor`                                                          |
| Error strings and per-route codes               | One error shape `{code, message, details?}` with a fixed set of codes                                        |
| One generic 404                                 | Specific miss codes: `not_found` (never existed), `not_current` (no longer current)                          |
| `at` historical reads                           | Removed: use the Project or Topic `series/{measure}` route with a `from`/`to` window for measurement history |

## Properties [#properties]

| v2                                        | v3                                                                                                          |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `trendScore`                              | `trend` for continued attention and the sole current ranking measurement                                    |
| `trendScoreDelta`                         | `trendDelta {value, window: "PT24H"}`                                                                       |
| `signals[]` on Project                    | `intel[]`: a short preview of recent intel                                                                  |
| `cut` (undocumented)                      | `grade`: documented values `chipped` → `flawless`, filterable                                               |
| `stanceSeries` (undocumented)             | `stance` on Topic detail                                                                                    |
| `coingeckoData` block                     | Removed: `symbol`, `image`, and `categories` are now top-level fields; provider identifiers are not exposed |
| `tokens[]`                                | Typed `assets[]`: `{type, chain, address, primary}`                                                         |
| `xHandle`                                 | `identifiers.x` (join keys under `identifiers`, e.g. `identifiers.coingecko`)                               |
| `rationale`                               | Removed: use Intel items and their citations                                                                |
| `frontierReport {url, preview}` on topics | `report {id, title, publishedAt}` ref: fetch via `/v3/reports/{id}`                                         |

## Deprecation headers [#deprecation-headers]

Deprecated v2 routes respond with an RFC 9745 `Deprecation` header and an
RFC 8288 `Link` header pointing at the v3 successor, so clients can detect
the migration path programmatically.


# Reference



See [Overview](/developers/v3) for authentication and request basics. Base URL: `https://api.aixbt.tech`.

## Projects [#projects]

* [`GET /v3/projects`](/developers/v3/reference/get-v3-projects) — List Projects
* [`GET /v3/projects/{idOrSlug}`](/developers/v3/reference/get-v3-projects-idOrSlug) — Get a Project
* [`GET /v3/projects/{idOrSlug}/series/{measure}`](/developers/v3/reference/get-v3-projects-idOrSlug-series-measure) — Get a Project measurement series

## Topics [#topics]

* [`GET /v3/topics`](/developers/v3/reference/get-v3-topics) — List the current Topic leaderboard
* [`GET /v3/topics/{topicId}`](/developers/v3/reference/get-v3-topics-topicId) — Get a Topic
* [`GET /v3/topics/{topicId}/projects`](/developers/v3/reference/get-v3-topics-topicId-projects) — List Projects associated with a Topic
* [`GET /v3/topics/{topicId}/series/{measure}`](/developers/v3/reference/get-v3-topics-topicId-series-measure) — Get a Topic measurement series

## Intel [#intel]

* [`GET /v3/intel`](/developers/v3/reference/get-v3-intel) — List Intel
* [`GET /v3/intel/{id}`](/developers/v3/reference/get-v3-intel-id) — Get an Intel item

## Reports [#reports]

* [`GET /v3/reports`](/developers/v3/reference/get-v3-reports) — List published Reports
* [`GET /v3/reports/{id}`](/developers/v3/reference/get-v3-reports-id) — Get a published Report

## Clusters [#clusters]

* [`GET /v3/clusters`](/developers/v3/reference/get-v3-clusters) — List Clusters

## Alerts [#alerts]

* [`GET /v3/alerts`](/developers/v3/reference/get-v3-alerts) — List my alert subscriptions
* [`POST /v3/alerts`](/developers/v3/reference/post-v3-alerts) — Create an alert subscription
* [`DELETE /v3/alerts/{id}`](/developers/v3/reference/delete-v3-alerts-id) — Delete an alert subscription
* [`GET /v3/alerts/{id}`](/developers/v3/reference/get-v3-alerts-id) — Get an alert subscription
* [`PATCH /v3/alerts/{id}`](/developers/v3/reference/patch-v3-alerts-id) — Update an alert subscription
* [`GET /v3/alerts/destinations`](/developers/v3/reference/get-v3-alerts-destinations) — List my delivery destinations

## Vocabulary [#vocabulary]

* [`GET /v3/vocabulary`](/developers/v3/reference/get-v3-vocabulary) — Get the filter vocabularies

## Me [#me]

* [`GET /v3/me`](/developers/v3/reference/get-v3-me) — Get the signed-in account

## Meta [#meta]

* [`GET /v3/openapi.yaml`](/developers/v3/reference/get-v3-openapi.yaml) — Get this contract


# List Projects

`GET /v3/projects`

Canonical Project collection, sorted by `trend` (default),
`createdAt`, or `reinforcedAt`, always descending. All filters come
from the documented filter values; catalog-derived values
(categories, chains, asset types) are discoverable via
`GET /v3/vocabulary`.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "$ref": "#/components/parameters/Cursor"
  },
  {
    "$ref": "#/components/parameters/Limit"
  },
  {
    "name": "sort",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "trend",
        "createdAt",
        "reinforcedAt"
      ],
      "default": "trend"
    }
  },
  {
    "name": "ids",
    "in": "query",
    "description": "Comma-separated canonical Project ids.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "slugs",
    "in": "query",
    "description": "Comma-separated Project slugs (aliases resolve).",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "names",
    "in": "query",
    "description": "Comma-separated display names, case-insensitive.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "xHandles",
    "in": "query",
    "description": "Comma-separated X handles without the at sign.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "tickers",
    "in": "query",
    "description": "Comma-separated asset tickers.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "categories",
    "in": "query",
    "description": "Comma-separated canonical taxonomy slugs.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "chain",
    "in": "query",
    "description": "Restrict to Projects with an asset deployment on this chain.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "address",
    "in": "query",
    "description": "Asset contract address (EVM case-insensitive, other chains case-sensitive).",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "assetTypes",
    "in": "query",
    "description": "Comma-separated asset types (see `/v3/vocabulary`).",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "universe",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "crypto",
        "tradfi"
      ],
      "default": "crypto"
    }
  },
  {
    "name": "minTrend",
    "in": "query",
    "description": "Minimum current trend measurement.",
    "schema": {
      "type": "number"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Project page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Project"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/CollectionMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "First page of Projects ranked by trend",
            "value": {
              "data": [
                {
                  "id": "665f0a2b1c9d440000a1b2c3",
                  "slug": "examplechain",
                  "name": "ExampleChain",
                  "universe": "crypto",
                  "symbol": "EXC",
                  "description": "Modular settlement layer for restaked rollups.",
                  "identifiers": {
                    "coingecko": "examplechain",
                    "x": "examplechain"
                  },
                  "image": "https://images.aixbt.tech/projects/examplechain.png",
                  "trend": 87.4,
                  "rank": 3,
                  "categories": [
                    "modular-blockchains",
                    "restaking"
                  ],
                  "assets": [
                    {
                      "type": "token",
                      "chain": "ethereum",
                      "address": "0xabc0000000000000000000000000000000000001",
                      "primary": true
                    }
                  ],
                  "intel": [
                    {
                      "id": "6890aa000000000000000001",
                      "headline": "Mainnet v2 date confirmed",
                      "grade": "polished",
                      "detectedAt": "2026-08-04T21:14:00Z"
                    }
                  ],
                  "createdAt": "2026-05-02T10:00:00Z",
                  "updatedAt": "2026-08-05T04:58:11Z",
                  "reinforcedAt": "2026-08-05T03:40:00Z"
                }
              ],
              "meta": {
                "nextCursor": "b3BhcXVlLWN1cnNvcg",
                "history": {
                  "lookbackDays": 90,
                  "earliestAvailableAt": "2026-05-07T00:00:00Z"
                },
                "versions": {
                  "trendModel": "trend-v3"
                }
              }
            }
          },
          "empty": {
            "summary": "Filter matched nothing",
            "value": {
              "data": [],
              "meta": {
                "nextCursor": null
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  },
  "503": {
    "$ref": "#/components/responses/Unavailable"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get a Project

`GET /v3/projects/{idOrSlug}`

Project detail by canonical id or slug. Slug aliases (from renames or
merges) resolve to the canonical resource; the response always carries
the canonical `slug`. Includes a bounded `relatedProjects` co-mention
preview derived from the same posts that support Project Intel;
observational only, not partnership or endorsement.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "$ref": "#/components/parameters/IdOrSlug"
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Project detail.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/ProjectDetail"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Detail with related Projects",
            "value": {
              "data": {
                "id": "665f0a2b1c9d440000a1b2c3",
                "slug": "examplechain",
                "name": "ExampleChain",
                "universe": "crypto",
                "symbol": "EXC",
                "description": "Modular settlement layer for restaked rollups.",
                "identifiers": {
                  "coingecko": "examplechain",
                  "x": "examplechain"
                },
                "image": "https://images.aixbt.tech/projects/examplechain.png",
                "trend": 87.4,
                "trendDelta": {
                  "value": 12.1,
                  "window": "PT24H"
                },
                "rank": 3,
                "categories": [
                  "modular-blockchains",
                  "restaking"
                ],
                "assets": [
                  {
                    "type": "token",
                    "chain": "ethereum",
                    "address": "0xabc0000000000000000000000000000000000001",
                    "primary": true
                  }
                ],
                "intel": [
                  {
                    "id": "6890aa000000000000000001",
                    "headline": "Mainnet v2 date confirmed",
                    "grade": "polished",
                    "detectedAt": "2026-08-04T21:14:00Z"
                  }
                ],
                "relatedProjects": [
                  {
                    "project": {
                      "id": "665f0a2b1c9d440000a1b2c4",
                      "slug": "otherchain",
                      "name": "OtherChain"
                    },
                    "kind": "co_mention",
                    "sharedIntel": 14,
                    "window": "P14D",
                    "asOf": "2026-08-05T04:45:00Z"
                  }
                ],
                "createdAt": "2026-05-02T10:00:00Z",
                "updatedAt": "2026-08-05T04:58:11Z",
                "reinforcedAt": "2026-08-05T03:40:00Z"
              },
              "meta": {
                "history": {
                  "lookbackDays": 90,
                  "earliestAvailableAt": "2026-05-07T00:00:00Z"
                },
                "versions": {
                  "trendModel": "trend-v3",
                  "relations": "co-mention-v1"
                }
              }
            }
          },
          "partial": {
            "summary": "Assetless Project with nothing tradable yet",
            "value": {
              "data": {
                "id": "665f0a2b1c9d440000a1b2c5",
                "slug": "stealthlabs",
                "name": "StealthLabs",
                "universe": "crypto",
                "description": "Pre-token research collective.",
                "trend": 41.2,
                "categories": [
                  "ai-agents"
                ],
                "assets": [],
                "intel": [],
                "createdAt": "2026-07-29T08:00:00Z",
                "updatedAt": "2026-08-05T02:10:00Z"
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  },
  "503": {
    "$ref": "#/components/responses/Unavailable"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get a Project measurement series

`GET /v3/projects/{idOrSlug}/series/{measure}`

One series contract for the public measures. `trend` is the hourly
canonical score history; `rank` is the committed Trend rank-transition
series exactly as recorded: change points, not
resampled intervals (`value` is `null` while unranked). Point
timestamps preserve the actual measurement boundary and
`meta.basis` states which cadence applies. Points are objects, never
positional arrays.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "$ref": "#/components/parameters/IdOrSlug"
  },
  {
    "name": "measure",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "trend",
        "rank"
      ]
    }
  },
  {
    "name": "from",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "to",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "include",
    "in": "query",
    "description": "`clusters` adds per-point cluster attribution only to `trend` series.",
    "schema": {
      "type": "string",
      "enum": [
        "clusters"
      ]
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Series page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "object",
              "required": [
                "project",
                "points"
              ],
              "properties": {
                "project": {
                  "$ref": "#/components/schemas/ProjectRef"
                },
                "points": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SeriesPoint"
                  }
                }
              }
            },
            "meta": {
              "$ref": "#/components/schemas/SeriesMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Hourly trend series",
            "value": {
              "data": {
                "project": {
                  "id": "665f0a2b1c9d440000a1b2c3",
                  "slug": "examplechain",
                  "name": "ExampleChain"
                },
                "points": [
                  {
                    "at": "2026-08-05T03:00:00Z",
                    "value": 84.1
                  },
                  {
                    "at": "2026-08-05T04:00:00Z",
                    "value": 87.4
                  }
                ]
              },
              "meta": {
                "measure": "trend",
                "basis": "hourly",
                "window": {
                  "from": "2026-08-04T05:00:00Z",
                  "to": "2026-08-05T05:00:00Z"
                }
              }
            }
          },
          "rank": {
            "summary": "Rank transition series over an explicit window",
            "value": {
              "data": {
                "project": {
                  "id": "665f0a2b1c9d440000a1b2c3",
                  "slug": "examplechain",
                  "name": "ExampleChain"
                },
                "points": [
                  {
                    "at": "2026-07-20T11:45:00Z",
                    "value": 7
                  },
                  {
                    "at": "2026-07-20T12:00:00Z",
                    "value": null
                  }
                ]
              },
              "meta": {
                "measure": "rank",
                "basis": "rank_transitions",
                "window": {
                  "from": "2026-07-20T11:00:00Z",
                  "to": "2026-07-20T12:00:00Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  },
  "503": {
    "$ref": "#/components/responses/Unavailable"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# List the current Topic leaderboard

`GET /v3/topics`

The current Topic leaderboard (top 25), a bounded set, so
there is no cursor. `meta.snapshot` carries the shared evidence
cutoff. `trend` represents continued attention. With `projectId` (or
`projectSlug`) the same authority is
projected inversely: only Topics observationally associated with that
Project, each item gaining an `association` block.

## Authentication

None. This endpoint is public.

## Parameters

```json
[
  {
    "name": "ranking",
    "in": "query",
    "description": "Ranking measurement used to select and order the leaderboard.",
    "schema": {
      "type": "string",
      "enum": [
        "trend"
      ],
      "default": "trend"
    }
  },
  {
    "name": "projectId",
    "in": "query",
    "description": "Current canonical Project id. Filters the current leaderboard by observational Topic associations.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "projectSlug",
    "in": "query",
    "description": "Current canonical Project slug or slug alias. Filters the same current observational associations as projectId.",
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Leaderboard.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TopicListItem"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/TopicSnapshotMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Current leaderboard head",
            "value": {
              "data": [
                {
                  "id": "topic_a1b2c3d4e5f601234567",
                  "rank": 1,
                  "name": "Restaking yield compression",
                  "summary": "Yields across restaking protocols compress as new AVS demand stalls.",
                  "trend": 93.2,
                  "postCount": 412,
                  "authorCount": 118,
                  "lastSeenAt": "2026-08-05T04:52:00Z",
                  "clusters": [
                    {
                      "cluster": {
                        "id": "cl_defi",
                        "name": "DeFi researchers"
                      },
                      "share": 0.41
                    }
                  ],
                  "report": {
                    "id": "tr_9f2b6c41d8a35e07b1c4f6a2d5e8091c3b7a4f60d2e5c8b1a4f7092c5d8e3b6a",
                    "title": "Restaking Yield Compression",
                    "publishedAt": "2026-08-04T18:00:00Z"
                  }
                }
              ],
              "meta": {
                "snapshot": {
                  "completedAt": "2026-08-05T04:55:00Z",
                  "latestEvidenceAt": "2026-08-05T04:52:10Z",
                  "windowStartedAt": "2026-08-04T04:55:00Z"
                }
              }
            }
          },
          "empty": {
            "summary": "Project with no associated Topics",
            "value": {
              "data": [],
              "meta": {
                "snapshot": {
                  "completedAt": "2026-08-05T04:55:00Z",
                  "latestEvidenceAt": "2026-08-05T04:52:10Z",
                  "windowStartedAt": "2026-08-04T04:55:00Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get a Topic

`GET /v3/topics/{topicId}`

Topic detail. Carries the versioned `stance` series: bucketed,
target-scoped stance of the Topic conversation itself
(`supportive`, `skeptical`, `neutral`, `mixed`, `unknown`),
independent from Project-targeted sentiment.

## Authentication

None. This endpoint is public.

## Parameters

```json
[
  {
    "name": "topicId",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^topic_[a-f0-9]{20}$"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Topic detail.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/TopicDetail"
            },
            "meta": {
              "$ref": "#/components/schemas/TopicSnapshotMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Detail with stance series",
            "value": {
              "data": {
                "id": "topic_a1b2c3d4e5f601234567",
                "rank": 1,
                "name": "Restaking yield compression",
                "summary": "Yields across restaking protocols compress as new AVS demand stalls.",
                "trend": 93.2,
                "postCount": 412,
                "authorCount": 118,
                "lastSeenAt": "2026-08-05T04:52:00Z",
                "clusters": [
                  {
                    "cluster": {
                      "id": "cl_defi",
                      "name": "DeFi researchers"
                    },
                    "share": 0.41
                  }
                ],
                "report": {
                  "id": "tr_9f2b6c41d8a35e07b1c4f6a2d5e8091c3b7a4f60d2e5c8b1a4f7092c5d8e3b6a",
                  "title": "Restaking Yield Compression",
                  "publishedAt": "2026-08-04T18:00:00Z"
                },
                "stance": {
                  "buckets": [
                    {
                      "from": "2026-08-05T03:00:00Z",
                      "to": "2026-08-05T04:00:00Z",
                      "dominant": "skeptical",
                      "shares": {
                        "supportive": 0.18,
                        "skeptical": 0.47,
                        "neutral": 0.22,
                        "mixed": 0.08,
                        "unknown": 0.05
                      }
                    }
                  ]
                }
              },
              "meta": {
                "snapshot": {
                  "completedAt": "2026-08-05T04:55:00Z",
                  "latestEvidenceAt": "2026-08-05T04:52:10Z",
                  "windowStartedAt": "2026-08-04T04:55:00Z"
                },
                "versions": {
                  "stanceSchema": "1",
                  "stanceClassifier": "stance-v2"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# List Projects associated with a Topic

`GET /v3/topics/{topicId}/projects`

The authoritative Topic→Project association collection. An
association is observational: canonical Project-attributed posts that
are members of the Topic at the shared cutoff in the sustained-attention
cohort. It never implies
partnership, endorsement, taxonomy, causality, or a primary Project.
Coverage is a statement about source completeness, separate from
association eligibility.

## Authentication

None. This endpoint is public.

## Parameters

```json
[
  {
    "name": "topicId",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^topic_[a-f0-9]{20}$"
    }
  },
  {
    "name": "ranking",
    "in": "query",
    "description": "Topic ranking cohort used to resolve the association snapshot.",
    "schema": {
      "type": "string",
      "enum": [
        "trend"
      ],
      "default": "trend"
    }
  },
  {
    "$ref": "#/components/parameters/Cursor"
  },
  {
    "$ref": "#/components/parameters/Limit"
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Association page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TopicProjectAssociation"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/AssociationMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Associations at the current window",
            "value": {
              "data": [
                {
                  "project": {
                    "id": "665f0a2b1c9d440000a1b2c3",
                    "slug": "examplechain",
                    "name": "ExampleChain"
                  },
                  "observedPosts": 96,
                  "distinctAuthors": 44,
                  "shareOfTopicPosts": 0.23,
                  "firstObservedAt": "2026-08-04T06:10:00Z",
                  "lastObservedAt": "2026-08-05T04:41:00Z",
                  "sentiment": {
                    "populated": 61,
                    "coverage": 0.64
                  }
                }
              ],
              "meta": {
                "nextCursor": null,
                "window": {
                  "from": "2026-08-04T04:55:00Z",
                  "to": "2026-08-05T04:55:00Z"
                },
                "versions": {
                  "resolver": "project-resolver-v4",
                  "membership": "topic-membership-v2"
                }
              }
            }
          },
          "empty": {
            "summary": "No qualifying associations",
            "value": {
              "data": [],
              "meta": {
                "nextCursor": null,
                "window": {
                  "from": "2026-08-04T04:55:00Z",
                  "to": "2026-08-05T04:55:00Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get a Topic measurement series

`GET /v3/topics/{topicId}/series/{measure}`

The same measurement-series contract used by Projects, for one known
Topic id. `trend` keeps the newest real completed score boundary in
each hourly bucket. `rank` is the committed Trend-boundary series reduced to change points;
`value` is `null` when a complete leaderboard publishes the Topic as
unranked. Point timestamps preserve the actual completed measurement
boundary. Topic history requires an API key.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "topicId",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^topic_[a-f0-9]{20}$"
    }
  },
  {
    "name": "measure",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "trend",
        "rank"
      ]
    }
  },
  {
    "name": "from",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "to",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Series page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "object",
              "required": [
                "topic",
                "points"
              ],
              "properties": {
                "topic": {
                  "$ref": "#/components/schemas/TopicRef"
                },
                "points": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SeriesPoint"
                  }
                }
              }
            },
            "meta": {
              "$ref": "#/components/schemas/SeriesMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Hourly Topic trend series",
            "value": {
              "data": {
                "topic": {
                  "id": "topic_a1b2c3d4e5f601234567",
                  "name": "Restaking yield compression"
                },
                "points": [
                  {
                    "at": "2026-08-05T03:45:00Z",
                    "value": 91.8
                  },
                  {
                    "at": "2026-08-05T04:45:00Z",
                    "value": 93.2
                  }
                ]
              },
              "meta": {
                "measure": "trend",
                "basis": "hourly",
                "window": {
                  "from": "2026-08-04T05:00:00Z",
                  "to": "2026-08-05T05:00:00Z"
                },
                "versions": {
                  "trendModel": "trend-nb-predictive-v2",
                  "topicAlgorithm": "trend-nb-predictive-v2.topic-relevance-v3"
                },
                "history": {
                  "lookbackDays": 90,
                  "earliestAvailableAt": "2026-05-07T00:00:00Z"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  },
  "503": {
    "$ref": "#/components/responses/Unavailable"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# List Intel

`GET /v3/intel`

Discrete evidence-graded developments. `grades` filters on the
evidence ladder from `chipped` to `flawless`. Project filters combine
with AND across kinds and OR within one comma-separated value.

`search` is free-text search: the query parses into meaningful terms
that must all match, against project identity (names, tickers,
handles, addresses, chains) and intel text. Matched items carry a
`searchMatches` array explaining each match. Search results page
through `meta.nextCursor`. Every non-empty query shape is accepted.
When responsive candidate or recent-result bounds may omit matches,
`meta.searchCoverage` names the bound and `meta.executedSearch`
discloses any normalized scope that differs from the request.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "$ref": "#/components/parameters/Cursor"
  },
  {
    "$ref": "#/components/parameters/Limit"
  },
  {
    "name": "search",
    "in": "query",
    "description": "Free-text deep search; combines with every other filter.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "sort",
    "in": "query",
    "description": "`detectedAt` orders by first sighting; `reinforcedAt` by the\nlatest confirming observation of any kind (an echoed story).\n",
    "schema": {
      "type": "string",
      "enum": [
        "reinforcedAt",
        "detectedAt"
      ],
      "default": "detectedAt"
    }
  },
  {
    "name": "projectIds",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "projectSlugs",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "names",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "xHandles",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "tickers",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "address",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "assetTypes",
    "in": "query",
    "description": "Comma-separated asset types of the parent Project.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "marketCap",
    "in": "query",
    "description": "Restrict to Projects whose current market cap is in the named band: `low` (under $80M), `mid` ($80M to $500M), or `large` ($500M and above). Projects without a current market cap are excluded. The band is a filter only; responses carry no market data.",
    "schema": {
      "type": "string",
      "enum": [
        "low",
        "mid",
        "large"
      ]
    }
  },
  {
    "name": "projectRanking",
    "in": "query",
    "description": "Restrict to Projects in the named ranking cohort.",
    "schema": {
      "type": "string",
      "enum": [
        "trend"
      ]
    }
  },
  {
    "name": "clusterIds",
    "in": "query",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "categories",
    "in": "query",
    "description": "Comma-separated intel event categories (see `/v3/vocabulary`).",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "grades",
    "in": "query",
    "description": "Comma-separated evidence grades.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "sentiments",
    "in": "query",
    "description": "Comma-separated sentiment values.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "hasOfficialSource",
    "in": "query",
    "schema": {
      "type": "boolean"
    }
  },
  {
    "name": "minClusters",
    "in": "query",
    "schema": {
      "type": "integer",
      "minimum": 1
    }
  },
  {
    "name": "detectedAfter",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "detectedBefore",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "reinforcedAfter",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "reinforcedBefore",
    "in": "query",
    "schema": {
      "type": "string",
      "format": "date-time"
    }
  },
  {
    "name": "activity",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "all",
        "observations",
        "none"
      ],
      "default": "all"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Intel page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Intel"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/IntelCollectionMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Recent graded intel",
            "value": {
              "data": [
                {
                  "id": "6890aa000000000000000001",
                  "headline": "Mainnet v2 date confirmed",
                  "description": "ExampleChain confirmed the v2 mainnet date for September 3rd with a public changelog entry.",
                  "grade": "polished",
                  "project": {
                    "id": "665f0a2b1c9d440000a1b2c3",
                    "slug": "examplechain",
                    "name": "ExampleChain"
                  },
                  "category": "product-launch",
                  "clusters": [
                    {
                      "id": "cl_defi",
                      "name": "DeFi researchers"
                    }
                  ],
                  "observationCount": 9,
                  "hasOfficialSource": true,
                  "citations": [
                    "https://blog.example.chain/v2-mainnet"
                  ],
                  "sentiment": {
                    "value": "positive"
                  },
                  "detectedAt": "2026-08-04T21:14:00Z",
                  "reinforcedAt": "2026-08-05T03:40:00Z"
                }
              ],
              "meta": {
                "nextCursor": "b3BhcXVlLWN1cnNvcg",
                "history": {
                  "lookbackDays": 90,
                  "earliestAvailableAt": "2026-05-07T00:00:00Z"
                }
              }
            }
          },
          "empty": {
            "summary": "No intel matched the qualifiers",
            "value": {
              "data": [],
              "meta": {
                "nextCursor": null
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get an Intel item

`GET /v3/intel/{id}`

Intel detail with the activity trail and cluster composition. The
history boundary is enforced against the intel's own recency
(`reinforcedAt`, falling back to `detectedAt`).

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "activity",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "all",
        "observations",
        "none"
      ],
      "default": "all"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Intel detail.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/IntelDetail"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Detail with activity and composition",
            "value": {
              "data": {
                "id": "6890aa000000000000000001",
                "headline": "Mainnet v2 date confirmed",
                "description": "ExampleChain confirmed the v2 mainnet date for September 3rd with a public changelog entry.",
                "grade": "polished",
                "project": {
                  "id": "665f0a2b1c9d440000a1b2c3",
                  "slug": "examplechain",
                  "name": "ExampleChain"
                },
                "category": "product-launch",
                "clusters": [
                  {
                    "id": "cl_defi",
                    "name": "DeFi researchers"
                  }
                ],
                "observationCount": 9,
                "hasOfficialSource": true,
                "citations": [
                  "https://blog.example.chain/v2-mainnet"
                ],
                "sentiment": {
                  "value": "positive"
                },
                "detectedAt": "2026-08-04T21:14:00Z",
                "reinforcedAt": "2026-08-05T03:40:00Z",
                "activity": [
                  {
                    "action": "observation",
                    "detectedAt": "2026-08-04T21:14:00Z",
                    "occurredAt": "2026-08-04T21:14:00Z",
                    "eventTime": {
                      "status": "instant",
                      "at": "2026-09-03T00:00:00Z",
                      "precision": "day",
                      "relationToSource": "future"
                    },
                    "headline": "First sighting",
                    "source": {
                      "url": "https://x.com/someone/status/1",
                      "official": false
                    },
                    "sentiment": {
                      "value": "positive"
                    }
                  },
                  {
                    "action": "official_statement",
                    "detectedAt": "2026-08-04T22:03:00Z",
                    "occurredAt": "2026-08-04T22:03:00Z",
                    "eventTime": {
                      "status": "unknown",
                      "reason": "ambiguous"
                    },
                    "source": {
                      "url": "https://blog.example.chain/v2-mainnet",
                      "official": true
                    }
                  }
                ],
                "clusterComposition": [
                  {
                    "cluster": {
                      "id": "cl_defi",
                      "name": "DeFi researchers"
                    },
                    "percentage": 62.5
                  },
                  {
                    "cluster": {
                      "id": "cl_other",
                      "name": "Other"
                    },
                    "percentage": 37.5
                  }
                ]
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# List published Reports

`GET /v3/reports`

Top-level read-only collection of published research artifacts, newest
first, with relationship filters. List items are bounded previews;
the full body requires the `topic-reports` entitlement on the detail
route.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "$ref": "#/components/parameters/Cursor"
  },
  {
    "$ref": "#/components/parameters/Limit"
  },
  {
    "name": "projectId",
    "in": "query",
    "description": "Current canonical Project id. Matches Reports whose frozen publication-time binding used this id or one of its absorbed id aliases.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "projectSlug",
    "in": "query",
    "description": "Current canonical Project slug or slug alias. Matches the same frozen publication-time bindings as projectId.",
    "schema": {
      "type": "string"
    }
  },
  {
    "name": "topicId",
    "in": "query",
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Report page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/ReportListItem"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/CollectionMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Latest reports",
            "value": {
              "data": [
                {
                  "id": "tr_9f2b6c41d8a35e07b1c4f6a2d5e8091c3b7a4f60d2e5c8b1a4f7092c5d8e3b6a",
                  "title": "Restaking Yield Compression",
                  "publishedAt": "2026-08-04T18:00:00Z",
                  "revisedAt": null,
                  "primarySubject": {
                    "type": "topic",
                    "topic": {
                      "id": "topic_a1b2c3d4e5f601234567",
                      "name": "Restaking yield compression"
                    }
                  },
                  "relatedSubjects": [
                    {
                      "type": "project",
                      "project": {
                        "id": "665f0a2b1c9d440000a1b2c3",
                        "slug": "examplechain",
                        "name": "ExampleChain"
                      }
                    }
                  ],
                  "preview": "Yields across restaking protocols compress as new AVS demand stalls..."
                }
              ],
              "meta": {
                "nextCursor": null
              }
            }
          },
          "empty": {
            "summary": "No reports for the filter",
            "value": {
              "data": [],
              "meta": {
                "nextCursor": null
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get a published Report

`GET /v3/reports/{id}`

Full report artifact: body, typed sources, and the publication-time
evidence block. Requires the `topic-reports` entitlement. The
evidence block quotes market figures with source attribution as
part of the published research.

## Authentication

Required. Send an API key in the `x-api-key` header.
Required account access: `topic-reports`.

## Parameters

```json
[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Report detail.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Report"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Full report",
            "value": {
              "data": {
                "id": "tr_9f2b6c41d8a35e07b1c4f6a2d5e8091c3b7a4f60d2e5c8b1a4f7092c5d8e3b6a",
                "title": "Restaking Yield Compression",
                "publishedAt": "2026-08-04T18:00:00Z",
                "revisedAt": null,
                "primarySubject": {
                  "type": "topic",
                  "topic": {
                    "id": "topic_a1b2c3d4e5f601234567",
                    "name": "Restaking yield compression"
                  }
                },
                "relatedSubjects": [
                  {
                    "type": "project",
                    "project": {
                      "id": "665f0a2b1c9d440000a1b2c3",
                      "slug": "examplechain",
                      "name": "ExampleChain"
                    }
                  }
                ],
                "summary": "Yields across restaking protocols compress as new AVS demand stalls.",
                "body": "## Thesis\n\nYields compress because...",
                "sources": [
                  {
                    "title": "AVS demand dashboard",
                    "url": "https://dune.com/example/avs",
                    "publishedAt": "2026-08-03T00:00:00Z"
                  }
                ],
                "evidence": {
                  "snapshotAt": "2026-08-04T18:00:00Z",
                  "entities": [
                    {
                      "project": {
                        "id": "665f0a2b1c9d440000a1b2c3",
                        "slug": "examplechain",
                        "name": "ExampleChain"
                      },
                      "observations": [
                        {
                          "key": "avs_count",
                          "value": 41,
                          "unit": "count",
                          "provider": "aixbt",
                          "observedAt": "2026-08-04T17:58:00Z",
                          "freshness": "fresh"
                        }
                      ]
                    }
                  ]
                }
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# List Clusters

`GET /v3/clusters`

Audience/source archetypes used as an analysis dimension across Topics and Intel.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "universe",
    "in": "query",
    "schema": {
      "type": "string",
      "enum": [
        "crypto",
        "tradfi"
      ],
      "default": "crypto"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Clusters.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Cluster"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Crypto universe clusters",
            "value": {
              "data": [
                {
                  "id": "cl_defi",
                  "name": "DeFi researchers",
                  "description": "Protocol analysts and yield researchers.",
                  "universe": "crypto"
                }
              ],
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# List my alert subscriptions

`GET /v3/alerts`

Alert subscriptions owned by the calling credential. One owner may
hold at most 50 subscriptions, paused rows included. Lists the
API-manageable kinds (`intelligence.material`, `rank.entered`);
preset subscriptions managed in product Settings do not appear
here.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "$ref": "#/components/parameters/Cursor"
  },
  {
    "$ref": "#/components/parameters/Limit"
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Alert page.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/Alert"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/CollectionMeta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Owner subscriptions",
            "value": {
              "data": [
                {
                  "id": "66a10a2b1c9d440000d1e2f3",
                  "status": "active",
                  "trigger": "intelligence.material",
                  "selector": {
                    "followedProjects": true,
                    "qualifiers": {
                      "grades": [
                        "polished",
                        "flawless"
                      ],
                      "categories": [
                        "product-launch"
                      ]
                    }
                  },
                  "cadence": "hourly",
                  "destinationIds": [
                    "66a10a2b1c9d440000aa0001"
                  ],
                  "createdAt": "2026-08-01T10:00:00Z",
                  "updatedAt": "2026-08-05T04:00:00Z"
                }
              ],
              "meta": {
                "nextCursor": null
              }
            }
          },
          "empty": {
            "summary": "No subscriptions yet",
            "value": {
              "data": [],
              "meta": {
                "nextCursor": null
              }
            }
          }
        }
      }
    }
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Create an alert subscription

`POST /v3/alerts`

Creates an owner-scoped subscription: selector + one trigger +
delivery cadence + explicit destination ids. Destinations are
provisioned in product Settings and referenced here by id. Chat
cadence defaults to `hourly`; `instant` is subject to a per-day
platform safety ceiling. Webhook destinations receive every admitted
event regardless of cadence. The 50-subscription owner cap and
selector list bounds (20 values per list) are enforced. An account
holds at most one `rank.entered` subscription; creating a second
while one exists fails with `invalid_request`.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AlertCreate"
      },
      "examples": {
        "materialIntel": {
          "summary": "Material intel on followed Projects",
          "value": {
            "trigger": "intelligence.material",
            "selector": {
              "followedProjects": true,
              "qualifiers": {
                "grades": [
                  "polished",
                  "flawless"
                ]
              }
            },
            "cadence": "hourly",
            "destinationIds": [
              "66a10a2b1c9d440000aa0001"
            ]
          }
        },
        "rankEntry": {
          "summary": "Rank entry into the top 10",
          "value": {
            "trigger": "rank.entered",
            "rankThreshold": 10,
            "selector": {
              "qualifiers": {
                "categories": [
                  "modular-blockchains"
                ]
              }
            },
            "cadence": "instant",
            "destinationIds": [
              "66a10a2b1c9d440000aa0002"
            ]
          }
        }
      }
    }
  }
}
```

## Responses

```json
{
  "201": {
    "description": "Created subscription.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Alert"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Created",
            "value": {
              "data": {
                "id": "66a10a2b1c9d440000d1e2f4",
                "status": "active",
                "trigger": "rank.entered",
                "rankThreshold": 10,
                "selector": {
                  "qualifiers": {
                    "categories": [
                      "modular-blockchains"
                    ]
                  }
                },
                "cadence": "instant",
                "destinationIds": [
                  "66a10a2b1c9d440000aa0002"
                ],
                "createdAt": "2026-08-05T05:00:00Z",
                "updatedAt": "2026-08-05T05:00:00Z"
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "403": {
    "$ref": "#/components/responses/Forbidden"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Delete an alert subscription

`DELETE /v3/alerts/{id}`

Removes the subscription; delivery history retention is unaffected.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "204": {
    "description": "Deleted."
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get an alert subscription

`GET /v3/alerts/{id}`

Owner-scoped read; another owner's id behaves as `not_found`.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Subscription.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Alert"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "One subscription",
            "value": {
              "data": {
                "id": "66a10a2b1c9d440000d1e2f3",
                "status": "active",
                "trigger": "intelligence.material",
                "selector": {
                  "followedProjects": true
                },
                "cadence": "hourly",
                "destinationIds": [
                  "66a10a2b1c9d440000aa0001"
                ],
                "createdAt": "2026-08-01T10:00:00Z",
                "updatedAt": "2026-08-05T04:00:00Z"
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Update an alert subscription

`PATCH /v3/alerts/{id}`

Partial update: pause/resume, rename, change cadence, selector,
threshold, or destinations. Semantics are identical to creation.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "name": "id",
    "in": "path",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/AlertUpdate"
      },
      "examples": {
        "pause": {
          "summary": "Pause delivery",
          "value": {
            "status": "paused"
          }
        }
      }
    }
  }
}
```

## Responses

```json
{
  "200": {
    "description": "Updated subscription.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Alert"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Paused",
            "value": {
              "data": {
                "id": "66a10a2b1c9d440000d1e2f3",
                "status": "paused",
                "trigger": "intelligence.material",
                "selector": {
                  "followedProjects": true
                },
                "cadence": "hourly",
                "destinationIds": [
                  "66a10a2b1c9d440000aa0001"
                ],
                "createdAt": "2026-08-01T10:00:00Z",
                "updatedAt": "2026-08-05T05:10:00Z"
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "400": {
    "$ref": "#/components/responses/BadRequest"
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "404": {
    "$ref": "#/components/responses/SubjectMiss"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# List my delivery destinations

`GET /v3/alerts/destinations`

Read-only list of destinations connected in product Settings
(Telegram, Discord, signed webhooks). Creation, secret rotation,
and repair stay in Settings; subscriptions reference these ids.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Destinations.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/AlertDestination"
              }
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Connected destinations",
            "value": {
              "data": [
                {
                  "id": "66a10a2b1c9d440000aa0001",
                  "kind": "telegram",
                  "label": "Team channel",
                  "status": "active"
                },
                {
                  "id": "66a10a2b1c9d440000aa0002",
                  "kind": "webhook",
                  "label": "prod ingest",
                  "status": "active"
                }
              ],
              "meta": {}
            }
          }
        }
      }
    }
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get the filter vocabularies

`GET /v3/vocabulary`

One discovery surface for every value a v3 filter accepts. Closed
vocabularies (grades, sentiments, stances, sort keys, activity modes,
rankings, universes, asset types, series measures) are versioned with
the contract; catalog-derived sets (project categories, intel
categories, chains) are composed from their owning catalogs at read
time and carry their own versions.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Vocabularies.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Vocabulary"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "Current vocabularies",
            "value": {
              "data": {
                "grades": [
                  "chipped",
                  "flawed",
                  "cut",
                  "polished",
                  "flawless"
                ],
                "sentiments": [
                  "positive",
                  "neutral",
                  "negative"
                ],
                "stances": [
                  "supportive",
                  "skeptical",
                  "neutral",
                  "mixed",
                  "unknown"
                ],
                "assetTypes": [
                  "token",
                  "stablecoin",
                  "nft-collection"
                ],
                "marketCapBands": [
                  "low",
                  "mid",
                  "large"
                ],
                "projectSort": [
                  "trend",
                  "createdAt",
                  "reinforcedAt"
                ],
                "intelSort": [
                  "reinforcedAt",
                  "detectedAt"
                ],
                "activityModes": [
                  "all",
                  "observations",
                  "none"
                ],
                "projectRankings": [
                  "trend"
                ],
                "universes": [
                  "crypto",
                  "tradfi"
                ],
                "seriesMeasures": [
                  "trend",
                  "rank"
                ],
                "alertTriggers": [
                  "intelligence.material",
                  "rank.entered"
                ],
                "alertCadences": [
                  "instant",
                  "hourly",
                  "every_12h",
                  "daily"
                ],
                "projectCategories": [
                  {
                    "slug": "modular-blockchains",
                    "name": "Modular blockchains"
                  }
                ],
                "intelCategories": [
                  {
                    "slug": "product-launch",
                    "name": "Product launch"
                  }
                ],
                "chains": [
                  "ethereum",
                  "solana",
                  "base"
                ]
              },
              "meta": {
                "versions": {
                  "vocabulary": "3.0.0-draft.1",
                  "taxonomy": "taxonomy-v2"
                }
              }
            }
          }
        }
      }
    }
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get the signed-in account

`GET /v3/me`

The account behind the credential: its id, plan with billing
period, and wallet (last four characters only), plus the effective
rate limits and history window. Replaces `/v2/api-keys/info`.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "The signed-in account.",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "data",
            "meta"
          ],
          "properties": {
            "data": {
              "$ref": "#/components/schemas/Me"
            },
            "meta": {
              "$ref": "#/components/schemas/Meta"
            }
          }
        },
        "examples": {
          "success": {
            "summary": "A Frontier account",
            "value": {
              "data": {
                "account": {
                  "id": "66f1c0a2e4b0c1d2e3f40516",
                  "plan": {
                    "name": "AIXBT Frontier",
                    "via": "subscription",
                    "status": "active",
                    "periodStart": "2026-09-01T00:00:00Z",
                    "renewsAt": "2026-10-01T00:00:00Z",
                    "endsAt": null
                  },
                  "wallet": {
                    "chain": "eip155",
                    "last4": "a3F9"
                  }
                },
                "rateLimit": {
                  "perMinute": 100,
                  "perDay": 10000
                },
                "history": {
                  "lookbackDays": 90
                }
              },
              "meta": {}
            }
          }
        }
      }
    }
  },
  "401": {
    "$ref": "#/components/responses/Unauthorized"
  },
  "429": {
    "$ref": "#/components/responses/RateLimited"
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Get this contract

`GET /v3/openapi.yaml`

The canonical v3 OpenAPI document, served verbatim. No credential required.

## Authentication

None. This endpoint is public.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "This document.",
    "content": {
      "application/yaml": {
        "schema": {
          "type": "string"
        }
      }
    }
  },
  "500": {
    "$ref": "#/components/responses/Internal"
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v3/openapi.yaml).

# Overview



<Callout type="warn">
  v2 is deprecated. New integrations should use [API v3](/developers/v3);
  if you are on v2 today, the [migration guide](/developers/v3/migration)
  maps every route and field. v2 remains available while you migrate.
</Callout>

The base URL is `https://api.aixbt.tech/v2`.

## Authentication [#authentication]

This public request returns the current Trending topics ranking:

```bash
curl --fail-with-body "https://api.aixbt.tech/v2/topics"
```

Trend is the sole ranking.

Most data routes require a key from [Developer
access](https://aixbt.tech/profile#developer-access), sent in the `x-api-key` header:

```bash
curl --fail-with-body "https://api.aixbt.tech/v2/projects?limit=5" \
  -H "x-api-key: YOUR_API_KEY"
```

## Response contracts [#response-contracts]

Most data endpoints return `status` and `data`. List endpoints can also return
`pagination`, while endpoint-specific context appears under `meta`.

```json
{
  "status": 200,
  "data": [],
  "pagination": {
    "page": 1,
    "limit": 50,
    "totalCount": 0,
    "hasMore": false
  }
}
```

Response and error shapes are endpoint-specific. Consume `code` only when the
endpoint advertises it.

## Rate limits [#rate-limits]

Key-specific limits appear in [Developer
access](https://aixbt.tech/profile#developer-access). Responses expose the applicable
`X-RateLimit-*` headers. A rate-limited request returns `429` and `Retry-After`.

## Pagination and filtering [#pagination-and-filtering]

Paginated list endpoints use `page` and `limit`. Where multi-value filters are
supported, comma-separated values use OR logic within one parameter; separate
filter parameters use AND logic.

## Reference [#reference]

Use the [Reference](/developers/rest-api/reference) for each endpoint's
parameters, authentication, schemas, examples, and live request form. For help,
[contact support](/support/get-support).


# Reference



See [Overview](/developers/rest-api) for authentication and request basics. Base URL: `https://api.aixbt.tech`. v2 is deprecated; see the [v3 API](/developers/v3).

## API [#api]

* [`GET /v2`](/developers/rest-api/reference/get-v2) — V2 API root endpoint
* [`GET /v2/api-keys/info`](/developers/rest-api/reference/get-v2-api-keys-info) — Get API Key Information

## Topics [#topics]

* [`GET /v2/grounding`](/developers/rest-api/reference/get-v2-grounding) — Get Topic Rankings (Legacy Alias)
* [`GET /v2/grounding/history`](/developers/rest-api/reference/get-v2-grounding-history) — Get Topic Leaderboard History (Legacy Alias)
* [`GET /v2/topics`](/developers/rest-api/reference/get-v2-topics) — Get Topic Rankings
* [`GET /v2/topics/{id}/report`](/developers/rest-api/reference/get-v2-topics-id-report) — Get a Frontier Report

## Projects [#projects]

* [`GET /v2/projects`](/developers/rest-api/reference/get-v2-projects) — List Projects
* [`GET /v2/projects/{id}`](/developers/rest-api/reference/get-v2-projects-id) — Get Project
* [`GET /v2/projects/{id}/neighbors`](/developers/rest-api/reference/get-v2-projects-id-neighbors) — Project Neighbors (co-mentioned projects)

## Intel [#intel]

* [`GET /v2/intel`](/developers/rest-api/reference/get-v2-intel) — List Intel
* [`GET /v2/intel/{id}`](/developers/rest-api/reference/get-v2-intel-id) — Get Intel by ID

## Signals [#signals]

* [`GET /v2/signals`](/developers/rest-api/reference/get-v2-signals) — List Signals (deprecated alias of /v2/intel)
* [`GET /v2/signals/{id}`](/developers/rest-api/reference/get-v2-signals-id) — Get Signal by ID (deprecated alias)

## Momentum [#momentum]

* [`GET /v2/projects/{id}/momentum`](/developers/rest-api/reference/get-v2-projects-id-momentum) — Momentum History

## Rank [#rank]

* [`GET /v2/projects/{id}/rank`](/developers/rest-api/reference/get-v2-projects-id-rank) — Rank History

## Candles [#candles]

* [`GET /v2/projects/{id}/candles`](/developers/rest-api/reference/get-v2-projects-id-candles) — Price Candles (OHLCV)

## Metrics [#metrics]

* [`GET /v2/projects/{id}/metrics`](/developers/rest-api/reference/get-v2-projects-id-metrics) — Project Metrics Snapshot

## Clusters [#clusters]

* [`GET /v2/clusters`](/developers/rest-api/reference/get-v2-clusters) — List Clusters

## Intel Categories [#intel-categories]

* [`GET /v2/intel-categories`](/developers/rest-api/reference/get-v2-intel-categories) — List Intel Categories

## Blockchain Platforms [#blockchain-platforms]

* [`GET /v2/projects/chains`](/developers/rest-api/reference/get-v2-projects-chains) — List Blockchain Platforms

## Recipes [#recipes]

* [`GET /v2/recipes`](/developers/rest-api/reference/get-v2-recipes) — List available recipes
* [`GET /v2/recipes/{name}`](/developers/rest-api/reference/get-v2-recipes-name) — Get recipe by name
* [`POST /v2/recipes/execute`](/developers/rest-api/reference/post-v2-recipes-execute) — Execute a recipe
* [`POST /v2/recipes/validate`](/developers/rest-api/reference/post-v2-recipes-validate) — Validate a recipe


# V2 API root endpoint

`GET /v2`

## Authentication

None. This endpoint is public.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "API information",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "name",
            "version",
            "status"
          ],
          "properties": {
            "name": {
              "type": "string",
              "examples": [
                "AIXBT API"
              ]
            },
            "version": {
              "type": "string",
              "examples": [
                "2.0.0"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "active"
              ]
            }
          }
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get API Key Information

`GET /v2/api-keys/info`

Returns metadata and expiry for the authenticated API key.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "API key information",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status",
            "data"
          ],
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "type": "object",
              "required": [
                "id",
                "name",
                "type",
                "expiresAt"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                },
                "expiresAt": {
                  "description": "ISO 8601 expiry or `never` for a non-expiring key.",
                  "oneOf": [
                    {
                      "type": "string",
                      "format": "date-time"
                    },
                    {
                      "type": "string",
                      "enum": [
                        "never"
                      ]
                    }
                  ]
                }
              }
            }
          }
        }
      }
    }
  },
  "401": {
    "description": "Missing or invalid API key",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get Topic Rankings (Legacy Alias)

`GET /v2/grounding`

Deprecated compatibility path returning the top 10 ranked crypto topics.
New integrations should use `GET /v2/topics`. Topics are sorted by
recency-weighted 48-hour attention rank and include summary, score,
latest-24-hour tweet/author breadth, and freshness.

**No authentication required.** Returns real-time data for all requests.
Unauthenticated responses include `meta` with upgrade information.

**Authenticated:** Supports historical snapshots via `?at=`.
Using `?at=` without authentication returns 403.

## Authentication

None. This endpoint is public.

## Lifecycle

Deprecated.

## Parameters

```json
[
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical timestamp (ISO 8601). Returns the snapshot that was active at this time.\nOnly available for authenticated requests. Must be in the past.\n",
    "examples": {
      "default": {
        "value": "2026-03-25T12:00:00Z"
      }
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Top-10 topic rankings",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/UpgradeMeta"
                },
                {
                  "$ref": "#/components/schemas/HistoryResponseMeta"
                }
              ]
            },
            "data": {
              "type": "object",
              "properties": {
                "completedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "windowStartedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "topics": {
                  "type": "array",
                  "maxItems": 10,
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "rank": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      },
                      "summary": {
                        "type": "string"
                      },
                      "score": {
                        "type": "number"
                      },
                      "tweetCount": {
                        "type": "integer",
                        "description": "Qualifying tweets in the latest 24 hours"
                      },
                      "authorCount": {
                        "type": "integer",
                        "description": "Distinct qualifying authors in the latest 24 hours"
                      },
                      "lastSeenAt": {
                        "type": "string",
                        "format": "date-time"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid `at` parameter",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "No topic leaderboard snapshot found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get Topic Leaderboard History (Legacy Alias)

`GET /v2/grounding/history`

Deprecated compatibility path for paginated historical topic leaderboard snapshots.
New integrations should use `GET /v2/topics`.

Each snapshot contains up to 10 structured topics in attention-rank order.
Supports date range filtering with `from`/`to` and anchor clamping with `at`.
Requires authentication.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Lifecycle

Deprecated.

## Parameters

```json
[
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Anchor timestamp. Clamps `to` if it exceeds this value. Defaults to now."
  },
  {
    "in": "query",
    "name": "from",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Range start (createdAt >= from)"
  },
  {
    "in": "query",
    "name": "to",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Range end (createdAt <= to), clamped by `at`"
  },
  {
    "in": "query",
    "name": "page",
    "schema": {
      "type": "integer",
      "default": 1
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "type": "integer",
      "default": 50,
      "maximum": 50
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Paginated topic leaderboard history",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status",
            "data",
            "pagination"
          ],
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/TopicIndexSnapshot"
              }
            },
            "pagination": {
              "$ref": "#/components/schemas/Pagination"
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid parameters",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch topic history",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get Topic Rankings

`GET /v2/topics`

Returns the top 25 crypto narratives drawing the most attention on X,
ranked and refreshed hourly. This is the REST equivalent of the MCP
`get_trending_topics` tool.

No authentication is required.

## Authentication

None. This endpoint is public.

## Parameters

```json
[
  {
    "in": "query",
    "name": "ranking",
    "required": false,
    "schema": {
      "type": "string",
      "enum": [
        "trend"
      ],
      "default": "trend"
    },
    "description": "Trending sustained-attention board."
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Current topic rankings",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status",
            "data"
          ],
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "type": "object",
              "required": [
                "completedAt",
                "latestEvidenceAt",
                "windowStartedAt",
                "topics"
              ],
              "properties": {
                "completedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "latestEvidenceAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time",
                  "description": "Newest source tweet timestamp represented by the stored leaderboard"
                },
                "windowStartedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "topics": {
                  "type": "array",
                  "maxItems": 25,
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "rank",
                      "name",
                      "summary",
                      "score",
                      "tweetCount",
                      "authorCount",
                      "lastSeenAt",
                      "clusters",
                      "frontierReport"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "rank": {
                        "type": "integer"
                      },
                      "name": {
                        "type": "string"
                      },
                      "summary": {
                        "type": "string"
                      },
                      "score": {
                        "type": "number"
                      },
                      "tweetCount": {
                        "type": "integer",
                        "description": "Qualifying tweets in the latest 24 hours"
                      },
                      "authorCount": {
                        "type": "integer",
                        "description": "Distinct qualifying authors in the latest 24 hours"
                      },
                      "lastSeenAt": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "clusters": {
                        "type": "array",
                        "description": "Complete non-zero author-balanced cluster composition for the ranking window,\nsorted by descending share. Each author's mass is split across their labels;\nthe shares therefore sum approximately to the fraction of authors with at least one cluster label.\n",
                        "items": {
                          "type": "object",
                          "required": [
                            "id",
                            "name",
                            "share"
                          ],
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "share": {
                              "type": "number",
                              "minimum": 0,
                              "maximum": 1
                            }
                          }
                        }
                      },
                      "frontierReport": {
                        "type": [
                          "object",
                          "null"
                        ],
                        "required": [
                          "url",
                          "preview"
                        ],
                        "properties": {
                          "url": {
                            "type": "string",
                            "format": "uri"
                          },
                          "preview": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch topic rankings",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get a Frontier Report

`GET /v2/topics/{id}/report`

Returns the latest published full Frontier Report for a topic. The
`id` is the topic id returned by `GET /v2/topics`. This endpoint
requires an account-backed credential with Frontier Reports access.

## Authentication

Required. Send an API key in the `x-api-key` header.
Required account access: `topic-reports`.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string",
      "pattern": "^topic_[a-f0-9]{20}$"
    },
    "description": "Topic id from the topic rankings response"
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Latest published Frontier Report",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status",
            "data"
          ],
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "type": "object",
              "required": [
                "id",
                "url",
                "publishedAt",
                "title",
                "summary",
                "bodyMarkdown",
                "sources"
              ],
              "properties": {
                "id": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "publishedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "title": {
                  "type": "string"
                },
                "summary": {
                  "type": "string"
                },
                "bodyMarkdown": {
                  "type": "string",
                  "description": "GFM report body without internal source-id markers."
                },
                "market": {
                  "type": "object",
                  "description": "Publication-time and latest market snapshots. This field is omitted when market data is unavailable.",
                  "required": [
                    "publicationSnapshotAt",
                    "updatedAt",
                    "state",
                    "entities"
                  ],
                  "properties": {
                    "publicationSnapshotAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "updatedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "fresh",
                        "stale",
                        "partial",
                        "unavailable"
                      ]
                    },
                    "entities": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "identity",
                          "state",
                          "metrics"
                        ],
                        "properties": {
                          "identity": {
                            "type": "object",
                            "required": [
                              "projectId",
                              "name"
                            ],
                            "properties": {
                              "projectId": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              },
                              "symbol": {
                                "type": "string"
                              },
                              "coingeckoId": {
                                "type": "string"
                              },
                              "defillamaSlug": {
                                "type": "string"
                              }
                            }
                          },
                          "state": {
                            "type": "string",
                            "enum": [
                              "fresh",
                              "stale",
                              "partial",
                              "unavailable"
                            ]
                          },
                          "metrics": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "required": [
                                "key",
                                "value",
                                "publishedValue",
                                "unit",
                                "provider",
                                "observedAt",
                                "fetchedAt",
                                "freshness"
                              ],
                              "properties": {
                                "key": {
                                  "type": "string",
                                  "enum": [
                                    "price_usd",
                                    "market_cap_usd",
                                    "volume_24h_usd",
                                    "change_24h_pct",
                                    "tvl_usd",
                                    "fees_24h_usd",
                                    "revenue_24h_usd"
                                  ]
                                },
                                "value": {
                                  "type": [
                                    "number",
                                    "null"
                                  ]
                                },
                                "publishedValue": {
                                  "type": [
                                    "number",
                                    "null"
                                  ]
                                },
                                "unit": {
                                  "type": "string",
                                  "enum": [
                                    "usd",
                                    "percent"
                                  ]
                                },
                                "provider": {
                                  "type": "string",
                                  "enum": [
                                    "coingecko",
                                    "defillama",
                                    "project_metrics"
                                  ]
                                },
                                "observedAt": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "format": "date-time"
                                },
                                "fetchedAt": {
                                  "type": "string",
                                  "format": "date-time"
                                },
                                "freshness": {
                                  "type": "string",
                                  "enum": [
                                    "fresh",
                                    "stale",
                                    "unavailable"
                                  ]
                                },
                                "disagreement": {
                                  "type": "object",
                                  "required": [
                                    "comparedWith",
                                    "comparedValue",
                                    "differencePercent"
                                  ],
                                  "properties": {
                                    "comparedWith": {
                                      "type": "string",
                                      "enum": [
                                        "coingecko",
                                        "defillama",
                                        "project_metrics"
                                      ]
                                    },
                                    "comparedValue": {
                                      "type": "number"
                                    },
                                    "differencePercent": {
                                      "type": "number"
                                    }
                                  }
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "sources": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "id",
                      "title",
                      "url",
                      "publishedAt"
                    ],
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "title": {
                        "type": "string"
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "publishedAt": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid topic id",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "401": {
    "description": "Missing or invalid account-backed API key",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Current account plan lacks Frontier Reports access",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "No published Frontier Report for this topic",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch the Frontier Report",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# List Projects

`GET /v2/projects`

Returns a paginated list of projects with signals, coingeckoData, one canonical trendScore, and one trend rank.

**Filter Behavior:**
- Multi-value filters (projectIds, names, xHandles, tickers) use OR logic within the same filter
- Different filters use AND logic between them
- Project category filters accept canonical taxonomy slugs or supported CoinGecko aliases and match any listed category
- Market-cap filters require a known positive USD market cap; missing, null, or zero market cap is excluded
- Example: `names=eth,btc&tickers=SOL` returns projects matching (name=eth OR name=btc) AND ticker=SOL

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "query",
    "name": "page",
    "schema": {
      "type": "integer",
      "default": 1
    },
    "description": "Page number (1-indexed)"
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "type": "integer",
      "default": 50,
      "maximum": 50
    },
    "description": "Number of projects per page (max 50)"
  },
  {
    "in": "query",
    "name": "projectIds",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of project ObjectIds to filter by"
  },
  {
    "in": "query",
    "name": "names",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of project names to filter by (case-insensitive regex)"
  },
  {
    "in": "query",
    "name": "xHandles",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of X/Twitter handles to filter by"
  },
  {
    "in": "query",
    "name": "tickers",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of token tickers to filter by"
  },
  {
    "in": "query",
    "name": "chain",
    "schema": {
      "type": "string"
    },
    "description": "Filter by blockchain platform. See /projects/chains for values."
  },
  {
    "in": "query",
    "name": "categories",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated canonical project category slugs or supported CoinGecko aliases to filter by"
  },
  {
    "in": "query",
    "name": "address",
    "schema": {
      "type": "string"
    },
    "description": "Filter by contract address. EVM addresses are case-insensitive; non-EVM addresses (e.g., Solana) are case-sensitive.\nCan be combined with `chain` to filter by specific chain + address.\n",
    "examples": {
      "default": {
        "value": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599"
      }
    }
  },
  {
    "in": "query",
    "name": "minTrendScore",
    "schema": {
      "type": "number"
    },
    "description": "Minimum trend score threshold (0-100)"
  },
  {
    "in": "query",
    "name": "minMarketCap",
    "schema": {
      "type": "number",
      "minimum": 0
    },
    "description": "Minimum USD market cap. Requires projects to have a known positive market cap."
  },
  {
    "in": "query",
    "name": "maxMarketCap",
    "schema": {
      "type": "number",
      "minimum": 0
    },
    "description": "Maximum USD market cap. Requires projects to have a known positive market cap."
  },
  {
    "in": "query",
    "name": "sortBy",
    "schema": {
      "type": "string",
      "enum": [
        "trendScore",
        "createdAt",
        "reinforcedAt"
      ],
      "default": "trendScore"
    },
    "description": "Field to sort results by (always descending)."
  },
  {
    "in": "query",
    "name": "hasToken",
    "schema": {
      "type": "boolean"
    },
    "description": "Filter by token presence. `true` returns only projects with contract addresses, `false` returns only projects without."
  },
  {
    "in": "query",
    "name": "intelSortBy",
    "schema": {
      "type": "string",
      "enum": [
        "reinforcedAt",
        "createdAt",
        "detectedAt"
      ],
      "default": "detectedAt"
    },
    "description": "Sort embedded intel by original detection date (default) or supporting-evidence recency (`createdAt` and `detectedAt` are aliases)"
  },
  {
    "in": "query",
    "name": "intelActivity",
    "schema": {
      "$ref": "#/components/schemas/ActivityMode"
    },
    "description": "Controls activity data on embedded intel items.\n`all` (default) — full timeline; `observations` — observation entries only; `none` — omit activity array.\n"
  },
  {
    "in": "query",
    "name": "createdAfter",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Filter projects created on or after this date (ISO 8601)"
  },
  {
    "in": "query",
    "name": "createdBefore",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Filter projects created on or before this date (ISO 8601)"
  },
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical timestamp (ISO 8601). Returns project data as it existed at this point in time.\nMust be in the past.\nWhen used, responses include a `provenance` field indicating data source.\n",
    "examples": {
      "default": {
        "value": "2026-03-25T12:00:00Z"
      }
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Paginated list of projects with signals",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "xHandle": {
                    "type": "string"
                  },
                  "trendScore": {
                    "type": "number",
                    "minimum": 0,
                    "maximum": 100
                  },
                  "trendScoreDelta": {
                    "type": "number",
                    "description": "Change in trend score since the previous scoring refresh"
                  },
                  "rank": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "description": "Leaderboard position (1-100). Omitted when the project is not in the current ranked roster."
                  },
                  "rankBand": {
                    "type": "string",
                    "enum": [
                      "strong",
                      "corroborated"
                    ],
                    "description": "Evidence eligibility band for the current rank. Omitted when the project is unranked."
                  },
                  "coingeckoData": {
                    "type": "object",
                    "properties": {
                      "apiId": {
                        "type": "string"
                      },
                      "symbol": {
                        "type": "string"
                      },
                      "slug": {
                        "type": "string"
                      },
                      "description": {
                        "type": "string"
                      },
                      "contractAddress": {
                        "type": "string"
                      },
                      "categories": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      },
                      "image": {
                        "type": "object",
                        "properties": {
                          "thumb": {
                            "type": "string",
                            "format": "uri"
                          },
                          "small": {
                            "type": "string",
                            "format": "uri"
                          },
                          "large": {
                            "type": "string",
                            "format": "uri"
                          }
                        }
                      }
                    }
                  },
                  "metrics": {
                    "type": "object",
                    "description": "Price and market data from CoinGecko (updated every minute)",
                    "properties": {
                      "usd": {
                        "type": "number",
                        "description": "Current price in USD"
                      },
                      "usdMarketCap": {
                        "type": "number",
                        "description": "Market capitalization in USD"
                      },
                      "usd24hVol": {
                        "type": "number",
                        "description": "24-hour trading volume in USD"
                      },
                      "usd24hChange": {
                        "type": "number",
                        "description": "24-hour price change percentage"
                      },
                      "lastUpdatedAt": {
                        "type": "number",
                        "description": "Unix timestamp in seconds of the last metrics update"
                      },
                      "high24h": {
                        "type": "number"
                      },
                      "low24h": {
                        "type": "number"
                      },
                      "athUsd": {
                        "type": "number"
                      },
                      "athDate": {
                        "type": "string",
                        "format": "date-time"
                      },
                      "athChangePct": {
                        "type": "number"
                      },
                      "priceChange7d": {
                        "type": "number"
                      },
                      "priceChange14d": {
                        "type": "number"
                      },
                      "priceChange30d": {
                        "type": "number"
                      }
                    }
                  },
                  "tokens": {
                    "type": "array",
                    "description": "Contract addresses by blockchain platform",
                    "items": {
                      "type": "object",
                      "properties": {
                        "chain": {
                          "type": "string"
                        },
                        "address": {
                          "type": "string"
                        },
                        "source": {
                          "type": "string",
                          "description": "Data source (coingecko, dexscreener, tweet, grok)"
                        },
                        "primary": {
                          "type": "boolean",
                          "description": "Whether this is the project's current primary token"
                        }
                      }
                    }
                  },
                  "primaryComputedAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "When the primary token selection was computed"
                  },
                  "createdAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Project creation timestamp (ISO 8601)"
                  },
                  "updatedAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Project last updated timestamp (ISO 8601)"
                  },
                  "reinforcedAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Timestamp of last signal activity (created or reinforced) for this project"
                  },
                  "provenance": {
                    "type": "string",
                    "enum": [
                      "historical",
                      "constructed"
                    ],
                    "description": "Data source indicator (only present when `at` parameter is used).\n`historical` = reconstructed from a stored snapshot.\n`constructed` = assembled from available data (no exact snapshot found).\n"
                  },
                  "momentumContext": {
                    "$ref": "#/components/schemas/MomentumContext"
                  },
                  "signals": {
                    "type": "array",
                    "description": "10 most recent intel items sorted by detection date by default",
                    "items": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "detectedAt": {
                          "type": "string",
                          "format": "date-time",
                          "description": "Intel detection date"
                        },
                        "reinforcedAt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "Date when this intel was last reinforced with independent supporting evidence; null for research-only intel"
                        },
                        "description": {
                          "type": "string"
                        },
                        "headline": {
                          "type": "string",
                          "description": "Plain-language summary up to 10 words"
                        },
                        "projectName": {
                          "type": "string"
                        },
                        "projectId": {
                          "type": "string"
                        },
                        "citations": {
                          "type": "array",
                          "description": "Vetted non-X citations supporting this intel",
                          "items": {
                            "type": "string"
                          }
                        },
                        "category": {
                          "type": "string"
                        },
                        "observationCount": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "Number of observation-type activity entries"
                        },
                        "hasOfficialSource": {
                          "type": "boolean",
                          "description": "Whether any observation came from an official project source"
                        },
                        "officialSourceUrl": {
                          "type": "string",
                          "format": "uri",
                          "description": "Canonical official X provenance retained when the source observation is omitted from public activity"
                        },
                        "sentiment": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "minimum": -1,
                          "maximum": 1,
                          "description": "Aggregate sentiment averaged across activity entries"
                        },
                        "referencesMetrics": {
                          "type": [
                            "boolean",
                            "null"
                          ],
                          "description": "Whether this intel description references market metrics. `null` when not classified."
                        },
                        "clusters": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/SignalCluster"
                          }
                        },
                        "activity": {
                          "type": "array",
                          "description": "Activity timeline. Present unless `intelActivity=none`.",
                          "items": {
                            "$ref": "#/components/schemas/SignalActivity"
                          }
                        }
                      }
                    }
                  }
                }
              }
            },
            "pagination": {
              "type": "object",
              "properties": {
                "page": {
                  "type": "integer"
                },
                "limit": {
                  "type": "integer"
                },
                "totalCount": {
                  "type": "integer"
                },
                "hasMore": {
                  "type": "boolean"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "503": {
    "description": "Historical data service temporarily unavailable (only when `at` is used)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get Project

`GET /v2/projects/{id}`

Returns a project by ID, including the 10 most recent signals, full coingeckoData, and its canonical trend score.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "MongoDB ObjectId of the project"
  },
  {
    "in": "query",
    "name": "intelSortBy",
    "schema": {
      "type": "string",
      "enum": [
        "reinforcedAt",
        "createdAt",
        "detectedAt"
      ],
      "default": "detectedAt"
    },
    "description": "Sort embedded intel by original detection date (default) or supporting-evidence recency (`createdAt` and `detectedAt` are aliases)"
  },
  {
    "in": "query",
    "name": "intelActivity",
    "schema": {
      "$ref": "#/components/schemas/ActivityMode"
    },
    "description": "Controls activity data on embedded intel items.\n`all` (default) — full timeline; `observations` — observation entries only; `none` — omit activity array.\n"
  },
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical timestamp (ISO 8601). Returns project data as it existed at this point in time.\nMust be in the past.\nWhen used, responses include a `provenance` field indicating data source.\n",
    "examples": {
      "default": {
        "value": "2026-03-25T12:00:00Z"
      }
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Project details with signals",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "examples": [
                    "507f1f77bcf86cd799439011"
                  ]
                },
                "name": {
                  "type": "string",
                  "examples": [
                    "ethereum"
                  ]
                },
                "description": {
                  "type": "string"
                },
                "xHandle": {
                  "type": "string",
                  "examples": [
                    "ethereum"
                  ]
                },
                "trendScore": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100,
                  "examples": [
                    85
                  ]
                },
                "trendScoreDelta": {
                  "type": "number",
                  "description": "Change in trend score since the previous scoring refresh"
                },
                "rank": {
                  "type": "integer",
                  "minimum": 1,
                  "maximum": 100,
                  "description": "Leaderboard position (1-100). Omitted when the project is not in the current ranked roster.",
                  "examples": [
                    7
                  ]
                },
                "rankBand": {
                  "type": "string",
                  "enum": [
                    "strong",
                    "corroborated"
                  ],
                  "description": "Evidence eligibility band for the current rank. Omitted when the project is unranked.",
                  "examples": [
                    "strong"
                  ]
                },
                "coingeckoData": {
                  "type": "object",
                  "properties": {
                    "apiId": {
                      "type": "string",
                      "examples": [
                        "ethereum"
                      ]
                    },
                    "symbol": {
                      "type": "string",
                      "examples": [
                        "eth"
                      ]
                    },
                    "slug": {
                      "type": "string"
                    },
                    "description": {
                      "type": "string"
                    },
                    "contractAddress": {
                      "type": "string"
                    },
                    "categories": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "image": {
                      "type": "object",
                      "properties": {
                        "thumb": {
                          "type": "string",
                          "format": "uri"
                        },
                        "small": {
                          "type": "string",
                          "format": "uri"
                        },
                        "large": {
                          "type": "string",
                          "format": "uri"
                        }
                      }
                    }
                  }
                },
                "metrics": {
                  "type": "object",
                  "description": "Price and market data from CoinGecko (updated every minute)",
                  "properties": {
                    "usd": {
                      "type": "number",
                      "description": "Current price in USD"
                    },
                    "usdMarketCap": {
                      "type": "number",
                      "description": "Market capitalization in USD"
                    },
                    "usd24hVol": {
                      "type": "number",
                      "description": "24-hour trading volume in USD"
                    },
                    "usd24hChange": {
                      "type": "number",
                      "description": "24-hour price change percentage"
                    },
                    "lastUpdatedAt": {
                      "type": "number",
                      "description": "Unix timestamp in seconds of the last metrics update"
                    },
                    "high24h": {
                      "type": "number"
                    },
                    "low24h": {
                      "type": "number"
                    },
                    "athUsd": {
                      "type": "number"
                    },
                    "athDate": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "athChangePct": {
                      "type": "number"
                    },
                    "priceChange7d": {
                      "type": "number"
                    },
                    "priceChange14d": {
                      "type": "number"
                    },
                    "priceChange30d": {
                      "type": "number"
                    }
                  }
                },
                "tokens": {
                  "type": "array",
                  "description": "Contract addresses by blockchain platform",
                  "items": {
                    "type": "object",
                    "properties": {
                      "chain": {
                        "type": "string"
                      },
                      "address": {
                        "type": "string"
                      },
                      "source": {
                        "type": "string",
                        "description": "Data source (coingecko, dexscreener, tweet, grok)"
                      },
                      "primary": {
                        "type": "boolean",
                        "description": "Whether this is the project's current primary token"
                      }
                    }
                  }
                },
                "primaryComputedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "When the primary token selection was computed"
                },
                "createdAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Project creation timestamp (ISO 8601)"
                },
                "updatedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Project last updated timestamp (ISO 8601)"
                },
                "reinforcedAt": {
                  "type": "string",
                  "format": "date-time",
                  "description": "Timestamp of last signal activity (created or reinforced) for this project"
                },
                "provenance": {
                  "type": "string",
                  "enum": [
                    "historical",
                    "constructed"
                  ],
                  "description": "Data source indicator (only present when `at` parameter is used).\n`historical` = reconstructed from a stored snapshot.\n`constructed` = assembled from available data (no exact snapshot found).\n"
                },
                "momentumContext": {
                  "$ref": "#/components/schemas/MomentumContext"
                },
                "signals": {
                  "type": "array",
                  "description": "10 most recent intel items sorted by detection date by default",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "detectedAt": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Intel detection date"
                      },
                      "reinforcedAt": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time",
                        "description": "Date when this intel was last reinforced with independent supporting evidence; null for research-only intel"
                      },
                      "description": {
                        "type": "string"
                      },
                      "headline": {
                        "type": "string",
                        "description": "Plain-language summary up to 10 words"
                      },
                      "projectName": {
                        "type": "string"
                      },
                      "projectId": {
                        "type": "string"
                      },
                      "category": {
                        "type": "string"
                      },
                      "citations": {
                        "type": "array",
                        "description": "Vetted non-X citations supporting this intel",
                        "items": {
                          "type": "string"
                        }
                      },
                      "observationCount": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Number of observation-type activity entries"
                      },
                      "hasOfficialSource": {
                        "type": "boolean",
                        "description": "Whether any observation came from an official project source"
                      },
                      "officialSourceUrl": {
                        "type": "string",
                        "format": "uri",
                        "description": "Canonical official X provenance retained when the source observation is omitted from public activity"
                      },
                      "sentiment": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "minimum": -1,
                        "maximum": 1,
                        "description": "Aggregate sentiment averaged across activity entries"
                      },
                      "referencesMetrics": {
                        "type": [
                          "boolean",
                          "null"
                        ],
                        "description": "Whether this intel description references market metrics. `null` when not classified."
                      },
                      "clusters": {
                        "type": "array",
                        "items": {
                          "$ref": "#/components/schemas/SignalCluster"
                        }
                      },
                      "activity": {
                        "type": "array",
                        "description": "Activity timeline. Present unless `intelActivity=none`.",
                        "items": {
                          "$ref": "#/components/schemas/SignalActivity"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid project ID format",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Project not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "503": {
    "description": "Historical data service temporarily unavailable (only when `at` is used)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Project Neighbors (co-mentioned projects)

`GET /v2/projects/{id}/neighbors`

Projects co-mentioned with this one in the same intel posts within a recency
window — neighbours in the source-sharing graph, ranked by how often they
co-occur. Two projects are neighbours when the same originating post
(`source.sourceId`) appears in the activity ledger of a signal for each.
High-degree roundup posts are excluded. After canonical-id dedup, a
candidate must share at least two source posts from at least two distinct
authors; the seed itself is excluded.

This is a co-occurrence signal (discussed alongside), not a structural
relationship like shared team, ecosystem, or category.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "MongoDB ObjectId of the seed project"
  },
  {
    "in": "query",
    "name": "since",
    "schema": {
      "type": "string",
      "default": "14d"
    },
    "description": "Recency window. Relative forms like `14d`, `7d`, `48h`.\n",
    "examples": {
      "default": {
        "value": "14d"
      }
    }
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "type": "integer",
      "default": 5,
      "minimum": 1,
      "maximum": 50
    },
    "description": "Number of neighbours to return (1-50)"
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Ranked list of neighbour projects",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "projectId": {
                    "type": "string"
                  },
                  "projectName": {
                    "type": "string"
                  },
                  "joiningSignals": {
                    "type": "integer",
                    "description": "Distinct candidate signals sharing >= 1 source with the seed"
                  },
                  "joiningReinforcements": {
                    "type": "integer",
                    "description": "Row count of shared-source activity entries"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid project id or since parameter",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch project neighbors",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# List Intel

`GET /v2/intel`

Returns intel (formerly summaries) with filtering and pagination support.

**Filter Behavior:**
- Project filters (projectIds, names, xHandles, tickers) use AND logic between different filters
- projectRanking filters intel to the current ranked project roster, up to 100 projects. Live queries use current project ranks; historical `at` queries use stored score snapshots at the requested timestamp.
- Multiple values within a single filter use OR logic
- Cluster filter returns intel containing ANY of the specified cluster IDs
- Category filter returns intel matching ANY of the specified categories (OR logic)
- Date filters (detectedAfter/detectedBefore) filter by original detection date
- Date filters (reinforcedAfter/reinforcedBefore) filter by last reinforced date
- All date filters can be used independently, together, or combined (AND logic)
- Every non-empty search shape is accepted; responsive bounds and the exact executed scope are disclosed in pagination

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "query",
    "name": "projectIds",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of project IDs to filter by"
  },
  {
    "in": "query",
    "name": "names",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of project names to filter by (case-insensitive regex match)"
  },
  {
    "in": "query",
    "name": "xHandles",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of X/Twitter handles to filter by"
  },
  {
    "in": "query",
    "name": "tickers",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of token tickers to filter by"
  },
  {
    "in": "query",
    "name": "projectRanking",
    "schema": {
      "type": "string",
      "enum": [
        "trend"
      ]
    },
    "description": "Filter intel to the current ranked project roster, up to 100 projects."
  },
  {
    "in": "query",
    "name": "address",
    "schema": {
      "type": "string"
    },
    "description": "Filter by contract address. Finds projects matching the address, then returns their intel.\nEVM addresses are case-insensitive; non-EVM addresses (e.g., Solana) are case-sensitive.\n",
    "examples": {
      "default": {
        "value": "0x2260fac5e5542a773aa44fbcfedf7c193bc2c599"
      }
    }
  },
  {
    "in": "query",
    "name": "clusterIds",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated list of community cluster IDs to filter by (OR logic)"
  },
  {
    "in": "query",
    "name": "categories",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated category names to filter by (OR logic).\nValid values: FINANCIAL_EVENT, TOKEN_ECONOMICS, TECH_EVENT, MARKET_ACTIVITY, ONCHAIN_METRICS, PARTNERSHIP, TEAM_UPDATE, REGULATORY, WHALE_ACTIVITY, RISK_ALERT, VISIBILITY_EVENT, OPINION_SPECULATION\n",
    "examples": {
      "default": {
        "value": "TECH_EVENT,PARTNERSHIP"
      }
    }
  },
  {
    "in": "query",
    "name": "hasOfficialSource",
    "schema": {
      "type": "boolean"
    },
    "description": "If true, only return intel from official project sources"
  },
  {
    "in": "query",
    "name": "hasToken",
    "schema": {
      "type": "string",
      "enum": [
        "true",
        "false"
      ]
    },
    "description": "Filter intel by whether their associated project has at least one token.\nWhen 'true', only intel from projects with tokens is returned.\nWhen 'false', only intel from projects without tokens is returned.\n"
  },
  {
    "in": "query",
    "name": "marketCap",
    "schema": {
      "type": "string",
      "enum": [
        "low",
        "mid",
        "large"
      ]
    },
    "description": "Filter intel by the current market cap of its project: low (under $80M),\nmid ($80M to $500M), or large ($500M and above). Projects without a\ncurrent market cap are excluded. Not supported with at.\n"
  },
  {
    "in": "query",
    "name": "detectedAfter",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Filter intel originally detected after this date (ISO datetime)",
    "examples": {
      "default": {
        "value": "2025-01-01T00:00:00Z"
      }
    }
  },
  {
    "in": "query",
    "name": "detectedBefore",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Filter intel originally detected before this date (ISO datetime)",
    "examples": {
      "default": {
        "value": "2025-01-31T23:59:59Z"
      }
    }
  },
  {
    "in": "query",
    "name": "reinforcedAfter",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Filter intel reinforced after this date (ISO datetime)",
    "examples": {
      "default": {
        "value": "2025-01-01T00:00:00Z"
      }
    }
  },
  {
    "in": "query",
    "name": "reinforcedBefore",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Filter intel reinforced before this date (ISO datetime)",
    "examples": {
      "default": {
        "value": "2025-01-31T23:59:59Z"
      }
    }
  },
  {
    "in": "query",
    "name": "minClusters",
    "schema": {
      "type": "integer",
      "minimum": 1
    },
    "description": "Minimum number of community clusters represented on an intel item.\nCommunity clusters are overlapping account archetypes, so this is a coverage filter. Use source and reinforcement details for confirmation.\nWhen provided, only intel with at least this many clusters is returned.\nWhen omitted, no cluster count filter is applied.\n"
  },
  {
    "in": "query",
    "name": "sentiment",
    "schema": {
      "type": "string"
    },
    "description": "Comma-separated sentiment buckets to filter by (OR logic).\nAccepted values (case-insensitive): `positive`, `neutral`, `negative`.\n\nEach intel's `sentiment` field is a continuous value in [-1, 1]\n(the average of per-activity sentiments). Buckets are derived\nwith these thresholds:\n- **positive**: sentiment ≥ 0.25\n- **neutral**: -0.25 < sentiment < 0.25\n- **negative**: sentiment ≤ -0.25\n\nOmitting the param (or selecting all three buckets) applies no filter.\n",
    "examples": {
      "default": {
        "value": "positive,negative"
      }
    }
  },
  {
    "in": "query",
    "name": "search",
    "schema": {
      "type": "string"
    },
    "description": "Free-text Intel search. Every query shape is accepted; pagination metadata discloses responsive coverage bounds and the exact executed scope."
  },
  {
    "in": "query",
    "name": "sortBy",
    "schema": {
      "type": "string",
      "enum": [
        "reinforcedAt",
        "createdAt",
        "detectedAt"
      ],
      "default": "detectedAt"
    },
    "description": "Sort intel by original detection date (default) or supporting-evidence recency"
  },
  {
    "in": "query",
    "name": "page",
    "schema": {
      "type": "integer",
      "default": 1
    },
    "description": "Page number for pagination (1-indexed)"
  },
  {
    "in": "query",
    "name": "limit",
    "schema": {
      "type": "integer",
      "default": 50,
      "maximum": 50
    },
    "description": "Number of results per page (max 50)"
  },
  {
    "in": "query",
    "name": "activity",
    "schema": {
      "$ref": "#/components/schemas/ActivityMode"
    },
    "description": "Controls activity data in the response.\n`all` (default) — full timeline; `observations` — observation entries only; `none` — omit activity array.\n"
  },
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical timestamp (ISO 8601). Returns intel as it existed at this point in time.\nOnly available for authenticated requests. Must be in the past.\n\nWhen used:\n- Only intel detected at or before the timestamp is returned\n- `citations`, `observationCount`, `reinforcedAt`, `clusters`, `hasOfficialSource`, `description`, `headline`, and `sentiment` are derived from activity at or before the timestamp\n",
    "examples": {
      "default": {
        "value": "2026-03-25T12:00:00Z"
      }
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "List of intel with pagination metadata",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "detectedAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Date when this intel was first detected"
                  },
                  "reinforcedAt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time",
                    "description": "Date when this intel was last reinforced with independent supporting evidence; null for research-only intel"
                  },
                  "description": {
                    "type": "string",
                    "description": "Intel description"
                  },
                  "citations": {
                    "type": "array",
                    "description": "Vetted non-X citations supporting this intel",
                    "items": {
                      "type": "string"
                    }
                  },
                  "projectName": {
                    "type": "string"
                  },
                  "projectId": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "observationCount": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Number of observation-type activity entries on this intel"
                  },
                  "hasOfficialSource": {
                    "type": "boolean",
                    "description": "Whether any observation on this intel came from an official project source"
                  },
                  "officialSourceUrl": {
                    "type": "string",
                    "format": "uri",
                    "description": "Canonical official X provenance retained when the source observation is omitted from public activity"
                  },
                  "sentiment": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "minimum": -1,
                    "maximum": 1,
                    "description": "Aggregate sentiment for this intel, averaged across all activity entries (each scored -1, 0, or 1).\nBucket thresholds for filtering: positive ≥ 0.25, neutral in (-0.25, 0.25), negative ≤ -0.25.\n`null` when no sentiment has been classified.\n"
                  },
                  "referencesMetrics": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "description": "Whether this intel description references market metrics. `null` when not classified."
                  },
                  "metrics": {
                    "type": [
                      "object",
                      "null"
                    ],
                    "description": "Project market metrics attached when `referencesMetrics` is true and metrics are available.",
                    "properties": {
                      "usd": {
                        "type": [
                          "number",
                          "null"
                        ]
                      },
                      "usdMarketCap": {
                        "type": [
                          "number",
                          "null"
                        ]
                      },
                      "usd24hVol": {
                        "type": [
                          "number",
                          "null"
                        ]
                      },
                      "usd24hChange": {
                        "type": [
                          "number",
                          "null"
                        ]
                      },
                      "lastUpdatedAt": {
                        "type": [
                          "number",
                          "null"
                        ]
                      }
                    }
                  },
                  "clusters": {
                    "type": "array",
                    "items": {
                      "$ref": "#/components/schemas/SignalCluster"
                    }
                  },
                  "activity": {
                    "type": "array",
                    "description": "Activity timeline. Present unless `activity=none`.",
                    "items": {
                      "$ref": "#/components/schemas/SignalActivity"
                    }
                  }
                }
              }
            },
            "pagination": {
              "type": "object",
              "properties": {
                "page": {
                  "type": "integer"
                },
                "limit": {
                  "type": "integer"
                },
                "totalCount": {
                  "type": "integer"
                },
                "totalCountExact": {
                  "type": "boolean",
                  "description": "False when totalCount is a responsive lower bound rather than an exact count."
                },
                "hasMore": {
                  "type": "boolean"
                },
                "searchCoverage": {
                  "type": "string",
                  "enum": [
                    "bounded_candidates",
                    "bounded_recent",
                    "bounded_candidates_recent"
                  ]
                },
                "searchQuery": {
                  "type": "string"
                },
                "executedSearch": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid request parameters",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get Intel by ID

`GET /v2/intel/{id}`

Returns full intel detail including activity history and cluster composition.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "Intel (summary) ID"
  },
  {
    "in": "query",
    "name": "activity",
    "schema": {
      "$ref": "#/components/schemas/ActivityMode"
    },
    "description": "Controls whether the activity timeline is full, observation-only, or omitted."
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Intel detail with activity and cluster composition",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "detectedAt": {
                  "type": "string",
                  "format": "date-time"
                },
                "reinforcedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                },
                "description": {
                  "type": "string"
                },
                "headline": {
                  "type": "string",
                  "description": "Plain-language summary up to 10 words"
                },
                "citations": {
                  "type": "array",
                  "description": "Vetted non-X citations supporting this intel",
                  "items": {
                    "type": "string"
                  }
                },
                "projectName": {
                  "type": "string"
                },
                "projectId": {
                  "type": "string"
                },
                "projectImage": {
                  "type": "string",
                  "format": "uri"
                },
                "category": {
                  "type": "string"
                },
                "observationCount": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Number of observation-type activity entries on this intel"
                },
                "hasOfficialSource": {
                  "type": "boolean",
                  "description": "Whether any observation on this intel came from an official project source"
                },
                "officialSourceUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "Canonical official X provenance retained when the source observation is omitted from public activity"
                },
                "sentiment": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "minimum": -1,
                  "maximum": 1,
                  "description": "Aggregate sentiment, averaged across all activity entries (each scored -1, 0, or 1).\nBucket thresholds: positive ≥ 0.25, neutral in (-0.25, 0.25), negative ≤ -0.25.\n`null` when no sentiment has been classified.\n"
                },
                "referencesMetrics": {
                  "type": [
                    "boolean",
                    "null"
                  ],
                  "description": "Whether this intel description references market metrics. `null` when not classified."
                },
                "metrics": {
                  "type": [
                    "object",
                    "null"
                  ],
                  "description": "Project market metrics attached when `referencesMetrics` is true and metrics are available.",
                  "properties": {
                    "usd": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "usdMarketCap": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "usd24hVol": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "usd24hChange": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "lastUpdatedAt": {
                      "type": [
                        "number",
                        "null"
                      ]
                    }
                  }
                },
                "clusters": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SignalCluster"
                  }
                },
                "activity": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/SignalActivity"
                  }
                },
                "clusterComposition": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": {
                        "type": "string"
                      },
                      "name": {
                        "type": "string"
                      },
                      "percentage": {
                        "type": "number"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid intel ID format",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Requested intel is outside the credential history window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Intel not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch intel",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# List Signals (deprecated alias of /v2/intel)

`GET /v2/signals`

**Deprecated compatibility alias.** Signals were renamed to Intel.
This route responds with the exact `GET /v2/intel` contract — same
parameters, response shape, and errors — and adds `Deprecation` and
`Link: successor-version` headers. Migrate to `/v2/intel`.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Lifecycle

Deprecated. Successor: `/v2/intel`.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Identical to the GET /v2/intel response",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "description": "See GET /v2/intel"
        }
      }
    }
  },
  "400": {
    "description": "Invalid query parameters",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "401": {
    "description": "Invalid API key",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Missing API key or history window exceeded",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get Signal by ID (deprecated alias)

`GET /v2/signals/{id}`

**Deprecated compatibility alias.** Responds with the exact
`GET /v2/intel/{id}` contract. Migrate to `/v2/intel/{id}`.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Lifecycle

Deprecated. Successor: `/v2/intel`.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Identical to the GET /v2/intel/{id} response",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "description": "See GET /v2/intel/{id}"
        }
      }
    }
  },
  "400": {
    "description": "Invalid intel ID",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "401": {
    "description": "Invalid API key",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Missing API key or history window exceeded",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Intel not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Momentum History

`GET /v2/projects/{id}/momentum`

Returns hourly momentum history with cluster attribution breakdown. A multi-cluster source appears once under each cluster. Includes score history for a project over a specified time period. Default period is the last 7 days.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "The project ID"
  },
  {
    "in": "query",
    "name": "start",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Start timestamp (ISO 8601 format). Defaults to 7 days ago.",
    "examples": {
      "default": {
        "value": "2025-11-21T00:00:00.000Z"
      }
    }
  },
  {
    "in": "query",
    "name": "end",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "End timestamp (ISO 8601 format). Defaults to now.",
    "examples": {
      "default": {
        "value": "2025-11-28T00:00:00.000Z"
      }
    }
  },
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical anchor timestamp (ISO 8601). Sets the end of the momentum time window.\nMust be in the past.\n\nWhen used:\n- If `end` is not provided, `at` sets the end of the window\n- If `end` is provided, `at` acts as a ceiling — `end` is capped to whichever is earlier\n- If `start` is not provided, it defaults to 7 days before `at`\n",
    "examples": {
      "default": {
        "value": "2026-03-25T12:00:00Z"
      }
    }
  },
  {
    "in": "query",
    "name": "includeClusters",
    "schema": {
      "type": "string",
      "enum": [
        "true",
        "false"
      ],
      "default": "true"
    },
    "description": "Whether to include per-hour cluster attribution breakdown. Set to \"false\" to return only momentum scores (faster, smaller response)."
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Momentum and score history data",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "object",
              "properties": {
                "projectId": {
                  "type": "string",
                  "examples": [
                    "507f1f77bcf86cd799439011"
                  ]
                },
                "projectName": {
                  "type": "string",
                  "examples": [
                    "ethereum"
                  ]
                },
                "data": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "timestamp": {
                        "type": "string",
                        "format": "date-time",
                        "examples": [
                          "2025-11-30T12:00:00.000Z"
                        ]
                      },
                      "trendScore": {
                        "type": "number",
                        "minimum": 0,
                        "maximum": 100,
                        "examples": [
                          43
                        ]
                      },
                      "clusters": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "examples": [
                                "VC"
                              ]
                            },
                            "name": {
                              "type": "string",
                              "examples": [
                                "VC"
                              ]
                            },
                            "count": {
                              "type": "integer",
                              "examples": [
                                3
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid project ID format or invalid date parameters",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Project not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch project momentum",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Rank History

`GET /v2/projects/{id}/rank`

Returns rank position history with scores over a time window. Only includes timestamps where the project was in the ranked roster, which contains up to 100 projects. Default period is the last 7 days.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "The project ID"
  },
  {
    "in": "query",
    "name": "start",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Start timestamp (ISO 8601 format). Defaults to 7 days ago."
  },
  {
    "in": "query",
    "name": "end",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "End timestamp (ISO 8601 format). Defaults to now."
  },
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical anchor timestamp (ISO 8601). Sets the end of the rank time window.\nMust be in the past.\n"
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Rank position history with scores",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/HistoryResponseMeta"
            },
            "data": {
              "type": "object",
              "properties": {
                "projectId": {
                  "type": "string",
                  "examples": [
                    "507f1f77bcf86cd799439011"
                  ]
                },
                "projectName": {
                  "type": "string",
                  "examples": [
                    "ethereum"
                  ]
                },
                "data": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "timestamp": {
                        "type": "string",
                        "format": "date-time",
                        "examples": [
                          "2026-03-30T12:00:00.000Z"
                        ]
                      },
                      "rank": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100,
                        "examples": [
                          3
                        ]
                      },
                      "trendScore": {
                        "type": "number",
                        "description": "Trend score at this timestamp",
                        "examples": [
                          85
                        ]
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid project ID format or invalid date parameters",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required, or requested history is outside the credential window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Project not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch project rank",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "503": {
    "description": "Rank data temporarily unavailable (TimescaleDB connectivity issue)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Price Candles (OHLCV)

`GET /v2/projects/{id}/candles`

Returns OHLCV candlestick data from TimescaleDB metric history.
Each candle is an array: `[timestamp_ms, open, high, low, close, volume24h]`.

`volume24h` is the rolling 24-hour volume at candle close, not per-interval volume.

**Interval defaults and caps:**
| Interval | Default range | Max range |
|----------|--------------|-----------|
| `5m`     | 24 hours     | 48 hours  |
| `1h`     | 7 days       | 14 days   |
| `1d`     | 30 days      | 90 days   |

If the requested range exceeds the max, `start` is clamped forward (most recent candles are returned).

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "MongoDB ObjectId of the project"
  },
  {
    "in": "query",
    "name": "interval",
    "required": true,
    "schema": {
      "type": "string",
      "enum": [
        "5m",
        "1h",
        "1d"
      ]
    },
    "description": "Candle interval"
  },
  {
    "in": "query",
    "name": "start",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Start timestamp (ISO 8601). Defaults to interval-dependent lookback from end."
  },
  {
    "in": "query",
    "name": "end",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "End timestamp (ISO 8601). Defaults to now."
  },
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical anchor timestamp (ISO 8601). Caps `end` and shifts the default lookback.\nMust be in the past.\n\nWhen used:\n- If `end` is not provided, `at` sets the end of the window\n- If `end` is provided, `at` acts as a ceiling — `end` is capped to whichever is earlier\n- If `start` is not provided, it defaults to the interval's default lookback before `at`\n",
    "examples": {
      "default": {
        "value": "2026-03-25T12:00:00Z"
      }
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "OHLCV candle data",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/UpgradeMeta"
            },
            "data": {
              "type": "object",
              "properties": {
                "projectId": {
                  "type": "string",
                  "examples": [
                    "507f1f77bcf86cd799439011"
                  ]
                },
                "projectName": {
                  "type": "string",
                  "examples": [
                    "Bitcoin"
                  ]
                },
                "interval": {
                  "type": "string",
                  "examples": [
                    "1h"
                  ]
                },
                "candles": {
                  "type": "array",
                  "description": "Array of candle arrays. Each inner array: [timestamp_ms, open, high, low, close, volume24h].\nTimestamps are Unix milliseconds. volume24h is rolling 24h volume at candle close.\n",
                  "items": {
                    "type": "array",
                    "minItems": 6,
                    "maxItems": 6,
                    "items": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "examples": [
                      [
                        1709395200000,
                        0.0523,
                        0.0531,
                        0.0519,
                        0.0527,
                        1234567
                      ]
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid parameters (bad interval, project ID format, or date format)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required. Provide an API key to access this endpoint.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Project not found, or price candles are not available for an NFT collection",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch candle data",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "503": {
    "description": "Price data temporarily unavailable (TimescaleDB connectivity issue)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Project Metrics Snapshot

`GET /v2/projects/{id}/metrics`

Point-in-time snapshot of project market metrics (price, volume, 24h change,
derived fields like price-change-7d/14d/30d and ATH change percentage).

Without `at`, returns the live metrics subdocument from the project record
(sourced from CoinGecko by the metrics sync).

With `at`, reads from Timescale `metric_log` (latest row ≤ `at` within a 2-hour
lookback) and recomputes derived fields from `at - 7d / 14d / 30d` lookups.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "id",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "MongoDB ObjectId of the project"
  },
  {
    "in": "query",
    "name": "at",
    "schema": {
      "type": "string",
      "format": "date-time"
    },
    "description": "Historical timestamp (ISO 8601). Returns project metrics as they existed\nat this point in time. Must be in the past.\n",
    "examples": {
      "default": {
        "value": "2026-03-25T12:00:00Z"
      }
    }
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Project metrics snapshot",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "meta": {
              "$ref": "#/components/schemas/UpgradeMeta"
            },
            "data": {
              "type": "object",
              "properties": {
                "projectId": {
                  "type": "string",
                  "examples": [
                    "507f1f77bcf86cd799439011"
                  ]
                },
                "projectName": {
                  "type": "string",
                  "examples": [
                    "ethereum"
                  ]
                },
                "metrics": {
                  "type": "object",
                  "properties": {
                    "usd": {
                      "type": "number"
                    },
                    "usdMarketCap": {
                      "type": "number"
                    },
                    "usd24hVol": {
                      "type": "number"
                    },
                    "usd24hChange": {
                      "type": "number"
                    },
                    "lastUpdatedAt": {
                      "type": "number",
                      "description": "Unix timestamp (seconds)"
                    },
                    "high24h": {
                      "type": "number"
                    },
                    "low24h": {
                      "type": "number"
                    },
                    "athUsd": {
                      "type": "number"
                    },
                    "athDate": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "athChangePct": {
                      "type": "number"
                    },
                    "priceChange7d": {
                      "type": "number"
                    },
                    "priceChange14d": {
                      "type": "number"
                    },
                    "priceChange30d": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid project ID format or invalid `at` parameter",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Authentication required. Provide an API key to access this endpoint.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Project not found, token metrics are not available for an NFT collection, or no metrics are available at the requested timestamp",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch project metrics",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "503": {
    "description": "Historical queries temporarily unavailable (TimescaleDB connectivity issue)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# List Clusters

`GET /v2/clusters`

Returns crypto community clusters by default. Pass `universe=tradfi` to list TradFi account labels.
Use crypto cluster IDs with the `clusterIds` parameter on the /v2/intel endpoint to filter signals by source.

## Authentication

None. This endpoint is public.

## Parameters

```json
[
  {
    "in": "query",
    "name": "universe",
    "required": false,
    "schema": {
      "type": "string",
      "enum": [
        "crypto",
        "tradfi"
      ]
    },
    "description": "Cluster universe to list. Defaults to crypto."
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "List of clusters",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "universe": {
                    "type": "string",
                    "enum": [
                      "crypto",
                      "tradfi"
                    ]
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Invalid universe",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Internal server error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# List Intel Categories

`GET /v2/intel-categories`

Returns all active intel categories with id, name, and description.
Use category names with the `categories` parameter on the /intel endpoint to filter intel by category.

## Authentication

None. This endpoint is public.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "List of intel categories",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "500": {
    "description": "Internal server error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# List Blockchain Platforms

`GET /v2/projects/chains`

Returns supported blockchain platform identifiers for project filtering.

## Authentication

None. This endpoint is public.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Supported blockchain platforms",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status",
            "data"
          ],
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch blockchain platforms",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# List available recipes

`GET /v2/recipes`

Returns a list of all curated AIXBT recipes available in the registry.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "List of recipe summaries",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status",
            "data"
          ],
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "type": "array",
              "items": {
                "$ref": "#/components/schemas/RecipeSummary"
              }
            }
          }
        }
      }
    }
  },
  "500": {
    "description": "Failed to list recipes",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Get recipe by name

`GET /v2/recipes/{name}`

Returns the full YAML definition for a specific recipe.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

```json
[
  {
    "in": "path",
    "name": "name",
    "required": true,
    "schema": {
      "type": "string"
    },
    "description": "Recipe name"
  }
]
```

## Request body

None.

## Responses

```json
{
  "200": {
    "description": "Recipe details with YAML definition",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "required": [
            "status",
            "data"
          ],
          "properties": {
            "status": {
              "type": "integer",
              "examples": [
                200
              ]
            },
            "data": {
              "$ref": "#/components/schemas/RecipeDetail"
            }
          }
        }
      }
    }
  },
  "404": {
    "description": "Recipe not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Failed to fetch recipe",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Execute a recipe

`POST /v2/recipes/execute`

Executes a recipe either from raw YAML or by registry name. AIXBT steps execute server-side
via direct service calls. Provider steps return auto-fallback results with metadata for
client-side enrichment.

Exactly one of `yaml` or `recipeName` must be provided.
The credential owner must have API access. MCP is not required.

When execution yields at an agent step, the response includes carry-forward data and
instructions for the agent. Resume by calling this endpoint again with `resumeFromStep`,
`resumeInput`, and `carryForward` from the previous response.

## Authentication

Required. Send an API key in the `x-api-key` header.
Required account access: `api`.

## Parameters

None.

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "yaml": {
            "type": "string",
            "description": "Raw YAML recipe definition"
          },
          "recipeName": {
            "type": "string",
            "description": "Registry recipe name"
          },
          "params": {
            "type": "object",
            "additionalProperties": {
              "oneOf": [
                {
                  "type": "string"
                },
                {
                  "type": "number"
                },
                {
                  "type": "boolean"
                }
              ]
            },
            "description": "Recipe parameters"
          },
          "resumeFromStep": {
            "type": "string",
            "description": "Step ID to resume from"
          },
          "resumeInput": {
            "type": "object",
            "description": "Agent output from the yielded step"
          },
          "carryForward": {
            "type": "object",
            "description": "Pre-yield step data from previous response"
          }
        }
      }
    }
  }
}
```

## Responses

```json
{
  "200": {
    "description": "Recipe execution result (awaiting_agent or complete)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/RecipeExecutionResult"
        }
      }
    }
  },
  "400": {
    "description": "Validation error or invalid request",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "401": {
    "description": "Missing or invalid API key",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "403": {
    "description": "Current account plan lacks access, or a recipe step requests history outside the account's entitlement window.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Registry recipe not found",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "500": {
    "description": "Internal execution error",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "502": {
    "description": "Recipe step execution failed",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "503": {
    "description": "Required service is unavailable",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# Validate a recipe

`POST /v2/recipes/validate`

Validates a raw YAML recipe definition without executing it. Returns structural
validation issues and basic recipe metadata when valid.

## Authentication

Required. Send an API key in the `x-api-key` header.

## Parameters

None.

## Request body

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "type": "object",
        "properties": {
          "yaml": {
            "type": "string",
            "description": "Raw YAML recipe definition to validate (mutually exclusive with name)"
          },
          "recipeName": {
            "type": "string",
            "description": "Registry recipe name to validate (mutually exclusive with yaml)"
          }
        }
      }
    }
  }
}
```

## Responses

```json
{
  "200": {
    "description": "Validation result",
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "valid": {
              "type": "boolean"
            },
            "issues": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "path": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                }
              }
            },
            "recipe": {
              "type": "object",
              "description": "Present when valid",
              "properties": {
                "name": {
                  "type": "string"
                },
                "version": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "stepCount": {
                  "type": "integer"
                },
                "paramCount": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  },
  "400": {
    "description": "Missing or invalid input (yaml/recipeName)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "404": {
    "description": "Recipe not found (when using recipeName)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "429": {
    "description": "Rate limit exceeded",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}
```

Schema references resolve against the [canonical OpenAPI specification](https://api.aixbt.tech/v2/openapi.yaml).

# MCP



AIXBT exposes one Streamable HTTP MCP server at
`https://api.aixbt.tech/mcp`. Only the Topic tools, `list_topics` and
`get_topic`, work without credentials; calling a protected tool returns an
OAuth 2.1 challenge so an interactive client can ask the user to sign in.

## Connect [#connect]

For app-specific setup, see [ChatGPT](/chatgpt), [Claude](/claude),
[Grok Bot](/grok-bot), or [Hermes Agent](/hermes).

In other interactive clients, add the server URL above with no headers.

For non-interactive use, create an API key in
[Developer access](https://aixbt.tech/profile#developer-access), then keep it
in your client's secret or environment-variable store:

```json
{
  "mcpServers": {
    "aixbt": {
      "type": "streamable-http",
      "url": "https://api.aixbt.tech/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```

## Add the research skill [#add-the-research-skill]

The connector exposes AIXBT data and tools. Add the [research skill](/developers/skill)
for the research workflow when your client supports skills.

## Discover tools [#discover-tools]

Your client discovers the current tools and input/output schemas through the
MCP handshake and `tools/list`, without signing in. Treat that response, not
a copied tool inventory, as the contract.

The tools expose the same resources and access rules as [API v3](/developers/v3).
Use the discovered schemas for current filters and response shapes.


# Research skill



The AIXBT research skill is a concise workflow for finding and synthesizing
AIXBT data. Use it in an agent connected through the
[MCP connector](/developers/mcp) or [API v3](/developers/v3). The
[ChatGPT plugin](/chatgpt) packages the skill with the connector.

<a href="/skills.md" download="SKILL.md">
  Download SKILL.md
</a>

## Install [#install]

1. Give the agent access to AIXBT through MCP or API v3.
2. Download the skill above and add it through your client's skill-import flow.
3. If the client expects a directory, save it as `research-crypto-market/SKILL.md`.


# Webhooks



A webhook destination receives new alerts and report notifications as `alert.v4` JSON:

* `intelligence.material` when material intel matches an alert's filters.
* `rank.entered` when a project or topic enters your selected ranking.
* `report.published` when a subscribed new topic report is published. Its compact
  `event.report` contains the id and account-authorized URL for the full report.

Current scored `alert.v4` events carry `event.ranking` (`trend`) and the
ranking-neutral `event.measurement`. New payloads do not use `event.trend`.
Destinations pinned to `alert.v3` keep `event.trend` during the compatibility window;
retrying or replaying a delivery does not change its schema version.

## Set up [#set-up]

1. Open [Alerts](https://aixbt.tech/alerts) and add a webhook with a public HTTPS endpoint.
2. Registration sends a `destination.test` request. Return the `challenge`
   value from its JSON body as the plain-text response body. To try the
   flow before your receiver exists, register
   `https://docs.aixbt.tech/api/webhook-echo` first.
3. Store the signing secret when it appears. It is shown once.
4. Select the webhook on the alerts or reports you want delivered.

## Verify every request [#verify-every-request]

Read the `AIXBT-Webhook-Timestamp` and `AIXBT-Webhook-Signature` headers and
check them against the exact raw request body with your stored secret. Do not
parse and re-serialize the body before verifying:

```ts
import { createHmac, timingSafeEqual } from 'node:crypto'

export function verifyAixbtWebhook(
  rawBody: Buffer,
  timestamp: string, // AIXBT-Webhook-Timestamp header
  signature: string, // AIXBT-Webhook-Signature header
  secret: string, // shown once in Alerts
): boolean {
  const sentAt = Number(timestamp)
  if (!Number.isSafeInteger(sentAt) || sentAt < 1) return false
  if (Math.abs(Date.now() / 1000 - sentAt) > 300) return false

  const expected = createHmac('sha256', secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest('hex')
  return signature.split(',').some(part => {
    const digest = part.trim().split('=')[1] ?? ''
    return (
      /^[a-f0-9]{64}$/.test(digest) &&
      timingSafeEqual(Buffer.from(digest, 'hex'), Buffer.from(expected, 'hex'))
    )
  })
}
```

The signature header carries one entry, or two separated by a comma for 24
hours after you rotate the secret, so your stored secret keeps verifying
straight through a rotation. The `AIXBT-Webhook-Event`,
`AIXBT-Webhook-Event-ID`, and `AIXBT-Webhook-Delivery-ID` headers tell you
what arrived without parsing the body.

## Respond [#respond]

Return `2xx` after accepting a delivery. `408`, `429`, and `5xx` responses
are retried, honoring a bounded `Retry-After`; other `4xx` responses are not.
A `410` disables the destination, and repeated `401` or `404` responses pause
it until a test succeeds.

## Process deliveries [#process-deliveries]

Delivery is at-least-once and can arrive late or out of order. Deduplicate by the
`delivery.id` body field; an intentional replay repeats it with a higher
`delivery.replayCount`. Acknowledge an unknown event type with `2xx`.


---

## Resources

---

# Get Support



Email [support@aixbt.tech](mailto:support@aixbt.tech).


---

# OpenAPI component schemas — API v3

Shared schemas referenced by the endpoint contracts above.

```json
{
  "Error": {
    "type": "object",
    "required": [
      "code",
      "message"
    ],
    "properties": {
      "code": {
        "type": "string",
        "enum": [
          "invalid_request",
          "credential_required",
          "invalid_credential",
          "entitlement_required",
          "history_window_exceeded",
          "not_found",
          "not_current",
          "rate_limited",
          "internal_error",
          "service_unavailable"
        ]
      },
      "message": {
        "type": "string"
      },
      "details": {
        "type": "object",
        "additionalProperties": true,
        "description": "Optional structured context (field errors, subject locators, limits)."
      }
    }
  },
  "Meta": {
    "type": "object",
    "description": "Response metadata. Empty when nothing applies.",
    "properties": {
      "history": {
        "$ref": "#/components/schemas/HistoryMeta"
      },
      "versions": {
        "type": "object",
        "additionalProperties": {
          "type": "string"
        },
        "description": "Named component versions that shaped this response."
      }
    }
  },
  "CollectionMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Meta"
      },
      {
        "type": "object",
        "required": [
          "nextCursor"
        ],
        "properties": {
          "nextCursor": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Cursor for the next page; `null` on the last page."
          }
        }
      }
    ]
  },
  "IntelCollectionMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/CollectionMeta"
      },
      {
        "type": "object",
        "properties": {
          "searchCoverage": {
            "type": "string",
            "enum": [
              "bounded_candidates",
              "bounded_recent",
              "bounded_candidates_recent"
            ],
            "description": "Responsive search bounds that may have omitted matching Intel."
          },
          "searchQuery": {
            "type": "string",
            "description": "Normalized search requested by the caller."
          },
          "executedSearch": {
            "type": "string",
            "description": "Exact normalized term scope executed by bounded search."
          }
        }
      }
    ]
  },
  "HistoryMeta": {
    "type": "object",
    "description": "The history window applied to this response. Both fields are null when the account has no history limit.",
    "required": [
      "lookbackDays",
      "earliestAvailableAt"
    ],
    "properties": {
      "lookbackDays": {
        "oneOf": [
          {
            "type": "integer"
          },
          {
            "type": "null"
          }
        ]
      },
      "earliestAvailableAt": {
        "oneOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  },
  "ProjectRef": {
    "type": "object",
    "required": [
      "id",
      "slug",
      "name"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "slug": {
        "type": "string",
        "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
        "maxLength": 64
      },
      "name": {
        "type": "string"
      }
    }
  },
  "TopicRef": {
    "type": "object",
    "required": [
      "id",
      "name"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "ClusterRef": {
    "type": "object",
    "required": [
      "id",
      "name"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "ReportRef": {
    "type": "object",
    "required": [
      "id",
      "title",
      "publishedAt",
      "revisedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "title": {
        "type": "string"
      },
      "publishedAt": {
        "type": "string",
        "format": "date-time"
      },
      "revisedAt": {
        "oneOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ]
      }
    }
  },
  "IntelRef": {
    "type": "object",
    "required": [
      "id",
      "grade",
      "detectedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "headline": {
        "type": "string"
      },
      "grade": {
        "$ref": "#/components/schemas/Grade"
      },
      "detectedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "Grade": {
    "type": "string",
    "enum": [
      "chipped",
      "flawed",
      "cut",
      "polished",
      "flawless"
    ],
    "description": "Evidence grade of an Intel item, lowest to highest. Grades describe\nthe shape of the evidence, never the truth of the claim.\n"
  },
  "Sentiment": {
    "type": "object",
    "required": [
      "value"
    ],
    "properties": {
      "value": {
        "type": "string",
        "enum": [
          "positive",
          "neutral",
          "negative"
        ]
      }
    }
  },
  "Identifiers": {
    "type": "object",
    "description": "Stable external join keys for composing AIXBT data with sources the\nconsumer licenses directly. Keys are additive per universe (tradfi\nadds e.g. exchange listing identifiers); values are identifiers\nonly; v3 never attaches the external source's data to them.\n",
    "properties": {
      "coingecko": {
        "type": "string",
        "description": "CoinGecko API id of the primary asset."
      },
      "x": {
        "type": "string",
        "description": "X handle without the at sign."
      }
    }
  },
  "Asset": {
    "type": "object",
    "required": [
      "type",
      "primary"
    ],
    "description": "Canonical instrument identity owned by the Asset registry. Identity\nonly; v3 never attaches third-party market values to an asset.\nUniverse-specific fields are additive per type (crypto types carry\n`chain` and `address`).\n",
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "token",
          "stablecoin",
          "nft-collection"
        ]
      },
      "chain": {
        "type": "string"
      },
      "address": {
        "type": "string"
      },
      "symbol": {
        "type": "string"
      },
      "primary": {
        "type": "boolean",
        "description": "The Project's primary instrument."
      }
    }
  },
  "Project": {
    "type": "object",
    "required": [
      "id",
      "slug",
      "name",
      "universe",
      "trend",
      "categories",
      "assets",
      "createdAt",
      "updatedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "slug": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "universe": {
        "type": "string",
        "enum": [
          "crypto",
          "tradfi"
        ],
        "description": "Entity universe; shares the Cluster enum. Ranks are universe-scoped."
      },
      "symbol": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "identifiers": {
        "$ref": "#/components/schemas/Identifiers"
      },
      "image": {
        "type": "string",
        "format": "uri"
      },
      "trend": {
        "type": "number",
        "description": "Canonical trend measurement from the shared trend model.\nComparable only within the same `meta.versions.trendModel`.\n"
      },
      "trendDelta": {
        "type": "object",
        "required": [
          "value",
          "window"
        ],
        "description": "Series-derived change over the stated window (PT24H), computed\nfrom the hourly trend history. Emitted on Project detail; absent\nwhen history is too shallow to state one.\n",
        "properties": {
          "value": {
            "type": "number"
          },
          "window": {
            "type": "string",
            "enum": [
              "PT24H"
            ]
          }
        }
      },
      "rank": {
        "type": "integer",
        "description": "Committed leaderboard rank within the Project's universe; absent while unranked."
      },
      "categories": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Canonical taxonomy slugs."
      },
      "assets": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Asset"
        }
      },
      "intel": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/IntelRef"
        },
        "description": "Bounded preview of current Intel, newest first."
      },
      "createdAt": {
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "reinforcedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "ProjectDetail": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Project"
      },
      {
        "type": "object",
        "properties": {
          "relatedProjects": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RelatedProject"
            }
          }
        }
      }
    ]
  },
  "RelatedProject": {
    "type": "object",
    "required": [
      "project",
      "kind",
      "sharedIntel",
      "window",
      "asOf"
    ],
    "properties": {
      "project": {
        "$ref": "#/components/schemas/ProjectRef"
      },
      "kind": {
        "type": "string",
        "enum": [
          "co_mention"
        ],
        "description": "Observational relation kind; never partnership or endorsement."
      },
      "sharedIntel": {
        "type": "integer",
        "description": "Distinct co-mentioning Intel items in the window."
      },
      "window": {
        "type": "string",
        "description": "ISO 8601 duration of the observation window."
      },
      "asOf": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "SeriesPoint": {
    "type": "object",
    "required": [
      "at",
      "value"
    ],
    "properties": {
      "at": {
        "type": "string",
        "format": "date-time"
      },
      "value": {
        "oneOf": [
          {
            "type": "number"
          },
          {
            "type": "null"
          }
        ],
        "description": "`null` marks a boundary where the subject was unranked or unmeasured."
      },
      "clusters": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "count"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "count": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "SeriesMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Meta"
      },
      {
        "type": "object",
        "required": [
          "measure",
          "basis",
          "window"
        ],
        "properties": {
          "measure": {
            "type": "string",
            "enum": [
              "trend",
              "rank"
            ]
          },
          "basis": {
            "type": "string",
            "enum": [
              "hourly",
              "rank_transitions"
            ],
            "description": "How points are spaced: latest real measurement per one-hour bucket, or rank change points."
          },
          "window": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    ]
  },
  "TopicListItem": {
    "type": "object",
    "required": [
      "id",
      "rank",
      "name",
      "summary",
      "postCount",
      "authorCount",
      "lastSeenAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "rank": {
        "type": "integer"
      },
      "name": {
        "type": "string"
      },
      "summary": {
        "type": "string"
      },
      "trend": {
        "type": "number"
      },
      "postCount": {
        "type": "integer"
      },
      "authorCount": {
        "type": "integer"
      },
      "lastSeenAt": {
        "type": "string",
        "format": "date-time"
      },
      "clusters": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "cluster",
            "share"
          ],
          "properties": {
            "cluster": {
              "$ref": "#/components/schemas/ClusterRef"
            },
            "share": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          }
        }
      },
      "report": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/ReportRef"
          },
          {
            "type": "null"
          }
        ]
      },
      "association": {
        "$ref": "#/components/schemas/TopicAssociationFacts"
      }
    }
  },
  "TopicDetail": {
    "allOf": [
      {
        "$ref": "#/components/schemas/TopicListItem"
      },
      {
        "type": "object",
        "properties": {
          "stance": {
            "$ref": "#/components/schemas/StanceSeries"
          }
        }
      }
    ]
  },
  "StanceSeries": {
    "type": "object",
    "required": [
      "buckets"
    ],
    "description": "Bucketed stance of the Topic conversation itself, independent from\nProject-targeted sentiment. Versions travel in `meta.versions`.\n",
    "properties": {
      "buckets": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "from",
            "to",
            "dominant",
            "shares"
          ],
          "properties": {
            "from": {
              "type": "string",
              "format": "date-time"
            },
            "to": {
              "type": "string",
              "format": "date-time"
            },
            "dominant": {
              "$ref": "#/components/schemas/Stance"
            },
            "shares": {
              "type": "object",
              "additionalProperties": {
                "type": "number"
              },
              "description": "Share per stance value, summing to 1."
            }
          }
        }
      }
    }
  },
  "Stance": {
    "type": "string",
    "enum": [
      "supportive",
      "skeptical",
      "neutral",
      "mixed",
      "unknown"
    ]
  },
  "TopicSnapshotMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Meta"
      },
      {
        "type": "object",
        "required": [
          "snapshot"
        ],
        "properties": {
          "snapshot": {
            "type": "object",
            "required": [
              "completedAt",
              "windowStartedAt"
            ],
            "properties": {
              "completedAt": {
                "type": "string",
                "format": "date-time"
              },
              "latestEvidenceAt": {
                "type": "string",
                "format": "date-time"
              },
              "windowStartedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    ]
  },
  "TopicAssociationFacts": {
    "type": "object",
    "required": [
      "observedPosts",
      "distinctAuthors",
      "shareOfTopicPosts",
      "firstObservedAt",
      "lastObservedAt"
    ],
    "properties": {
      "observedPosts": {
        "type": "integer"
      },
      "distinctAuthors": {
        "type": "integer"
      },
      "shareOfTopicPosts": {
        "type": "number",
        "minimum": 0,
        "maximum": 1
      },
      "firstObservedAt": {
        "type": "string",
        "format": "date-time"
      },
      "lastObservedAt": {
        "type": "string",
        "format": "date-time"
      },
      "sentiment": {
        "type": "object",
        "properties": {
          "populated": {
            "type": "integer"
          },
          "coverage": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        }
      }
    }
  },
  "TopicProjectAssociation": {
    "allOf": [
      {
        "type": "object",
        "required": [
          "project"
        ],
        "properties": {
          "project": {
            "$ref": "#/components/schemas/ProjectRef"
          }
        }
      },
      {
        "$ref": "#/components/schemas/TopicAssociationFacts"
      }
    ]
  },
  "AssociationMeta": {
    "allOf": [
      {
        "$ref": "#/components/schemas/CollectionMeta"
      },
      {
        "type": "object",
        "required": [
          "window"
        ],
        "properties": {
          "window": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time"
              },
              "to": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      }
    ]
  },
  "Intel": {
    "type": "object",
    "required": [
      "id",
      "description",
      "grade",
      "project",
      "category",
      "observationCount",
      "hasOfficialSource",
      "citations",
      "detectedAt",
      "reinforcedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "headline": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "grade": {
        "$ref": "#/components/schemas/Grade"
      },
      "project": {
        "$ref": "#/components/schemas/ProjectRef"
      },
      "category": {
        "type": "string",
        "description": "Intel event category (a vocabulary distinct from Project taxonomy)."
      },
      "clusters": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/ClusterRef"
        }
      },
      "observationCount": {
        "type": "integer"
      },
      "hasOfficialSource": {
        "type": "boolean"
      },
      "officialSourceUrl": {
        "type": "string",
        "format": "uri",
        "description": "Canonical official X provenance for the intel, including research-only observations omitted from activity."
      },
      "citations": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "uri"
        },
        "description": "Vetted non-X citations supporting this intel."
      },
      "sentiment": {
        "$ref": "#/components/schemas/Sentiment"
      },
      "detectedAt": {
        "type": "string",
        "format": "date-time"
      },
      "reinforcedAt": {
        "type": "string",
        "format": "date-time",
        "nullable": true,
        "description": "Null until the first attention-contributing source activates the gem."
      },
      "activity": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/IntelActivity"
        }
      },
      "searchMatches": {
        "type": "array",
        "description": "Present only on an active `search`: why this item matched,\nderived from stored data.\n",
        "items": {
          "type": "object",
          "required": [
            "kind",
            "term"
          ],
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "contract_address",
                "canonical_chain",
                "current_official_x_handle",
                "project_identity",
                "asset_profile",
                "current_official_x_profile",
                "project_profile",
                "intel_text"
              ]
            },
            "term": {
              "type": "string"
            },
            "excerpt": {
              "type": "string",
              "description": "Short public text containing the match, when it is not already visible."
            }
          }
        }
      }
    }
  },
  "IntelActivity": {
    "type": "object",
    "required": [
      "action",
      "detectedAt",
      "occurredAt"
    ],
    "description": "One entry in the intel evidence trail. Detection time records when the\nsource was observed; event time records when the source claims the\nevent happened.\n",
    "properties": {
      "action": {
        "type": "string",
        "enum": [
          "observation",
          "official_statement",
          "correction",
          "merge"
        ]
      },
      "detectedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Source observation timestamp."
      },
      "occurredAt": {
        "type": "string",
        "format": "date-time",
        "deprecated": true,
        "x-successor": "#/components/schemas/IntelActivity/properties/detectedAt",
        "description": "Deprecated legacy timestamp: provider publication when known, otherwise detectedAt. Use eventTime for claimed event time."
      },
      "eventTime": {
        "$ref": "#/components/schemas/IntelEventTime"
      },
      "headline": {
        "type": "string"
      },
      "source": {
        "type": "object",
        "required": [
          "url",
          "official"
        ],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "official": {
            "type": "boolean"
          }
        }
      },
      "sentiment": {
        "$ref": "#/components/schemas/Sentiment"
      },
      "clusters": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/ClusterRef"
        }
      }
    }
  },
  "IntelEventTime": {
    "description": "Claimed event time, sanitized from internal source evidence.",
    "oneOf": [
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "at",
          "precision",
          "relationToSource"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "instant"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "precision": {
            "type": "string",
            "enum": [
              "instant",
              "day",
              "week",
              "month"
            ]
          },
          "relationToSource": {
            "type": "string",
            "enum": [
              "current",
              "historical",
              "future"
            ]
          }
        }
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "startAt",
          "endAt",
          "precision",
          "relationToSource"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "interval"
          },
          "startAt": {
            "type": "string",
            "format": "date-time"
          },
          "endAt": {
            "type": "string",
            "format": "date-time",
            "description": "Exclusive boundary after the final supported period."
          },
          "precision": {
            "type": "string",
            "enum": [
              "day",
              "week",
              "month"
            ]
          },
          "relationToSource": {
            "type": "string",
            "enum": [
              "current",
              "historical",
              "future"
            ]
          }
        }
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "relationToSource"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "relative_unresolved"
          },
          "relationToSource": {
            "type": "string",
            "enum": [
              "before_post",
              "after_post",
              "around_post"
            ]
          }
        }
      },
      {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "status",
          "reason"
        ],
        "properties": {
          "status": {
            "type": "string",
            "const": "unknown"
          },
          "reason": {
            "type": "string",
            "enum": [
              "not_stated",
              "ambiguous",
              "ongoing"
            ]
          }
        }
      }
    ]
  },
  "IntelDetail": {
    "allOf": [
      {
        "$ref": "#/components/schemas/Intel"
      },
      {
        "type": "object",
        "properties": {
          "clusterComposition": {
            "type": "array",
            "description": "Top clusters by share, with an `Other` bucket.",
            "items": {
              "type": "object",
              "required": [
                "cluster",
                "percentage"
              ],
              "properties": {
                "cluster": {
                  "$ref": "#/components/schemas/ClusterRef"
                },
                "percentage": {
                  "type": "number",
                  "minimum": 0,
                  "maximum": 100
                }
              }
            }
          }
        }
      }
    ]
  },
  "ReportSubject": {
    "type": "object",
    "required": [
      "type"
    ],
    "properties": {
      "type": {
        "type": "string",
        "enum": [
          "project",
          "topic"
        ]
      },
      "project": {
        "$ref": "#/components/schemas/ProjectRef"
      },
      "topic": {
        "$ref": "#/components/schemas/TopicRef"
      }
    }
  },
  "ReportListItem": {
    "type": "object",
    "required": [
      "id",
      "title",
      "publishedAt",
      "primarySubject",
      "preview"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "title": {
        "type": "string"
      },
      "publishedAt": {
        "type": "string",
        "format": "date-time"
      },
      "revisedAt": {
        "oneOf": [
          {
            "type": "string",
            "format": "date-time"
          },
          {
            "type": "null"
          }
        ]
      },
      "primarySubject": {
        "$ref": "#/components/schemas/ReportSubject"
      },
      "relatedSubjects": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/ReportSubject"
        },
        "description": "Ordered, deduplicated Project bindings frozen from the Report's evidence membership and resolved to current Project identity; never inferred from prose, live Topic associations, or market evidence."
      },
      "preview": {
        "type": "string"
      }
    }
  },
  "Report": {
    "allOf": [
      {
        "$ref": "#/components/schemas/ReportListItem"
      },
      {
        "type": "object",
        "required": [
          "summary",
          "body",
          "sources"
        ],
        "properties": {
          "summary": {
            "type": "string"
          },
          "body": {
            "type": "string",
            "description": "Markdown body of the published artifact without internal source-id markers."
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "title",
                "url"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                },
                "publishedAt": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          },
          "evidence": {
            "type": "object",
            "description": "Publication-time evidence quoted by the artifact, with source\nattribution and observation timestamps. Immutable once\npublished.\n",
            "properties": {
              "snapshotAt": {
                "type": "string",
                "format": "date-time"
              },
              "entities": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "project",
                    "observations"
                  ],
                  "properties": {
                    "project": {
                      "$ref": "#/components/schemas/ProjectRef"
                    },
                    "observations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "required": [
                          "key",
                          "value",
                          "unit",
                          "provider",
                          "observedAt",
                          "freshness"
                        ],
                        "properties": {
                          "key": {
                            "type": "string"
                          },
                          "value": {
                            "type": "number"
                          },
                          "unit": {
                            "type": "string"
                          },
                          "provider": {
                            "type": "string"
                          },
                          "observedAt": {
                            "description": "Source-side observation timestamp. Null when\nthe provider publishes the figure without\none.\n",
                            "oneOf": [
                              {
                                "type": "string",
                                "format": "date-time"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          },
                          "freshness": {
                            "type": "string"
                          },
                          "disagreement": {
                            "type": "number"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    ]
  },
  "AlertTrigger": {
    "type": "string",
    "enum": [
      "intelligence.material",
      "rank.entered"
    ],
    "description": "The set of launch triggers."
  },
  "AlertCadence": {
    "type": "string",
    "enum": [
      "instant",
      "hourly",
      "every_12h",
      "daily"
    ],
    "description": "Chat delivery cadence. First event in a window delivers immediately;\nthe window bundles the rest. `instant` is subject to a per-day\nplatform safety ceiling. Webhooks ignore cadence and receive every\nadmitted event.\n"
  },
  "AlertQualifiers": {
    "type": "object",
    "description": "Filter qualifiers; each list holds at most 20 values.\n`grades`, `sentiments`, `clusterIds`, `maxRank`, and\n`hasOfficialSource` qualify `intelligence.material` subscriptions;\n`chains` qualifies `rank.entered`; `categories` and `assetTypes`\nqualify both.\n",
    "properties": {
      "categories": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "grades": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Grade"
        }
      },
      "sentiments": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "assetTypes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "clusterIds": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "chains": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "maxRank": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Only intel on Projects at or above this rank in the Trend cohort."
      },
      "hasOfficialSource": {
        "type": "boolean"
      }
    }
  },
  "AlertSelector": {
    "type": "object",
    "additionalProperties": false,
    "description": "What the subscription watches: the owner's followed Projects, the\ncurrently ranked cohort, a normalized keyword, or a qualifier-only cohort.\nExplicit per-Project and per-Topic id lists are not yet supported\nand will join additively.\n",
    "properties": {
      "followedProjects": {
        "type": "boolean",
        "description": "Only the owner's followed Projects. Mutually exclusive with the ranked Project scopes."
      },
      "trendingProjects": {
        "type": "boolean",
        "description": "Only Projects in the current Trend ranking. Mutually exclusive with `followedProjects`."
      },
      "keyword": {
        "type": "string",
        "minLength": 2,
        "maxLength": 64,
        "description": "Normalized once at save time; matched case-insensitively against source-derived text."
      },
      "qualifiers": {
        "$ref": "#/components/schemas/AlertQualifiers"
      }
    }
  },
  "Alert": {
    "type": "object",
    "required": [
      "id",
      "status",
      "trigger",
      "selector",
      "cadence",
      "destinationIds",
      "createdAt",
      "updatedAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "active",
          "paused"
        ]
      },
      "trigger": {
        "$ref": "#/components/schemas/AlertTrigger"
      },
      "rankThreshold": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Top-N boundary; present only with `rank.entered`."
      },
      "ranking": {
        "type": "string",
        "enum": [
          "trend"
        ],
        "default": "trend",
        "description": "Ranking watched by `rank.entered`; omitted stored rows mean Trend."
      },
      "selector": {
        "$ref": "#/components/schemas/AlertSelector"
      },
      "cadence": {
        "$ref": "#/components/schemas/AlertCadence"
      },
      "destinationIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1
      },
      "createdAt": {
        "type": "string",
        "format": "date-time"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "AlertCreate": {
    "type": "object",
    "required": [
      "trigger",
      "selector",
      "destinationIds"
    ],
    "properties": {
      "trigger": {
        "$ref": "#/components/schemas/AlertTrigger"
      },
      "rankThreshold": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100,
        "description": "Required when `trigger` is `rank.entered`."
      },
      "ranking": {
        "type": "string",
        "enum": [
          "trend"
        ],
        "default": "trend",
        "description": "Ranking watched by `rank.entered`."
      },
      "selector": {
        "$ref": "#/components/schemas/AlertSelector"
      },
      "cadence": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AlertCadence"
          }
        ],
        "default": "hourly"
      },
      "destinationIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1
      }
    }
  },
  "AlertUpdate": {
    "type": "object",
    "description": "Partial update; omitted fields are unchanged.",
    "properties": {
      "status": {
        "type": "string",
        "enum": [
          "active",
          "paused"
        ]
      },
      "rankThreshold": {
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      },
      "ranking": {
        "type": "string",
        "enum": [
          "trend"
        ]
      },
      "selector": {
        "$ref": "#/components/schemas/AlertSelector"
      },
      "cadence": {
        "$ref": "#/components/schemas/AlertCadence"
      },
      "destinationIds": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "minItems": 1
      }
    }
  },
  "AlertDestination": {
    "type": "object",
    "required": [
      "id",
      "kind",
      "label",
      "status"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "kind": {
        "type": "string",
        "enum": [
          "telegram",
          "discord",
          "webhook"
        ]
      },
      "label": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "pending",
          "active",
          "failing",
          "disabled"
        ]
      }
    }
  },
  "Cluster": {
    "type": "object",
    "required": [
      "id",
      "name",
      "description"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "universe": {
        "type": "string",
        "enum": [
          "crypto",
          "tradfi"
        ]
      }
    }
  },
  "Vocabulary": {
    "type": "object",
    "required": [
      "grades",
      "sentiments",
      "stances",
      "assetTypes",
      "marketCapBands",
      "projectSort",
      "intelSort",
      "activityModes",
      "projectRankings",
      "universes",
      "seriesMeasures",
      "alertTriggers",
      "alertCadences",
      "projectCategories",
      "intelCategories",
      "chains"
    ],
    "properties": {
      "grades": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Grade"
        }
      },
      "sentiments": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "stances": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/Stance"
        }
      },
      "assetTypes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "marketCapBands": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "projectSort": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "intelSort": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "activityModes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "projectRankings": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "universes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "seriesMeasures": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "alertTriggers": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/AlertTrigger"
        }
      },
      "alertCadences": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/AlertCadence"
        }
      },
      "projectCategories": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "slug",
            "name"
          ],
          "properties": {
            "slug": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        }
      },
      "intelCategories": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "slug",
            "name"
          ],
          "properties": {
            "slug": {
              "type": "string"
            },
            "name": {
              "type": "string"
            }
          }
        }
      },
      "chains": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  },
  "Me": {
    "type": "object",
    "required": [
      "account",
      "rateLimit",
      "history"
    ],
    "properties": {
      "account": {
        "type": "object",
        "required": [
          "id",
          "plan",
          "wallet"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "plan": {
            "description": "The account's plan. Null for x402 keys, which pay per request.",
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "name",
                  "via",
                  "status",
                  "periodStart",
                  "renewsAt",
                  "endsAt"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "via": {
                    "type": "string",
                    "enum": [
                      "subscription",
                      "holding",
                      "grant"
                    ],
                    "description": "A paid subscription, holding 600k+ AIXBT, or a manual grant."
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "active",
                      "trialing",
                      "past_due"
                    ]
                  },
                  "periodStart": {
                    "description": "Start of the current billing period.",
                    "oneOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "renewsAt": {
                    "description": "When the plan renews. Null when it will not renew.",
                    "oneOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "endsAt": {
                    "description": "When access ends if the plan does not renew.",
                    "oneOf": [
                      {
                        "type": "string",
                        "format": "date-time"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "wallet": {
            "description": "The account's wallet, identified by its last four characters only.",
            "oneOf": [
              {
                "type": "object",
                "required": [
                  "chain",
                  "last4"
                ],
                "properties": {
                  "chain": {
                    "type": "string",
                    "enum": [
                      "eip155",
                      "solana"
                    ]
                  },
                  "last4": {
                    "type": "string",
                    "minLength": 4,
                    "maxLength": 4
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "rateLimit": {
        "type": "object",
        "required": [
          "perMinute",
          "perDay"
        ],
        "properties": {
          "perMinute": {
            "type": "integer"
          },
          "perDay": {
            "type": "integer"
          }
        }
      },
      "history": {
        "type": "object",
        "required": [
          "lookbackDays"
        ],
        "properties": {
          "lookbackDays": {
            "description": "Days of history available. Null means no limit.",
            "oneOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      }
    }
  }
}
```

---

# OpenAPI component schemas — API v2 (deprecated)

Shared schemas referenced by the endpoint contracts above.

```json
{
  "ApiError": {
    "type": "object",
    "required": [
      "error"
    ],
    "description": "Error response. Middleware may include additional rate-limit or access metadata.",
    "properties": {
      "error": {
        "type": "string"
      },
      "message": {
        "type": "string"
      },
      "code": {
        "type": "string"
      },
      "status": {
        "type": "integer"
      },
      "data": {
        "nullable": true
      },
      "meta": {
        "type": "object",
        "additionalProperties": true
      },
      "details": {
        "type": "object",
        "additionalProperties": true
      },
      "pagination": {
        "$ref": "#/components/schemas/Pagination"
      },
      "limitType": {
        "type": "string",
        "enum": [
          "minute",
          "day"
        ],
        "description": "Rate-limit window that was exhausted."
      },
      "retryAfterMs": {
        "type": "integer",
        "minimum": 0,
        "description": "Milliseconds until the exhausted window resets."
      },
      "limits": {
        "type": "object",
        "required": [
          "minute",
          "day"
        ],
        "properties": {
          "minute": {
            "$ref": "#/components/schemas/RateLimitWindow"
          },
          "day": {
            "$ref": "#/components/schemas/RateLimitWindow"
          }
        }
      },
      "issues": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "path",
            "message"
          ],
          "properties": {
            "path": {
              "type": "string"
            },
            "message": {
              "type": "string"
            }
          }
        }
      }
    },
    "additionalProperties": true
  },
  "RateLimitWindow": {
    "type": "object",
    "required": [
      "limit",
      "remaining",
      "resetAt"
    ],
    "properties": {
      "limit": {
        "type": "integer",
        "minimum": 0
      },
      "remaining": {
        "type": "integer",
        "minimum": 0
      },
      "resetAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "Pagination": {
    "type": "object",
    "required": [
      "page",
      "limit",
      "totalCount",
      "hasMore"
    ],
    "properties": {
      "page": {
        "type": "integer",
        "minimum": 1
      },
      "limit": {
        "type": "integer",
        "minimum": 1
      },
      "totalCount": {
        "type": "integer",
        "minimum": 0
      },
      "hasMore": {
        "type": "boolean"
      }
    }
  },
  "HistoryAccessMeta": {
    "type": "object",
    "required": [
      "lookbackDays",
      "earliestAvailableAt"
    ],
    "properties": {
      "lookbackDays": {
        "type": [
          "integer",
          "null"
        ],
        "examples": [
          90
        ]
      },
      "earliestAvailableAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      }
    }
  },
  "HistoryResponseMeta": {
    "type": "object",
    "required": [
      "history"
    ],
    "properties": {
      "history": {
        "$ref": "#/components/schemas/HistoryAccessMeta"
      }
    }
  },
  "TopicIndexTopic": {
    "type": "object",
    "required": [
      "id",
      "rank",
      "name",
      "summary",
      "score",
      "tweetCount",
      "authorCount",
      "lastSeenAt"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "rank": {
        "type": "integer",
        "minimum": 1
      },
      "name": {
        "type": "string"
      },
      "summary": {
        "type": "string"
      },
      "score": {
        "type": "number"
      },
      "tweetCount": {
        "type": "integer",
        "minimum": 0
      },
      "authorCount": {
        "type": "integer",
        "minimum": 0
      },
      "lastSeenAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "TopicIndexSnapshot": {
    "type": "object",
    "required": [
      "completedAt",
      "latestEvidenceAt",
      "windowStartedAt",
      "topics"
    ],
    "properties": {
      "completedAt": {
        "type": "string",
        "format": "date-time"
      },
      "latestEvidenceAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "windowStartedAt": {
        "type": "string",
        "format": "date-time"
      },
      "topics": {
        "type": "array",
        "maxItems": 10,
        "items": {
          "$ref": "#/components/schemas/TopicIndexTopic"
        }
      }
    }
  },
  "RecipeSummary": {
    "type": "object",
    "required": [
      "name",
      "version",
      "description",
      "paramCount",
      "estimatedTokens"
    ],
    "properties": {
      "name": {
        "type": "string"
      },
      "version": {
        "type": "string"
      },
      "description": {
        "type": "string"
      },
      "paramCount": {
        "type": "integer",
        "minimum": 0
      },
      "estimatedTokens": {
        "type": [
          "integer",
          "null"
        ],
        "minimum": 0
      }
    }
  },
  "RecipeDetail": {
    "type": "object",
    "required": [
      "name",
      "updatedAt",
      "yaml"
    ],
    "properties": {
      "name": {
        "type": "string"
      },
      "updatedAt": {
        "type": "string",
        "format": "date-time"
      },
      "yaml": {
        "type": "string"
      }
    }
  },
  "RecipeExecutionResult": {
    "oneOf": [
      {
        "type": "object",
        "required": [
          "status",
          "recipe",
          "version",
          "step",
          "instructions",
          "returns",
          "data",
          "tokenCount",
          "progress",
          "remaining"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "awaiting_agent"
            ]
          },
          "recipe": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "step": {
            "type": "string"
          },
          "instructions": {
            "type": "string"
          },
          "returns": {
            "type": "object",
            "additionalProperties": true
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "tokenCount": {
            "type": "integer",
            "minimum": 0
          },
          "progress": {
            "type": "object",
            "required": [
              "stepsCompleted",
              "stepsTotal",
              "segmentIndex",
              "segmentsTotal"
            ],
            "properties": {
              "stepsCompleted": {
                "type": "integer",
                "minimum": 0
              },
              "stepsTotal": {
                "type": "integer",
                "minimum": 0
              },
              "segmentIndex": {
                "type": "integer",
                "minimum": 0
              },
              "segmentsTotal": {
                "type": "integer",
                "minimum": 0
              }
            }
          },
          "remaining": {
            "type": "string"
          },
          "parallel": {
            "type": "object",
            "required": [
              "items",
              "itemKey",
              "concurrency",
              "perItemContext",
              "sharedContext"
            ],
            "properties": {
              "items": {
                "type": "array",
                "items": {}
              },
              "itemKey": {
                "type": "string"
              },
              "concurrency": {
                "type": "integer",
                "minimum": 1
              },
              "perItemContext": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "sharedContext": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "parallelExecution": {
            "type": "string"
          },
          "contextHints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "carryForward": {
            "type": "object",
            "additionalProperties": true
          },
          "meta": {
            "$ref": "#/components/schemas/HistoryResponseMeta"
          }
        },
        "additionalProperties": true
      },
      {
        "type": "object",
        "required": [
          "status",
          "recipe",
          "version",
          "timestamp",
          "data",
          "tokenCount"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "complete"
            ]
          },
          "recipe": {
            "type": "string"
          },
          "version": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "additionalProperties": true
          },
          "tokenCount": {
            "type": "integer",
            "minimum": 0
          },
          "hints": {
            "type": "object",
            "properties": {
              "combine": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "key": {
                "type": "string"
              },
              "include": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "analysis": {
            "type": "object",
            "required": [
              "instructions"
            ],
            "properties": {
              "instructions": {
                "type": "string"
              },
              "output": {
                "type": "string"
              },
              "context": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "contextHints": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "meta": {
            "$ref": "#/components/schemas/HistoryResponseMeta"
          }
        },
        "additionalProperties": true
      }
    ]
  },
  "UpgradeMeta": {
    "type": "object",
    "description": "Present on supported unauthenticated responses with an account access link.",
    "properties": {
      "upgrade": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "examples": [
              "https://aixbt.tech/subscribe"
            ]
          }
        }
      }
    }
  },
  "ActivityMode": {
    "type": "string",
    "enum": [
      "all",
      "observations",
      "none"
    ],
    "default": "all",
    "description": "Controls what activity data is included in the response.\n- `all` — full activity timeline (default)\n- `observations` — only observation entries (ingestion rows)\n- `none` — omit the activity array entirely\n"
  },
  "SignalCluster": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "name": {
        "type": "string"
      }
    }
  },
  "SignalActivity": {
    "type": "object",
    "description": "Sanitized activity timeline entry for an intel item",
    "properties": {
      "id": {
        "type": "string",
        "description": "Stable activity row ID"
      },
      "date": {
        "type": "string",
        "format": "date-time",
        "description": "Activity timestamp"
      },
      "action": {
        "type": "string",
        "description": "Canonical action: INITIAL_DETECTION, REFINED, NEW_DETAIL, TENSE_UPDATE, NO_CHANGE, PARSE_ERROR"
      },
      "source": {
        "type": "string",
        "description": "Platform source name (e.g. twitter, discord, telegram)"
      },
      "actor": {
        "type": "object",
        "description": "Agent actor metadata (present on agent-originated rows)",
        "properties": {
          "type": {
            "type": "string"
          }
        }
      },
      "officialSourceUrl": {
        "type": "string",
        "format": "uri",
        "description": "Canonical URL for the official source when available"
      },
      "clusters": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/SignalCluster"
        }
      },
      "incoming": {
        "type": "string",
        "description": "Description extracted from new content"
      },
      "result": {
        "type": "string",
        "description": "Description after merge"
      },
      "headline": {
        "type": "string",
        "description": "Plain-language summary up to 10 words"
      },
      "sentiment": {
        "type": [
          "number",
          "null"
        ],
        "minimum": -1,
        "maximum": 1,
        "description": "Sentiment value for this activity entry"
      },
      "citationEvidence": {
        "type": "array",
        "description": "Structured citation evidence (agent rows)",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "url": {
              "type": "string"
            },
            "targetActivityIds": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        }
      },
      "fromSignal": {
        "type": "object",
        "description": "Present for project-merge events",
        "properties": {
          "signalId": {
            "type": "string"
          },
          "projectId": {
            "type": "string"
          },
          "projectName": {
            "type": "string"
          }
        }
      },
      "isOfficial": {
        "type": "boolean",
        "description": "Whether this activity came from an official project source"
      },
      "changelog": {
        "type": "string",
        "description": "Terse noun-phrase describing what changed"
      }
    }
  },
  "TopListContext": {
    "type": "object",
    "properties": {
      "enteredAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "currentHours": {
        "type": [
          "integer",
          "null"
        ]
      },
      "wasYesterday": {
        "type": [
          "boolean",
          "null"
        ]
      },
      "entryCount24h": {
        "type": [
          "integer",
          "null"
        ],
        "description": "Entries into this band in the last 24h (>1 = volatile)"
      },
      "stabilityLabel": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "flash",
          "fresh",
          "persistent",
          "durable"
        ],
        "description": "flash (<2h), fresh (2-6h), persistent (6-24h), durable (>=24h)"
      }
    }
  },
  "MomentumContext": {
    "type": [
      "object",
      "null"
    ],
    "description": "Momentum and leaderboard stability context. Present when project insights are available.",
    "properties": {
      "trendTrajectory": {
        "type": [
          "string",
          "null"
        ],
        "enum": [
          "rising",
          "decaying",
          "stable",
          "new"
        ],
        "description": "24h canonical trend-score direction"
      },
      "distinctClusters": {
        "type": [
          "integer",
          "null"
        ]
      },
      "peakRank48h": {
        "type": [
          "integer",
          "null"
        ]
      },
      "bestRank14d": {
        "type": [
          "integer",
          "null"
        ]
      },
      "rankedSince": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time"
      },
      "leaderboard": {
        "type": "object",
        "properties": {
          "top10": {
            "$ref": "#/components/schemas/TopListContext"
          },
          "top25": {
            "$ref": "#/components/schemas/TopListContext"
          }
        }
      }
    }
  },
  "SignalResponse": {
    "type": "object",
    "required": [
      "id",
      "detectedAt",
      "reinforcedAt",
      "description",
      "citations",
      "projectName",
      "projectId",
      "category",
      "observationCount",
      "hasOfficialSource",
      "clusters"
    ],
    "properties": {
      "id": {
        "type": "string"
      },
      "detectedAt": {
        "type": "string",
        "format": "date-time",
        "description": "Date when this intel was first detected"
      },
      "reinforcedAt": {
        "type": [
          "string",
          "null"
        ],
        "format": "date-time",
        "description": "Date when this intel was last reinforced with independent supporting evidence; null for research-only intel"
      },
      "description": {
        "type": "string"
      },
      "headline": {
        "type": "string",
        "description": "Plain-language summary up to 10 words"
      },
      "citations": {
        "type": "array",
        "description": "Vetted non-X citations supporting this intel",
        "items": {
          "type": "string"
        }
      },
      "projectName": {
        "type": "string"
      },
      "projectId": {
        "type": "string"
      },
      "category": {
        "type": "string"
      },
      "observationCount": {
        "type": "integer",
        "minimum": 0,
        "description": "Number of observation-type activity entries on this intel"
      },
      "hasOfficialSource": {
        "type": "boolean",
        "description": "Whether any observation on this intel came from an official project source"
      },
      "officialSourceUrl": {
        "type": "string",
        "format": "uri",
        "description": "Canonical official X provenance retained when the source observation is omitted from public activity"
      },
      "sentiment": {
        "type": [
          "number",
          "null"
        ],
        "minimum": -1,
        "maximum": 1,
        "description": "Aggregate sentiment, averaged across all activity entries.\nBucket thresholds: positive >= 0.25, neutral in (-0.25, 0.25), negative <= -0.25.\n`null` when no sentiment has been classified.\n"
      },
      "referencesMetrics": {
        "type": [
          "boolean",
          "null"
        ],
        "description": "Whether this intel description references market metrics. `null` when not classified."
      },
      "metrics": {
        "type": [
          "object",
          "null"
        ],
        "description": "Project market metrics attached when `referencesMetrics` is true and metrics are available.",
        "properties": {
          "usd": {
            "type": [
              "number",
              "null"
            ]
          },
          "usdMarketCap": {
            "type": [
              "number",
              "null"
            ]
          },
          "usd24hVol": {
            "type": [
              "number",
              "null"
            ]
          },
          "usd24hChange": {
            "type": [
              "number",
              "null"
            ]
          },
          "lastUpdatedAt": {
            "type": [
              "number",
              "null"
            ]
          }
        }
      },
      "clusters": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/SignalCluster"
        }
      },
      "activity": {
        "type": "array",
        "description": "Activity timeline. Present unless `activity=none`.",
        "items": {
          "$ref": "#/components/schemas/SignalActivity"
        }
      }
    }
  }
}
```