# Get Token Overview

### Base URL

```
https://api.coinvera.io/api/v1/overview
```

***

### Authentication

Every request must include a valid API key in the headers. Without it, the API will return a `401 Unauthorized` error.

* **Header name:** `x-api-key`
* **Format:**

  ```
  x-api-key: YOUR_API_KEY_HERE
  ```

***

### Request Method

```
GET /api/v1/overview
```

***

### Query Parameters

| Parameter | Type   | Required | Description                                                            |
| --------- | ------ | -------- | ---------------------------------------------------------------------- |
| `ca`      | string | Yes      | SPL token mint address on Solana (the contract address for the token). |

* Example mint:

  ```
  So11111111111111111111111111111111111111112
  ```

***

**Code Example**

```javascript
const axios = require('axios');

const x_api_key = ""; 

const tokenAddresses = [
    ""
];

async function getOverview(ca) {
    try {
        const url = `https://api.coinvera.io/api/v1/overview?ca=${ca}`;
        const response = await axios.get(url, {
            headers: {
                "Content-Type": "application/json",
                "x-api-key": x_api_key,
            }
        });
        return { ca, ...response.data };
    } catch (err) {
        return { ca, error: err.message };
    }
}

async function getOverviewForAllTokens() {
    const results = await Promise.all(tokenAddresses.map(getOverview));
    results.forEach(res => {
        if (res.error) {
            console.log(`Error for ${res.ca}: ${res.error}`);
        } else {
            console.log(`Token: ${res.ca}`);
            console.log(res);
            console.log('-------------------------');
        }
    });
}

getOverviewForAllTokens();
```

### Example Response

A successful `200 OK` response returns a JSON object similar to the following. Actual values will vary by token.

```json
{
  "ca": "3VCkk4EVWQjCP8usuVK9ArfSmViFAcNcTMPivFJPpump",
  "name": "Jesse Pinkman",
  "symbol": "Pinkman",
  "image": "https://ipfs.io/ipfs/bafkreicr3t3bcwqvdeyshtrlhgxsfj3qphotlx2nz6ybrnkq2juluql3bu",
  "description": null,
  "socials": {
    "twitter": "https://x.com/i/communities/1930604634453750232",
    "website": "https://x.com/i/communities/1930604634453750232"
  },
  "decimals": "6",
  "supply": "999999885",
  "mintAuthority": null,
  "freezeAuthority": null,
  "updateAuthority": "TSLvdd1pWpHVjahSpsvCXUbgwsL3JAcvokwaKt1eokM",
  "creators": [
    {
      "address": "3Tx9rimPi7nwAyNqHB8U4JhdcaLdhpVLuN9uSENYWJoY",
      "verified": false,
      "share": "100"
    }
  ],
  "isToken2022": false,
  "top10HoldersBalance": "1422967.838701",
  "top10HoldersPercent": "0.14",
  "top20HoldersBalance": "1422976.395499",
  "top20HoldersPercent": "0.14",
  "dex": "PumpFun",
  "priceInSol": "0.000000028033304403000017",
  "priceInUsd": "0.000004247922989399055",
  "marketCap": "4247.922500887911"
}

```

### Response Field Descriptions

| Field                 | Type             | Description                                                                                                       |
| --------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `ca`                  | string           | SPL token mint address (identical to the `ca` query parameter).                                                   |
| `name`                | string           | Token’s registered name (if available).                                                                           |
| `symbol`              | string           | SPL token symbol (e.g., “USDC,” “RAY,” “Pinkman”).                                                                |
| `image`               | string (URL)     | URL to a hosted image (often IPFS). May be `null` if none is registered.                                          |
| `description`         | string or null   | Optional text description of the token.                                                                           |
| **`socials`**         | object           | Contains optional social or official links.                                                                       |
| `twitter`             | string (URL)     | Link to the token’s Twitter/X community or handle.                                                                |
| `website`             | string (URL)     | Token’s official website or landing page URL.                                                                     |
| `decimals`            | string (integer) | Number of decimal places. For example, if `decimals = "6"`, then a raw supply of `"100000000"` equals 100 tokens. |
| `supply`              | string           | Total minted supply in the smallest unit (raw integer). Divide by 10^`decimals` to get human-readable amount.     |
| `mintAuthority`       | string or null   | Public key with permission to mint new tokens. Shows `null` if no mint authority exists.                          |
| `freezeAuthority`     | string or null   | Public key that can freeze token accounts. `null` if no freeze authority is set.                                  |
| `updateAuthority`     | string           | Public key that can update on-chain metadata (for tokens using Metaplex metadata).                                |
| **`creators`**        | array            | List of creator entries (for tokens using Metaplex).                                                              |
| `address`             | string           | Creator’s public key.                                                                                             |
| `verified`            | boolean          | Whether the creator has been verified by Metaplex.                                                                |
| `share`               | string (integer) | Percentage of royalties (0–100) assigned to this creator.                                                         |
| `isToken2022`         | boolean          | Indicates if the token uses the Token 2022 standard (`true` or `false`).                                          |
| `top10HoldersBalance` | string (decimal) | Combined balance of the top 10 holders, in human units (after dividing by 10^`decimals`).                         |
| `top10HoldersPercent` | string (decimal) | Percentage of total supply held by the top 10 addresses.                                                          |
| `top20HoldersBalance` | string (decimal) | Combined balance of the top 20 holders, in human units.                                                           |
| `top20HoldersPercent` | string (decimal) | Percentage of total supply held by the top 20 addresses.                                                          |
| `dex`                 | string           | Primary DEX or liquidity source used for pricing (e.g., “Raydium,” “Serum,” “PumpFun,” etc.).                     |
| `priceInSol`          | string (decimal) | Current token price denominated in SOL. Multiply by 10^9 to convert to lamports if needed (1 SOL = 10⁹ lamports). |
| `priceInUsd`          | string (decimal) | Current token price in USD.                                                                                       |
| `marketCap`           | string (decimal) | Market capitalization in USD (circulating supply in human units × `priceInUsd`).                                  |

> **Note:** Many numeric values are returned as strings to preserve precision. Parse them carefully (e.g., `parseFloat(priceInUsd)`) and convert supply fields by dividing by 10^`decimals` for a human-readable amount.

***

### Error Responses

In case of an error—such as a missing parameter, invalid API key, or server issue—the API returns a non‐`200` status code with this structure:

```json
{
  "status": "error",
  "error": {
    "code": 400,
    "message": "Invalid request: missing required parameter 'ca'"
  }
}
```


---

# 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.coinvera.io/integration/solana/get-token-overview.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.