cabalspy-xyz Analytics API

openapi: 3.2.0
info:
  title: CabalSpy Analytics API
  version: 1.0.0
  description: 'REST API for CabalSpy on-chain labeled wallet data: tracked KOL, Smart Money and Whale wallets on Solana, BNB Chain, Base, Ethereum and Robinhood Chain (blockchain values: solana, bnb, base, eth, rh), with wallet profiles, leaderboards, PnL, token holders and transactions, bundle detection (Solana only), live signals and analytics.


    Wallet type availability per chain: Solana has kol, smart, whale. BNB, Base and Robinhood Chain have kol, smart. ETH has kol.


    Authentication: every request needs an API key, passed either as the api_key query parameter or as an Authorization Bearer header (the two are equivalent). Get a free key at https://apidashboard.cabalspy.xyz/.


    Credits: a REST request costs 10 credits on every plan. The free tier includes 10,000 credits per month; credits reset on the first of every month.


    Rate limits: requests per second by plan are 5 (Free), 20 (Starter), 50 (Pro) and 100 (Business). Exceeding the limit returns 429 rate_limited; wait and retry.


    Responses share an envelope: success, data, meta (request_id, cached, cache_age_seconds, version, timestamp) and, on some endpoints, pagination.


    Real-time data is available separately over WebSocket at wss://stream.cabalspy.xyz (not described by this document; 1 credit per event received).'
  termsOfService: https://www.cabalspy.xyz/terms/
  contact:
    name: CabalSpy
    email: contact@cabalspy.xyz
servers:
- url: https://api.cabalspy.xyz/v1
security:
- ApiKeyQuery: []
- BearerAuth: []
tags:
- name: Analytics
  description: Aggregate analytics over tracked wallets.
paths:
  /analytics:
    get:
      operationId: getAnalytics
      summary: Aggregate analytics
      description: Aggregate analytics over tracked wallets for a period. All modes share the wrapper (mode, blockchain, type, period, currency); most_traded and top_performers put items in a data array, volume_trend returns time bucketed volume points in the data array, and win_rate returns summary fields directly in the wrapper. Costs 10 credits per request.
      tags:
      - Analytics
      externalDocs:
        url: https://docs.cabalspy.xyz/analytics
      parameters:
      - name: blockchain
        in: query
        required: true
        description: Chain. One of solana, bnb, base, eth.
        schema:
          type: string
          enum:
          - solana
          - bnb
          - base
          - eth
          - rh
      - name: type
        in: query
        required: true
        description: Wallet category kol, smart or whale.
        schema:
          type: string
          enum:
          - kol
          - smart
          - whale
      - name: mode
        in: query
        required: true
        description: Analytics view. One of most_traded, top_performers, win_rate, volume_trend.
        schema:
          type: string
          enum:
          - most_traded
          - top_performers
          - win_rate
          - volume_trend
      - name: period
        in: query
        required: true
        description: Aggregation window, one of 6h, 1d, 7d or 30d.
        schema:
          type: string
          enum:
          - 6h
          - 1d
          - 7d
          - 30d
      - name: limit
        in: query
        required: false
        description: Maximum number of items to return, for list modes.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: True on success.
                  data:
                    type: object
                    properties:
                      mode:
                        type: string
                        description: The requested mode.
                      blockchain:
                        type: string
                      type:
                        type: string
                      period:
                        type: string
                      currency:
                        type: string
                      data:
                        type: array
                        description: Present for most_traded, top_performers and volume_trend. most_traded items carry rank, mint, token_name, wallet_count, total_volume, total_buy, total_sell, net_flow, buying_pressure, currency, first_buy_at. top_performers items carry profile and period_stats. volume_trend items are time bucketed volume points.
                        items:
                          type: object
                          additionalProperties: true
                      total_wallets:
                        type: integer
                        description: win_rate mode. Total wallets considered.
                      wallets_with_trades:
                        type: integer
                        description: win_rate mode. Wallets that traded in the period.
                      win_count:
                        type: integer
                        description: win_rate mode. Winning closed positions.
                      closed_count:
                        type: integer
                        description: win_rate mode. Total closed positions.
                      win_rate_percentage:
                        type: number
                        description: win_rate mode. Win rate as a percentage.
                      distribution:
                        $ref: '#/components/schemas/WinRateBuckets'
                    additionalProperties: true
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                  meta:
                    $ref: '#/components/schemas/Meta'
                additionalProperties: true
              example:
                success: true
                data:
                  mode: most_traded
                  blockchain: solana
                  type: kol
                  period: 7d
                  currency: SOL
                  data:
                  - rank: 1
                    mint: 3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump
                    token_name: invisibull
                    wallet_count: 12
                    total_volume: 312.5
                    total_buy: 180.25
                    total_sell: 132.25
                    net_flow: 48.0
                    buying_pressure: 57.6
                    currency: SOL
                    first_buy_at: '2026-07-01T09:58:00Z'
                pagination:
                  limit: 20
                  total: 1
                  has_more: false
                  next_cursor: null
                meta:
                  request_id: req_5162c7cf7f87
                  cached: false
                  cache_age_seconds: 0
                  version: 1.0.0
                  timestamp: '2026-07-06T11:01:57Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    BadRequest:
      description: Bad request. Code missing_parameter (a required parameter is missing) or invalid_parameter (a parameter is missing or has an invalid value, for example a chain and wallet type combination that does not exist such as eth with whale).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Code rate_limited. Rate limit exceeded (the plan's requests-per-second limit), wait and retry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Code forbidden. API key invalid or credits exhausted.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Code unauthorized. API key missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      description: Error response. The documentation specifies the HTTP status and an error code (missing_parameter, invalid_parameter, unauthorized, forbidden, not_found, rate_limited) but not the exact body layout, so no fields are asserted here.
      additionalProperties: true
    Meta:
      type: object
      description: Request metadata returned with every response.
      properties:
        request_id:
          type: string
        cached:
          type: boolean
        cache_age_seconds:
          type: integer
        version:
          type: string
        timestamp:
          type: string
      additionalProperties: true
    Pagination:
      type: object
      description: Standard pagination object. Depending on the endpoint it appears inside data or next to data at the top level of the response.
      properties:
        limit:
          type:
          - integer
          - 'null'
          description: Requested page size (null means all).
        total:
          type: integer
          description: Total number of items.
        has_more:
          type: boolean
          description: Whether more pages follow.
        next_cursor:
          type:
          - string
          - 'null'
          description: Cursor for the next page (null means end).
      additionalProperties: true
    WinRateBuckets:
      type: object
      description: Profit buckets.
      properties:
        above_500:
          type: integer
          description: Positions with more than 500 percent gain.
        above_100_to_500:
          type: integer
          description: Positions with 100 to 500 percent gain.
        above_zero_to_100:
          type: integer
          description: Positions with 0 to 100 percent gain.
        below_zero:
          type: integer
          description: Losing positions.
      additionalProperties: true
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Your API key as the api_key query parameter.
    BearerAuth:
      type: http
      scheme: bearer
      description: Your API key as an Authorization Bearer header.
externalDocs:
  description: CabalSpy API documentation
  url: https://docs.cabalspy.xyz/