> ## Documentation Index
> Fetch the complete documentation index at: https://docs.believe.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Market Summary (Deprecated)

> This endpoint retrieves comprehensive market data for a specified token address including market cap, liquidity, price, and supply information.

<Warning>
  **Deprecated**: This endpoint is part of the deprecated tokenomics API. For new implementations, use the [Flywheel
  API](/api-reference/getting-started) which provides comprehensive tokenomic management. Market data functionality may be integrated into future
  Flywheel API versions.
</Warning>

## Overview

The Get Market Summary endpoint provides comprehensive market data for a specified token address. It returns real-time information including market capitalization, liquidity, current price, total supply, circulating supply, and holder count.

**NOTE**: This endpoint only works for /v1 tokens.

## Authentication

This endpoint requires API key authentication. The API key can have any scope.

To authenticate, provide your API key in the `x-believe-api-key` request header.

Example:
`x-believe-api-key: your_actual_api_key_here`

## Rate Limiting

Requests to this endpoint are rate-limited to 1 request every 2 seconds per API key.

## Idempotency

To prevent accidental duplicate operations, this endpoint supports idempotency via the `x-idempotency-key` header.

* **Header**: `x-idempotency-key`
* **Value**: A unique string (e.g., a UUID) generated by the client for each distinct operation.
* **Purpose**: If a request is retried (e.g., due to a network error) with the same `x-idempotency-key` as a previously successful request, the server should recognize it and not perform the operation a second time, instead returning the result of the original successful operation. This ensures that operations are processed at most once.

Example:
`x-idempotency-key: your_unique_generated_uuid_v4_here`

## Path Parameters

| Field     | Type   | Required | Description                                                  |
| --------- | ------ | -------- | ------------------------------------------------------------ |
| `address` | string | Yes      | The token address for which to retrieve market summary data. |

### Example Request

```
GET /v1/tokenomics/market-summary/So11111111111111111111111111111111111111112
```

## Response Body

On success, the API returns a JSON object with the following fields:

| Field               | Type   | Description                                             |
| ------------------- | ------ | ------------------------------------------------------- |
| `marketCap`         | number | The total market capitalization of the token.           |
| `liquidity`         | number | The current liquidity available for the token.          |
| `price`             | number | The current price of the token.                         |
| `totalSupply`       | number | The total supply of tokens that have been created.      |
| `circulatingSupply` | number | The number of tokens that are currently in circulation. |
| `address`           | string | The token address that was queried.                     |
| `holder`            | number | The total number of holders of this token.              |

### Example Response (Success)

```json theme={null}
{
  "marketCap": 1250000.5,
  "liquidity": 450000.25,
  "price": 0.125,
  "totalSupply": 10000000,
  "circulatingSupply": 8500000,
  "address": "So11111111111111111111111111111111111111112",
  "holder": 1542
}
```

### Functional Error Codes

Beyond authentication and rate limiting, the market summary endpoint can return specific error codes related to the market data retrieval operation itself. These are typically returned with a 404 Not Found status.

| Error Code                   | Description                                                                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ERR_PRICE_TOKENS_NOT_FOUND` | The token address provided could not be found or market data is not available for this token. Ensure the token address is correct and the token exists. |

When these errors occur, the API response will typically include the error code and a message providing more details, similar to the authentication error format.

Example (404 Not Found):

```json theme={null}
{
  "error": "ERR_PRICE_TOKENS_NOT_FOUND",
  "message": "Token market data not available"
}
```


## OpenAPI

````yaml GET /v1/tokenomics/market-summary/{address}
openapi: 3.1.0
info:
  title: OpenAPI Plant Store
  description: >-
    A sample API that uses a plant store as an example to demonstrate features
    in the OpenAPI specification
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://public.believe.app
security:
  - bearerAuth: []
paths:
  /v1/tokenomics/market-summary/{address}:
    get:
      tags:
        - Tokenomics
      summary: Get Market Summary
      description: >-
        This endpoint retrieves comprehensive market data for a specified token
        address including market cap, liquidity, price, and supply information.
      parameters:
        - name: address
          in: path
          description: The token address for which to retrieve market summary data.
          required: true
          schema:
            type: string
        - name: x-idempotency-key
          in: header
          description: >-
            A unique key generated by the client to ensure a request is
            processed at most once.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful market summary retrieval.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MarketSummaryResponse'
        '401':
          description: Unauthorized - API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found - Token address not found or market data not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
components:
  schemas:
    MarketSummaryResponse:
      type: object
      required:
        - marketCap
        - liquidity
        - price
        - totalSupply
        - circulatingSupply
        - address
        - holder
      properties:
        marketCap:
          type: number
          description: The total market capitalization of the token.
        liquidity:
          type: number
          description: The current liquidity available for the token.
        price:
          type: number
          description: The current price of the token.
        totalSupply:
          type: number
          description: The total supply of tokens that have been created.
        circulatingSupply:
          type: number
          description: The number of tokens that are currently in circulation.
        address:
          type: string
          description: The token address that was queried.
        holder:
          type: number
          description: The total number of holders of this token.
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-believe-api-key

````