Interaction

Connector page for the birdeye.so API.
Each endpoint is mapped and callable via a dedicated method.
Be sure to call an endpoint in line with the permissions of your API.

cyhole.birdeye.Birdeye

Birdeye(
    api_key: str | None = None,
    chain: str = BirdeyeChain.SOLANA.value,
)

Bases: Interaction

              flowchart TD
              cyhole.birdeye.Birdeye[Birdeye]
              cyhole.core.interaction.Interaction[Interaction]

                              cyhole.core.interaction.Interaction --> cyhole.birdeye.Birdeye
                


              click cyhole.birdeye.Birdeye href "" "cyhole.birdeye.Birdeye"
              click cyhole.core.interaction.Interaction href "" "cyhole.core.interaction.Interaction"
            

Class used to connect https://birdeye.so API. To have access Birdeye API (public or private) is required to have a valid API key.

Check https://docs.birdeye.so for all the details on the available endpoints.

Info

If the API key is not provided during the object creation, then it is automatically retrieved from ENV variable BIRDEYE_API_KEY.

Parameters:

Name	Type	Description	Default
api_key	str | None	specify the API key to use for the connection.	None
chain	str	identifier of the chain to use in all the requests. The supported chains are available on BirdeyeChain. Import them from the library to use the correct identifier.	BirdeyeChain.SOLANA.value

Example

import asyncio
from cyhole.birdeye import Birdeye

birdeye = Birdeye()

# Get current token list on Solana
# synchronous
response = birdeye.client.get_token_list()
print(f"Currently listed {len(response.data.tokens)} tokens on Solana")

# asynchronous
async def main() -> None:
    async with birdeye.async_client as client:
        response = await client.get_token_list()
        print(f"Currently listed {len(response.data.tokens)} tokens on Solana")

asyncio.run(main())

Raises:

Type	Description
MissingAPIKeyError	if no API Key was available during the object creation.

Source code in src/cyhole/birdeye/interaction.py

def __init__(self, api_key: str | None = None, chain: str = BirdeyeChain.SOLANA.value) -> None:

    # set API
    self.api_key = api_key if api_key is not None else os.environ.get("BIRDEYE_API_KEY")
    if self.api_key is None:
        raise MissingAPIKeyError("no API key is provided during object's creation.")

    # headers setup
    headers = {
        "X-API-KEY": self.api_key,
        "x-chain": chain
    }
    super().__init__(headers)
    self.headers: dict[str, str]

    # clients
    self.client = BirdeyeClient(self, headers = headers)
    self.async_client = BirdeyeAsyncClient(self, headers = headers)

    # API urls
    self.url_api_public = "https://public-api.birdeye.so/defi/"
    self.url_api_private = "https://public-api.birdeye.so/defi/"
    self.url_api_private_wallet = "https://public-api.birdeye.so/v1/wallet"
    self.url_api_token_v1 = "https://public-api.birdeye.so/token/v1/"
    self.url_api_holder_v1 = "https://public-api.birdeye.so/holder/v1/"
    self.url_api_utils_v1 = "https://public-api.birdeye.so/utils/v1/"
    return

_get_token_list

_get_token_list(
    sync: Literal[True],
    sort_by: str = BirdeyeSort.SORT_V24HUSD.value,
    order_by: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    min_liquidity: float | None = None,
    max_liquidity: float | None = None,
    ui_amount_mode: str | None = None,
) -> GetTokenListResponse

_get_token_list(
    sync: Literal[False],
    sort_by: str = BirdeyeSort.SORT_V24HUSD.value,
    order_by: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    min_liquidity: float | None = None,
    max_liquidity: float | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetTokenListResponse]

_get_token_list(
    sync: bool,
    sort_by: str = BirdeyeSort.SORT_V24HUSD.value,
    order_by: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    min_liquidity: float | None = None,
    max_liquidity: float | None = None,
    ui_amount_mode: str | None = None,
) -> (
    GetTokenListResponse
    | Coroutine[None, None, GetTokenListResponse]
)

This function refers to the PUBLIC API endpoint Token - List (V1) and is used to retrieve a ranked list of tokens on the selected chain, scored by the chosen metric (USD volume, market cap, 24h change, or liquidity). It is the legacy V1 listing endpoint: results are returned in a flat page of at most 50 entries and each row carries the core identity, price/liquidity, market cap and 24h volume fields that power Birdeye's public token discovery views.

Parameters:

Name	Type	Description	Default
sort_by	str	define the metric used to rank the returned tokens (e.g. USD volume in the last 24h, market cap, 24h change, or liquidity). The supported values are available on BirdeyeSort. Import them from the library to use the correct identifier.	BirdeyeSort.SORT_V24HUSD.value
order_by	str	define the order of the ranking (ascending or descending). The supported values are available on BirdeyeOrder. Import them from the library to use the correct identifier.	BirdeyeOrder.DESCENDING.value
offset	int | None	zero-based offset to use for pagination. Combined with limit it returns the [offset, offset + limit) slice of the ranking. Default behaviour: 0.	None
limit	int | None	number of records to return per page. The API caps this at 50; values above 50 are rejected by Birdeye. Default behaviour: 50.	None
min_liquidity	float | None	exclusive lower bound on the on-chain liquidity (USD) of returned tokens. Birdeye applies a default of 100 server-side when not provided.	None
max_liquidity	float | None	exclusive upper bound on the on-chain liquidity (USD) of returned tokens. If not provided, the API does not apply any upper bound.	None
ui_amount_mode	str | None	how to format scaled-UI-amount token figures on Solana. The supported values are available on BirdeyeUIAmountMode. Only applies on Solana; ignored on other chains. Default behaviour: scaled.	None

Returns:

Type	Description
GetTokenListResponse | Coroutine[None, None, GetTokenListResponse]	ranked list of tokens for the selected chain along with the snapshot timestamp.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_list(
    self,
    sync: bool,
    sort_by: str = BirdeyeSort.SORT_V24HUSD.value,
    order_by: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    min_liquidity: float | None = None,
    max_liquidity: float | None = None,
    ui_amount_mode: str | None = None
) -> GetTokenListResponse | Coroutine[None, None, GetTokenListResponse]:
    """
        This function refers to the **PUBLIC** API endpoint **[Token - List (V1)](https://docs.birdeye.so/reference/get-defi-tokenlist)** and is used
        to retrieve a ranked list of tokens on the selected chain, scored by the chosen metric
        (USD volume, market cap, 24h change, or liquidity). It is the legacy V1 listing endpoint:
        results are returned in a flat page of at most 50 entries and each row carries the core
        identity, price/liquidity, market cap and 24h volume fields that power Birdeye's public
        token discovery views.

        Parameters:
            sort_by: define the metric used to rank the returned tokens (e.g. USD volume in the
                last 24h, market cap, 24h change, or liquidity).
                The supported values are available on [`BirdeyeSort`][cyhole.birdeye.param.BirdeyeSort].
                Import them from the library to use the correct identifier.
            order_by: define the order of the ranking (ascending or descending).
                The supported values are available on [`BirdeyeOrder`][cyhole.birdeye.param.BirdeyeOrder].
                Import them from the library to use the correct identifier.
            offset: zero-based offset to use for pagination. Combined with `limit` it returns the
                `[offset, offset + limit)` slice of the ranking. Default behaviour: `0`.
            limit: number of records to return per page. The API caps this at `50`; values above
                `50` are rejected by Birdeye. Default behaviour: `50`.
            min_liquidity: exclusive lower bound on the on-chain liquidity (USD) of returned tokens.
                Birdeye applies a default of `100` server-side when not provided.
            max_liquidity: exclusive upper bound on the on-chain liquidity (USD) of returned tokens.
                If not provided, the API does not apply any upper bound.
            ui_amount_mode: how to format scaled-UI-amount token figures on Solana.
                The supported values are available on [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode].
                Only applies on Solana; ignored on other chains. Default behaviour: `scaled`.

        Returns:
            ranked list of tokens for the selected chain along with the snapshot timestamp.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # check param consistency
    BirdeyeSort.check(sort_by)
    BirdeyeOrder.check(order_by)
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    # set params
    url = self.url_api_public + "tokenlist"
    params = {
        "sort_by" : sort_by,
        "sort_type" : order_by,
        "offset" : offset,
        "limit": limit,
        "min_liquidity": min_liquidity,
        "max_liquidity": max_liquidity,
        "ui_amount_mode": ui_amount_mode
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetTokenListResponse, params = params)

_get_v3_token_list

_get_v3_token_list(
    sync: Literal[True],
    query: GetV3TokenListQuery | None = None,
) -> GetV3TokenListResponse

_get_v3_token_list(
    sync: Literal[False],
    query: GetV3TokenListQuery | None = None,
) -> Coroutine[None, None, GetV3TokenListResponse]

_get_v3_token_list(
    sync: bool, query: GetV3TokenListQuery | None = None
) -> (
    GetV3TokenListResponse
    | Coroutine[None, None, GetV3TokenListResponse]
)

This function refers to the PRIVATE API endpoint Token - List (V3) and is used to retrieve a paginated ranked list of tokens on the selected chain, with a much richer filter surface than the legacy V1 listing endpoint: callers can rank by any of the 46 metrics exposed on BirdeyeV3TokenListSortBy and restrict results by liquidity, market cap, FDV, holder count, recent-listing time, last-trade time and a wide range of per-window (1m..30d) volume, price-change and trade-count thresholds. Each entry returned by the endpoint mirrors the cyhole V3TokenListItem shape (identity, supply, liquidity, price, per-window aggregates).

Info

The endpoint is restricted by Birdeye to Solana, Base, BSC, Ethereum and Monad. Pagination must satisfy offset + limit <= 10000; each page is capped at 100 entries.

Parameters:

Name	Type	Description	Default
query	GetV3TokenListQuery | None	optional GetV3TokenListQuery instance holding the desired sort metric, sort direction, pagination cursor and filters. When None (or omitted) the call uses Birdeye's defaults — top 100 tokens sorted by liquidity descending.	None

Returns:

Type	Description
GetV3TokenListResponse | Coroutine[None, None, GetV3TokenListResponse]	paginated list of tokens decoded as GetV3TokenListResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_list(
    self,
    sync: bool,
    query: GetV3TokenListQuery | None = None
) -> GetV3TokenListResponse | Coroutine[None, None, GetV3TokenListResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - List (V3)](https://docs.birdeye.so/reference/get-defi-v3-token-list)** and is used
        to retrieve a paginated ranked list of tokens on the selected chain, with a much richer filter
        surface than the legacy V1 listing endpoint: callers can rank by any of the 46 metrics exposed
        on [`BirdeyeV3TokenListSortBy`][cyhole.birdeye.param.BirdeyeV3TokenListSortBy] and restrict
        results by liquidity, market cap, FDV, holder count, recent-listing time, last-trade time
        and a wide range of per-window (1m..30d) volume, price-change and trade-count thresholds.
        Each entry returned by the endpoint mirrors the cyhole [`V3TokenListItem`][cyhole.birdeye.schema.V3TokenListItem]
        shape (identity, supply, liquidity, price, per-window aggregates).

        !!! info
            The endpoint is restricted by Birdeye to Solana, Base, BSC, Ethereum and Monad. Pagination
            must satisfy `offset + limit <= 10000`; each page is capped at 100 entries.

        Parameters:
            query: optional [`GetV3TokenListQuery`][cyhole.birdeye.schema.GetV3TokenListQuery] instance
                holding the desired sort metric, sort direction, pagination cursor and filters. When
                `None` (or omitted) the call uses Birdeye's defaults — top 100 tokens sorted by liquidity
                descending.

        Returns:
            paginated list of tokens decoded as [`GetV3TokenListResponse`][cyhole.birdeye.schema.GetV3TokenListResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    if query is None:
        query = GetV3TokenListQuery()

    # check param consistency
    BirdeyeV3TokenListSortBy.check(query.sort_by)
    BirdeyeOrder.check(query.sort_type)
    if query.ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(query.ui_amount_mode)

    # set params - drop None values so we only send what was set
    url = self.url_api_public + "v3/token/list"
    params = {k: v for k, v in query.model_dump().items() if v is not None}

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetV3TokenListResponse, params = params)

_get_v3_token_list_scroll

_get_v3_token_list_scroll(
    sync: Literal[True],
    query: GetV3TokenListScrollQuery | None = None,
) -> GetV3TokenListScrollResponse

_get_v3_token_list_scroll(
    sync: Literal[False],
    query: GetV3TokenListScrollQuery | None = None,
) -> Coroutine[None, None, GetV3TokenListScrollResponse]

_get_v3_token_list_scroll(
    sync: bool,
    query: GetV3TokenListScrollQuery | None = None,
) -> (
    GetV3TokenListScrollResponse
    | Coroutine[None, None, GetV3TokenListScrollResponse]
)

This function refers to the PRIVATE API endpoint Token - List (V3) Scroll and is used to iterate through the full v3 token list using a server-issued opaque cursor instead of offset/limit pagination. Each call returns up to 5 000 token entries (vs the 100/page cap of the offset-based v3 list) and an next_scroll_id cursor; pass that cursor back as scroll_id on the next call to fetch the next batch of the same scroll session. Filters (liquidity, market cap, FDV, holder, recent listing time, per-window thresholds, ...) are honoured only on the first call (with scroll_id left to None) and ignored on continuation calls. Items share the V3TokenListItem shape used by the regular v3 list, with the additional creation_time field populated on scroll results.

Info

Birdeye enforces a hard cap of one active scroll_id per account per 30 seconds.

Parameters:

Name	Type	Description	Default
query	GetV3TokenListScrollQuery | None	optional GetV3TokenListScrollQuery instance. Leave None to start a fresh scroll with Birdeye's defaults (top 5 000 tokens by liquidity descending). To continue a previous scroll set query = GetV3TokenListScrollQuery(scroll_id = <previous next_scroll_id>).	None

Returns:

Type	Description
GetV3TokenListScrollResponse | Coroutine[None, None, GetV3TokenListScrollResponse]	scroll batch decoded as GetV3TokenListScrollResponse.
GetV3TokenListScrollResponse | Coroutine[None, None, GetV3TokenListScrollResponse]	Inspect data.next_scroll_id / data.has_next to decide whether to keep iterating.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_list_scroll(
    self,
    sync: bool,
    query: GetV3TokenListScrollQuery | None = None
) -> GetV3TokenListScrollResponse | Coroutine[None, None, GetV3TokenListScrollResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - List (V3) Scroll](https://docs.birdeye.so/reference/get-defi-v3-token-list-scroll)** and is used
        to iterate through the full v3 token list using a server-issued opaque cursor instead of
        offset/limit pagination. Each call returns up to 5 000 token entries (vs the 100/page cap
        of the offset-based v3 list) and an `next_scroll_id` cursor; pass that cursor back as
        `scroll_id` on the next call to fetch the next batch of the same scroll session. Filters
        (liquidity, market cap, FDV, holder, recent listing time, per-window thresholds, ...) are
        honoured only on the first call (with `scroll_id` left to `None`) and ignored on
        continuation calls. Items share the [`V3TokenListItem`][cyhole.birdeye.schema.V3TokenListItem]
        shape used by the regular v3 list, with the additional `creation_time` field populated
        on scroll results.

        !!! info
            Birdeye enforces a hard cap of one active `scroll_id` per account per 30 seconds.

        Parameters:
            query: optional [`GetV3TokenListScrollQuery`][cyhole.birdeye.schema.GetV3TokenListScrollQuery]
                instance. Leave `None` to start a fresh scroll with Birdeye's defaults (top 5 000
                tokens by liquidity descending). To continue a previous scroll set
                `query = GetV3TokenListScrollQuery(scroll_id = <previous next_scroll_id>)`.

        Returns:
            scroll batch decoded as [`GetV3TokenListScrollResponse`][cyhole.birdeye.schema.GetV3TokenListScrollResponse].
            Inspect `data.next_scroll_id` / `data.has_next` to decide whether to keep iterating.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    if query is None:
        query = GetV3TokenListScrollQuery()

    # check param consistency
    BirdeyeV3TokenListSortBy.check(query.sort_by)
    BirdeyeOrder.check(query.sort_type)
    if query.ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(query.ui_amount_mode)

    # set params - drop None values so we only send what was set
    url = self.url_api_public + "v3/token/list/scroll"
    params = {k: v for k, v in query.model_dump().items() if v is not None}

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetV3TokenListScrollResponse, params = params)

_get_v2_tokens_new_listing

_get_v2_tokens_new_listing(
    sync: Literal[True],
    time_to: int | None = None,
    limit: int | None = None,
    meme_platform_enabled: bool | None = None,
) -> GetV2TokensNewListingResponse

_get_v2_tokens_new_listing(
    sync: Literal[False],
    time_to: int | None = None,
    limit: int | None = None,
    meme_platform_enabled: bool | None = None,
) -> Coroutine[None, None, GetV2TokensNewListingResponse]

_get_v2_tokens_new_listing(
    sync: bool,
    time_to: int | None = None,
    limit: int | None = None,
    meme_platform_enabled: bool | None = None,
) -> (
    GetV2TokensNewListingResponse
    | Coroutine[None, None, GetV2TokensNewListingResponse]
)

This function refers to the PRIVATE API endpoint Token - New Listing and is used to retrieve a feed of tokens that Birdeye has just detected listings for on the selected chain, ordered most-recent first. It is the canonical way to discover freshly-launched tokens before they show up in the ranked token list, and powers Birdeye's "new pairs" UIs. The endpoint returns a single batch (no offset pagination); call it repeatedly with an updated time_to to walk further back in time.

Info

Available on every Birdeye chain except Sui. The meme_platform_enabled toggle is Solana-only.

Parameters:

Name	Type	Description	Default
time_to	int | None	optional unix-second cursor; when set Birdeye returns only listings observed at or before this timestamp. Default behaviour: most recent listings.	None
limit	int | None	number of records to return (1..20). Default behaviour: 10.	None
meme_platform_enabled	bool | None	when True includes listings detected on meme-coin launchpads such as pump.fun (Solana only). Default behaviour: False.	None

Returns:

Type	Description
GetV2TokensNewListingResponse | Coroutine[None, None, GetV2TokensNewListingResponse]	feed of newly-listed tokens decoded as GetV2TokensNewListingResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _get_v2_tokens_new_listing(
    self,
    sync: bool,
    time_to: int | None = None,
    limit: int | None = None,
    meme_platform_enabled: bool | None = None
) -> GetV2TokensNewListingResponse | Coroutine[None, None, GetV2TokensNewListingResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - New Listing](https://docs.birdeye.so/reference/get-defi-v2-tokens-new_listing)** and is used
        to retrieve a feed of tokens that Birdeye has just detected listings for on the selected
        chain, ordered most-recent first. It is the canonical way to discover freshly-launched
        tokens before they show up in the ranked token list, and powers Birdeye's "new pairs"
        UIs. The endpoint returns a single batch (no offset pagination); call it repeatedly with
        an updated `time_to` to walk further back in time.

        !!! info
            Available on every Birdeye chain except Sui. The `meme_platform_enabled` toggle is
            Solana-only.

        Parameters:
            time_to: optional unix-second cursor; when set Birdeye returns only listings observed at
                or before this timestamp. Default behaviour: most recent listings.
            limit: number of records to return (1..20). Default behaviour: `10`.
            meme_platform_enabled: when `True` includes listings detected on meme-coin launchpads
                such as pump.fun (Solana only). Default behaviour: `False`.

        Returns:
            feed of newly-listed tokens decoded as [`GetV2TokensNewListingResponse`][cyhole.birdeye.schema.GetV2TokensNewListingResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
    """
    url = self.url_api_public + "v2/tokens/new_listing"
    params = {
        "time_to": time_to,
        "limit": limit,
        "meme_platform_enabled": str(meme_platform_enabled).lower() if meme_platform_enabled is not None else None,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetV2TokensNewListingResponse, params = params)

_get_v2_markets

_get_v2_markets(
    sync: Literal[True],
    address: str,
    sort_by: str = BirdeyeV2MarketsSortBy.LIQUIDITY.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
) -> GetV2MarketsResponse

_get_v2_markets(
    sync: Literal[False],
    address: str,
    sort_by: str = BirdeyeV2MarketsSortBy.LIQUIDITY.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
) -> Coroutine[None, None, GetV2MarketsResponse]

_get_v2_markets(
    sync: bool,
    address: str,
    sort_by: str = BirdeyeV2MarketsSortBy.LIQUIDITY.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
) -> (
    GetV2MarketsResponse
    | Coroutine[None, None, GetV2MarketsResponse]
)

This function refers to the PRIVATE API endpoint Token - All Market List and is used to retrieve the list of markets (trading pairs) Birdeye knows for a given token, ranked by liquidity or 24h USD volume. Each entry describes the market address, its source (DEX/aggregator), the base/quote token identities, current liquidity, price, and 24h trade/volume/unique-wallet aggregates plus the percent change vs the previous 24h window. Useful when a caller wants to drill down from a token to where it actually trades.

Parameters:

Name	Type	Description	Default
address	str	contract address of the token whose markets must be listed.	required
sort_by	str	ranking metric. Pick one of the constants on BirdeyeV2MarketsSortBy.	BirdeyeV2MarketsSortBy.LIQUIDITY.value
sort_type	str	ascending or descending order. Pick one of the constants on BirdeyeOrder.	BirdeyeOrder.DESCENDING.value
offset	int | None	zero-based pagination offset. Default behaviour: 0.	None
limit	int | None	number of records to return (1..20). Default behaviour: 10.	None

Returns:

Type	Description
GetV2MarketsResponse | Coroutine[None, None, GetV2MarketsResponse]	paginated list of markets decoded as GetV2MarketsResponse,
GetV2MarketsResponse | Coroutine[None, None, GetV2MarketsResponse]	plus the total number of markets Birdeye tracks for the token in data.total.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v2_markets(
    self,
    sync: bool,
    address: str,
    sort_by: str = BirdeyeV2MarketsSortBy.LIQUIDITY.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None
) -> GetV2MarketsResponse | Coroutine[None, None, GetV2MarketsResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - All Market List](https://docs.birdeye.so/reference/get-defi-v2-markets)** and is used
        to retrieve the list of markets (trading pairs) Birdeye knows for a given token, ranked
        by liquidity or 24h USD volume. Each entry describes the market address, its source
        (DEX/aggregator), the base/quote token identities, current liquidity, price, and 24h
        trade/volume/unique-wallet aggregates plus the percent change vs the previous 24h window.
        Useful when a caller wants to drill down from a token to where it actually trades.

        Parameters:
            address: contract address of the token whose markets must be listed.
            sort_by: ranking metric. Pick one of the constants on
                [`BirdeyeV2MarketsSortBy`][cyhole.birdeye.param.BirdeyeV2MarketsSortBy].
            sort_type: ascending or descending order. Pick one of the constants on
                [`BirdeyeOrder`][cyhole.birdeye.param.BirdeyeOrder].
            offset: zero-based pagination offset. Default behaviour: `0`.
            limit: number of records to return (1..20). Default behaviour: `10`.

        Returns:
            paginated list of markets decoded as [`GetV2MarketsResponse`][cyhole.birdeye.schema.GetV2MarketsResponse],
            plus the total number of markets Birdeye tracks for the token in `data.total`.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    BirdeyeV2MarketsSortBy.check(sort_by)
    BirdeyeOrder.check(sort_type)

    url = self.url_api_public + "v2/markets"
    params = {
        "address": address,
        "sort_by": sort_by,
        "sort_type": sort_type,
        "offset": offset,
        "limit": limit,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetV2MarketsResponse, params = params)

_get_v3_token_meta_data

_get_v3_token_meta_data(
    sync: Literal[True], address: str
) -> GetV3TokenMetaDataResponse

_get_v3_token_meta_data(
    sync: Literal[True], address: list[str]
) -> GetV3TokenMetaDataMultipleResponse

_get_v3_token_meta_data(
    sync: Literal[False], address: str
) -> Coroutine[None, None, GetV3TokenMetaDataResponse]

_get_v3_token_meta_data(
    sync: Literal[False], address: list[str]
) -> Coroutine[
    None, None, GetV3TokenMetaDataMultipleResponse
]

_get_v3_token_meta_data(
    sync: bool, address: str | list[str]
) -> (
    GetV3TokenMetaDataResponse
    | GetV3TokenMetaDataMultipleResponse
    | Coroutine[None, None, GetV3TokenMetaDataResponse]
    | Coroutine[
        None, None, GetV3TokenMetaDataMultipleResponse
    ]
)

This function refers to the v3 Birdeye token-metadata endpoints Token - Metadata (Single) and Token - Metadata (Multiple). They return the lightweight identity payload for one or more tokens on the selected chain (address, symbol, name, decimals, logo URL and the free-form extensions bag of social links / CoinGecko id). This is the right call when a caller just needs to resolve a token address to a display name and icon without paying for the full Token - Overview payload.

The method is polymorphic: pass a single str address and the function routes to /defi/v3/token/meta-data/single, returning a GetV3TokenMetaDataResponse; pass a list[str] of addresses and it routes to /defi/v3/token/meta-data/multiple, returning a GetV3TokenMetaDataMultipleResponse whose data is a dict keyed by token address.

Parameters:

Name	Type	Description	Default
address	str | list[str]	a single token contract address (string) or a list of token contract addresses. The list flavour issues one HTTP call instead of N.	required

Returns:

Type	Description
GetV3TokenMetaDataResponse | GetV3TokenMetaDataMultipleResponse | Coroutine[None, None, GetV3TokenMetaDataResponse] | Coroutine[None, None, GetV3TokenMetaDataMultipleResponse]	metadata payload for the requested token(s); the concrete type depends on the input
GetV3TokenMetaDataResponse | GetV3TokenMetaDataMultipleResponse | Coroutine[None, None, GetV3TokenMetaDataResponse] | Coroutine[None, None, GetV3TokenMetaDataMultipleResponse]	cardinality (see above).

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_meta_data(
    self,
    sync: bool,
    address: str | list[str]
) -> (
    GetV3TokenMetaDataResponse
    | GetV3TokenMetaDataMultipleResponse
    | Coroutine[None, None, GetV3TokenMetaDataResponse]
    | Coroutine[None, None, GetV3TokenMetaDataMultipleResponse]
):
    """
        This function refers to the v3 Birdeye token-metadata endpoints **[Token - Metadata (Single)](https://docs.birdeye.so/reference/get-defi-v3-token-meta-data-single)**
        and **[Token - Metadata (Multiple)](https://docs.birdeye.so/reference/get-defi-v3-token-meta-data-multiple)**.
        They return the lightweight identity payload for one or more tokens on the selected chain
        (address, symbol, name, decimals, logo URL and the free-form `extensions` bag of social
        links / CoinGecko id). This is the right call when a caller just needs to resolve a token
        address to a display name and icon without paying for the full Token - Overview payload.

        The method is polymorphic: pass a single `str` address and the function routes to
        `/defi/v3/token/meta-data/single`, returning a [`GetV3TokenMetaDataResponse`][cyhole.birdeye.schema.GetV3TokenMetaDataResponse];
        pass a `list[str]` of addresses and it routes to `/defi/v3/token/meta-data/multiple`,
        returning a [`GetV3TokenMetaDataMultipleResponse`][cyhole.birdeye.schema.GetV3TokenMetaDataMultipleResponse]
        whose `data` is a dict keyed by token address.

        Parameters:
            address: a single token contract address (string) or a list of token contract addresses.
                The list flavour issues one HTTP call instead of N.

        Returns:
            metadata payload for the requested token(s); the concrete type depends on the input
            cardinality (see above).

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
    """
    if isinstance(address, str):
        url = self.url_api_public + "v3/token/meta-data/single"
        params = {"address": address}
        response_model: type = GetV3TokenMetaDataResponse
    else:
        url = self.url_api_public + "v3/token/meta-data/multiple"
        params = {"list_address": ",".join(address)}
        response_model = GetV3TokenMetaDataMultipleResponse

    return self.api_return_model(sync, RequestType.GET.value, url, response_model, params = params)

_get_v3_token_market_data

_get_v3_token_market_data(
    sync: Literal[True],
    address: str,
    ui_amount_mode: str | None = None,
) -> GetV3TokenMarketDataResponse

_get_v3_token_market_data(
    sync: Literal[True],
    address: list[str],
    ui_amount_mode: str | None = None,
) -> GetV3TokenMarketDataMultipleResponse

_get_v3_token_market_data(
    sync: Literal[False],
    address: str,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetV3TokenMarketDataResponse]

_get_v3_token_market_data(
    sync: Literal[False],
    address: list[str],
    ui_amount_mode: str | None = None,
) -> Coroutine[
    None, None, GetV3TokenMarketDataMultipleResponse
]

_get_v3_token_market_data(
    sync: bool,
    address: str | list[str],
    ui_amount_mode: str | None = None,
) -> (
    GetV3TokenMarketDataResponse
    | GetV3TokenMarketDataMultipleResponse
    | Coroutine[None, None, GetV3TokenMarketDataResponse]
    | Coroutine[
        None, None, GetV3TokenMarketDataMultipleResponse
    ]
)

This function refers to the v3 Birdeye token market-data endpoints Token - Market Data (Single) and Token - Market Data (Multiple). They return a compact market snapshot per token: price, liquidity, total/circulating supply, FDV, market cap and holder count. It is a cheaper alternative to Token - Overview when a caller only needs the headline numbers without the per-window trade/volume breakdown.

The method is polymorphic: pass a single str address and the function routes to /defi/v3/token/market-data, returning a GetV3TokenMarketDataResponse; pass a list[str] of addresses and it routes to /defi/v3/token/market-data/multiple, returning a GetV3TokenMarketDataMultipleResponse whose data is a dict keyed by token address.

Parameters:

Name	Type	Description	Default
address	str | list[str]	a single token contract address (string) or a list of token contract addresses.	required
ui_amount_mode	str | None	how to format scaled-UI-amount token figures on Solana. The supported values are available on BirdeyeUIAmountMode. Only applies on Solana; ignored on other chains. Default behaviour: scaled.	None

Returns:

Type	Description
GetV3TokenMarketDataResponse | GetV3TokenMarketDataMultipleResponse | Coroutine[None, None, GetV3TokenMarketDataResponse] | Coroutine[None, None, GetV3TokenMarketDataMultipleResponse]	market snapshot payload for the requested token(s); the concrete type depends on the
GetV3TokenMarketDataResponse | GetV3TokenMarketDataMultipleResponse | Coroutine[None, None, GetV3TokenMarketDataResponse] | Coroutine[None, None, GetV3TokenMarketDataMultipleResponse]	input cardinality (see above).

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_market_data(
    self,
    sync: bool,
    address: str | list[str],
    ui_amount_mode: str | None = None
) -> (
    GetV3TokenMarketDataResponse
    | GetV3TokenMarketDataMultipleResponse
    | Coroutine[None, None, GetV3TokenMarketDataResponse]
    | Coroutine[None, None, GetV3TokenMarketDataMultipleResponse]
):
    """
        This function refers to the v3 Birdeye token market-data endpoints **[Token - Market Data (Single)](https://docs.birdeye.so/reference/get-defi-v3-token-market-data)**
        and **[Token - Market Data (Multiple)](https://docs.birdeye.so/reference/get-defi-v3-token-market-data-multiple)**.
        They return a compact market snapshot per token: price, liquidity, total/circulating supply,
        FDV, market cap and holder count. It is a cheaper alternative to Token - Overview when a
        caller only needs the headline numbers without the per-window trade/volume breakdown.

        The method is polymorphic: pass a single `str` address and the function routes to
        `/defi/v3/token/market-data`, returning a [`GetV3TokenMarketDataResponse`][cyhole.birdeye.schema.GetV3TokenMarketDataResponse];
        pass a `list[str]` of addresses and it routes to `/defi/v3/token/market-data/multiple`,
        returning a [`GetV3TokenMarketDataMultipleResponse`][cyhole.birdeye.schema.GetV3TokenMarketDataMultipleResponse]
        whose `data` is a dict keyed by token address.

        Parameters:
            address: a single token contract address (string) or a list of token contract addresses.
            ui_amount_mode: how to format scaled-UI-amount token figures on Solana.
                The supported values are available on [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode].
                Only applies on Solana; ignored on other chains. Default behaviour: `scaled`.

        Returns:
            market snapshot payload for the requested token(s); the concrete type depends on the
            input cardinality (see above).

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    if isinstance(address, str):
        url = self.url_api_public + "v3/token/market-data"
        params: dict[str, Any] = {"address": address}
        response_model: type = GetV3TokenMarketDataResponse
    else:
        url = self.url_api_public + "v3/token/market-data/multiple"
        params = {"list_address": ",".join(address)}
        response_model = GetV3TokenMarketDataMultipleResponse
    if ui_amount_mode is not None:
        params["ui_amount_mode"] = ui_amount_mode

    return self.api_return_model(sync, RequestType.GET.value, url, response_model, params = params)

_get_v3_token_trade_data

_get_v3_token_trade_data(
    sync: Literal[True],
    address: str,
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> GetV3TokenTradeDataResponse

_get_v3_token_trade_data(
    sync: Literal[True],
    address: list[str],
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> GetV3TokenTradeDataMultipleResponse

_get_v3_token_trade_data(
    sync: Literal[False],
    address: str,
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetV3TokenTradeDataResponse]

_get_v3_token_trade_data(
    sync: Literal[False],
    address: list[str],
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[
    None, None, GetV3TokenTradeDataMultipleResponse
]

_get_v3_token_trade_data(
    sync: bool,
    address: str | list[str],
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> (
    GetV3TokenTradeDataResponse
    | GetV3TokenTradeDataMultipleResponse
    | Coroutine[None, None, GetV3TokenTradeDataResponse]
    | Coroutine[
        None, None, GetV3TokenTradeDataMultipleResponse
    ]
)

This function refers to the v3 Birdeye token trade-data endpoints Token - Trade Data (Single) and Token - Trade Data (Multiple). They return the full trading-activity snapshot of a token: latest price, price history at the 1m/5m/30m/1h/2h/4h/6h/8h/12h/24h windows, per-window (1m..24h) unique-wallet counts and full sell/buy/volume breakdowns, all aligned with the equivalent metric over the previous window. This is the "give me everything about how this token is trading" call — heavier than Token - Market Data but lighter than Token - Overview as it skips the identity and supply sections.

The method is polymorphic: pass a single str address and the function routes to /defi/v3/token/trade-data/single, returning a GetV3TokenTradeDataResponse; pass a list[str] of addresses and it routes to /defi/v3/token/trade-data/multiple, returning a GetV3TokenTradeDataMultipleResponse whose data is a dict keyed by token address.

Parameters:

Name	Type	Description	Default
address	str | list[str]	a single token contract address (string) or a list of token contract addresses.	required
frames	str | None	optional comma-separated list of additional custom time intervals to include in the response (up to 8 entries). Same grammar as on Token - Overview: minute intervals 1m..1440m, multiples-of-5 second intervals 5s..3600s, and 1h/2h/4h/8h/24h. Default behaviour: only the standard windows listed above are returned.	None
ui_amount_mode	str | None	how to format scaled-UI-amount token figures on Solana. The supported values are available on BirdeyeUIAmountMode. Only applies on Solana; ignored on other chains. Default behaviour: scaled.	None

Returns:

Type	Description
GetV3TokenTradeDataResponse | GetV3TokenTradeDataMultipleResponse | Coroutine[None, None, GetV3TokenTradeDataResponse] | Coroutine[None, None, GetV3TokenTradeDataMultipleResponse]	trading-activity snapshot for the requested token(s); the concrete type depends on the
GetV3TokenTradeDataResponse | GetV3TokenTradeDataMultipleResponse | Coroutine[None, None, GetV3TokenTradeDataResponse] | Coroutine[None, None, GetV3TokenTradeDataMultipleResponse]	input cardinality (see above).

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_trade_data(
    self,
    sync: bool,
    address: str | list[str],
    frames: str | None = None,
    ui_amount_mode: str | None = None
) -> (
    GetV3TokenTradeDataResponse
    | GetV3TokenTradeDataMultipleResponse
    | Coroutine[None, None, GetV3TokenTradeDataResponse]
    | Coroutine[None, None, GetV3TokenTradeDataMultipleResponse]
):
    """
        This function refers to the v3 Birdeye token trade-data endpoints **[Token - Trade Data (Single)](https://docs.birdeye.so/reference/get-defi-v3-token-trade-data-single)**
        and **[Token - Trade Data (Multiple)](https://docs.birdeye.so/reference/get-defi-v3-token-trade-data-multiple)**.
        They return the full trading-activity snapshot of a token: latest price, price history at the
        1m/5m/30m/1h/2h/4h/6h/8h/12h/24h windows, per-window (1m..24h) unique-wallet counts and full
        sell/buy/volume breakdowns, all aligned with the equivalent metric over the previous window.
        This is the "give me everything about how this token is trading" call — heavier than
        Token - Market Data but lighter than Token - Overview as it skips the identity and supply
        sections.

        The method is polymorphic: pass a single `str` address and the function routes to
        `/defi/v3/token/trade-data/single`, returning a [`GetV3TokenTradeDataResponse`][cyhole.birdeye.schema.GetV3TokenTradeDataResponse];
        pass a `list[str]` of addresses and it routes to `/defi/v3/token/trade-data/multiple`,
        returning a [`GetV3TokenTradeDataMultipleResponse`][cyhole.birdeye.schema.GetV3TokenTradeDataMultipleResponse]
        whose `data` is a dict keyed by token address.

        Parameters:
            address: a single token contract address (string) or a list of token contract addresses.
            frames: optional comma-separated list of additional custom time intervals to include in
                the response (up to 8 entries). Same grammar as on Token - Overview: minute intervals
                `1m..1440m`, multiples-of-5 second intervals `5s..3600s`, and `1h/2h/4h/8h/24h`.
                Default behaviour: only the standard windows listed above are returned.
            ui_amount_mode: how to format scaled-UI-amount token figures on Solana.
                The supported values are available on [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode].
                Only applies on Solana; ignored on other chains. Default behaviour: `scaled`.

        Returns:
            trading-activity snapshot for the requested token(s); the concrete type depends on the
            input cardinality (see above).

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    if isinstance(address, str):
        url = self.url_api_public + "v3/token/trade-data/single"
        params: dict[str, Any] = {"address": address}
        response_model: type = GetV3TokenTradeDataResponse
    else:
        url = self.url_api_public + "v3/token/trade-data/multiple"
        params = {"list_address": ",".join(address)}
        response_model = GetV3TokenTradeDataMultipleResponse
    if frames is not None:
        params["frames"] = frames
    if ui_amount_mode is not None:
        params["ui_amount_mode"] = ui_amount_mode

    return self.api_return_model(sync, RequestType.GET.value, url, response_model, params = params)

_get_v3_token_exit_liquidity

_get_v3_token_exit_liquidity(
    sync: Literal[True], address: str
) -> GetV3TokenExitLiquidityResponse

_get_v3_token_exit_liquidity(
    sync: Literal[True], address: list[str]
) -> GetV3TokenExitLiquidityMultipleResponse

_get_v3_token_exit_liquidity(
    sync: Literal[False], address: str
) -> Coroutine[None, None, GetV3TokenExitLiquidityResponse]

_get_v3_token_exit_liquidity(
    sync: Literal[False], address: list[str]
) -> Coroutine[
    None, None, GetV3TokenExitLiquidityMultipleResponse
]

_get_v3_token_exit_liquidity(
    sync: bool, address: str | list[str]
) -> (
    GetV3TokenExitLiquidityResponse
    | GetV3TokenExitLiquidityMultipleResponse
    | Coroutine[None, None, GetV3TokenExitLiquidityResponse]
    | Coroutine[
        None, None, GetV3TokenExitLiquidityMultipleResponse
    ]
)

This function refers to the v3 Birdeye token exit-liquidity endpoints Token - Liquidity (Single) and Token - Liquidity (Multiple). They return Birdeye's estimate of how much value the largest holders of a token could realistically extract by selling without crashing the price, computed from the on-chain liquidity profile of the token's biggest markets. The single variant returns the payload directly under data; the multiple variant returns data.items as a list (one entry per requested address).

Info

Birdeye restricts both endpoints to the Base chain at the time of writing.

The method is polymorphic: pass a single str address and the function routes to /defi/v3/token/exit-liquidity, returning a GetV3TokenExitLiquidityResponse; pass a list[str] of addresses and it routes to /defi/v3/token/exit-liquidity/multiple, returning a GetV3TokenExitLiquidityMultipleResponse whose data.items is a list of entries.

Parameters:

Name	Type	Description	Default
address	str | list[str]	a single token contract address (string) or a list of token contract addresses.	required

Returns:

Type	Description
GetV3TokenExitLiquidityResponse | GetV3TokenExitLiquidityMultipleResponse | Coroutine[None, None, GetV3TokenExitLiquidityResponse] | Coroutine[None, None, GetV3TokenExitLiquidityMultipleResponse]	exit-liquidity payload for the requested token(s); the concrete type depends on the
GetV3TokenExitLiquidityResponse | GetV3TokenExitLiquidityMultipleResponse | Coroutine[None, None, GetV3TokenExitLiquidityResponse] | Coroutine[None, None, GetV3TokenExitLiquidityMultipleResponse]	input cardinality (see above).

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_exit_liquidity(
    self,
    sync: bool,
    address: str | list[str]
) -> (
    GetV3TokenExitLiquidityResponse
    | GetV3TokenExitLiquidityMultipleResponse
    | Coroutine[None, None, GetV3TokenExitLiquidityResponse]
    | Coroutine[None, None, GetV3TokenExitLiquidityMultipleResponse]
):
    """
        This function refers to the v3 Birdeye token exit-liquidity endpoints **[Token - Liquidity (Single)](https://docs.birdeye.so/reference/get-defi-v3-token-exit-liquidity)**
        and **[Token - Liquidity (Multiple)](https://docs.birdeye.so/reference/get-defi-v3-token-exit-liquidity-multiple)**.
        They return Birdeye's estimate of how much value the largest holders of a token could
        realistically extract by selling without crashing the price, computed from the on-chain
        liquidity profile of the token's biggest markets. The single variant returns the payload
        directly under `data`; the multiple variant returns `data.items` as a list (one entry per
        requested address).

        !!! info
            Birdeye restricts both endpoints to the **Base** chain at the time of writing.

        The method is polymorphic: pass a single `str` address and the function routes to
        `/defi/v3/token/exit-liquidity`, returning a [`GetV3TokenExitLiquidityResponse`][cyhole.birdeye.schema.GetV3TokenExitLiquidityResponse];
        pass a `list[str]` of addresses and it routes to `/defi/v3/token/exit-liquidity/multiple`,
        returning a [`GetV3TokenExitLiquidityMultipleResponse`][cyhole.birdeye.schema.GetV3TokenExitLiquidityMultipleResponse]
        whose `data.items` is a list of entries.

        Parameters:
            address: a single token contract address (string) or a list of token contract addresses.

        Returns:
            exit-liquidity payload for the requested token(s); the concrete type depends on the
            input cardinality (see above).

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
    """
    if isinstance(address, str):
        url = self.url_api_public + "v3/token/exit-liquidity"
        params: dict[str, Any] = {"address": address}
        response_model: type = GetV3TokenExitLiquidityResponse
    else:
        url = self.url_api_public + "v3/token/exit-liquidity/multiple"
        params = {"list_address": ",".join(address)}
        response_model = GetV3TokenExitLiquidityMultipleResponse

    return self.api_return_model(sync, RequestType.GET.value, url, response_model, params = params)

_get_v3_token_mint_burn_txs

_get_v3_token_mint_burn_txs(
    sync: Literal[True],
    address: str,
    type: str = BirdeyeMintBurnType.ALL.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    after_time: int | None = None,
    before_time: int | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> GetV3TokenMintBurnTxsResponse

_get_v3_token_mint_burn_txs(
    sync: Literal[False],
    address: str,
    type: str = BirdeyeMintBurnType.ALL.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    after_time: int | None = None,
    before_time: int | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> Coroutine[None, None, GetV3TokenMintBurnTxsResponse]

_get_v3_token_mint_burn_txs(
    sync: bool,
    address: str,
    type: str = BirdeyeMintBurnType.ALL.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    after_time: int | None = None,
    before_time: int | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> (
    GetV3TokenMintBurnTxsResponse
    | Coroutine[None, None, GetV3TokenMintBurnTxsResponse]
)

This function refers to the PRIVATE API endpoint Token - Mint/Burn and is used to retrieve the on-chain mint and burn transactions of an SPL token: every transaction that either increases or decreases the token's total supply. Each entry exposes the on-chain signature, the affected mint, the program that emitted the instruction, raw and UI-formatted amounts, slot, and the block timestamp. Useful for auditing supply changes (rewards, redemptions, buybacks) outside of normal trades.

Info

Birdeye restricts this endpoint to the Solana chain at the time of writing.

Parameters:

Name	Type	Description	Default
address	str	contract address of the SPL token whose mint/burn history must be retrieved.	required
type	str	kind of supply change to return. Pick one of the constants on BirdeyeMintBurnType. Default behaviour: all.	BirdeyeMintBurnType.ALL.value
sort_type	str	ascending or descending order on block_time. Pick one of the constants on BirdeyeOrder. Default behaviour: desc (most recent first).	BirdeyeOrder.DESCENDING.value
after_time	int | None	optional inclusive lower bound on the transaction block time, in unix seconds; None to disable.	None
before_time	int | None	optional inclusive upper bound on the transaction block time, in unix seconds; None to disable.	None
offset	int | None	zero-based pagination offset. Default behaviour: 0. Birdeye requires offset + limit <= 10000.	None
limit	int | None	number of records to return (1..100). Default behaviour: 100.	None

Returns:

Type	Description
GetV3TokenMintBurnTxsResponse | Coroutine[None, None, GetV3TokenMintBurnTxsResponse]	ranked list of mint/burn transactions decoded as
GetV3TokenMintBurnTxsResponse | Coroutine[None, None, GetV3TokenMintBurnTxsResponse]	GetV3TokenMintBurnTxsResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_mint_burn_txs(
    self,
    sync: bool,
    address: str,
    type: str = BirdeyeMintBurnType.ALL.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    after_time: int | None = None,
    before_time: int | None = None,
    offset: int | None = None,
    limit: int | None = None
) -> GetV3TokenMintBurnTxsResponse | Coroutine[None, None, GetV3TokenMintBurnTxsResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Mint/Burn](https://docs.birdeye.so/reference/get-defi-v3-token-mint-burn-txs)** and is used
        to retrieve the on-chain mint and burn transactions of an SPL token: every transaction that
        either increases or decreases the token's total supply. Each entry exposes the on-chain
        signature, the affected mint, the program that emitted the instruction, raw and UI-formatted
        amounts, slot, and the block timestamp. Useful for auditing supply changes (rewards,
        redemptions, buybacks) outside of normal trades.

        !!! info
            Birdeye restricts this endpoint to the **Solana** chain at the time of writing.

        Parameters:
            address: contract address of the SPL token whose mint/burn history must be retrieved.
            type: kind of supply change to return. Pick one of the constants on
                [`BirdeyeMintBurnType`][cyhole.birdeye.param.BirdeyeMintBurnType].
                Default behaviour: `all`.
            sort_type: ascending or descending order on `block_time`. Pick one of the constants on
                [`BirdeyeOrder`][cyhole.birdeye.param.BirdeyeOrder]. Default behaviour: `desc`
                (most recent first).
            after_time: optional inclusive lower bound on the transaction block time, in unix
                seconds; `None` to disable.
            before_time: optional inclusive upper bound on the transaction block time, in unix
                seconds; `None` to disable.
            offset: zero-based pagination offset. Default behaviour: `0`.
                Birdeye requires `offset + limit <= 10000`.
            limit: number of records to return (1..100). Default behaviour: `100`.

        Returns:
            ranked list of mint/burn transactions decoded as
            [`GetV3TokenMintBurnTxsResponse`][cyhole.birdeye.schema.GetV3TokenMintBurnTxsResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    BirdeyeMintBurnType.check(type)
    BirdeyeOrder.check(sort_type)

    url = self.url_api_public + "v3/token/mint-burn-txs"
    params = {
        "address": address,
        "sort_by": "block_time",
        "sort_type": sort_type,
        "type": type,
        "after_time": after_time,
        "before_time": before_time,
        "offset": offset,
        "limit": limit,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetV3TokenMintBurnTxsResponse, params = params)

_get_v2_tokens_top_traders

_get_v2_tokens_top_traders(
    sync: Literal[True],
    address: str,
    time_frame: str = BirdeyeV2TopTradersTimeFrame.H24.value,
    sort_by: str = BirdeyeV2TopTradersSortBy.VOLUME.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> GetV2TopTradersResponse

_get_v2_tokens_top_traders(
    sync: Literal[False],
    address: str,
    time_frame: str = BirdeyeV2TopTradersTimeFrame.H24.value,
    sort_by: str = BirdeyeV2TopTradersSortBy.VOLUME.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetV2TopTradersResponse]

_get_v2_tokens_top_traders(
    sync: bool,
    address: str,
    time_frame: str = BirdeyeV2TopTradersTimeFrame.H24.value,
    sort_by: str = BirdeyeV2TopTradersSortBy.VOLUME.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> (
    GetV2TopTradersResponse
    | Coroutine[None, None, GetV2TopTradersResponse]
)

This function refers to the PRIVATE API endpoint Token - Top Traders and is used to retrieve the wallets that traded the most of a given token over a configurable time frame, ranked by raw volume, USD volume, trade count, or realised/unrealised PnL. Each entry exposes the wallet address, optional Birdeye tags (whale, bot, ...), trade and volume splits between buy and sell sides, and Solana-only profit-and-loss figures. Useful when surfacing the dominant participants behind a token's recent activity.

Info

The PnL-based sort metrics (total_pnl, unrealized_pnl, realized_pnl, volume_usd) and the longer time frames (2d..90d) are restricted by Birdeye to Solana. On every other chain only volume / trade sort and time frames up to 24h are honoured.

Parameters:

Name	Type	Description	Default
address	str	contract address of the token whose top traders must be listed.	required
time_frame	str	trailing window for the metrics. Pick one of the constants on BirdeyeV2TopTradersTimeFrame. Default behaviour: 24h.	BirdeyeV2TopTradersTimeFrame.H24.value
sort_by	str	ranking metric. Pick one of the constants on BirdeyeV2TopTradersSortBy. Default behaviour: volume.	BirdeyeV2TopTradersSortBy.VOLUME.value
sort_type	str	ascending or descending order. Pick one of the constants on BirdeyeOrder. Default behaviour: desc.	BirdeyeOrder.DESCENDING.value
offset	int | None	zero-based pagination offset. Default behaviour: 0. Birdeye requires offset + limit <= 10000.	None
limit	int | None	number of records to return. Default behaviour: 10.	None
ui_amount_mode	str | None	how to format scaled-UI-amount token figures on Solana. Pick a BirdeyeUIAmountMode member or leave None for the server default (scaled).	None

Returns:

Type	Description
GetV2TopTradersResponse | Coroutine[None, None, GetV2TopTradersResponse]	ranked list of top trader entries decoded as
GetV2TopTradersResponse | Coroutine[None, None, GetV2TopTradersResponse]	GetV2TopTradersResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v2_tokens_top_traders(
    self,
    sync: bool,
    address: str,
    time_frame: str = BirdeyeV2TopTradersTimeFrame.H24.value,
    sort_by: str = BirdeyeV2TopTradersSortBy.VOLUME.value,
    sort_type: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None
) -> GetV2TopTradersResponse | Coroutine[None, None, GetV2TopTradersResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Top Traders](https://docs.birdeye.so/reference/get-defi-v2-tokens-top_traders)** and is used
        to retrieve the wallets that traded the most of a given token over a configurable time
        frame, ranked by raw volume, USD volume, trade count, or realised/unrealised PnL. Each
        entry exposes the wallet address, optional Birdeye tags (`whale`, `bot`, ...), trade and
        volume splits between buy and sell sides, and Solana-only profit-and-loss figures.
        Useful when surfacing the dominant participants behind a token's recent activity.

        !!! info
            The PnL-based sort metrics (`total_pnl`, `unrealized_pnl`, `realized_pnl`,
            `volume_usd`) and the longer time frames (2d..90d) are restricted by Birdeye to
            Solana. On every other chain only `volume` / `trade` sort and time frames up to 24h
            are honoured.

        Parameters:
            address: contract address of the token whose top traders must be listed.
            time_frame: trailing window for the metrics. Pick one of the constants on
                [`BirdeyeV2TopTradersTimeFrame`][cyhole.birdeye.param.BirdeyeV2TopTradersTimeFrame].
                Default behaviour: `24h`.
            sort_by: ranking metric. Pick one of the constants on
                [`BirdeyeV2TopTradersSortBy`][cyhole.birdeye.param.BirdeyeV2TopTradersSortBy].
                Default behaviour: `volume`.
            sort_type: ascending or descending order. Pick one of the constants on
                [`BirdeyeOrder`][cyhole.birdeye.param.BirdeyeOrder]. Default behaviour: `desc`.
            offset: zero-based pagination offset. Default behaviour: `0`. Birdeye requires
                `offset + limit <= 10000`.
            limit: number of records to return. Default behaviour: `10`.
            ui_amount_mode: how to format scaled-UI-amount token figures on Solana. Pick a
                [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode] member or leave
                `None` for the server default (`scaled`).

        Returns:
            ranked list of top trader entries decoded as
            [`GetV2TopTradersResponse`][cyhole.birdeye.schema.GetV2TopTradersResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    BirdeyeV2TopTradersTimeFrame.check(time_frame)
    BirdeyeV2TopTradersSortBy.check(sort_by)
    BirdeyeOrder.check(sort_type)
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    url = self.url_api_public + "v2/tokens/top_traders"
    params = {
        "address": address,
        "time_frame": time_frame,
        "sort_type": sort_type,
        "sort_by": sort_by,
        "offset": offset,
        "limit": limit,
        "ui_amount_mode": ui_amount_mode,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetV2TopTradersResponse, params = params)

_get_token_holder

_get_token_holder(
    sync: Literal[True],
    token_address: str,
    wallets: None = None,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> GetTokenHolderResponse

_get_token_holder(
    sync: Literal[True],
    token_address: str,
    wallets: list[str],
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> PostTokenHolderBatchResponse

_get_token_holder(
    sync: Literal[False],
    token_address: str,
    wallets: None = None,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetTokenHolderResponse]

_get_token_holder(
    sync: Literal[False],
    token_address: str,
    wallets: list[str],
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, PostTokenHolderBatchResponse]

_get_token_holder(
    sync: bool,
    token_address: str,
    wallets: list[str] | None = None,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> (
    GetTokenHolderResponse
    | PostTokenHolderBatchResponse
    | Coroutine[None, None, GetTokenHolderResponse]
    | Coroutine[None, None, PostTokenHolderBatchResponse]
)

This function consolidates the Birdeye top-holder and batch-balance endpoints Token - Holder and Token - Holder (Batch) under a single polymorphic call:

• leave wallets to its default None to retrieve the ranked list of largest holders of token_address (GET /defi/v3/token/holder). The response is decoded as GetTokenHolderResponse and exposes the mint, owner, token_account, raw and UI-formatted balance for each holder.
• pass wallets as a list of specific wallet addresses to look up their balance in token_address (POST /token/v1/holder/batch). The response is decoded as PostTokenHolderBatchResponse and exposes mint, owner, balance (raw) and amount (UI) per requested wallet.

Info

Both endpoints are restricted by Birdeye to the Solana chain at the time of writing.

Parameters:

Name	Type	Description	Default
token_address	str	contract address of the SPL token to look up.	required
wallets	list[str] | None	list of wallet addresses whose balances must be fetched. When None the call switches to the top-holder ranking.	None
offset	int | None	zero-based pagination offset for the top-holder ranking. Ignored when wallets is provided. Default behaviour: 0.	None
limit	int | None	number of records to return for the top-holder ranking. Ignored when wallets is provided. Default behaviour: 100.	None
ui_amount_mode	str | None	how to format scaled-UI-amount token figures. Pick a BirdeyeUIAmountMode member or leave None for the server default (scaled).	None

Returns:

Type	Description
GetTokenHolderResponse | PostTokenHolderBatchResponse | Coroutine[None, None, GetTokenHolderResponse] | Coroutine[None, None, PostTokenHolderBatchResponse]	top-holder ranking or per-wallet balance list; the concrete type depends on whether
GetTokenHolderResponse | PostTokenHolderBatchResponse | Coroutine[None, None, GetTokenHolderResponse] | Coroutine[None, None, PostTokenHolderBatchResponse]	wallets was provided.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_holder(
    self,
    sync: bool,
    token_address: str,
    wallets: list[str] | None = None,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None
) -> (
    GetTokenHolderResponse
    | PostTokenHolderBatchResponse
    | Coroutine[None, None, GetTokenHolderResponse]
    | Coroutine[None, None, PostTokenHolderBatchResponse]
):
    """
        This function consolidates the Birdeye top-holder and batch-balance endpoints
        **[Token - Holder](https://docs.birdeye.so/reference/get-defi-v3-token-holder)**
        and **[Token - Holder (Batch)](https://docs.birdeye.so/reference/post-token-v1-holder-batch)**
        under a single polymorphic call:

        - leave `wallets` to its default `None` to retrieve the ranked list of largest holders
          of `token_address` (`GET /defi/v3/token/holder`). The response is decoded as
          [`GetTokenHolderResponse`][cyhole.birdeye.schema.GetTokenHolderResponse] and exposes
          the `mint`, `owner`, `token_account`, raw and UI-formatted balance for each holder.
        - pass `wallets` as a list of specific wallet addresses to look up their balance in
          `token_address` (`POST /token/v1/holder/batch`). The response is decoded as
          [`PostTokenHolderBatchResponse`][cyhole.birdeye.schema.PostTokenHolderBatchResponse]
          and exposes `mint`, `owner`, `balance` (raw) and `amount` (UI) per requested wallet.

        !!! info
            Both endpoints are restricted by Birdeye to the **Solana** chain at the time of writing.

        Parameters:
            token_address: contract address of the SPL token to look up.
            wallets: list of wallet addresses whose balances must be fetched. When `None`
                the call switches to the top-holder ranking.
            offset: zero-based pagination offset for the top-holder ranking. Ignored when
                `wallets` is provided. Default behaviour: `0`.
            limit: number of records to return for the top-holder ranking. Ignored when
                `wallets` is provided. Default behaviour: `100`.
            ui_amount_mode: how to format scaled-UI-amount token figures. Pick a
                [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode] member or leave
                `None` for the server default (`scaled`).

        Returns:
            top-holder ranking or per-wallet balance list; the concrete type depends on whether
            `wallets` was provided.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    if wallets is None:
        # GET top-holder ranking
        url = self.url_api_public + "v3/token/holder"
        params: dict[str, Any] = {
            "address": token_address,
            "offset": offset,
            "limit": limit,
        }
        if ui_amount_mode is not None:
            params["ui_amount_mode"] = ui_amount_mode

        return self.api_return_model(sync, RequestType.GET.value, url, GetTokenHolderResponse, params = params)

    # POST batch balance
    url = self.url_api_token_v1 + "holder/batch"
    body = {
        "token_address": token_address,
        "wallets": wallets,
    }
    headers = self.headers.copy()
    headers["content-type"] = "application/json"
    post_params = {}
    if ui_amount_mode is not None:
        post_params["ui_amount_mode"] = ui_amount_mode

    return self.api_return_model(sync, RequestType.POST.value, url, PostTokenHolderBatchResponse, json = body, headers = headers, params = post_params or None)

_get_holder_distribution

_get_holder_distribution(
    sync: Literal[True],
    token_address: str,
    address_type: str = BirdeyeHolderDistributionAddressType.WALLET.value,
    mode: str = BirdeyeHolderDistributionMode.TOP.value,
    top_n: int | None = None,
    min_percent: float | None = None,
    max_percent: float | None = None,
    include_list: bool | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> GetHolderDistributionResponse

_get_holder_distribution(
    sync: Literal[False],
    token_address: str,
    address_type: str = BirdeyeHolderDistributionAddressType.WALLET.value,
    mode: str = BirdeyeHolderDistributionMode.TOP.value,
    top_n: int | None = None,
    min_percent: float | None = None,
    max_percent: float | None = None,
    include_list: bool | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> Coroutine[None, None, GetHolderDistributionResponse]

_get_holder_distribution(
    sync: bool,
    token_address: str,
    address_type: str = BirdeyeHolderDistributionAddressType.WALLET.value,
    mode: str = BirdeyeHolderDistributionMode.TOP.value,
    top_n: int | None = None,
    min_percent: float | None = None,
    max_percent: float | None = None,
    include_list: bool | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> (
    GetHolderDistributionResponse
    | Coroutine[None, None, GetHolderDistributionResponse]
)

This function refers to the PRIVATE API endpoint Token - Holder Distribution and is used to summarise how the supply of a token is spread across its holders. The endpoint can run in two modes: in top mode it returns the top-N holders by holding amount, in percent mode it returns the holders whose share of total supply falls inside a [min_percent, max_percent] band. Each call also returns an aggregate summary (total holding, cumulative percent of supply, wallet count) over the filtered set — very useful for "how much of the supply is in whale hands" style answers.

Info

The endpoint is restricted by Birdeye to the Solana chain at the time of writing.

Parameters:

Name	Type	Description	Default
token_address	str	contract address of the SPL token whose distribution must be analysed.	required
address_type	str	whether to group holders by wallet owner or by SPL token account address. Pick one of the constants on BirdeyeHolderDistributionAddressType. Default behaviour: wallet.	BirdeyeHolderDistributionAddressType.WALLET.value
mode	str	filter mode (top-N vs supply-share range). Pick one of the constants on BirdeyeHolderDistributionMode. Default behaviour: top.	BirdeyeHolderDistributionMode.TOP.value
top_n	int | None	number of top holders to return when mode = top. Ignored otherwise. Default behaviour: 10.	None
min_percent	float | None	inclusive lower bound on the holder share when mode = percent. Expressed as a fraction in [0, 1]. None disables the lower bound.	None
max_percent	float | None	inclusive upper bound on the holder share when mode = percent. None disables the upper bound.	None
include_list	bool | None	when False, omit the holders list from the response and return only the aggregate summary; useful to save bandwidth on large queries. Default behaviour: True.	None
offset	int | None	zero-based pagination offset. Default behaviour: 0. Birdeye requires offset + limit <= 10000.	None
limit	int | None	number of records to return. Default behaviour: 50.	None

Returns:

Type	Description
GetHolderDistributionResponse | Coroutine[None, None, GetHolderDistributionResponse]	holder-distribution payload decoded as
GetHolderDistributionResponse | Coroutine[None, None, GetHolderDistributionResponse]	GetHolderDistributionResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_holder_distribution(
    self,
    sync: bool,
    token_address: str,
    address_type: str = BirdeyeHolderDistributionAddressType.WALLET.value,
    mode: str = BirdeyeHolderDistributionMode.TOP.value,
    top_n: int | None = None,
    min_percent: float | None = None,
    max_percent: float | None = None,
    include_list: bool | None = None,
    offset: int | None = None,
    limit: int | None = None
) -> GetHolderDistributionResponse | Coroutine[None, None, GetHolderDistributionResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Holder Distribution](https://docs.birdeye.so/reference/get-holder-v1-distribution)** and is used
        to summarise how the supply of a token is spread across its holders. The endpoint can run
        in two modes: in `top` mode it returns the top-N holders by holding amount, in `percent`
        mode it returns the holders whose share of total supply falls inside a `[min_percent, max_percent]`
        band. Each call also returns an aggregate `summary` (total holding, cumulative percent of
        supply, wallet count) over the filtered set — very useful for "how much of the supply is
        in whale hands" style answers.

        !!! info
            The endpoint is restricted by Birdeye to the **Solana** chain at the time of writing.

        Parameters:
            token_address: contract address of the SPL token whose distribution must be analysed.
            address_type: whether to group holders by wallet owner or by SPL token account address.
                Pick one of the constants on
                [`BirdeyeHolderDistributionAddressType`][cyhole.birdeye.param.BirdeyeHolderDistributionAddressType].
                Default behaviour: `wallet`.
            mode: filter mode (top-N vs supply-share range). Pick one of the constants on
                [`BirdeyeHolderDistributionMode`][cyhole.birdeye.param.BirdeyeHolderDistributionMode].
                Default behaviour: `top`.
            top_n: number of top holders to return when `mode = top`. Ignored otherwise.
                Default behaviour: `10`.
            min_percent: inclusive lower bound on the holder share when `mode = percent`. Expressed
                as a fraction in `[0, 1]`. `None` disables the lower bound.
            max_percent: inclusive upper bound on the holder share when `mode = percent`. `None`
                disables the upper bound.
            include_list: when `False`, omit the `holders` list from the response and return only
                the aggregate summary; useful to save bandwidth on large queries. Default
                behaviour: `True`.
            offset: zero-based pagination offset. Default behaviour: `0`.
                Birdeye requires `offset + limit <= 10000`.
            limit: number of records to return. Default behaviour: `50`.

        Returns:
            holder-distribution payload decoded as
            [`GetHolderDistributionResponse`][cyhole.birdeye.schema.GetHolderDistributionResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    BirdeyeHolderDistributionAddressType.check(address_type)
    BirdeyeHolderDistributionMode.check(mode)

    url = self.url_api_holder_v1 + "distribution"
    params = {
        "token_address": token_address,
        "address_type": address_type,
        "mode": mode,
        "top_n": top_n,
        "min_percent": min_percent,
        "max_percent": max_percent,
        "include_list": str(include_list).lower() if include_list is not None else None,
        "offset": offset,
        "limit": limit,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetHolderDistributionResponse, params = params)

_get_token_holder_profile

_get_token_holder_profile(
    sync: Literal[True],
    token_address: str,
    interval: str = "1h",
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None,
) -> GetHolderProfileResponse

_get_token_holder_profile(
    sync: Literal[False],
    token_address: str,
    interval: str = "1h",
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None,
) -> Coroutine[None, None, GetHolderProfileResponse]

_get_token_holder_profile(
    sync: bool,
    token_address: str,
    interval: str = "1h",
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None,
) -> (
    GetHolderProfileResponse
    | Coroutine[None, None, GetHolderProfileResponse]
)

This function refers to the PRIVATE API endpoint Token - Holder Profile and is used to retrieve Birdeye's holder-profile summary of a token: headline holder counts, a 1h market snapshot (liquidity, market cap, buy/sell volume breakdown, top-10 holder concentration) and a per-tag aggregate breakdown across the five Birdeye holder tags (bundler, sniper, insider, dev, smart_trader). Useful for surfacing "who is actually holding this token" at a glance.

Info

The endpoint is restricted by Birdeye to the Solana chain at the time of writing. Bundler-tag data may exhibit a short delay versus the other tags per the API docs.

Parameters:

Name	Type	Description	Default
token_address	str	contract address of the SPL token whose holder profile must be retrieved.	required
interval	str	time interval for the volume figures. At the time of writing Birdeye only supports 1h. Default behaviour: 1h.	'1h'
ui_amount_mode	str | None	how to format scaled-UI-amount token figures. Pick a BirdeyeUIAmountMode member or leave None for the server default (raw).	None
include_zero_balance	bool | None	when True (the API default) zero-balance wallets are kept in the per-tag aggregates; set to False to exclude them. None defers to the server default.	None

Returns:

Type	Description
GetHolderProfileResponse | Coroutine[None, None, GetHolderProfileResponse]	holder-profile payload decoded as
GetHolderProfileResponse | Coroutine[None, None, GetHolderProfileResponse]	GetHolderProfileResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_holder_profile(
    self,
    sync: bool,
    token_address: str,
    interval: str = "1h",
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None
) -> GetHolderProfileResponse | Coroutine[None, None, GetHolderProfileResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Holder Profile](https://docs.birdeye.so/reference/get-token-v1-holder-profile)** and is used
        to retrieve Birdeye's holder-profile summary of a token: headline holder counts, a 1h
        market snapshot (liquidity, market cap, buy/sell volume breakdown, top-10 holder
        concentration) and a per-tag aggregate breakdown across the five Birdeye holder tags
        (`bundler`, `sniper`, `insider`, `dev`, `smart_trader`). Useful for surfacing "who is
        actually holding this token" at a glance.

        !!! info
            The endpoint is restricted by Birdeye to the **Solana** chain at the time of writing.
            Bundler-tag data may exhibit a short delay versus the other tags per the API docs.

        Parameters:
            token_address: contract address of the SPL token whose holder profile must be retrieved.
            interval: time interval for the volume figures. At the time of writing Birdeye only
                supports `1h`. Default behaviour: `1h`.
            ui_amount_mode: how to format scaled-UI-amount token figures. Pick a
                [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode] member or leave
                `None` for the server default (`raw`).
            include_zero_balance: when `True` (the API default) zero-balance wallets are kept in
                the per-tag aggregates; set to `False` to exclude them. `None` defers to the
                server default.

        Returns:
            holder-profile payload decoded as
            [`GetHolderProfileResponse`][cyhole.birdeye.schema.GetHolderProfileResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    url = self.url_api_token_v1 + "holder-profile"
    params = {
        "token_address": token_address,
        "interval": interval,
        "ui_amount_mode": ui_amount_mode,
        "include_zero_balance": str(include_zero_balance).lower() if include_zero_balance is not None else None,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetHolderProfileResponse, params = params)

_get_token_holder_positions

_get_token_holder_positions(
    sync: Literal[True],
    token_address: str,
    labels: str | None = None,
    order_type: str = BirdeyeOrder.DESCENDING.value,
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> GetTokenHolderPositionsResponse

_get_token_holder_positions(
    sync: Literal[False],
    token_address: str,
    labels: str | None = None,
    order_type: str = BirdeyeOrder.DESCENDING.value,
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> Coroutine[None, None, GetTokenHolderPositionsResponse]

_get_token_holder_positions(
    sync: bool,
    token_address: str,
    labels: str | None = None,
    order_type: str = BirdeyeOrder.DESCENDING.value,
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None,
    offset: int | None = None,
    limit: int | None = None,
) -> (
    GetTokenHolderPositionsResponse
    | Coroutine[None, None, GetTokenHolderPositionsResponse]
)

This function refers to the PRIVATE API endpoint Token - Holder Positions and is used to retrieve a paginated list of wallet positions for a given token, optionally filtered by Birdeye holder tags. Each entry describes the wallet's current holding, percent of supply, average buy price, cumulative buy/sell counts and volumes (both in token UI units and USD), profit-and-loss in USD, and the timestamp of its first observed trade. Useful for drilling from a token down to its individual notable holders / traders.

Info

The endpoint is restricted by Birdeye to the Solana chain at the time of writing. Bundler-tag data may exhibit a short delay versus the other tags per the API docs.

Parameters:

Name	Type	Description	Default
token_address	str	contract address of the SPL token whose holder positions must be listed.	required
labels	str | None	comma-separated list of holder tags (bundler, sniper, insider, dev, smart_trader) to restrict the result to wallets carrying at least one of the tags; None returns all wallets regardless of tags.	None
order_type	str	ascending or descending order on the underlying amount sort field (the only metric the API supports today). Pick one of the constants on BirdeyeOrder. Default behaviour: desc.	BirdeyeOrder.DESCENDING.value
ui_amount_mode	str | None	how to format scaled-UI-amount token figures. Pick a BirdeyeUIAmountMode member or leave None for the server default (raw).	None
include_zero_balance	bool | None	when True (the API default) wallets with zero current balance are kept in the result; set to False to exclude them. None defers to the server default.	None
offset	int | None	zero-based pagination offset. Default behaviour: 0.	None
limit	int | None	number of records to return. Default behaviour: 50.	None

Returns:

Type	Description
GetTokenHolderPositionsResponse | Coroutine[None, None, GetTokenHolderPositionsResponse]	paginated list of per-wallet positions decoded as
GetTokenHolderPositionsResponse | Coroutine[None, None, GetTokenHolderPositionsResponse]	GetTokenHolderPositionsResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_holder_positions(
    self,
    sync: bool,
    token_address: str,
    labels: str | None = None,
    order_type: str = BirdeyeOrder.DESCENDING.value,
    ui_amount_mode: str | None = None,
    include_zero_balance: bool | None = None,
    offset: int | None = None,
    limit: int | None = None
) -> GetTokenHolderPositionsResponse | Coroutine[None, None, GetTokenHolderPositionsResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Holder Positions](https://docs.birdeye.so/reference/get-token-v1-holder-positions)** and is used
        to retrieve a paginated list of wallet positions for a given token, optionally filtered
        by Birdeye holder tags. Each entry describes the wallet's current holding, percent of
        supply, average buy price, cumulative buy/sell counts and volumes (both in token UI
        units and USD), profit-and-loss in USD, and the timestamp of its first observed trade.
        Useful for drilling from a token down to its individual notable holders / traders.

        !!! info
            The endpoint is restricted by Birdeye to the **Solana** chain at the time of writing.
            Bundler-tag data may exhibit a short delay versus the other tags per the API docs.

        Parameters:
            token_address: contract address of the SPL token whose holder positions must be listed.
            labels: comma-separated list of holder tags (`bundler`, `sniper`, `insider`, `dev`,
                `smart_trader`) to restrict the result to wallets carrying at least one of the
                tags; `None` returns all wallets regardless of tags.
            order_type: ascending or descending order on the underlying `amount` sort field
                (the only metric the API supports today). Pick one of the constants on
                [`BirdeyeOrder`][cyhole.birdeye.param.BirdeyeOrder]. Default behaviour: `desc`.
            ui_amount_mode: how to format scaled-UI-amount token figures. Pick a
                [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode] member or leave
                `None` for the server default (`raw`).
            include_zero_balance: when `True` (the API default) wallets with zero current balance
                are kept in the result; set to `False` to exclude them. `None` defers to the
                server default.
            offset: zero-based pagination offset. Default behaviour: `0`.
            limit: number of records to return. Default behaviour: `50`.

        Returns:
            paginated list of per-wallet positions decoded as
            [`GetTokenHolderPositionsResponse`][cyhole.birdeye.schema.GetTokenHolderPositionsResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    BirdeyeOrder.check(order_type)
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    url = self.url_api_token_v1 + "holder-positions"
    params = {
        "token_address": token_address,
        "labels": labels,
        "sort_by": "amount",
        "order_type": order_type,
        "ui_amount_mode": ui_amount_mode,
        "include_zero_balance": str(include_zero_balance).lower() if include_zero_balance is not None else None,
        "offset": offset,
        "limit": limit,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetTokenHolderPositionsResponse, params = params)

_get_token_holder_chart

_get_token_holder_chart(
    sync: Literal[True],
    token_address: str,
    chart_type: str = BirdeyeHolderChartType.H1.value,
    time_from: int | None = None,
    time_to: int | None = None,
    mode: str = BirdeyeHolderChartMode.PADDING.value,
    percent_mode: str = BirdeyeHolderChartPercentMode.BEGINNING.value,
    count: int | None = None,
) -> GetTokenHolderChartResponse

_get_token_holder_chart(
    sync: Literal[False],
    token_address: str,
    chart_type: str = BirdeyeHolderChartType.H1.value,
    time_from: int | None = None,
    time_to: int | None = None,
    mode: str = BirdeyeHolderChartMode.PADDING.value,
    percent_mode: str = BirdeyeHolderChartPercentMode.BEGINNING.value,
    count: int | None = None,
) -> Coroutine[None, None, GetTokenHolderChartResponse]

_get_token_holder_chart(
    sync: bool,
    token_address: str,
    chart_type: str = BirdeyeHolderChartType.H1.value,
    time_from: int | None = None,
    time_to: int | None = None,
    mode: str = BirdeyeHolderChartMode.PADDING.value,
    percent_mode: str = BirdeyeHolderChartPercentMode.BEGINNING.value,
    count: int | None = None,
) -> (
    GetTokenHolderChartResponse
    | Coroutine[None, None, GetTokenHolderChartResponse]
)

This function refers to the PRIVATE API endpoint Token - Holder Chart and is used to retrieve a time-series of holder-count snapshots for a given token, suitable for plotting "holders over time" charts. Each data point exposes the absolute holder count and both an absolute (net_change) and relative (percent_change) delta versus the chosen reference (window beginning or previous point).

Info

The endpoint is restricted by Birdeye to the Solana chain at the time of writing.

Parameters:

Name	Type	Description	Default
token_address	str	contract address of the SPL token whose holder chart must be retrieved.	required
chart_type	str	resolution of the chart points. Pick one of the constants on BirdeyeHolderChartType. Default behaviour: 1h.	BirdeyeHolderChartType.H1.value
time_from	int | None	optional inclusive lower bound on the data-point timestamp, in unix seconds. None lets Birdeye pick the start of the window.	None
time_to	int | None	optional inclusive upper bound on the data-point timestamp, in unix seconds. None lets Birdeye pick the end of the window (typically "now").	None
mode	str	how Birdeye handles missing data points. Pick one of the constants on BirdeyeHolderChartMode. Default behaviour: padding.	BirdeyeHolderChartMode.PADDING.value
percent_mode	str	reference point for percent_change. Pick one of the constants on BirdeyeHolderChartPercentMode. Default behaviour: beginning.	BirdeyeHolderChartPercentMode.BEGINNING.value
count	int | None	maximum number of data points to return. Default behaviour: 20.	None

Returns:

Type	Description
GetTokenHolderChartResponse | Coroutine[None, None, GetTokenHolderChartResponse]	time-series of holder-count points decoded as
GetTokenHolderChartResponse | Coroutine[None, None, GetTokenHolderChartResponse]	GetTokenHolderChartResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_holder_chart(
    self,
    sync: bool,
    token_address: str,
    chart_type: str = BirdeyeHolderChartType.H1.value,
    time_from: int | None = None,
    time_to: int | None = None,
    mode: str = BirdeyeHolderChartMode.PADDING.value,
    percent_mode: str = BirdeyeHolderChartPercentMode.BEGINNING.value,
    count: int | None = None
) -> GetTokenHolderChartResponse | Coroutine[None, None, GetTokenHolderChartResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Holder Chart](https://docs.birdeye.so/reference/get-token-v1-holder-chart)** and is used
        to retrieve a time-series of holder-count snapshots for a given token, suitable for
        plotting "holders over time" charts. Each data point exposes the absolute holder count
        and both an absolute (`net_change`) and relative (`percent_change`) delta versus the
        chosen reference (window beginning or previous point).

        !!! info
            The endpoint is restricted by Birdeye to the **Solana** chain at the time of writing.

        Parameters:
            token_address: contract address of the SPL token whose holder chart must be retrieved.
            chart_type: resolution of the chart points. Pick one of the constants on
                [`BirdeyeHolderChartType`][cyhole.birdeye.param.BirdeyeHolderChartType].
                Default behaviour: `1h`.
            time_from: optional inclusive lower bound on the data-point timestamp, in unix seconds.
                `None` lets Birdeye pick the start of the window.
            time_to: optional inclusive upper bound on the data-point timestamp, in unix seconds.
                `None` lets Birdeye pick the end of the window (typically "now").
            mode: how Birdeye handles missing data points. Pick one of the constants on
                [`BirdeyeHolderChartMode`][cyhole.birdeye.param.BirdeyeHolderChartMode].
                Default behaviour: `padding`.
            percent_mode: reference point for `percent_change`. Pick one of the constants on
                [`BirdeyeHolderChartPercentMode`][cyhole.birdeye.param.BirdeyeHolderChartPercentMode].
                Default behaviour: `beginning`.
            count: maximum number of data points to return. Default behaviour: `20`.

        Returns:
            time-series of holder-count points decoded as
            [`GetTokenHolderChartResponse`][cyhole.birdeye.schema.GetTokenHolderChartResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    BirdeyeHolderChartType.check(chart_type)
    BirdeyeHolderChartMode.check(mode)
    BirdeyeHolderChartPercentMode.check(percent_mode)

    url = self.url_api_token_v1 + "holder/chart"
    params = {
        "token_address": token_address,
        "chart_type": chart_type,
        "from": time_from,
        "to": time_to,
        "mode": mode,
        "percent_mode": percent_mode,
        "count": count,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetTokenHolderChartResponse, params = params)

_post_token_transfer

_post_token_transfer(
    sync: Literal[True], body: PostTokenTransferBody
) -> PostTokenTransferResponse

_post_token_transfer(
    sync: Literal[False], body: PostTokenTransferBody
) -> Coroutine[None, None, PostTokenTransferResponse]

_post_token_transfer(
    sync: bool, body: PostTokenTransferBody
) -> (
    PostTokenTransferResponse
    | Coroutine[None, None, PostTokenTransferResponse]
)

This function refers to the PRIVATE API endpoint Token - Transfer List and is used to retrieve the list of on-chain transfer transactions of a given SPL token, optionally filtered by time window, transferred amount, USD value, and either side wallet address. Each entry exposes the sender / receiver wallet and SPL token account, raw and UI-formatted amount, per-token price, total USD value, slot/block and timestamp. Pagination is cursor-based: pass the cursor returned by Birdeye on the previous call via body.cursor to fetch the next page.

Info

The endpoint is restricted by Birdeye to the Solana chain at the time of writing.

Parameters:

Name	Type	Description	Default
body	PostTokenTransferBody	filled-in PostTokenTransferBody instance carrying the required token_address and any optional filters and the pagination cursor/limit.	required

Returns:

Type	Description
PostTokenTransferResponse | Coroutine[None, None, PostTokenTransferResponse]	paginated list of transfer entries decoded as
PostTokenTransferResponse | Coroutine[None, None, PostTokenTransferResponse]	PostTokenTransferResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _post_token_transfer(
    self,
    sync: bool,
    body: PostTokenTransferBody
) -> PostTokenTransferResponse | Coroutine[None, None, PostTokenTransferResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Transfer List](https://docs.birdeye.so/reference/post-token-v1-transfer)** and is used
        to retrieve the list of on-chain transfer transactions of a given SPL token, optionally
        filtered by time window, transferred amount, USD value, and either side wallet address.
        Each entry exposes the sender / receiver wallet and SPL token account, raw and
        UI-formatted amount, per-token price, total USD value, slot/block and timestamp.
        Pagination is cursor-based: pass the cursor returned by Birdeye on the previous call
        via `body.cursor` to fetch the next page.

        !!! info
            The endpoint is restricted by Birdeye to the **Solana** chain at the time of writing.

        Parameters:
            body: filled-in [`PostTokenTransferBody`][cyhole.birdeye.schema.PostTokenTransferBody]
                instance carrying the required `token_address` and any optional filters and the
                pagination cursor/limit.

        Returns:
            paginated list of transfer entries decoded as
            [`PostTokenTransferResponse`][cyhole.birdeye.schema.PostTokenTransferResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
    """
    url = self.url_api_token_v1 + "transfer"
    headers = self.headers.copy()
    headers["content-type"] = "application/json"

    return self.api_return_model(
        sync,
        RequestType.POST.value,
        url,
        PostTokenTransferResponse,
        json = body.model_dump(exclude_none = True),
        headers = headers,
    )

_post_token_transfer_total

_post_token_transfer_total(
    sync: Literal[True], body: PostTokenTransferTotalBody
) -> PostTokenTransferTotalResponse

_post_token_transfer_total(
    sync: Literal[False], body: PostTokenTransferTotalBody
) -> Coroutine[None, None, PostTokenTransferTotalResponse]

_post_token_transfer_total(
    sync: bool, body: PostTokenTransferTotalBody
) -> (
    PostTokenTransferTotalResponse
    | Coroutine[None, None, PostTokenTransferTotalResponse]
)

This function refers to the PRIVATE API endpoint Token - Transfer Total and is used to return the count of SPL token transfer transactions of a given token matching the same filter set as the Transfer List endpoint (time window, transferred amount, USD value, sender / receiver wallet). It is the cheap counterpart of _post_token_transfer when only the aggregate count is needed (no individual entries, no pagination).

Info

The endpoint is restricted by Birdeye to the Solana chain at the time of writing.

Parameters:

Name	Type	Description	Default
body	PostTokenTransferTotalBody	filled-in PostTokenTransferTotalBody instance carrying the required token_address and any optional filters.	required

Returns:

Type	Description
PostTokenTransferTotalResponse | Coroutine[None, None, PostTokenTransferTotalResponse]	aggregate count payload decoded as
PostTokenTransferTotalResponse | Coroutine[None, None, PostTokenTransferTotalResponse]	PostTokenTransferTotalResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _post_token_transfer_total(
    self,
    sync: bool,
    body: PostTokenTransferTotalBody
) -> PostTokenTransferTotalResponse | Coroutine[None, None, PostTokenTransferTotalResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Transfer Total](https://docs.birdeye.so/reference/post-token-v1-transfer-total)** and is used
        to return the **count** of SPL token transfer transactions of a given token matching the
        same filter set as the Transfer List endpoint (time window, transferred amount, USD
        value, sender / receiver wallet). It is the cheap counterpart of
        [`_post_token_transfer`][cyhole.birdeye.interaction.Birdeye._post_token_transfer] when
        only the aggregate count is needed (no individual entries, no pagination).

        !!! info
            The endpoint is restricted by Birdeye to the **Solana** chain at the time of writing.

        Parameters:
            body: filled-in [`PostTokenTransferTotalBody`][cyhole.birdeye.schema.PostTokenTransferTotalBody]
                instance carrying the required `token_address` and any optional filters.

        Returns:
            aggregate count payload decoded as
            [`PostTokenTransferTotalResponse`][cyhole.birdeye.schema.PostTokenTransferTotalResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
    """
    url = self.url_api_token_v1 + "transfer/total"
    headers = self.headers.copy()
    headers["content-type"] = "application/json"

    return self.api_return_model(
        sync,
        RequestType.POST.value,
        url,
        PostTokenTransferTotalResponse,
        json = body.model_dump(exclude_none = True),
        headers = headers,
    )

_get_token_trending

_get_token_trending(
    sync: Literal[True],
    sort_by: str = BirdeyeTokenTrendingSortBy.RANK.value,
    sort_type: str = BirdeyeOrder.ASCENDING.value,
    interval: str = BirdeyeTokenTrendingInterval.H24.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> GetTokenTrendingResponse

_get_token_trending(
    sync: Literal[False],
    sort_by: str = BirdeyeTokenTrendingSortBy.RANK.value,
    sort_type: str = BirdeyeOrder.ASCENDING.value,
    interval: str = BirdeyeTokenTrendingInterval.H24.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetTokenTrendingResponse]

_get_token_trending(
    sync: bool,
    sort_by: str = BirdeyeTokenTrendingSortBy.RANK.value,
    sort_type: str = BirdeyeOrder.ASCENDING.value,
    interval: str = BirdeyeTokenTrendingInterval.H24.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None,
) -> (
    GetTokenTrendingResponse
    | Coroutine[None, None, GetTokenTrendingResponse]
)

This function refers to the PRIVATE API endpoint Token - Trending List and is used to retrieve Birdeye's up-to-date ranking of trending tokens on the selected chain. Each entry exposes the trending rank, identity, current price, liquidity, market cap, FDV and the 24h USD volume / price change figures. Useful when surfacing "what is hot right now" on a token discovery UI.

Parameters:

Name	Type	Description	Default
sort_by	str	ranking metric. Pick one of the constants on BirdeyeTokenTrendingSortBy. Default behaviour: rank (i.e. Birdeye's own ordering).	BirdeyeTokenTrendingSortBy.RANK.value
sort_type	str	ascending or descending order. Pick one of the constants on BirdeyeOrder. Default behaviour: asc (so position 1 — most trending — comes first).	BirdeyeOrder.ASCENDING.value
interval	str	trailing window used for the trending computation. Pick one of the constants on BirdeyeTokenTrendingInterval. Default behaviour: 24h.	BirdeyeTokenTrendingInterval.H24.value
offset	int | None	zero-based pagination offset. Default behaviour: 0.	None
limit	int | None	number of records to return per page. Default behaviour: 20.	None
ui_amount_mode	str | None	how to format scaled-UI-amount token figures on Solana. Pick a BirdeyeUIAmountMode member or leave None for the server default (scaled).	None

Returns:

Type	Description
GetTokenTrendingResponse | Coroutine[None, None, GetTokenTrendingResponse]	trending-list payload decoded as
GetTokenTrendingResponse | Coroutine[None, None, GetTokenTrendingResponse]	GetTokenTrendingResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_trending(
    self,
    sync: bool,
    sort_by: str = BirdeyeTokenTrendingSortBy.RANK.value,
    sort_type: str = BirdeyeOrder.ASCENDING.value,
    interval: str = BirdeyeTokenTrendingInterval.H24.value,
    offset: int | None = None,
    limit: int | None = None,
    ui_amount_mode: str | None = None
) -> GetTokenTrendingResponse | Coroutine[None, None, GetTokenTrendingResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Trending List](https://docs.birdeye.so/reference/get-defi-token_trending)** and is used
        to retrieve Birdeye's up-to-date ranking of trending tokens on the selected chain. Each
        entry exposes the trending rank, identity, current price, liquidity, market cap, FDV
        and the 24h USD volume / price change figures. Useful when surfacing "what is hot right
        now" on a token discovery UI.

        Parameters:
            sort_by: ranking metric. Pick one of the constants on
                [`BirdeyeTokenTrendingSortBy`][cyhole.birdeye.param.BirdeyeTokenTrendingSortBy].
                Default behaviour: `rank` (i.e. Birdeye's own ordering).
            sort_type: ascending or descending order. Pick one of the constants on
                [`BirdeyeOrder`][cyhole.birdeye.param.BirdeyeOrder]. Default behaviour: `asc`
                (so position 1 — most trending — comes first).
            interval: trailing window used for the trending computation. Pick one of the
                constants on [`BirdeyeTokenTrendingInterval`][cyhole.birdeye.param.BirdeyeTokenTrendingInterval].
                Default behaviour: `24h`.
            offset: zero-based pagination offset. Default behaviour: `0`.
            limit: number of records to return per page. Default behaviour: `20`.
            ui_amount_mode: how to format scaled-UI-amount token figures on Solana. Pick a
                [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode] member or leave
                `None` for the server default (`scaled`).

        Returns:
            trending-list payload decoded as
            [`GetTokenTrendingResponse`][cyhole.birdeye.schema.GetTokenTrendingResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    BirdeyeTokenTrendingSortBy.check(sort_by)
    BirdeyeOrder.check(sort_type)
    BirdeyeTokenTrendingInterval.check(interval)
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    url = self.url_api_public + "token_trending"
    params = {
        "sort_by": sort_by,
        "sort_type": sort_type,
        "interval": interval,
        "offset": offset,
        "limit": limit,
        "ui_amount_mode": ui_amount_mode,
    }

    return self.api_return_model(sync, RequestType.GET.value, url, GetTokenTrendingResponse, params = params)

_get_token_creation_info

_get_token_creation_info(
    sync: Literal[True], address: str
) -> GetTokenCreationInfoResponse

_get_token_creation_info(
    sync: Literal[False], address: str
) -> Coroutine[None, None, GetTokenCreationInfoResponse]

_get_token_creation_info(
    sync: bool, address: str
) -> (
    GetTokenCreationInfoResponse
    | Coroutine[None, None, GetTokenCreationInfoResponse]
)

This function refers to the PRIVATE API endpoint Token - Creation Token Info and is used to retrieve the on-chain transaction that originally minted a given token together with its slot, block timestamp (both unix and human-readable), creator/owner address and decimals. It is the canonical way to answer "when and by whom was this token created?" on Birdeye-supported chains and is typically used as part of a token vetting flow (age check, deployer profiling).

Info

Currently the endpoint is restricted by Birdeye to the Solana, BSC, Base, Ethereum and Monad chains.

Parameters:

Name	Type	Description	Default
address	str	contract address of the token whose creation information must be retrieved.	required

Returns:

Type	Description
GetTokenCreationInfoResponse | Coroutine[None, None, GetTokenCreationInfoResponse]	creation transaction hash, slot, block timestamps, creator/owner address and decimals.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_creation_info(
    self,
    sync: bool,
    address: str
) -> GetTokenCreationInfoResponse | Coroutine[None, None, GetTokenCreationInfoResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Creation Token Info](https://docs.birdeye.so/reference/get-defi-token_creation_info)** and is used
        to retrieve the on-chain transaction that originally minted a given token together with its
        slot, block timestamp (both unix and human-readable), creator/owner address and decimals.
        It is the canonical way to answer "when and by whom was this token created?" on Birdeye-supported
        chains and is typically used as part of a token vetting flow (age check, deployer profiling).

        !!! info
            Currently the endpoint is restricted by Birdeye to the Solana, BSC, Base, Ethereum and Monad chains.

        Parameters:
            address: contract address of the token whose creation information must be retrieved.

        Returns:
            creation transaction hash, slot, block timestamps, creator/owner address and decimals.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # set params
    url = self.url_api_public + "token_creation_info"
    params = {
        "address" : address
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetTokenCreationInfoResponse, params = params)

_get_token_security

_get_token_security(
    sync: Literal[True], address: str
) -> GetTokenSecurityResponse

_get_token_security(
    sync: Literal[False], address: str
) -> Coroutine[None, None, GetTokenSecurityResponse]

_get_token_security(
    sync: bool, address: str
) -> (
    GetTokenSecurityResponse
    | Coroutine[None, None, GetTokenSecurityResponse]
)

This function refers to the PRIVATE API endpoint Token - Security and is used to retrieve Birdeye's risk profile of a token: ownership and authority addresses, creator/owner balances, top-holder concentration, freeze/mint/Token-2022 flags, lock information and metadata mutability. It is the canonical endpoint behind Birdeye's "is this token safe?" checks and is typically consumed when surfacing scam/rug warnings before showing a swap UI.

Info

The endpoint is available on every Birdeye chain except Sui. The response payload differs between Solana (typed schema below) and EVM chains (free-form dictionary).

Parameters:

Name	Type	Description	Default
address	str	contract address of the token to analyse on the currently selected chain.	required

Returns:

Type	Description
GetTokenSecurityResponse | Coroutine[None, None, GetTokenSecurityResponse]	security profile of the token. Observe that the content of data depends on the selected chain: on Solana the payload is decoded as GetTokenSecurityDataSolana; on other chains it is exposed as a raw dictionary.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_security(
    self,
    sync: bool,
    address: str
) -> GetTokenSecurityResponse | Coroutine[None, None, GetTokenSecurityResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Security](https://docs.birdeye.so/reference/get-defi-token_security)** and is used
        to retrieve Birdeye's risk profile of a token: ownership and authority addresses, creator/owner
        balances, top-holder concentration, freeze/mint/Token-2022 flags, lock information and
        metadata mutability. It is the canonical endpoint behind Birdeye's "is this token safe?"
        checks and is typically consumed when surfacing scam/rug warnings before showing a swap UI.

        !!! info
            The endpoint is available on every Birdeye chain except Sui. The response payload
            differs between Solana (typed schema below) and EVM chains (free-form dictionary).

        Parameters:
            address: contract address of the token to analyse on the currently selected chain.

        Returns:
            security profile of the token.
                Observe that the content of `data` depends on the selected chain: on Solana the
                payload is decoded as
                [`GetTokenSecurityDataSolana`][cyhole.birdeye.schema.GetTokenSecurityDataSolana];
                on other chains it is exposed as a raw dictionary.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # set params
    url = self.url_api_public + "token_security"
    params = {
        "address" : address
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetTokenSecurityResponse, params = params)

_get_token_overview

_get_token_overview(
    sync: Literal[True],
    address: str,
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> GetTokenOverviewResponse

_get_token_overview(
    sync: Literal[False],
    address: str,
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetTokenOverviewResponse]

_get_token_overview(
    sync: bool,
    address: str,
    frames: str | None = None,
    ui_amount_mode: str | None = None,
) -> (
    GetTokenOverviewResponse
    | Coroutine[None, None, GetTokenOverviewResponse]
)

This function refers to the PRIVATE API endpoint Token - Overview and is used to retrieve Birdeye's full analytics snapshot of a single token: identity (address, symbol, name, social links), pricing (current price and per-window history at 1m/5m/30m/1h/2h/4h/6h/8h/12h/24h), liquidity, supply (total, circulating, holders count), unique-wallet counts and per-side trade activity (sell, buy, volume in both token-UI units and USD) for the trailing 1m/5m/30m/1h/2h/4h/8h/24h windows together with the equivalent metric over the previous window and a precomputed percent change. It is the canonical endpoint behind Birdeye's token detail page and is normally used as the "give me everything you know about this token" call.

Parameters:

Name	Type	Description	Default
address	str	contract address of the token whose analytics snapshot must be retrieved.	required
frames	str | None	comma-separated list of additional custom time intervals to include in the response (up to 8 entries). Birdeye accepts minute intervals from 1m to 1440m, second intervals in multiples of 5 from 5s to 3600s, and hour intervals among 1h, 2h, 4h, 8h and 24h. Default behaviour: only the standard windows listed above are returned.	None
ui_amount_mode	str | None	how to format scaled-UI-amount token figures on Solana. The supported values are available on BirdeyeUIAmountMode. Only applies on Solana; ignored on other chains. Default behaviour: scaled.	None

Returns:

Type	Description
GetTokenOverviewResponse | Coroutine[None, None, GetTokenOverviewResponse]	token analytics snapshot decoded as GetTokenOverviewData.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_token_overview(
    self,
    sync: bool,
    address: str,
    frames: str | None = None,
    ui_amount_mode: str | None = None
) -> GetTokenOverviewResponse | Coroutine[None, None, GetTokenOverviewResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Token - Overview](https://docs.birdeye.so/reference/get-defi-token_overview)** and is used
        to retrieve Birdeye's full analytics snapshot of a single token: identity (address, symbol,
        name, social links), pricing (current price and per-window history at 1m/5m/30m/1h/2h/4h/6h/8h/12h/24h),
        liquidity, supply (total, circulating, holders count), unique-wallet counts and
        per-side trade activity (sell, buy, volume in both token-UI units and USD) for the trailing
        1m/5m/30m/1h/2h/4h/8h/24h windows together with the equivalent metric over the previous window
        and a precomputed percent change. It is the canonical endpoint behind Birdeye's token detail
        page and is normally used as the "give me everything you know about this token" call.

        Parameters:
            address: contract address of the token whose analytics snapshot must be retrieved.
            frames: comma-separated list of additional custom time intervals to include in the
                response (up to 8 entries). Birdeye accepts minute intervals from `1m` to `1440m`,
                second intervals in multiples of 5 from `5s` to `3600s`, and hour intervals among
                `1h`, `2h`, `4h`, `8h` and `24h`. Default behaviour: only the standard windows
                listed above are returned.
            ui_amount_mode: how to format scaled-UI-amount token figures on Solana.
                The supported values are available on [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode].
                Only applies on Solana; ignored on other chains. Default behaviour: `scaled`.

        Returns:
            token analytics snapshot decoded as [`GetTokenOverviewData`][cyhole.birdeye.schema.GetTokenOverviewData].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # check param consistency
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    # set params
    url = self.url_api_public + "token_overview"
    params = {
        "address" : address,
        "frames" : frames,
        "ui_amount_mode" : ui_amount_mode
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetTokenOverviewResponse, params = params)

_get_price

_get_price(
    sync: Literal[True],
    address: str,
    include_liquidity: bool | None = None,
) -> GetPriceResponse

_get_price(
    sync: Literal[False],
    address: str,
    include_liquidity: bool | None = None,
) -> Coroutine[None, None, GetPriceResponse]

_get_price(
    sync: bool,
    address: str,
    include_liquidity: bool | None = None,
) -> (
    GetPriceResponse
    | Coroutine[None, None, GetPriceResponse]
)

This function refers to the PUBLIC API endpoint Price and is used to get the current price of a token according on a specific chain on Birdeye.

Parameters:

Name	Type	Description	Default
address	str	CA of the token to search on the chain.	required
include_liquidity	bool | None	include the current liquidity of the token. Default Value: None (False)	None

Returns:

Type	Description
GetPriceResponse | Coroutine[None, None, GetPriceResponse]	token's price returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_price(
    self,
    sync: bool,
    address: str,
    include_liquidity: bool | None = None
) -> GetPriceResponse | Coroutine[None, None, GetPriceResponse]:
    """
        This function refers to the **PUBLIC** API endpoint **[Price](https://docs.birdeye.so/reference/get_defi-price)** and is used 
        to get the current price of a token according on a specific chain on Birdeye.

        Parameters:
            address: CA of the token to search on the chain.
            include_liquidity: include the current liquidity of the token.
                Default Value: `None` (`False`)

        Returns:
            token's price returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """        # set params
    url = self.url_api_public + "price"
    params = {
        "address" : address,
        "include_liquidity" : str(include_liquidity).lower() if include_liquidity else None
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetPriceResponse, params = params)

_get_price_multiple

_get_price_multiple(
    sync: Literal[True],
    list_address: list[str],
    include_liquidity: bool | None = None,
) -> GetPriceMultipleResponse

_get_price_multiple(
    sync: Literal[False],
    list_address: list[str],
    include_liquidity: bool | None = None,
) -> Coroutine[None, None, GetPriceMultipleResponse]

_get_price_multiple(
    sync: bool,
    list_address: list[str],
    include_liquidity: bool | None = None,
) -> (
    GetPriceMultipleResponse
    | Coroutine[None, None, GetPriceMultipleResponse]
)

This function refers to the PRIVATE API endpoint Price - Multiple and is used to get the current price of multeple tokens on a specific chain on Birdeye.

Parameters:

Name	Type	Description	Default
list_address	list[str]	CA of the tokens to search on the chain.	required
include_liquidity	bool | None	include the current liquidity of the token. Default Value: None (False)	None

Returns:

Type	Description
GetPriceMultipleResponse | Coroutine[None, None, GetPriceMultipleResponse]	list of tokens returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_price_multiple(
    self,
    sync: bool,
    list_address: list[str],
    include_liquidity: bool | None = None
) -> GetPriceMultipleResponse | Coroutine[None, None, GetPriceMultipleResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Price - Multiple](https://docs.birdeye.so/reference/get_defi-multi-price)** and is used 
        to get the current price of multeple tokens on a specific chain on Birdeye.

        Parameters:
            list_address: CA of the tokens to search on the chain.
            include_liquidity: include the current liquidity of the token.
                Default Value: `None` (`False`)

        Returns:
            list of tokens returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # set params
    url = self.url_api_public + "multi_price"
    params = {
        "list_address" : ",".join(list_address),
        "include_liquidity" : str(include_liquidity).lower() if include_liquidity else None
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetPriceMultipleResponse, params = params)

_get_price_historical

_get_price_historical(
    sync: Literal[True],
    address: str,
    address_type: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
) -> GetPriceHistoricalResponse

_get_price_historical(
    sync: Literal[False],
    address: str,
    address_type: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
) -> Coroutine[None, None, GetPriceHistoricalResponse]

_get_price_historical(
    sync: bool,
    address: str,
    address_type: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
) -> (
    GetPriceHistoricalResponse
    | Coroutine[None, None, GetPriceHistoricalResponse]
)

This function refers to the PUBLIC API endpoint Price - Historical and is used to get the history of prices of a token according on a specific chain on Birdeye.

Parameters:

Name	Type	Description	Default
address	str	CA of the token to search on the chain.	required
address_type	str	the type of address involved in the extraction. The supported chains are available on BirdeyeAddressType. Import them from the library to use the correct identifier.	required
timeframe	str	the type of timeframe involved in the extraction. The timeframe is used to define intervall between a measure and the next one. The supported chains are available on BirdeyeTimeFrame. Import them from the library to use the correct identifier.	required
dt_from	datetime	beginning time to take take price data.	required
dt_to	datetime | None	end time to take take price data. It should be dt_from < dt_to. If not ptovided (None), the current time is used.	None

Returns:

Type	Description
GetPriceHistoricalResponse | Coroutine[None, None, GetPriceHistoricalResponse]	list of prices returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_price_historical(
    self,
    sync: bool,
    address: str,
    address_type: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None
) -> GetPriceHistoricalResponse | Coroutine[None, None, GetPriceHistoricalResponse]:
    """
        This function refers to the **PUBLIC** API endpoint **[Price - Historical](https://docs.birdeye.so/reference/get_defi-history-price)** and is used 
        to get the history of prices of a token according on a specific chain on Birdeye.

        Parameters:
            address: CA of the token to search on the chain.
            address_type: the type of address involved in the extraction.
                The supported chains are available on [`BirdeyeAddressType`][cyhole.birdeye.param.BirdeyeAddressType].
                Import them from the library to use the correct identifier.
            timeframe: the type of timeframe involved in the extraction.
                The timeframe is used to define intervall between a measure and the next one.
                The supported chains are available on [`BirdeyeTimeFrame`][cyhole.birdeye.param.BirdeyeTimeFrame].
                Import them from the library to use the correct identifier.
            dt_from: beginning time to take take price data.
            dt_to: end time to take take price data.
                It should be `dt_from` < `dt_to`.
                If not ptovided (None), the current time is used.

        Returns:
            list of prices returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # check param consistency
    BirdeyeAddressType.check(address_type)
    BirdeyeTimeFrame.check(timeframe)

    # set default
    if dt_to is None:
        dt_to = datetime.now()

    # check consistency
    if dt_from > dt_to:
        raise BirdeyeTimeRangeError("Inconsistent timewindow provided: 'dt_from' > 'dt_to'")

    # set params
    url = self.url_api_public + "history_price"
    params = {
        "address" : address,
        "address_type" : address_type,
        "type" : timeframe,
        "time_from" : int(dt_from.timestamp()),
        "time_to" : int(dt_to.timestamp())
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetPriceHistoricalResponse, params = params)

_get_price_volume_single

_get_price_volume_single(
    sync: Literal[True],
    address: str,
    timeframe: str = BirdeyeHourTimeFrame.H24.value,
) -> GetPriceVolumeSingleResponse

_get_price_volume_single(
    sync: Literal[False],
    address: str,
    timeframe: str = BirdeyeHourTimeFrame.H24.value,
) -> Coroutine[None, None, GetPriceVolumeSingleResponse]

_get_price_volume_single(
    sync: bool,
    address: str,
    timeframe: str = BirdeyeHourTimeFrame.H24.value,
) -> (
    GetPriceVolumeSingleResponse
    | Coroutine[None, None, GetPriceVolumeSingleResponse]
)

This function refers to the PRIVATE API endpoint Price Volume - Single Token and is used to get the current price and volume data for a specified token over a given time period on Birdeye.

Parameters:

Name	Type	Description	Default
address	str	CA of the token to search on the chain.	required
timeframe	str	the type of timeframe involved in the extraction. The timeframe is used to define intervall between a measure and the next one. The supported timeframes are available on BirdeyeHourTimeFrame. Import them from the library to use the correct identifier.	BirdeyeHourTimeFrame.H24.value

Returns:

Type	Description
GetPriceVolumeSingleResponse | Coroutine[None, None, GetPriceVolumeSingleResponse]	current price and volume data for a specified token over a given time period.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is not aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_price_volume_single(self, sync: bool, address: str, timeframe: str = BirdeyeHourTimeFrame.H24.value) -> GetPriceVolumeSingleResponse | Coroutine[None, None, GetPriceVolumeSingleResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Price Volume - Single Token](https://docs.birdeye.so/reference/get_defi-price-volume-single)** and is used 
        to get the current price and volume data for a specified token over a given time period on Birdeye.

        Parameters:
            address: CA of the token to search on the chain.
            timeframe: the type of timeframe involved in the extraction.
                The timeframe is used to define intervall between a measure and the next one.
                The supported timeframes are available on [`BirdeyeHourTimeFrame`][cyhole.birdeye.param.BirdeyeHourTimeFrame].
                Import them from the library to use the correct identifier.

        Returns:
            current price and volume data for a specified token over a given time period.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is not aligned to it.
    """
    # check param consistency
    BirdeyeHourTimeFrame.check(timeframe)

    # set params
    url = self.url_api_private + "price_volume/single"
    params = {
        "address" : address,
        "type" : timeframe
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetPriceVolumeSingleResponse, params = params)

_post_price_volume_multi

_post_price_volume_multi(
    sync: Literal[True],
    list_address: list[str],
    timeframe: str = BirdeyeHourTimeFrame.H24.value,
) -> PostPriceVolumeMultiResponse

_post_price_volume_multi(
    sync: Literal[False],
    list_address: list[str],
    timeframe: str = BirdeyeHourTimeFrame.H24.value,
) -> Coroutine[None, None, PostPriceVolumeMultiResponse]

_post_price_volume_multi(
    sync: bool,
    list_address: list[str],
    timeframe: str = BirdeyeHourTimeFrame.H24.value,
) -> (
    PostPriceVolumeMultiResponse
    | Coroutine[None, None, PostPriceVolumeMultiResponse]
)

This function refers to the PRIVATE API endpoint Price Volume - Multiple Token and is used to get the current price and volume data for multiple tokens over a given time period on Birdeye.

Parameters:

Name	Type	Description	Default
list_address	list[str]	list of CA of the tokens to search on the chain.	required
timeframe	str	the type of timeframe involved in the extraction. The timeframe is used to define intervall between a measure and the next one. The supported timeframes are available on BirdeyeHourTimeFrame. Import them from the library to use the correct identifier.	BirdeyeHourTimeFrame.H24.value

Returns:

Type	Description
PostPriceVolumeMultiResponse | Coroutine[None, None, PostPriceVolumeMultiResponse]	current price and volume data for multiple tokens over a given time period.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is not aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _post_price_volume_multi(self, sync: bool, list_address: list[str], timeframe: str = BirdeyeHourTimeFrame.H24.value) -> PostPriceVolumeMultiResponse | Coroutine[None, None, PostPriceVolumeMultiResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Price Volume - Multiple Token](https://docs.birdeye.so/reference/post_defi-price-volume-multi)** and is used 
        to get the current price and volume data for multiple tokens over a given time period on Birdeye.

        Parameters:
            list_address: list of CA of the tokens to search on the chain.
            timeframe: the type of timeframe involved in the extraction.
                The timeframe is used to define intervall between a measure and the next one.
                The supported timeframes are available on [`BirdeyeHourTimeFrame`][cyhole.birdeye.param.BirdeyeHourTimeFrame].
                Import them from the library to use the correct identifier.

        Returns:
            current price and volume data for multiple tokens over a given time period.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is not aligned to it.
    """
    # check param consistency
    BirdeyeHourTimeFrame.check(timeframe)

    # set params
    url = self.url_api_private + "price_volume/multi"

    # set headers
    headers = self.headers.copy()
    headers["content-type"] = "application/json"

    # set body
    body = {
        "list_address" : ",".join(list_address),
        "type" : timeframe
    }

    # execute request
    return self.api_return_model(sync, RequestType.POST.value, url, PostPriceVolumeMultiResponse, json = body, headers = headers)

_get_trades_token

_get_trades_token(
    sync: Literal[True],
    address: str,
    trade_type: str = BirdeyeTradeType.SWAP.value,
    offset: int | None = None,
    limit: int | None = None,
) -> GetTradesTokenResponse

_get_trades_token(
    sync: Literal[False],
    address: str,
    trade_type: str = BirdeyeTradeType.SWAP.value,
    offset: int | None = None,
    limit: int | None = None,
) -> Coroutine[None, None, GetTradesTokenResponse]

_get_trades_token(
    sync: bool,
    address: str,
    trade_type: str = BirdeyeTradeType.SWAP.value,
    offset: int | None = None,
    limit: int | None = None,
) -> (
    GetTradesTokenResponse
    | Coroutine[None, None, GetTradesTokenResponse]
)

This function refers to the PRIVATE API endpoint Trades - Token and is used to get the associated trades of a token according on a specific chain on Birdeye.

Parameters:

Name	Type	Description	Default
address	str	CA of the token to search on the chain.	required
trade_type	str	the type of transactions to extract. The supported chains are available on BirdeyeTradeType. Import them from the library to use the correct identifier.	BirdeyeTradeType.SWAP.value
offset	int | None	offset to apply in the extraction.	None
limit	int | None	limit the number of returned records in the extraction.	None

Returns:

Type	Description
GetTradesTokenResponse | Coroutine[None, None, GetTradesTokenResponse]	list of prices returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_trades_token(
        self,
        sync: bool,
        address: str,
        trade_type: str = BirdeyeTradeType.SWAP.value,
        offset: int | None = None,
        limit: int | None = None
) -> GetTradesTokenResponse | Coroutine[None, None, GetTradesTokenResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Trades - Token](https://docs.birdeye.so/reference/get_defi-txs-token)** and is used 
        to get the associated trades of a token according on a specific chain on Birdeye.

        Parameters:
            address: CA of the token to search on the chain.
            trade_type: the type of transactions to extract.
                The supported chains are available on [`BirdeyeTradeType`][cyhole.birdeye.param.BirdeyeTradeType].
                Import them from the library to use the correct identifier.
            offset: offset to apply in the extraction.
            limit: limit the number of returned records in the extraction.

        Returns:
            list of prices returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # check param consistency
    BirdeyeTradeType.check(trade_type)

    # set params
    url = self.url_api_private + "txs/token"
    params = {
        "address" : address,
        "tx_type" : trade_type,
        "offset" : offset,
        "limit": limit
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetTradesTokenResponse, params = params)

_get_trades_pair

_get_trades_pair(
    sync: Literal[True],
    address: str,
    trade_type: str = BirdeyeTradeType.SWAP.value,
    order_by: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
) -> GetTradesPairResponse

_get_trades_pair(
    sync: Literal[False],
    address: str,
    trade_type: str = BirdeyeTradeType.SWAP.value,
    order_by: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
) -> Coroutine[None, None, GetTradesPairResponse]

_get_trades_pair(
    sync: bool,
    address: str,
    trade_type: str = BirdeyeTradeType.SWAP.value,
    order_by: str = BirdeyeOrder.DESCENDING.value,
    offset: int | None = None,
    limit: int | None = None,
) -> (
    GetTradesPairResponse
    | Coroutine[None, None, GetTradesPairResponse]
)

This function refers to the PRIVATE API endpoint Trades - Pair and is used to get the associated trades of a tokens pair according on a specific chain on Birdeye. Use the 'Trades - Token' endpoint to retrieve the trades associated to a specific token.

Parameters:

Name	Type	Description	Default
address	str	CA of the token to search on the chain.	required
trade_type	str	the type of transactions to extract. The supported chains are available on BirdeyeTradeType. Import them from the library to use the correct identifier.	BirdeyeTradeType.SWAP.value
order_by	str	define the type of ordering to apply in the extraction; e.g. ascending or descending. The sorting types are available on BirdeyeOrder. Import them from the library to use the correct identifier.	BirdeyeOrder.DESCENDING.value
offset	int | None	offset to apply in the extraction.	None
limit	int | None	limit the number of returned records in the extraction.	None

Returns:

Type	Description
GetTradesPairResponse | Coroutine[None, None, GetTradesPairResponse]	list of prices returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_trades_pair(
        self,
        sync: bool,
        address: str,
        trade_type: str = BirdeyeTradeType.SWAP.value,
        order_by: str = BirdeyeOrder.DESCENDING.value,
        offset: int | None = None,
        limit: int | None = None
) -> GetTradesPairResponse | Coroutine[None, None, GetTradesPairResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Trades - Pair](https://docs.birdeye.so/reference/get_defi-txs-pair)** and is used 
        to get the associated trades of a tokens pair according on a specific chain on Birdeye. 
        Use the 'Trades - Token' endpoint to retrieve the trades associated to a specific token.

        Parameters:
            address: CA of the token to search on the chain.
            trade_type: the type of transactions to extract.
                The supported chains are available on [`BirdeyeTradeType`][cyhole.birdeye.param.BirdeyeTradeType].
                Import them from the library to use the correct identifier.
            order_by: define the type of ordering to apply in the 
                extraction; e.g. ascending or descending.
                The sorting types are available on [`BirdeyeOrder`][cyhole.birdeye.param.BirdeyeOrder].
                Import them from the library to use the correct identifier.
            offset: offset to apply in the extraction.
            limit: limit the number of returned records in the extraction.

        Returns:
            list of prices returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # check param consistency
    BirdeyeOrder.check(order_by)
    BirdeyeTradeType.check(trade_type)

    # set params
    url = self.url_api_private + "txs/pair"
    params = {
        "address" : address,
        "tx_type" : trade_type,
        "sort_type": order_by,
        "offset" : offset,
        "limit": limit
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetTradesPairResponse, params = params)

_get_ohlcv

_get_ohlcv(
    sync: Literal[True],
    address: str,
    address_type: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
    chain: str = BirdeyeChain.SOLANA.value,
) -> GetOHLCVTokenPairResponse

_get_ohlcv(
    sync: Literal[False],
    address: str,
    address_type: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
    chain: str = BirdeyeChain.SOLANA.value,
) -> Coroutine[None, None, GetOHLCVTokenPairResponse]

_get_ohlcv(
    sync: bool,
    address: str,
    address_type: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
    chain: str = BirdeyeChain.SOLANA.value,
) -> (
    GetOHLCVTokenPairResponse
    | Coroutine[None, None, GetOHLCVTokenPairResponse]
)

This function refers to the PRIVATE API endpoint OHLCV - Token/Pair and is used to get the Open, High, Low, Close, and Volume (OHLCV) data for a specific token/pair on a chain on Birdeye.

Parameters:

Name	Type	Description	Default
address	str	CA of the token to search on the chain.	required
address_type	str	the type of address involved in the extraction (token/pair). The supported chains are available on BirdeyeAddressType. Import them from the library to use the correct identifier.	required
timeframe	str	the type of timeframe involved in the extraction. The timeframe is used to define intervall between a measure and the next one. The supported chains are available on BirdeyeTimeFrame. Import them from the library to use the correct identifier.	required
dt_from	datetime	beginning time to take take price data.	required
dt_to	datetime | None	end time to take take price data. It should be dt_from < dt_to. If not ptovided (None), the current time is used.	None

Returns:

Type	Description
GetOHLCVTokenPairResponse | Coroutine[None, None, GetOHLCVTokenPairResponse]	list of prices returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_ohlcv(
        self,
        sync: bool,
        address: str,
        address_type: str,
        timeframe: str,
        dt_from: datetime,
        dt_to: datetime | None = None,
        chain: str = BirdeyeChain.SOLANA.value
) -> GetOHLCVTokenPairResponse | Coroutine[None, None, GetOHLCVTokenPairResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[OHLCV - Token/Pair](https://docs.birdeye.so/reference/get_defi-ohlcv)** and is used to get the 
        Open, High, Low, Close, and Volume (OHLCV) data for a specific token/pair on a chain on Birdeye.

        Parameters:
            address: CA of the token to search on the chain.
            address_type: the type of address involved in the extraction (token/pair).
                The supported chains are available on [`BirdeyeAddressType`][cyhole.birdeye.param.BirdeyeAddressType].
                Import them from the library to use the correct identifier.
            timeframe: the type of timeframe involved in the extraction.
                The timeframe is used to define intervall between a measure and the next one.
                The supported chains are available on [`BirdeyeTimeFrame`][cyhole.birdeye.param.BirdeyeTimeFrame].
                Import them from the library to use the correct identifier.
            dt_from: beginning time to take take price data.
            dt_to: end time to take take price data.
                It should be `dt_from` < `dt_to`.
                If not ptovided (None), the current time is used.

        Returns:
            list of prices returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # check param consistency
    BirdeyeAddressType.check(address_type)
    BirdeyeTimeFrame.check(timeframe)

    # set default
    if dt_to is None:
        dt_to = datetime.now()

    # check consistency
    if dt_from > dt_to:
        raise BirdeyeTimeRangeError("Inconsistent timewindow provided: 'dt_from' > 'dt_to'")

    # set params
    url = self.url_api_public + "ohlcv"
    if address_type == BirdeyeAddressType.PAIR.value:
        url = url + "/" + BirdeyeAddressType.PAIR.value
    params = {
        "address" : address,
        "type" : timeframe,
        "time_from" : int(dt_from.timestamp()),
        "time_to" : int(dt_to.timestamp())
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetOHLCVTokenPairResponse, params = params)

_get_ohlcv_base_quote

_get_ohlcv_base_quote(
    sync: Literal[True],
    base_address: str,
    quote_address: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
    chain: str = BirdeyeChain.SOLANA.value,
) -> GetOHLCVBaseQuoteResponse

_get_ohlcv_base_quote(
    sync: Literal[False],
    base_address: str,
    quote_address: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
    chain: str = BirdeyeChain.SOLANA.value,
) -> Coroutine[None, None, GetOHLCVBaseQuoteResponse]

_get_ohlcv_base_quote(
    sync: bool,
    base_address: str,
    quote_address: str,
    timeframe: str,
    dt_from: datetime,
    dt_to: datetime | None = None,
    chain: str = BirdeyeChain.SOLANA.value,
) -> (
    GetOHLCVBaseQuoteResponse
    | Coroutine[None, None, GetOHLCVBaseQuoteResponse]
)

This function refers to the PRIVATE API endpoint OHLCV - Base/Quote and is used to get the Open, High, Low, Close, and Volume (OHLCV) data for a specific base/quote combination on a chain on Birdeye.

Parameters:

Name	Type	Description	Default
base_address	str	CA of the token to search on the chain.	required
quote_address	str	CA of the token to search on the chain.	required
timeframe	str	the type of timeframe involved in the extraction. The timeframe is used to define intervall between a measure and the next one. The supported chains are available on BirdeyeTimeFrame. Import them from the library to use the correct identifier.	required
dt_from	datetime	beginning time to take take price data.	required
dt_to	datetime | None	end time to take take price data. It should be dt_from < dt_to. If not ptovided (None), the current time is used.	None

Returns: list of prices returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameter belonging to the value list is aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_ohlcv_base_quote(
        self,
        sync: bool,
        base_address: str,
        quote_address: str,
        timeframe: str,
        dt_from: datetime,
        dt_to: datetime | None = None,
        chain: str = BirdeyeChain.SOLANA.value
) -> GetOHLCVBaseQuoteResponse | Coroutine[None, None, GetOHLCVBaseQuoteResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[OHLCV - Base/Quote](https://docs.birdeye.so/reference/get_defi-ohlcv-base-quote)** and is used to get the 
        Open, High, Low, Close, and Volume (OHLCV) data for a specific base/quote combination 
        on a chain on Birdeye.

        Parameters:
            base_address: CA of the token to search on the chain.
            quote_address: CA of the token to search on the chain.
            timeframe: the type of timeframe involved in the extraction.
                The timeframe is used to define intervall between a measure and the next one.
                The supported chains are available on [`BirdeyeTimeFrame`][cyhole.birdeye.param.BirdeyeTimeFrame].
                Import them from the library to use the correct identifier.
            dt_from: beginning time to take take price data.
            dt_to: end time to take take price data.
                It should be `dt_from` < `dt_to`.
                If not ptovided (None), the current time is used.
        Returns:
            list of prices returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameter belonging to the value list is aligned to it.
    """
    # check param consistency
    BirdeyeTimeFrame.check(timeframe)

    # set default
    if dt_to is None:
        dt_to = datetime.now()

    # check consistency
    if dt_from > dt_to:
        raise BirdeyeTimeRangeError("Inconsistent timewindow provided: 'dt_from' > 'dt_to'")

    # set params
    url = self.url_api_public + "ohlcv/base_quote"
    params = {
        "base_address" : base_address,
        "quote_address" : quote_address,
        "type" : timeframe,
        "time_from" : int(dt_from.timestamp()),
        "time_to" : int(dt_to.timestamp())
    }

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetOHLCVBaseQuoteResponse, params = params)

_get_wallet_supported_networks

_get_wallet_supported_networks(
    sync: Literal[True],
) -> GetWalletSupportedNetworksResponse

_get_wallet_supported_networks(
    sync: Literal[False],
) -> Coroutine[
    None, None, GetWalletSupportedNetworksResponse
]

_get_wallet_supported_networks(
    sync: bool,
) -> (
    GetWalletSupportedNetworksResponse
    | Coroutine[
        None, None, GetWalletSupportedNetworksResponse
    ]
)

This function refers to the PRIVATE API endpoint Wallet - Supported Networks and it is used to get the list of supported chains on Birdeye.

Returns:

Type	Description
GetWalletSupportedNetworksResponse | Coroutine[None, None, GetWalletSupportedNetworksResponse]	list of chains returned by birdeye.so.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _get_wallet_supported_networks(self, sync: bool) -> GetWalletSupportedNetworksResponse | Coroutine[None, None, GetWalletSupportedNetworksResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Wallet - Supported Networks](https://docs.birdeye.so/reference/get_v1-wallet-list-supported-chain)** and 
        it is used to get the list of supported chains on Birdeye.

        Returns:
            list of chains returned by birdeye.so.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
    """
    url = self.url_api_private_wallet + "/list_supported_chain"

    # execute request
    return self.api_return_model(sync, RequestType.GET.value, url, GetWalletSupportedNetworksResponse)

_get_v3_search

_get_v3_search(
    sync: Literal[True],
    query: GetV3SearchQuery | None = None,
) -> GetV3SearchResponse

_get_v3_search(
    sync: Literal[False],
    query: GetV3SearchQuery | None = None,
) -> Coroutine[None, None, GetV3SearchResponse]

_get_v3_search(
    sync: bool, query: GetV3SearchQuery | None = None
) -> (
    GetV3SearchResponse
    | Coroutine[None, None, GetV3SearchResponse]
)

This function refers to the PRIVATE API endpoint Search and is used to search for tokens and/or markets across one or all of Birdeye's supported chains. Callers can narrow results by keyword, entity type, matching mode, chain, and a range of sort metrics; the response groups matches into type buckets ("token" and "market") each containing a ranked list of matching items. Useful for token-discovery UIs, autocomplete search boxes, and cross-chain asset lookups.

Info

The verify_token filter is Solana-only. The markets filter restricts results to specific DEX sources (e.g. Raydium, Orca). Page size is capped at 20 items per call.

Parameters:

Name	Type	Description	Default
query	GetV3SearchQuery | None	optional GetV3SearchQuery instance holding the search keyword, target type, matching mode, chain, sort options and pagination settings. When None (or omitted) the call uses Birdeye's defaults — all entity types, exact symbol matching, sorted by 24h USD volume descending.	None

Returns:

Type	Description
GetV3SearchResponse | Coroutine[None, None, GetV3SearchResponse]	search results grouped by entity type, decoded as
GetV3SearchResponse | Coroutine[None, None, GetV3SearchResponse]	GetV3SearchResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.
ParamUnknownError	if one of the input parameters belonging to the value list is not aligned to it.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_search(
    self,
    sync: bool,
    query: GetV3SearchQuery | None = None
) -> GetV3SearchResponse | Coroutine[None, None, GetV3SearchResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Search](https://docs.birdeye.so/reference/get-defi-v3-search)** and is used
        to search for tokens and/or markets across one or all of Birdeye's supported chains.
        Callers can narrow results by keyword, entity type, matching mode, chain, and a range of
        sort metrics; the response groups matches into type buckets (`"token"` and `"market"`)
        each containing a ranked list of matching items. Useful for token-discovery UIs, autocomplete
        search boxes, and cross-chain asset lookups.

        !!! info
            The `verify_token` filter is Solana-only. The `markets` filter restricts results to
            specific DEX sources (e.g. Raydium, Orca). Page size is capped at 20 items per call.

        Parameters:
            query: optional [`GetV3SearchQuery`][cyhole.birdeye.schema.GetV3SearchQuery] instance
                holding the search keyword, target type, matching mode, chain, sort options and
                pagination settings. When `None` (or omitted) the call uses Birdeye's defaults —
                all entity types, exact symbol matching, sorted by 24h USD volume descending.

        Returns:
            search results grouped by entity type, decoded as
            [`GetV3SearchResponse`][cyhole.birdeye.schema.GetV3SearchResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
            ParamUnknownError: if one of the input parameters belonging to the value list is not aligned to it.
    """
    if query is None:
        query = GetV3SearchQuery()

    # validate optional enum fields
    if query.target is not None:
        BirdeyeSearchTarget.check(query.target)
    if query.search_mode is not None:
        BirdeyeSearchMode.check(query.search_mode)
    if query.search_by is not None:
        BirdeyeSearchBy.check(query.search_by)
    if query.sort_by is not None:
        BirdeyeSearchSortBy.check(query.sort_by)
    if query.sort_type is not None:
        BirdeyeOrder.check(query.sort_type)
    if query.ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(query.ui_amount_mode)

    # build params — exclude None and coerce bool to lowercase string
    params = {}
    for key, value in query.model_dump().items():
        if value is None:
            continue
        if isinstance(value, bool):
            params[key] = "true" if value else "false"
        else:
            params[key] = value

    url = self.url_api_private + "v3/search"
    return self.api_return_model(sync, RequestType.GET.value, url, GetV3SearchResponse, params = params)

_get_utils_v1_credits

_get_utils_v1_credits(
    sync: Literal[True],
    time_from: int | None = None,
    time_to: int | None = None,
) -> GetUtilsV1CreditsResponse

_get_utils_v1_credits(
    sync: Literal[False],
    time_from: int | None = None,
    time_to: int | None = None,
) -> Coroutine[None, None, GetUtilsV1CreditsResponse]

_get_utils_v1_credits(
    sync: bool,
    time_from: int | None = None,
    time_to: int | None = None,
) -> (
    GetUtilsV1CreditsResponse
    | Coroutine[None, None, GetUtilsV1CreditsResponse]
)

This function refers to the PRIVATE API endpoint Utils - Credits and is used to retrieve the API credit usage for the current account over a given time range. Useful for monitoring consumption and detecting when the account is approaching its credit limit.

Parameters:

Name	Type	Description	Default
time_from	int | None	start of the time range as a unix timestamp in seconds; None to let the server choose the default start.	None
time_to	int | None	end of the time range as a unix timestamp in seconds; None to let the server choose the default end (typically the current time).	None

Returns:

Type	Description
GetUtilsV1CreditsResponse | Coroutine[None, None, GetUtilsV1CreditsResponse]	credit usage statistics decoded as
GetUtilsV1CreditsResponse | Coroutine[None, None, GetUtilsV1CreditsResponse]	GetUtilsV1CreditsResponse.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to related endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _get_utils_v1_credits(
    self,
    sync: bool,
    time_from: int | None = None,
    time_to: int | None = None
) -> GetUtilsV1CreditsResponse | Coroutine[None, None, GetUtilsV1CreditsResponse]:
    """
        This function refers to the **PRIVATE** API endpoint **[Utils - Credits](https://docs.birdeye.so/reference/get-utils-v1-credits)** and is used
        to retrieve the API credit usage for the current account over a given time range.
        Useful for monitoring consumption and detecting when the account is approaching its
        credit limit.

        Parameters:
            time_from: start of the time range as a unix timestamp in seconds; `None` to
                let the server choose the default start.
            time_to: end of the time range as a unix timestamp in seconds; `None` to
                let the server choose the default end (typically the current time).

        Returns:
            credit usage statistics decoded as
            [`GetUtilsV1CreditsResponse`][cyhole.birdeye.schema.GetUtilsV1CreditsResponse].

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to related endpoint.
    """
    url = self.url_api_utils_v1 + "credits"
    params = {
        "time_from": time_from,
        "time_to": time_to,
    }
    return self.api_return_model(sync, RequestType.GET.value, url, GetUtilsV1CreditsResponse, params = params)

_get_v3_all_time_trades

_get_v3_all_time_trades(
    sync: Literal[True],
    address: str | list[str],
    time_frame: str,
    ui_amount_mode: str | None = None,
) -> GetV3AllTimeTradesResponse

_get_v3_all_time_trades(
    sync: Literal[False],
    address: str | list[str],
    time_frame: str,
    ui_amount_mode: str | None = None,
) -> Coroutine[None, None, GetV3AllTimeTradesResponse]

_get_v3_all_time_trades(
    sync: bool,
    address: str | list[str],
    time_frame: str,
    ui_amount_mode: str | None = None,
) -> (
    GetV3AllTimeTradesResponse
    | Coroutine[None, None, GetV3AllTimeTradesResponse]
)

This function consolidates the Birdeye v3 all-time trade statistics endpoints All-Time Trades (Single) and All-Time Trades (Multiple) under a single polymorphic call.

Both variants return the same envelope: a list of GetV3AllTimeTradesItem objects containing cumulative trade counts and volumes (buy, sell, total in token UI units and USD) aggregated over the selected time_frame. This is useful for computing historical trading activity without having to stitch together per-window snapshots.

The method is polymorphic on the address argument:

• pass a single str address → issues a GET /defi/v3/all-time/trades/single.
• pass a list[str] of up to 20 addresses → issues a POST /defi/v3/all-time/trades/multiple.

Both return a GetV3AllTimeTradesResponse whose data list contains one item per requested token.

Parameters:

Name	Type	Description	Default
address	str | list[str]	a single token contract address (str) or a list of up to 20 token contract addresses (list[str]).	required
time_frame	str	the aggregation window. Must be one of the values from BirdeyeAllTimeTradesTimeFrame. Use BirdeyeAllTimeTradesTimeFrame.ALL_TIME to fetch statistics spanning the token's entire trading history.	required
ui_amount_mode	str | None	controls how token amounts are expressed for scaled-UI-amount SPL tokens on Solana. Accepted values are available on BirdeyeUIAmountMode. Ignored on non-Solana chains. Default behaviour: raw.	None

Returns:

Type	Description
GetV3AllTimeTradesResponse | Coroutine[None, None, GetV3AllTimeTradesResponse]	GetV3AllTimeTradesResponse
GetV3AllTimeTradesResponse | Coroutine[None, None, GetV3AllTimeTradesResponse]	with one trade-statistics item per requested token address.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to the endpoint.
ParamUnknownError	if time_frame or ui_amount_mode is not an accepted value.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_all_time_trades(
    self,
    sync: bool,
    address: str | list[str],
    time_frame: str,
    ui_amount_mode: str | None = None
) -> GetV3AllTimeTradesResponse | Coroutine[None, None, GetV3AllTimeTradesResponse]:
    """
        This function consolidates the Birdeye v3 all-time trade statistics endpoints
        **[All-Time Trades (Single)](https://docs.birdeye.so/reference/get-defi-v3-all-time-trades-single)**
        and **[All-Time Trades (Multiple)](https://docs.birdeye.so/reference/post-defi-v3-all-time-trades-multiple)**
        under a single polymorphic call.

        Both variants return the same envelope: a list of
        [`GetV3AllTimeTradesItem`][cyhole.birdeye.schema.GetV3AllTimeTradesItem] objects containing
        cumulative trade counts and volumes (buy, sell, total in token UI units and USD) aggregated
        over the selected `time_frame`. This is useful for computing historical trading activity
        without having to stitch together per-window snapshots.

        The method is polymorphic on the `address` argument:

        - pass a single `str` address → issues a `GET /defi/v3/all-time/trades/single`.
        - pass a `list[str]` of up to 20 addresses → issues a `POST /defi/v3/all-time/trades/multiple`.

        Both return a [`GetV3AllTimeTradesResponse`][cyhole.birdeye.schema.GetV3AllTimeTradesResponse]
        whose `data` list contains one item per requested token.

        Parameters:
            address: a single token contract address (`str`) or a list of up to 20 token contract
                addresses (`list[str]`).
            time_frame: the aggregation window. Must be one of the values from
                [`BirdeyeAllTimeTradesTimeFrame`][cyhole.birdeye.param.BirdeyeAllTimeTradesTimeFrame].
                Use `BirdeyeAllTimeTradesTimeFrame.ALL_TIME` to fetch statistics spanning the
                token's entire trading history.
            ui_amount_mode: controls how token amounts are expressed for scaled-UI-amount SPL
                tokens on Solana. Accepted values are available on
                [`BirdeyeUIAmountMode`][cyhole.birdeye.param.BirdeyeUIAmountMode]. Ignored on
                non-Solana chains. Default behaviour: `raw`.

        Returns:
            [`GetV3AllTimeTradesResponse`][cyhole.birdeye.schema.GetV3AllTimeTradesResponse]
            with one trade-statistics item per requested token address.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to the endpoint.
            ParamUnknownError: if `time_frame` or `ui_amount_mode` is not an accepted value.
    """
    BirdeyeAllTimeTradesTimeFrame.check(time_frame)
    if ui_amount_mode is not None:
        BirdeyeUIAmountMode.check(ui_amount_mode)

    params: dict[str, Any] = {"time_frame": time_frame}
    if ui_amount_mode is not None:
        params["ui_amount_mode"] = ui_amount_mode

    if isinstance(address, str):
        url = self.url_api_public + "v3/all-time/trades/single"
        params["address"] = address
        return self.api_return_model(sync, RequestType.GET.value, url, GetV3AllTimeTradesResponse, params = params)

    url = self.url_api_public + "v3/all-time/trades/multiple"
    params["list_address"] = ",".join(address)
    return self.api_return_model(sync, RequestType.POST.value, url, GetV3AllTimeTradesResponse, params = params)

_get_v3_token_meme_detail_single

_get_v3_token_meme_detail_single(
    sync: Literal[True], address: str
) -> GetV3TokenMemeDetailSingleResponse

_get_v3_token_meme_detail_single(
    sync: Literal[False], address: str
) -> Coroutine[
    None, None, GetV3TokenMemeDetailSingleResponse
]

_get_v3_token_meme_detail_single(
    sync: bool, address: str
) -> (
    GetV3TokenMemeDetailSingleResponse
    | Coroutine[
        None, None, GetV3TokenMemeDetailSingleResponse
    ]
)

This function refers to the PRIVATE API endpoint Meme Token Detail - Single and returns the full detail record for a single meme token.

The response bundles standard token identity fields (address, name, symbol, decimals, price, liquidity, supply, FDV, market cap, logo, extensions) with a meme_info block that exposes launchpad-specific data: the origin platform, creator wallet, bonding-curve pool state (reserves, supply), graduation status and progress toward the funding target. This endpoint is the right call when a caller needs both token fundamentals and meme-launchpad context in one request.

Parameters:

Name	Type	Description	Default
address	str	contract address of the meme token to look up.	required

Returns:

Type	Description
GetV3TokenMemeDetailSingleResponse | Coroutine[None, None, GetV3TokenMemeDetailSingleResponse]	GetV3TokenMemeDetailSingleResponse
GetV3TokenMemeDetailSingleResponse | Coroutine[None, None, GetV3TokenMemeDetailSingleResponse]	containing the full token and meme-info payload.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to the endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_meme_detail_single(
    self,
    sync: bool,
    address: str
) -> GetV3TokenMemeDetailSingleResponse | Coroutine[None, None, GetV3TokenMemeDetailSingleResponse]:
    """
        This function refers to the **PRIVATE** API endpoint
        **[Meme Token Detail - Single](https://docs.birdeye.so/reference/get-defi-v3-token-meme-detail-single)**
        and returns the full detail record for a single meme token.

        The response bundles standard token identity fields (address, name, symbol,
        decimals, price, liquidity, supply, FDV, market cap, logo, extensions) with a
        ``meme_info`` block that exposes launchpad-specific data: the origin platform,
        creator wallet, bonding-curve pool state (reserves, supply), graduation status
        and progress toward the funding target. This endpoint is the right call when a
        caller needs both token fundamentals and meme-launchpad context in one request.

        Parameters:
            address: contract address of the meme token to look up.

        Returns:
            [`GetV3TokenMemeDetailSingleResponse`][cyhole.birdeye.schema.GetV3TokenMemeDetailSingleResponse]
            containing the full token and meme-info payload.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to the endpoint.
    """
    url = self.url_api_public + "v3/token/meme/detail/single"
    params = {"address": address}
    return self.api_return_model(sync, RequestType.GET.value, url, GetV3TokenMemeDetailSingleResponse, params = params)

_get_v3_token_meme_list

_get_v3_token_meme_list(
    sync: Literal[True],
    query: GetV3TokenMemeListQuery | None,
) -> GetV3TokenMemeListResponse

_get_v3_token_meme_list(
    sync: Literal[False],
    query: GetV3TokenMemeListQuery | None,
) -> Coroutine[None, None, GetV3TokenMemeListResponse]

_get_v3_token_meme_list(
    sync: bool, query: GetV3TokenMemeListQuery | None
) -> (
    GetV3TokenMemeListResponse
    | Coroutine[None, None, GetV3TokenMemeListResponse]
)

This function refers to the PUBLIC API endpoint Meme Token - List and returns a paginated list of meme tokens from one or more launchpad platforms.

Each item in the response bundles token identity (address, name, symbol, logo), market metrics (price, liquidity, market cap, FDV, volume and trade counts across ten time windows), and a meme_info block covering the token's launchpad origin, bonding-curve pool state, progress toward the funding target, creator, and graduation status. Use this endpoint to screen meme tokens by momentum, liquidity, holder count, or graduation progress in one call.

Parameters:

Name	Type	Description	Default
sync	bool	if True run synchronously, else return a coroutine.	required
query	GetV3TokenMemeListQuery | None	optional query parameters controlling sorting, filtering, and pagination; pass None to use the API defaults (sort_by=progress_percent, sort_type=desc, source=all, offset=0, limit=100). Use a GetV3TokenMemeListQuery instance to customise the request.	required

Returns:

Type	Description
GetV3TokenMemeListResponse | Coroutine[None, None, GetV3TokenMemeListResponse]	GetV3TokenMemeListResponse
GetV3TokenMemeListResponse | Coroutine[None, None, GetV3TokenMemeListResponse]	containing a paginated list of meme token records together with a has_next
GetV3TokenMemeListResponse | Coroutine[None, None, GetV3TokenMemeListResponse]	flag indicating whether additional pages are available.

Raises:

Type	Description
BirdeyeAuthorisationError	if the API key provided does not give access to the endpoint.

Source code in src/cyhole/birdeye/interaction.py

def _get_v3_token_meme_list(
    self,
    sync: bool,
    query: GetV3TokenMemeListQuery | None
) -> GetV3TokenMemeListResponse | Coroutine[None, None, GetV3TokenMemeListResponse]:
    """
        This function refers to the **PUBLIC** API endpoint
        **[Meme Token - List](https://docs.birdeye.so/reference/get-defi-v3-token-meme-list)**
        and returns a paginated list of meme tokens from one or more launchpad platforms.

        Each item in the response bundles token identity (address, name, symbol, logo),
        market metrics (price, liquidity, market cap, FDV, volume and trade counts across
        ten time windows), and a ``meme_info`` block covering the token's launchpad origin,
        bonding-curve pool state, progress toward the funding target, creator, and graduation
        status. Use this endpoint to screen meme tokens by momentum, liquidity, holder count,
        or graduation progress in one call.

        Parameters:
            sync: if `True` run synchronously, else return a coroutine.
            query: optional query parameters controlling sorting, filtering, and pagination;
                pass `None` to use the API defaults (``sort_by=progress_percent``,
                ``sort_type=desc``, ``source=all``, ``offset=0``, ``limit=100``).
                Use a [`GetV3TokenMemeListQuery`][cyhole.birdeye.schema.GetV3TokenMemeListQuery]
                instance to customise the request.

        Returns:
            [`GetV3TokenMemeListResponse`][cyhole.birdeye.schema.GetV3TokenMemeListResponse]
            containing a paginated list of meme token records together with a ``has_next``
            flag indicating whether additional pages are available.

        Raises:
            BirdeyeAuthorisationError: if the API key provided does not give access to the endpoint.
    """
    params = query.model_dump(exclude_none = True) if query else {}
    url = self.url_api_public + "v3/token/meme/list"
    return self.api_return_model(sync, RequestType.GET.value, url, GetV3TokenMemeListResponse, params = params)