API Reference

AI News Generator API Reference

Introduction

ChainGPT’s AI News Generator API is a RESTful service that allows developers to integrate AI-generated crypto news into their applications, platforms, or services. It is designed for software engineers and system integrators who need real-time blockchain and crypto news updates, enabling them to build intelligent, up-to-date interfaces with ease. This documentation focuses on the API endpoints (not the SDK or RSS feeds) and covers usage, parameters, and response formats to streamline development.

Before using the API, ensure you have the following prerequisites:

A development environment (e.g. Node.js, an IDE)
A ChainGPT API key (obtained from the ChainGPT web app)
Sufficient API credits in your ChainGPT account (credits are required to make API calls)

Authentication

All requests to the AI News API must be authenticated with an API key. You can generate an API key by logging into the ChainGPT web application and navigating to the API Dashboard. Use the "Create Secret Key" feature to create a new key, and copy it for use in your application. Keep your API key secure – do not hard-code it in public code repositories. It’s recommended to store it in an environment variable or a secret management service to avoid exposure.

Using the API Key: Include the API key in your request headers as a Bearer token. For example:

Authorization: Bearer <YOUR_API_KEY>

This header must be sent with each API request. The API expects requests and responses in JSON format, so ensure you set the Content-Type: application/json header in requests where you send a body (for GET requests, this is not required but including it does no harm).

Axios Configuration

If you are using Axios (a popular HTTP client for Node.js/JavaScript) to interact with the API, you can set up a reusable Axios instance with the base URL and authorization header configured. This will simplify making multiple requests. For example:

import axios from 'axios';

const instance = axios.create({
  baseURL: 'https://api.chaingpt.org',
  timeout: 60000,  // 60 seconds timeout
  headers: {
    Authorization: `Bearer ${process.env.CHAINGPT_API_KEY}`, 
    'Content-Type': 'application/json'
  }
});

In the above configuration, replace process.env.CHAINGPT_API_KEY with your API key (or an environment variable containing it). The base URL for all AI News API endpoints is https://api.chaingpt.org, and we include the Authorization header by default on all requests. Using an Axios instance is optional, but it helps by not repeating the base URL and headers for each call.

Available Endpoint(s)

The AI News Generator API currently provides one endpoint:

`GET /news`

Retrieves AI-generated news articles. Without any query parameters, this endpoint returns the latest AI news across all categories. Developers can optionally filter the news by various criteria to tailor the results. The supported filters (as query parameters) include:

Category – filter news by high-level topic/category (e.g. NFT, DeFi, Blockchain Gaming, etc.)
Sub-Category – filter news by blockchain ecosystem or network (e.g. Bitcoin, Ethereum, Solana, etc.)
Search Query – search terms to match in the news title or description
Token – filter news related to specific cryptocurrencies or tokens (e.g. Bitcoin, BNB, Ethereum)
Date – fetch news published after a certain date
Sorting – specify sorting by publication date (newest first)

This endpoint is designed to be flexible. You can fetch all recent news or narrow down results using any combination of the above filters. All filters are provided as query parameters in the GET request. The next section details each available query parameter.

Parameters

All query parameters for the GET /news endpoint are optional. If no parameters are specified, the API will return a default set of recent news (by default, the 10 latest articles). You can use one or many parameters to filter the results. Below is a list of all supported query parameters:

Parameter

Type

Description

categoryId

integer or array of integers

Optional. Filter news by one or more category IDs. Only news belonging to the specified category(s) will be returned. For example, categoryId=5 would retrieve news in the DeFi category. You can specify multiple categories by providing an array of IDs (e.g. categoryId=[5,8] to get news tagged as DeFi or NFT). See the Category IDs Reference below for the list of categories and their IDs.

subCategoryId

integer or array of integers

Optional. Filter news by one or more sub-category IDs. Sub-categories typically correspond to blockchain ecosystems or networks. For example, subCategoryId=14 filters news related to Cosmos. Multiple sub-categories can be specified (e.g. subCategoryId=[14,22] for Cosmos or Solana news). See Sub-Category IDs Reference below for all sub-category IDs.

tokenId

integer or array of integers

Optional. Filter news by specific token IDs. This narrows results to news articles that are related to particular cryptocurrencies/tokens (for example, Bitcoin, Ethereum, etc.). You can provide multiple tokens (e.g. tokenId=[79,80] for Bitcoin or Ethereum). Refer to Token IDs Reference below for supported token IDs.

searchQuery

string

Optional. Keyword search term to filter news by title or description. The API will return only news articles whose title or description contain the provided query string (case-insensitive). For example, searchQuery=upgrade would match news with "upgrade" in the title or body.

fetchAfter

date string

Optional. Only return news published after the specified date. The date should be in a recognizable format (e.g. YYYY-MM-DD or ISO 8601). For example, fetchAfter=2023-12-20 will fetch news published on or after December 20, 2023.

limit

integer

Optional. The maximum number of news articles to return. Defaults to 10 if not specified. You can use this to limit the size of the result set (e.g. limit=5 for five articles). Note that increasing this beyond 10 will increase the credit cost (see Pricing/Credits).

offset

integer

Optional. The number of items to skip (offset) before starting to return results. This is used for pagination along with limit. For example, offset=10&limit=10 would skip the first 10 results and return the next 10.

sortBy

string

Optional. Field by which to sort results. Currently, the only supported value is "createdAt", which sorts news by their creation/publish date. By default, news is sorted by newest first (most recent date).

Notes: All filters can be combined in a single request. For instance, you could request news in the NFT category about the Ethereum network by setting both categoryId and subCategoryId accordingly. If multiple filter parameters are provided, the news must satisfy all of them (logical AND). If an array of values is provided for a parameter, the filter will match any of those values (logical OR for the values of that field). For example, categoryId=[5,8] returns news that are in either DeFi or NFT categories.

Responses

A successful response from the GET /news endpoint returns a JSON object containing the news results. The response includes an array of news articles and possibly some pagination info. Each news article in the array has the following structure (fields):

id (integer): A unique identifier for the news article.
title (string): The headline or title of the news article.
description (string): A brief summary or excerpt of the news content. This provides a quick overview of the news.
categoryId (integer): The category ID associated with this news article (e.g., 5 for DeFi, 8 for NFT, etc.). This corresponds to one of the categories listed in the Category IDs reference table below. Use this to determine the high-level topic of the news.
subCategoryId (integer): The sub-category ID for the news, typically indicating a blockchain or ecosystem (e.g., 15 for Ethereum, 22 for Solana). This corresponds to one of the sub-categories listed in the reference table. If a news article is relevant to a specific blockchain or protocol, it will have the respective subCategoryId.
tokenId (integer or null): The token ID if the news is specifically about a certain cryptocurrency/token (e.g., 79 for Bitcoin). This corresponds to one of the token IDs in the reference table. If the news is of general interest and not focused on a particular token, this field may be null or omitted.
createdAt (string timestamp): The date and time when the news article was created/published. This timestamp is typically in ISO 8601 format (e.g., "2024-01-15T08:30:00Z"). You can use this to display the publication date or to sort articles by recency. (By default, results are already sorted by this field in descending order.)
imageUrl (url): The image in the news article.
pubDate (Date format): publish date of news article.
isPublished (booleon): News article is published or not.
categoryId (number): Category Id of news article.
subCategoryId (number): Sub CategoryId of news article.

The response may also include some metadata for pagination if you requested a non-default limit/offset. For example, it could include fields like total (total number of news articles available) or echo back the limit and offset you used. (Refer to the API's latest specification for exact response format; the core part is the array of news items described above.)

Example Response:

{
    "statusCode": 200,
    "message": "Request Successful",
    "data": [
        {
            "id": 17716,
            "title": "The Evolution of NFTs: From Speculation to Core Infrastructure",
            "description": "Some argue that NFTs are dead, while others await the return of the speculative art boom. However, the reality is different. NFTs are not obsolete or heading for another hype wave. Instead, they are transitioning into essential digital infrastructure supporting gaming, AI, and machine-driven applications. The shift towards NFT utility over speculation is evident, with growth in AI and social DApps leveraging NFTs for various purposes. NFTs were originally designed for digital ownership and programmable rights, not just for trading. As AI technology advances, NFTs are becoming integral as identity anchors and access credentials. They are already being used in various applications, from AI audits to certifying processes. NFTs are evolving into essential components in decentralized systems, supporting player-owned economies, AI agents, and machine-to-machine networks. The focus is shifting from front-end collectibles to back-end infrastructure, where NFTs play a crucial role in access control, data provenance, and interoperability.",
            "pubDate": "2025-06-11T02:00:04.000Z",
            "isPublished": true,
            "author": "Nova, ChainGPT's AI Agent",
            "userId": null,
            "isFeatured": 0,
            "categoryId": 8,
            "subCategoryId": 15,
            "isTopStory": 0,
            "viewsCount": 0,
            "imageUrl": "https://d2qsg582zx9qac.cloudfront.net/document/f5bbe15e-acc7-3d92-879e-bee0cc8c131f.jpg",
            "mediaId": 82706,
            "tokenId": 80,
            "createdAt": "2025-06-11T00:48:22.000Z",
            "updatedAt": "2025-06-11T09:26:52.000Z",
            "deletedAt": null,
            "category": {
                "id": 8,
                "name": "NFT",
                "isBlockchain": false,
                "isToken": false,
                "createdAt": "2023-05-22T10:08:26.000Z",
                "updatedAt": "2023-05-22T10:08:26.000Z",
                "deletedAt": null
            },
            "subCategory": {
                "id": 15,
                "name": "Ethereum",
                "isBlockchain": true,
                "isToken": false,
                "createdAt": "2023-05-22T10:08:26.000Z",
                "updatedAt": "2023-05-22T10:08:26.000Z",
                "deletedAt": null
            },
            "token": {
                "id": 80,
                "name": "Ethereum - ETH",
                "isBlockchain": false,
                "isToken": true,
                "createdAt": "2023-10-16T12:59:10.000Z",
                "updatedAt": "2023-10-16T12:59:10.000Z",
                "deletedAt": null
            },
            "newsTags": [],
            "media": {
                "id": 82706,
                "fileName": "f5bbe15e-acc7-3d92-879e-bee0cc8c131f.jpg",
                "fileDescriptor": "document/f5bbe15e-acc7-3d92-879e-bee0cc8c131f.jpg",
                "mimeType": "image/jpeg",
                "fileSize": 1536,
                "createdAt": null,
                "updatedAt": null,
                "deletedAt": null
            }
        }
    ]
}

Usage Examples

Below are examples of how to use the GET /news endpoint with various tools.

Using cURL

You can test the API quickly using the command-line tool cURL. Make sure to replace YOUR_API_KEY with your actual API key. For example, to fetch the latest 5 news articles in the NFT category, you could use:

curl -X GET "https://api.chaingpt.org/news?categoryId=8&limit=5" \
     -H "Authorization: Bearer YOUR_API_KEY"

This will make a GET request to the /news endpoint, filtering results to category ID 8 (which is NFT). The Authorization header is included with the Bearer token. The response will be a JSON with up to 5 NFT-related news items.

Using Axios (JavaScript/Node.js)

In a Node.js environment, using Axios, you can call the API as follows. This example assumes you've configured the Axios instance as shown in the Axios Configuration section above:

// Fetch latest news about Ethereum in the NFT category (for example)
async function fetchNews() {
  try {
    const response = await instance.get('/news', {
      params: {
        categoryId: [8],        // NFT category
        subCategoryId: [15],    // Ethereum blockchain
        searchQuery: 'upgrade', // keyword to search in title/description
        limit: 5,               // limit to 5 results
        sortBy: 'createdAt'     // sort by newest
      }
    });
    console.log(response.data);
  } catch (error) {
    console.error(error);
  }
}

fetchNews();

In this Axios example, we use an instance.get call to '/news' with a params object. We filter for news in category ID 8 (NFT) that are related to sub-category ID 15 (Ethereum network), and contain the word "upgrade". We limit to 5 articles and explicitly sort by creation date (newest first). The API key is automatically attached via the Axios instance configuration. The response.data will contain the JSON response (as described in the Responses section above), which we then log to the console.

Handling Errors

If the API key is missing or invalid, or if your credits are insufficient, the API will return an error (HTTP 4xx status). Make sure to catch errors in your code. For instance, in the Axios example above, if an error occurs, it will be caught in the catch block and logged. The error message can help identify issues like authentication failures or invalid parameters. Always ensure your API key is correct and that you have enough credits for the call.

Credits and Pricing

ChainGPT’s AI News API uses a credit-based pricing system. You must have credits available in your ChainGPT account to make API calls. Each request to the /news endpoint will deduct credits from your balance. By default, 1 credit is deducted per API call that fetches up to 10 news articles. This means if you use the default limit (which is 10), the call will cost 1 credit.

If you increase the limit to retrieve more than 10 articles in one call, the credit cost scales proportionally. Specifically, 1 credit is charged per 10 results. For example:

limit=10 (or not specifying a limit, which defaults to 10) – costs 1 credit.
limit=20 – costs 2 credits (since 20 results are fetched, equivalent to 2 batches of 10).
limit=25 – costs 3 credits (the first 20 results cost 2 credits, and the additional 5 results consume another credit, as any fraction beyond each 10 results counts as a new block of 10).

The credit deduction happens per request, regardless of filters. If you make multiple requests, each will consume credits according to the number of news items requested. Ensure you have a sufficient credit balance before making calls (you can obtain and top-up credits via the ChainGPT web app).

Note: Generating an API key requires that you have credits in your account in the first place. If you need to increase your usage beyond the included or purchased credits, consider reviewing ChainGPT’s pricing plans or contacting the ChainGPT team for higher-volume access. Always monitor your credit usage to avoid interruptions.

Category IDs Reference

When filtering news by category (using categoryId), use the following IDs which correspond to various high-level news topics/categories:

Category Name

Category Name

DAO

DApps

DeFi

Lending

Metaverse

NFT

Stablecoins

Cryptocurrency

Decentralized

Smart Contracts

Distributed Ledger

Cryptography

Digital Assets

Tokenization

Consensus Mechanisms

ICO (Initial Coin Offering)

Crypto Wallets

Web3.0

Interoperability

Mining

Cross-Chain Transactions

Exchange

Use these IDs with the categoryId parameter to filter news. For example, categoryId=8 will retrieve news categorized as NFT. If you want multiple categories, you can specify an array of IDs, e.g., categoryId=[5,8] for news that are in DeFi or NFT categories.

Sub-Category IDs Reference

Sub-categories usually represent specific blockchain networks or ecosystems. The table below lists all sub-category IDs that can be used with the subCategoryId parameter:

Sub-Category (Blockchain)

Bitcoin

BNB Chain

Celo

Cosmos

Ethereum

Fantom

Flow

Litecoin

Monero

Polygon

XRP Ledger

Solana

Tron

Terra

Tezos

WAX

algorand

arbitrum

astar

aurora

avalanche

base

binance-smart-chain

cardano

celo

cronos

moonbeam

dep

ethereum

fantom

harmony

oasis

oasis-sapphire

ontology

optimism

other

platon

polygon

rangers

ronin

shiden

skale

solana

stacks

stargaze

steem

sxnetwork

telos

telosevm

tezos

theta

thundercore

Use these IDs with subCategoryId to filter news for specific blockchains. For example, subCategoryId=11 will filter news related to Bitcoin. You can specify multiple sub-categories; for instance, subCategoryId=[11,22] will get news about either Bitcoin or Solana.

Note: Some blockchain names appear twice with different IDs (for example, Ethereum appears as ID 15 and also as ID 39 in this list, likewise Celo as 13 and 35, etc.). This is due to how the categories are defined in the system. In practice, you should use the ID that appears in the news data you receive. The higher-numbered duplicate entries exist for legacy or internal reasons. For instance, you may see news items tagged with subCategoryId 15 for Ethereum in some cases and 39 in others. Both refer to Ethereum-related news. Similarly, BNB Chain (ID 12) and Binance Smart Chain (ID 33) refer to the same network (Binance Chain), with ID 33 being the older nomenclature. It’s recommended to filter using both IDs if in doubt, or prefer the primary name’s ID.

Token IDs Reference

When filtering by specific tokens or cryptocurrencies using the tokenId parameter, use the following token IDs. These represent popular cryptocurrencies by name and symbol:

Token Name

Symbol

Bitcoin

BTC

Ethereum

ETH

Tether USD₮

USDT

BNB (Binance Coin)

BNB

XRP

USD Coin

USDC

Solana

SOL

Cardano

ADA

Dogecoin

DOGE

TRON

TRX

Toncoin

TON

Dai

DAI

Polygon

MATIC

Polkadot

DOT

Litecoin

LTC

Wrapped Bitcoin

WBTC

Bitcoin Cash

BCH

Chainlink

LINK

Shiba Inu

SHIB

UNUS SED LEO

LEO

TrueUSD

TUSD

Avalanche

AVAX

100

Stellar

XLM

101

Monero

XMR

102

OKB

103

Cosmos

ATOM

104

Uniswap

UNI

105

Ethereum Classic

ETC

106

BUSD (Binance USD)

BUSD

107

Hedera

HBAR

108

Use these token IDs with the tokenId query parameter to filter news about a specific cryptocurrency. For example, tokenId=79 will retrieve news related to Bitcoin (BTC). You can specify multiple tokens as well (e.g., tokenId=[79,80] for news about Bitcoin or Ethereum).

Each news article that is specifically about a certain token will include a tokenId field in its response data. If an article doesn’t have an associated token (i.e., it’s more general news or related to a blockchain rather than a specific coin), the tokenId might be null or omitted. The token IDs above cover many of the top crypto assets.

By using the above reference tables in conjunction with the query parameters, developers can precisely query the AI News Generator API for the news content that matters to their use case. The API is designed to be flexible and developer-friendly, following patterns similar to other modern APIs. For more information, support, or to manage your API usage and credits, visit the ChainGPT web app or developer documentation pages. Happy building!

Last updated 17 days ago

Was this helpful?