# AI Agent APIs

### Overview

The AI Agent API provides endpoints to retrieve information about AI agents based on their blockchain address and chain ID. It also allows fetching a list of all AI agents stored in the system.

### Endpoints

#### **Create a New AI Agent**

* **Endpoint:** `POST /agent/new`
* **Authentication:** Required (`Bearer Token`)
* **Middleware:** `chainAuth`, `auth`
* **Description:** Creates a new AI agent with market and social data.
* **Request Body:**

  ```json
  {
    "address": "string", 
    "chain": "string",
    "logo": "string",
    "name": "string",
    "desc": "string",
    "link": {},
    "twitterUsername": "string"
  }
  ```
* **Responses:**
  * `200 OK`: Agent created successfully.
  * `403 Forbidden`: Missing parameters, agent already exists, or market info/social data retrieval failure.
  * `500 Internal Server Error`: Unexpected server error.

***

#### **Modify an AI Agent**

* **Endpoint:** `POST /agent/modify`
* **Authentication:** Required (`Bearer Token`)
* **Middleware:** `auth`
* **Description:** Updates an existing AI agent's details, including chain, social stats, and market info.
* **Request Body:**

  ```json
  {
    "id": "string",
    "address": "string",
    "chain": "string",
    "logo": "string",
    "name": "string",
    "desc": "string",
    "link": {},
    "twitterUsername": "string"
  }
  ```
* **Responses:**
  * `200 OK`: Agent modified successfully.
  * `403 Forbidden`: Missing parameters, invalid chain, or social/market data not found.
  * `500 Internal Server Error`: Unexpected server error.

***

#### **Delete an AI Agent**

* **Endpoint:** `POST /agent/delete`
* **Authentication:** Required (`Bearer Token`)
* **Middleware:** `auth`
* **Description:** Deletes an AI agent from the system.
* **Request Body:**

  ```json
  {
    "id": "string"
  }
  ```
* **Responses:**
  * `200 OK`: Agent deleted successfully.
  * `403 Forbidden`: Agent not found or missing parameters.
  * `500 Internal Server Error`: Unexpected server error.

***

Let me know if you need more refinements! 🚀

#### Get AI Agent Information

**Endpoint:**

```
GET /agent/:chain/:address
```

**Description:** Retrieves short information about a specific AI agent based on the provided blockchain chain ID and address.

**Parameters:**

| Parameter | Type     | Required | Description                                                                                 |
| --------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
| `chain`   | `int`    | Yes      | The blockchain chain ID (e.g., Ethereum(1),Solana(800), Binance Smart Chain(56), Base(8453) |
| `address` | `string` | Yes      | The AI agent's contract address on the blockchain                                           |

**Success Response:**

```json
{
  "status": "success",
  "data": {
    "address": "0x12345...",
    "name": {
      "short": "AgentX",
      "long": "AgentX AI"
    },
    "symbol": "AGX",
    "decimal": 18,
    "logo": {
      "small": "https://example.com/small-logo.png",
      "big": "https://example.com/big-logo.png"
    },
    "totalSupply": "1000000000",
    "description": "A powerful AI agent on the blockchain",
    "coingecko_url": "https://coingecko.com/en/coins/agentx",
    "chain": 1
  }
}
```

**Error Responses:**

* `403 Forbidden`: Invalid agent address or missing parameters
* `500 Internal Server Error`: Unexpected server failure

***

Get All AI Agents

**Endpoint:**

```
GET /agent/all
```

**Description:** Retrieves a list of all AI agents stored in the system.

**Success Response:**

```json
{
  "data": [
    {
      "id": "123",
      "chain": 1,
      "address": "0x12345...",
      "logo": "https://example.com/logo.png",
      "name": "AgentX",
      "desc": "A cutting-edge AI agent",
      "link": "https://example.com",
      "twitter": "@agentx",
      "market": "CoinGecko",
      "social": {
        "telegram": "t.me/agentx",
        "discord": "discord.gg/agentx"
      },
      "socialStats": 5000
    }
  ]
}
```

**Error Responses:**

* `500 Internal Server Error`: Unexpected server failure

#### Get AI Agent Information

**Endpoint:** `GET /agent/:chain/:address`

**Description:** Retrieves short information about a specific AI agent based on its chain and address.

**Response:**

* Success: `{ status: 'success', data: { agent details } }`
* Error: `{ status: 'error', msg: 'Invalid agent address' }`

***

#### Get All AI Agents

**Endpoint:** `GET /agent/all`

**Description:** Retrieves information about all AI agents.

**Response:**

* Success: `{ data: [ array of agent objects ] }`
* Error: `{ status: 'error', msg: 'Internal Server Error' }`

***

#### Get Top AI Agents

**Endpoint:** `GET /agent/top`

**Description:** Retrieves the top AI agents based on market cap or price.

**Query Parameters:**

* `no` (default: `100`): Number of top agents to return.
* `type` (default: `market`): Sorting criteria (`market` for market cap, `price` for price).

**Response:**

* Success:`{ data: [ array of top agents ] }`
* Error: `{ status: 'error', msg: 'Missing parameters' }`

***

#### Get AI Agents Statistics

**Endpoint:** `GET /agent/stats`

**Description:** Retrieves statistics on AI agents, including dominance by chain, market cap, social engagement, impressions, and average impressions.

**Response:**

* Success: `{ chains, market, totalMarketCap, smartEngagements, impression, avrImpression }`
* Error: `{ status: 'error', msg: 'Internal Server Error' }`

***

#### Get Specific AI Agent Details

**Endpoint:** `GET /agent/:id`

**Description:** Retrieves detailed information about a specific AI agent by its ID.

**Response:**

* Success: `{ status: 'success', agent }`
* Error: `{ status: 'error', msg: 'Agent not found' }`

***

### Error Handling

* `403 Forbidden`: Missing or invalid parameters.
* `500 Internal Server Error`: Unexpected server errors.


---

# 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://coat.gitbook.io/paal-ai-apis/paal-ai-api-docs/ai-agent-apis.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.