AI Signal API Reference (API)

The ChainGPT AI Signal API is a RESTful service that provides AI-generated crypto trading signals, enabling developers to access real-time market sentiment, on-chain events, and token-level intelligen

The API is designed for software engineers and system integrators who need programmatic access to structured signal data, including:

• Bullish, bearish, and neutral sentiment classifications

• Signal tags and narratives

• Market and price context

• Historical chart data

Using this API, developers can build:

• Trading dashboards

• Alerting systems

• Analytics platforms

• AI-driven trading tools

• Market intelligence applications

This documentation covers the API endpoints directly (not the SDK), including:

• Authentication

• Request formats

• Query parameters

• Response structures

• Pagination

• Credits and pricing

• Usage examples

---

Prerequisites

Before using the API, ensure you have the following:

• A development environment (e.g., Node.js, VS Code, WebStorm)

• A valid ChainGPT API key

• Sufficient API credits in your ChainGPT account

API keys can be generated through the ChainGPT web application.

---

Base URL

All AI Signal API endpoints use the following base URL:

https://api.chaingpt.org

---

Authentication

All requests to the AI Signal API must be authenticated using a Bearer token.

Generating an API Key

1. Log in to the ChainGPT web application

2. Navigate to the API Dashboard

3. Click Create Secret Key

4. Copy and securely store the generated key

Important: Never hard-code API keys in public repositories. Use environment variables or a secure secret management service.

---

Authorization Header

Include the API key in the request headers:

Authorization: Bearer <YOUR_API_KEY>

Required Headers

Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json

These headers must be included with every authenticated request.

---

Axios Configuration

If you are using Axios, you can create a reusable client instance:

import axios from 'axios';

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

---

Available Endpoints

Method	Endpoint	Description
POST	/ai-signal/details	Retrieve AI signals with optional filtering
GET	/ai-signal/tags	Retrieve available signal tags
GET	/ai-signal/narratives	Retrieve available signal narratives
GET	/ai-signal/chains	Retrieve available blockchain chains

---

POST /ai-signal/details

Retrieves AI-generated trading signals with complete metadata and filtering support.

Without any request body parameters, the endpoint returns the latest signals (default: 10).

This endpoint supports filtering by:

• Blockchain chain

• Search term

• Tags

• Narratives

• Sentiment

• CoinMarketCap ID

• Date range

---

Request Body

All fields are optional.

Field	Type	Description
chain	string[]	Filter by blockchain chain names. Partial matching supported. Example: ["Ethereum", "Polygon"]
search	string	Search signal titles using a case-insensitive partial match
tag	string[]	Filter by tag names. Partial matching supported
narrative	number[]	Filter by narrative IDs
cmcId	number	Filter by CoinMarketCap ID
from	number	Start timestamp (Unix seconds)
to	number	End timestamp (Unix seconds)
sentiment	string | string[]	Filter by "bullish", "bearish", or "neutral"

---

Query Parameters

Pagination parameters are passed in the URL query string.

Parameter	Type	Description
limit	integer	Maximum number of signals to return. Default: 10
offset	integer	Number of records to skip. Default: 0

Example

?limit=10&offset=20

---

Filtering Logic

AND Logic Between Fields

When multiple filters are combined, all conditions must match.

Example:

{
 "chain": ["Ethereum"],
 "sentiment": ["bullish"],
 "tag": ["defi"]
}

This returns signals that match:

• Ethereum

• Bullish sentiment

• DeFi tag

---

OR Logic Within Arrays

Array fields match any provided value.

Example:

{
 "sentiment": ["bullish", "neutral"]
}

This matches:

• Bullish signals

• Neutral signals

---

GET /ai-signal/tags

Returns a list of available tags associated with AI signals.

Tags are short descriptors such as:

• defi

• btc

• layer2

Use these values with the tag filter in POST /ai-signal/details.

---

Query Parameters

Parameter	Type	Description
search	string	Partial tag name search

---

Example Response

[
 { "id": 1, "name": "defi" },
 { "id": 2, "name": "btc" },
 { "id": 3, "name": "layer2" }
]

---

GET /ai-signal/narratives

Returns a list of market narratives associated with coins and signals.

Examples:

• AI Tokens

• Real World Assets

• Layer 2

Use the numeric id values returned by this endpoint in the narrative filter.

---

Query Parameters

Parameter	Type	Description
search	string	Partial narrative name search

---

Example Response

[
 { "id": 1, "name": "AI Tokens" },
 { "id": 5, "name": "Real World Assets" },
 { "id": 12, "name": "Layer 2" }
]

---

GET /ai-signal/chains

Returns a list of blockchain chains.

Without a search parameter, this endpoint returns only chains that currently have associated signals.

---

Query Parameters

Parameter	Type	Description
search	string	Partial chain name search

---

Example Response

[
 { "id": 1, "name": "Ethereum" },
 { "id": 2, "name": "BNB Chain" },
 { "id": 3, "name": "Polygon" }
]

---

Response Structure

POST /ai-signal/details Response

A successful response returns a paginated object containing signal records.

---

Signal Object

Field	Type	Description
id	string	Unique signal identifier
sentiment	string	"bullish", "bearish", or "neutral"
price	number	Token price in USD
marketCap	number	Market capitalization in USD
volume24h	number	24-hour trading volume
priceChange1h	number	1-hour price percentage change
fullyDilutedMarketCap	number	Fully diluted market cap
title	string	AI-generated signal headline
summary	string	AI-generated signal summary
recordedAt	string	ISO 8601 timestamp
coin	object	Coin metadata
tags	string[]	Associated tags
narratives	string[]	Associated narratives
graphData	object[]	Historical market data

---

Coin Object

Field	Type	Description
cmcId	number	CoinMarketCap ID
name	string	Token name
symbol	string	Token symbol
slug	string	URL-friendly slug
logo	string	Logo image URL

---

Pagination Metadata

Field	Type	Description
data	object[]	Signal records
total	number	Total matching records
limit	number	Applied limit
offset	number	Applied offset

---

Example Response

{
 "statusCode": 200,
 "message": "Request Successful",
 "data": {
   "data": [
     {
       "id": "a3f1c2d4-e5b6-7890-abcd-ef1234567890",
       "sentiment": "bullish",
       "price": 43250.75,
       "marketCap": 847392000000,
       "volume24h": 18500000000,
       "priceChange1h": 1.35,
       "fullyDilutedMarketCap": 908000000000,
       "title": "Bitcoin breaks key resistance level amid institutional accumulation",
       "summary": "On-chain data shows significant accumulation by large wallets as BTC pushes above the $43,000 resistance zone.",
       "recordedAt": "2024-01-15T08:30:00.000Z",
       "coin": {
         "cmcId": 1,
         "name": "Bitcoin",
         "symbol": "BTC",
         "slug": "bitcoin",
         "logo": "https://s2.coinmarketcap.com/static/img/coins/64x64/1.png"
       },
       "tags": ["btc", "resistance-break", "institutional"],
       "narratives": ["Store of Value", "Digital Gold"],
       "graphData": [
         {
           "time": "2024-01-15T07:00:00.000Z",
           "price": 42800.00,
           "volume": 18200000000
         }
       ]
     }
   ],
   "total": 142,
   "limit": 10,
   "offset": 0
 }
}

---

Usage Examples

Using cURL

Fetch Latest Bullish Ethereum Signals

curl -X POST "https://api.chaingpt.org/ai-signal/details?limit=5&offset=0" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "chain": ["Ethereum"],
      "sentiment": ["bullish"]
    }'

---

Fetch Available Tags

curl -X GET "https://api.chaingpt.org/ai-signal/tags" \
    -H "Authorization: Bearer YOUR_API_KEY"

---

Using Axios (Node.js)

Fetch Signals

async function fetchSignals() {
 try {
   const response = await instance.post(
     '/ai-signal/details',
     {
       chain: ['Ethereum', 'Polygon'],
       sentiment: ['bullish'],
       tag: ['defi'],
       from: 1700000000,
       to: 1701907200
     },
     {
       params: {
         limit: 10,
         offset: 0
       }
     }
   );


   console.log(response.data);
 } catch (error) {
   console.error(error);
 }
}


fetchSignals();

---

Fetch Available Chains

async function fetchChains() {
 try {
   const response = await instance.get('/ai-signal/chains');
   console.log(response.data);
 } catch (error) {
   console.error(error);
 }
}


fetchChains();

---

Error Handling

The API may return HTTP 4xx responses under the following conditions:

Status Code	Description
400 Bad Request	Invalid request body or parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Insufficient credits

---

Axios Error Handling Example

try {
const response = await instance.post('/ai-signal/details');
 console.log(response.data);
} catch (error) {
 if (error.response) {
   console.error(error.response.status);
   console.error(error.response.data);
 } else {
   console.error(error.message);
 }
}

---

Credits and Pricing

The AI Signal API uses a credit-based pricing model.

Credits are deducted based on the number of signals returned in the response.

---

Pricing Rule

1 Credit = Up to 10 Signals Returned

Credits are rounded up.

Formula

Credits = ceil(number_of_signals / 10)

---

Pricing Examples

Signals Returned	Credits Deducted
1 – 10	1 credit
11 – 20	2 credits
21 – 30	3 credits
N	⌈N / 10⌉ credits

---

Examples

• 8 signals → 1 credit

• 15 signals → 2 credits

• 25 signals → 3 credits

• 0 signals → 0 credits

Note: Lookup endpoints do not consume credits.

The following endpoints are free:

• /ai-signal/tags

• /ai-signal/narratives

• /ai-signal/chains

---

Sentiment Values Reference

Value	Description
"bullish"	Positive or upward momentum detected
"bearish"	Negative or downward momentum detected
"neutral"	No strong directional indication

---

Recommended Discovery Workflow

Before querying signals, use the lookup endpoints to discover valid filter values.

---

Step 1 — Fetch Chains

Use:

GET /ai-signal/chains

Purpose:

• Discover supported blockchains

• Retrieve valid chain filter values

---

Step 2 — Fetch Tags

Use:

GET /ai-signal/tags

Purpose:

• Discover available tags

• Retrieve valid tag filter values

---

Step 3 — Fetch Narratives

Use:

GET /ai-signal/narratives

Purpose:

• Discover narrative IDs

• Retrieve valid narrative filter values

---

Dynamic Documentation Querying

If additional information is needed beyond this document, the documentation supports dynamic querying through the ask query parameter.

---

Request Format

GET https://docs.chaingpt.org/dev-docs-b2b-saas-api-and-sdk/ai-signal-api/api-reference.md?ask=<question>

---

Example

GET https://docs.chaingpt.org/dev-docs-b2b-saas-api-and-sdk/ai-signal-api/api-reference.md?ask=How%20does%20pagination%20work?

---

When to Use Dynamic Queries

Use this mechanism when:

• Information is not explicitly documented

• Clarification is required

• Additional context is needed

• Related sections need to be retrieved dynamically

The response includes:

• A direct answer

• Relevant excerpts

• Related sources from the documentation

---

Conclusion

The ChainGPT AI Signal API provides structured, AI-powered crypto market intelligence through a flexible and developer-friendly REST interface.

By combining:

• Signal filters

• Market metadata

• Narratives

• Tags

• Sentiment analysis

• Historical graph data

developers can build advanced trading systems, analytics dashboards, and AI-driven market intelligence platforms efficiently and reliably.