openapi: 3.0.3
info:
  title: CryptoNews API
  description: >-
    REST API aggregating cryptocurrency news, Bitcoin sentiment analysis, and
    crypto market news from 50+ sources with filtering by currency and time
    range. Provides AI-powered sentiment analysis, delayed pricing for 600+
    coins, whale transaction tracking, and historical data from December 2020.
  version: '1'
  contact:
    url: https://cryptonews-api.com/
  termsOfService: https://cryptonews-api.com/termsandconditions
servers:
  - url: https://cryptonews-api.com/api/v1
    description: Production server
security:
  - tokenAuth: []
tags:
  - name: News
    description: Cryptocurrency news articles aggregated from 50+ sources
  - name: Categories
    description: News by category or sector
  - name: Trending
    description: Trending headlines and top mentions
  - name: Sentiment & Stats
    description: Sentiment analysis and statistical summaries
  - name: Prices
    description: Delayed cryptocurrency pricing data
  - name: Whale Transactions
    description: Large on-chain whale transaction tracking
  - name: Account
    description: Account and reference data
  - name: Digest
    description: Curated digest endpoints
paths:
  /:
    get:
      summary: Get Crypto News
      operationId: getCryptoNews
      description: >-
        Retrieve cryptocurrency news articles from 50+ sources. Filter by
        ticker symbol, include or exclude tickers, control pagination and
        item count per page.
      tags:
        - News
      parameters:
        - name: tickers
          in: query
          description: >-
            Comma-separated list of cryptocurrency ticker symbols to filter
            news by (e.g. BTC,ETH,XRP).
          schema:
            type: string
            example: BTC,ETH,XRP
        - name: tickers-include
          in: query
          description: >-
            Return only articles that mention all of the specified tickers
            (comma-separated). Stricter than tickers.
          schema:
            type: string
            example: BTC,ETH,XRP
        - name: tickers-only
          in: query
          description: >-
            Return only articles that mention exclusively the specified ticker
            and no other tickers.
          schema:
            type: string
            example: BTC
        - name: items
          in: query
          description: Number of news articles to return per page (max 50).
          schema:
            type: integer
            default: 50
            maximum: 50
            example: 50
        - name: page
          in: query
          description: Page number for pagination (starts at 1).
          schema:
            type: integer
            default: 1
            example: 1
        - name: token
          in: query
          description: API authentication token.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response with news articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /category:
    get:
      summary: Get News by Category
      operationId: getNewsByCategory
      description: >-
        Retrieve cryptocurrency news articles filtered by category section.
        Use section=general for general crypto news or section=alltickers
        for all ticker-based news.
      tags:
        - Categories
      parameters:
        - name: section
          in: query
          required: true
          description: >-
            Category section to filter by. Use 'general' for general crypto
            news or 'alltickers' for all ticker news.
          schema:
            type: string
            enum:
              - general
              - alltickers
            example: general
        - name: items
          in: query
          description: Number of news articles to return per page (max 50).
          schema:
            type: integer
            default: 50
            maximum: 50
            example: 50
        - name: page
          in: query
          description: Page number for pagination.
          schema:
            type: integer
            default: 1
            example: 1
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with categorized news articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /trending-headlines:
    get:
      summary: Get Trending Headlines
      operationId: getTrendingHeadlines
      description: >-
        Retrieve trending cryptocurrency news headlines. Optionally filter
        by specific ticker symbol.
      tags:
        - Trending
      parameters:
        - name: ticker
          in: query
          description: Cryptocurrency ticker symbol to filter trending headlines by.
          schema:
            type: string
            example: BTC
        - name: page
          in: query
          description: Page number for pagination.
          schema:
            type: integer
            default: 1
            example: 1
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with trending headlines
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadlinesResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /top-mention:
    get:
      summary: Get Top Mentioned Tickers
      operationId: getTopMention
      description: >-
        Retrieve the most frequently mentioned cryptocurrency tickers over a
        specified date range.
      tags:
        - Trending
      parameters:
        - name: date
          in: query
          description: Date range for top mention data.
          schema:
            type: string
            enum:
              - last24hours
              - last7days
              - last30days
            example: last7days
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with top mentioned tickers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TopMentionResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /stat:
    get:
      summary: Get Sentiment Statistics
      operationId: getSentimentStats
      description: >-
        Retrieve AI-powered sentiment analysis statistics for cryptocurrency
        news. Filter by section (general or alltickers) or specific ticker,
        and specify a date range.
      tags:
        - Sentiment & Stats
      parameters:
        - name: section
          in: query
          description: >-
            Section to get stats for. Use 'general' or 'alltickers'. Mutually
            exclusive with tickers parameter.
          schema:
            type: string
            enum:
              - general
              - alltickers
            example: general
        - name: tickers
          in: query
          description: >-
            Comma-separated ticker symbols to get stats for. Mutually exclusive
            with section parameter.
          schema:
            type: string
            example: BTC
        - name: date
          in: query
          description: Date range for sentiment statistics.
          schema:
            type: string
            enum:
              - last24hours
              - last7days
              - last30days
            example: last30days
        - name: page
          in: query
          description: Page number for pagination.
          schema:
            type: integer
            default: 1
            example: 1
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with sentiment statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /ticker-price:
    get:
      summary: Get Delayed Ticker Prices
      operationId: getTickerPrice
      description: >-
        Retrieve delayed cryptocurrency price data for one or more tickers.
        Supports 600+ coins. Prices are delayed (not real-time).
      tags:
        - Prices
      parameters:
        - name: tickers
          in: query
          description: >-
            Comma-separated list of ticker symbols to get prices for. If
            omitted, returns all available tickers.
          schema:
            type: string
            example: BTC,ETH,SOL,DOGE,XRP
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with delayed ticker prices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickerPriceResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /whale-transactions:
    get:
      summary: Get Whale Transactions
      operationId: getWhaleTransactions
      description: >-
        Retrieve large on-chain cryptocurrency transactions (whale
        transactions) filtered by ticker and date range or minimum amount.
      tags:
        - Whale Transactions
      parameters:
        - name: tickers
          in: query
          description: Comma-separated list of cryptocurrency tickers to filter by.
          schema:
            type: string
            example: BTC,ETH
        - name: date
          in: query
          description: Date range for whale transactions.
          schema:
            type: string
            enum:
              - last24hours
              - last7days
              - last30days
            example: last24hours
        - name: min_amount
          in: query
          description: Minimum transaction amount in USD to filter results.
          schema:
            type: integer
            example: 5000000
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with whale transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhaleTransactionsResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /whale-summary:
    get:
      summary: Get Whale Transaction Summary
      operationId: getWhaleSummary
      description: >-
        Retrieve a summary of whale cryptocurrency transactions for a
        specified ticker and time period.
      tags:
        - Whale Transactions
      parameters:
        - name: tickers
          in: query
          description: Cryptocurrency ticker symbol to summarize whale activity for.
          schema:
            type: string
            example: BTC
        - name: date
          in: query
          description: Date range for the whale transaction summary.
          schema:
            type: string
            enum:
              - last24hours
              - last7days
              - last30days
            example: last7days
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with whale transaction summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhaleSummaryResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /events:
    get:
      summary: Get Crypto Events
      operationId: getCryptoEvents
      description: >-
        Retrieve cryptocurrency events such as conferences, hard forks, and
        other scheduled events. Optionally filter by ticker symbol.
      tags:
        - News
      parameters:
        - name: tickers
          in: query
          description: Cryptocurrency ticker to filter events by.
          schema:
            type: string
            example: BTC
        - name: page
          in: query
          description: Page number for pagination.
          schema:
            type: integer
            default: 1
            example: 1
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with crypto events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventsResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /sundown-digest:
    get:
      summary: Get Sundown Digest
      operationId: getSundownDigest
      description: >-
        Retrieve the curated daily Sundown Digest of top cryptocurrency
        news stories.
      tags:
        - Digest
      parameters:
        - name: page
          in: query
          description: Page number for pagination.
          schema:
            type: integer
            default: 1
            example: 1
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with sundown digest
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
  /account/tickersdbv2:
    get:
      summary: Get Supported Tickers Database
      operationId: getSupportedTickers
      description: >-
        Retrieve the full database of supported cryptocurrency tickers
        available in the API.
      tags:
        - Account
      parameters:
        - name: token
          in: query
          required: true
          description: API authentication token.
          schema:
            type: string
      responses:
        '200':
          description: Successful response with supported tickers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TickersDbResponse'
        '401':
          description: Unauthorized - invalid or missing token
        '429':
          description: Rate limit exceeded
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: query
      name: token
      description: API key passed as a query parameter named 'token'
  schemas:
    NewsArticle:
      type: object
      description: A cryptocurrency news article
      properties:
        news_url:
          type: string
          format: uri
          description: URL of the original news article
        image_url:
          type: string
          format: uri
          description: URL of the article's featured image
        title:
          type: string
          description: Headline title of the news article
        text:
          type: string
          description: Summary or excerpt text of the article
        source_name:
          type: string
          description: Name of the news source
        date:
          type: string
          description: Publication date and time of the article
        topics:
          type: array
          items:
            type: string
          description: List of topics associated with the article
        sentiment:
          type: string
          enum:
            - Positive
            - Negative
            - Neutral
          description: AI-computed sentiment classification for the article
        type:
          type: string
          description: Type of news content (article, video, etc.)
        tickers:
          type: array
          items:
            type: string
          description: Cryptocurrency tickers mentioned in the article
    NewsResponse:
      type: object
      description: Response containing a list of cryptocurrency news articles
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
        total_pages:
          type: integer
          description: Total number of pages available
        count:
          type: integer
          description: Total count of articles available
    HeadlinesResponse:
      type: object
      description: Response containing trending headline articles
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
        total_pages:
          type: integer
          description: Total number of pages available
    TopMentionResponse:
      type: object
      description: Response containing top mentioned tickers
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              ticker:
                type: string
                description: Cryptocurrency ticker symbol
              mention_count:
                type: integer
                description: Number of times mentioned in the time period
              sentiment_score:
                type: number
                description: Average sentiment score for mentions
    StatResponse:
      type: object
      description: Response containing sentiment analysis statistics
      properties:
        data:
          type: array
          items:
            type: object
            properties:
              date:
                type: string
                description: Date for the stat entry
              positive:
                type: integer
                description: Count of positive sentiment articles
              negative:
                type: integer
                description: Count of negative sentiment articles
              neutral:
                type: integer
                description: Count of neutral sentiment articles
              ticker:
                type: string
                description: Ticker symbol if filtered by ticker
    TickerPrice:
      type: object
      description: Delayed price data for a single cryptocurrency ticker
      properties:
        ticker:
          type: string
          description: Cryptocurrency ticker symbol
        price:
          type: number
          description: Current delayed price in USD
        price_change_percentage_24h:
          type: number
          description: Percentage price change over last 24 hours
        market_cap:
          type: number
          description: Market capitalization in USD
        volume_24h:
          type: number
          description: 24-hour trading volume in USD
    TickerPriceResponse:
      type: object
      description: Response containing delayed ticker prices
      properties:
        data:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/TickerPrice'
          description: Map of ticker symbol to price data
    WhaleTransaction:
      type: object
      description: A large on-chain cryptocurrency transaction
      properties:
        id:
          type: string
          description: Unique identifier for the transaction
        blockchain:
          type: string
          description: Blockchain network the transaction occurred on
        symbol:
          type: string
          description: Cryptocurrency ticker symbol
        transaction_type:
          type: string
          description: Type of transaction (transfer, exchange deposit, etc.)
        from:
          type: string
          description: Sender address or label
        to:
          type: string
          description: Recipient address or label
        amount:
          type: number
          description: Transaction amount in crypto units
        amount_usd:
          type: number
          description: Transaction amount in USD
        timestamp:
          type: integer
          description: Unix timestamp of the transaction
    WhaleTransactionsResponse:
      type: object
      description: Response containing whale transactions
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/WhaleTransaction'
        count:
          type: integer
          description: Total number of transactions returned
    WhaleSummaryResponse:
      type: object
      description: Summary of whale transaction activity
      properties:
        data:
          type: object
          properties:
            total_transactions:
              type: integer
              description: Total number of whale transactions in the period
            total_volume_usd:
              type: number
              description: Total USD volume of whale transactions
            largest_transaction_usd:
              type: number
              description: Largest single transaction amount in USD
            exchange_inflow_usd:
              type: number
              description: Total USD value moving to exchanges
            exchange_outflow_usd:
              type: number
              description: Total USD value moving from exchanges
    CryptoEvent:
      type: object
      description: A scheduled cryptocurrency event
      properties:
        id:
          type: string
          description: Unique identifier for the event
        title:
          type: string
          description: Title of the event
        description:
          type: string
          description: Description of the event
        date:
          type: string
          description: Date of the event
        tickers:
          type: array
          items:
            type: string
          description: Related cryptocurrency tickers
        source:
          type: string
          description: Source of the event information
    EventsResponse:
      type: object
      description: Response containing cryptocurrency events
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/CryptoEvent'
        total_pages:
          type: integer
          description: Total number of pages available
    TickerInfo:
      type: object
      description: Information about a supported cryptocurrency ticker
      properties:
        ticker:
          type: string
          description: Cryptocurrency ticker symbol
        name:
          type: string
          description: Full name of the cryptocurrency
        logo:
          type: string
          format: uri
          description: URL of the cryptocurrency logo
    TickersDbResponse:
      type: object
      description: Response containing the supported tickers database
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/TickerInfo'
          description: List of all supported cryptocurrency tickers