GET
/
v1
/
tokenomics
/
market-summary
/
{address}
curl --request GET \
  --url https://public.believe.app/v1/tokenomics/market-summary/{address} \
  --header 'x-believe-api-key: <api-key>' \
  --header 'x-idempotency-key: <x-idempotency-key>'
{
  "marketCap": 123,
  "liquidity": 123,
  "price": 123,
  "totalSupply": 123,
  "circulatingSupply": 123,
  "address": "<string>",
  "holder": 123
}

​
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

FieldTypeRequiredDescription
addressstringYesThe 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:

FieldTypeDescription
marketCapnumberThe total market capitalization of the token.
liquiditynumberThe current liquidity available for the token.
pricenumberThe current price of the token.
totalSupplynumberThe total supply of tokens that have been created.
circulatingSupplynumberThe number of tokens that are currently in circulation.
addressstringThe token address that was queried.
holdernumberThe total number of holders of this token.

​
Example Response (Success)

{
  "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 CodeDescription
ERR_PRICE_TOKENS_NOT_FOUNDThe 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):

{
  "error": "ERR_PRICE_TOKENS_NOT_FOUND",
  "message": "Token market data not available"
}

Authorizations

​
x-believe-api-key
string
header
required

Headers

​
x-idempotency-key
string
required

A unique key generated by the client to ensure a request is processed at most once.

Path Parameters

​
address
string
required

The token address for which to retrieve market summary data.

Response

200
application/json

Successful market summary retrieval.

The response is of type object.