# AI Signal API Reference (API)

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](https://app.chaingpt.org/apidashboard) 
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:

```js
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:

```json5
{
 "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:

```json
{
 "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

```json
[
 { "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

```json
[
 { "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

```json
{
 "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

```javascript
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

```javascript
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

```javascript
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.

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

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

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.