AIXBT Me API

openapi: 3.2.0
info:
  title: AIXBT API v3 Me API
  version: 3.0.0-draft.1
  summary: Crypto intelligence API for Projects, Topics, Intel, Reports, and Clusters.
  description: 'The AIXBT API v3 contract. The implementation conforms to this document,

    the reference docs generate from it, and automated tests keep the served

    API and this document in sync. Interactive docs are served at `/v3/docs`;

    this document is served verbatim at `/v3/openapi.yaml`.


    ## Conventions


    - **Envelope**: every JSON success body is `{data, meta}`. There is no

    body-level `status` integer; the HTTP status code is the status.

    - **Errors**: every 4xx/5xx body is a single typed `Error` with a stable

    machine `code`. `401` means the credential is missing or invalid; `403`

    means the credential lacks an entitlement or crossed the history

    boundary.

    - **Pagination**: collections use opaque cursors: request `cursor` +

    `limit`, read `meta.nextCursor` (`null` on the last page). There are no

    page numbers and no total counts.

    - **Measurements**: v3 publishes AIXBT-owned measurements: `trend` for

    continued attention, `rank`, and attention counts,

    together with canonical identity. It does not redistribute third-party market

    data: no prices, market caps, volumes, or candles anywhere in this

    contract. Composition happens through `identifiers`: stable external

    join keys (CoinGecko id, X handle; additively extensible per universe)

    that let a consumer fetch market data under their own license. The one

    bounded exception is the publication-time evidence block inside an

    entitled Report, which quotes attributed observations as part of the

    research artifact. Intel lists accept a coarse `marketCap` band as a

    filter; the band selects results and is never returned as data.

    - **Access tiers**: Current Topic list, detail, and association routes are

    free and served under unauthenticated IP rate limits. Topic measurement

    history and everything else require an API key, and Report detail

    additionally requires the `topic-reports` entitlement. Alert management

    is owner-scoped to the calling credential; destination provisioning (chat

    connections) stays in product Settings and the API references

    destinations by id.

    - **Naming**: `trend` is the public attention measurement; `rank` is its

    position within the relevant Project or Topic cohort.

    Enumerated values are lowercase. Timestamps are ISO 8601 UTC and semantic

    (`detectedAt`, `reinforcedAt`, `observedAt`, never processing time).

    Intel activity keeps claimed `eventTime` separate from detection time;

    legacy `occurredAt` remains a deprecated provider-publication/detection

    fallback; it is never claimed event time.

    - **Locators**: Project path params accept the canonical id or the

    immutable public slug; responses always carry both. Merged or re-slugged

    Projects keep old locators resolving to the canonical resource.

    - **Universe**: every Project and Cluster belongs to the `crypto`

    universe.

    - **Assets**: a Project''s instrument identity is a typed `assets` array

    (`token`, `stablecoin`, `nft-collection` today). New asset types are

    added additively; the array shape never changes.

    - **History**: measurement series endpoints serve recorded history

    through their `from`/`to` windows, subject to the credential''s history

    window (`meta.history`).

    - **Subject misses**: a 404 body distinguishes `not_found` (never

    existed / bad locator) and `not_current` (exists, no longer current).

    - **Stability**: while `x-status` is `draft`, routes, fields, and values may

    change before stabilization. After stabilization, retiring routes first

    serve RFC 9745 `Deprecation` and RFC 8288

    `Link: rel="successor-version"` headers and are marked `deprecated: true`

    here with an `x-successor` pointer.

    - **Caching**: every response is `Cache-Control: private, no-store`.

    Rate limits are surfaced via `X-RateLimit-*` headers; breaches return

    `429` with `Retry-After`.'
  x-status: draft
servers:
- url: https://api.aixbt.tech
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: Me
  description: Your credential's entitlements, limits, and history window.
paths:
  /v3/me:
    get:
      operationId: getMe
      tags:
      - Me
      summary: Get the signed-in account
      description: '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`.'
      responses:
        '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'
components:
  schemas:
    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.
    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'
    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'
    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).
  responses:
    Internal:
      description: Unexpected server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            internal:
              value:
                code: internal_error
                message: Unexpected error.
    RateLimited:
      description: Rate limit exceeded; retry after the indicated delay.
      headers:
        Retry-After:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            rateLimited:
              value:
                code: rate_limited
                message: Minute limit reached.
                details:
                  limit: 100
                  window: minute
    Unauthorized:
      description: The credential is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            credentialRequired:
              value:
                code: credential_required
                message: Provide an API key via the x-api-key header.
            invalidCredential:
              value:
                code: invalid_credential
                message: The API key is expired or unknown.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: 'API key. The `Authorization` header is accepted as an equivalent

        carrier. Responses echo the credential class in `X-API-Key-Type`.

        '