API reference

`meteora`

Typed Python client for the Meteora DLMM Data API on Solana.

`MeteoraAPIError`

Bases: MeteoraError

Raised when the Meteora DLMM Data API returns an error response.

The API signals errors with a non-2xx HTTP status. The body, when present, is surfaced in :attr:message; otherwise it falls back to "HTTP <status>".

Attributes:

Name	Type	Description
`message`		The error message text, falling back to `"HTTP <status>"`.
`status_code`		The HTTP status code of the response.

Example::

from meteora import MeteoraClient, MeteoraAPIError

with MeteoraClient() as client:
    try:
        client.get_pool("not-a-real-address")
    except MeteoraAPIError as exc:
        print(exc.status_code, exc.message)

`MeteoraError`

Bases: Exception

Base class for all errors raised by this library.

Catch this to handle any failure originating from meteora (currently just :class:MeteoraAPIError). Network-level failures from the underlying httpx client propagate as httpx exceptions and are not wrapped.

`AsyncMeteoraClient`

Bases: _BaseClient

Asynchronous counterpart of :class:MeteoraClient.

Exposes the same endpoints as coroutines, backed by httpx.AsyncClient. Use it as an async context manager so the connection pool is closed for you; otherwise call :meth:aclose.

Example::

import asyncio
from meteora import AsyncMeteoraClient

async def main():
    async with AsyncMeteoraClient() as client:
        stats = await client.get_protocol_metrics()
        print(stats.total_pools)

asyncio.run(main())

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

Create an asynchronous client.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	DLMM Data API base URL. Defaults to the public endpoint (:data:`meteora.constants.DEFAULT_BASE_URL`); a trailing slash is tolerated.	`DEFAULT_BASE_URL`
`timeout`	`float`	Per-request timeout in seconds, applied when this client creates its own `httpx.AsyncClient`. Ignored if `client` is given.	`30.0`
`client`	`Optional[AsyncClient]`	An existing `httpx.AsyncClient` to reuse. When supplied, the caller owns its lifecycle and :meth:`aclose` will not close it.	`None`

`aclose()` `async`

Close the underlying async HTTP client.

No-op when an external httpx.AsyncClient was injected via the constructor (the caller owns that client's lifecycle).

`aenter()` `async`

Enter the async runtime context and return this client.

`aexit(exc_type, exc, tb)` `async`

Exit the async runtime context, closing the client via :meth:aclose.

`get_protocol_metrics()` `async`

Fetch aggregated protocol-level metrics across all pools.

Calls GET /stats/protocol_metrics.

Returns:

Name	Type	Description
`A`	`ProtocolMetrics`	class:`meteora.models.ProtocolMetrics`.

Raises:

Type	Description
`MeteoraAPIError`	If the API returns an error.

`get_pools(*, page=1, page_size=50, query=None, sort_by=None, filter_by=None)` `async`

Fetch a page of DLMM pools.

Async equivalent of :meth:MeteoraClient.get_pools; see that method for full argument documentation.

Parameters:

Name	Type	Description	Default
`page`	`int`	1-based page number to fetch.	`1`
`page_size`	`int`	Number of pools per page.	`50`
`query`	`Optional[str]`	Optional free-text filter.	`None`
`sort_by`	`Optional[str]`	Optional server-side sort field.	`None`
`filter_by`	`Optional[str]`	Optional time window for window-scoped metrics.	`None`

Returns:

Name	Type	Description
`A`	`PoolsPage`	class:`meteora.models.PoolsPage` envelope.

Raises:

Type	Description
`MeteoraAPIError`	If the API returns an error.

`get_pool(address)` `async`

Fetch a single pool by its on-chain address.

Calls GET /pools/{address}.

Parameters:

Name	Type	Description	Default
`address`	`str`	The pool (LB pair) address, base58.	required

Returns:

Name	Type	Description
`A`	`Pool`	class:`meteora.models.Pool`.

Raises:

Type	Description
`MeteoraAPIError`	If the pool is unknown or the address is malformed.

`get_pool_groups(*, page=1, page_size=50)` `async`

Fetch a page of token-pair pool groups.

Calls GET /pools/groups.

Parameters:

Name	Type	Description	Default
`page`	`int`	1-based page number to fetch.	`1`
`page_size`	`int`	Number of groups per page.	`50`

Returns:

Name	Type	Description
`A`	`PoolGroupsPage`	class:`meteora.models.PoolGroupsPage` envelope.

Raises:

Type	Description
`MeteoraAPIError`	If the API returns an error.

`get_pool_ohlcv(address, *, from_=None, to=None, resolution=None)` `async`

Fetch OHLCV price candles for a pool.

Async equivalent of :meth:MeteoraClient.get_pool_ohlcv.

Parameters:

Name	Type	Description	Default
`address`	`str`	The pool (LB pair) address, base58.	required
`from_`	`Optional[int]`	Optional range start (Unix seconds; sent as `from`).	`None`
`to`	`Optional[int]`	Optional range end (Unix seconds).	`None`
`resolution`	`Optional[str]`	Optional candle timeframe, e.g. `"1h"` or `"24h"`.	`None`

Returns:

Name	Type	Description
`An`	`OhlcvResponse`	class:`meteora.models.OhlcvResponse`.

Raises:

Type	Description
`MeteoraAPIError`	If the pool is unknown or the address is malformed.

`get_pool_volume_history(address)` `async`

Fetch historical volume and fees for a pool.

Calls GET /pools/{address}/volume/history.

Parameters:

Name	Type	Description	Default
`address`	`str`	The pool (LB pair) address, base58.	required

Returns:

Name	Type	Description
`A`	`VolumeHistoryResponse`	class:`meteora.models.VolumeHistoryResponse`.

Raises:

Type	Description
`MeteoraAPIError`	If the pool is unknown or the address is malformed.

`MeteoraClient`

Bases: _BaseClient

Synchronous client for the Meteora DLMM Data API.

Wraps the public, read-only DLMM endpoints (protocol metrics, pools, pool groups, OHLCV, volume history) with typed requests and responses. Every method raises :class:MeteoraAPIError on a non-2xx response.

Use it as a context manager so the underlying httpx connection pool is closed for you; otherwise call :meth:close when done.

Example::

from meteora import MeteoraClient

with MeteoraClient() as client:
    stats = client.get_protocol_metrics()
    print(stats.total_pools)
    page = client.get_pools(page=1, page_size=10, sort_by="tvl")
    for pool in page.data:
        print(pool.name, pool.tvl, pool.apy)

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

Create a synchronous client.

Parameters:

Name	Type	Description	Default
`base_url`	`str`	DLMM Data API base URL. Defaults to the public endpoint (:data:`meteora.constants.DEFAULT_BASE_URL`); a trailing slash is tolerated. Point this at a compatible proxy if needed.	`DEFAULT_BASE_URL`
`timeout`	`float`	Per-request timeout in seconds, applied when this client creates its own `httpx.Client`. Ignored if `client` is given.	`30.0`
`client`	`Optional[Client]`	An existing `httpx.Client` to reuse. When supplied, the caller owns its lifecycle and :meth:`close` will not close it.	`None`

`close()`

Close the underlying HTTP client.

No-op when an external httpx.Client was injected via the constructor (the caller owns that client's lifecycle).

`enter()`

Enter the runtime context and return this client.

`exit(exc_type, exc, tb)`

Exit the runtime context, closing the client via :meth:close.

`get_protocol_metrics()`

Fetch aggregated protocol-level metrics across all pools.

Calls GET /stats/protocol_metrics.

Returns:

Name	Type	Description
`A`	`ProtocolMetrics`	class:`meteora.models.ProtocolMetrics` with total/24h TVL, volume
	`ProtocolMetrics`	and fees, plus the total pool count.

Raises:

Type	Description
`MeteoraAPIError`	If the API returns an error.

`get_pools(*, page=1, page_size=50, query=None, sort_by=None, filter_by=None)`

Fetch a page of DLMM pools.

Calls GET /pools with offset pagination.

Parameters:

Name	Type	Description	Default
`page`	`int`	1-based page number to fetch.	`1`
`page_size`	`int`	Number of pools per page.	`50`
`query`	`Optional[str]`	Optional free-text filter (e.g. a token symbol or address).	`None`
`sort_by`	`Optional[str]`	Optional server-side sort in `"<field>:<asc\|desc>"` form, e.g. `"tvl:desc"` or `"volume:asc"`. A bare field name is rejected by the API with HTTP 400, so the direction is required.	`None`
`filter_by`	`Optional[str]`	Optional server-side filter expression in `"<field>:<value>"` form (e.g. `"has_farm:true"`). Passed through verbatim; the accepted fields are defined by the API.	`None`

Returns:

Name	Type	Description
`A`	`PoolsPage`	class:`meteora.models.PoolsPage` envelope with `total`,
	`PoolsPage`	`pages`, `current_page`, `page_size` and the `data` list.

Raises:

Type	Description
`MeteoraAPIError`	If the API returns an error.

`get_pool(address)`

Fetch a single pool by its on-chain address.

Calls GET /pools/{address}.

Parameters:

Name	Type	Description	Default
`address`	`str`	The pool (LB pair) address, base58.	required

Returns:

Name	Type	Description
`A`	`Pool`	class:`meteora.models.Pool` with full metrics and token metadata.

Raises:

Type	Description
`MeteoraAPIError`	If the pool is unknown or the address is malformed.

`get_pool_groups(*, page=1, page_size=50)`

Fetch a page of token-pair pool groups.

Calls GET /pools/groups. Each group aggregates every DLMM pool for a given token pair (combined TVL/volume, pool count, best fee/TVL ratio).

Parameters:

Name	Type	Description	Default
`page`	`int`	1-based page number to fetch.	`1`
`page_size`	`int`	Number of groups per page.	`50`

Returns:

Name	Type	Description
`A`	`PoolGroupsPage`	class:`meteora.models.PoolGroupsPage` envelope.

Raises:

Type	Description
`MeteoraAPIError`	If the API returns an error.

`get_pool_ohlcv(address, *, from_=None, to=None, resolution=None)`

Fetch OHLCV price candles for a pool.

Calls GET /pools/{address}/ohlcv. With no range arguments the API returns its default window.

Parameters:

Name	Type	Description	Default
`address`	`str`	The pool (LB pair) address, base58.	required
`from_`	`Optional[int]`	Optional range start as a Unix timestamp in seconds (sent as the `from` query param).	`None`
`to`	`Optional[int]`	Optional range end as a Unix timestamp in seconds.	`None`
`resolution`	`Optional[str]`	Optional candle timeframe, e.g. `"1h"` or `"24h"`.	`None`

Returns:

Name	Type	Description
`An`	`OhlcvResponse`	class:`meteora.models.OhlcvResponse` with the candle list.

Raises:

Type	Description
`MeteoraAPIError`	If the pool is unknown or the address is malformed.

`get_pool_volume_history(address)`

Fetch historical volume and fees for a pool.

Calls GET /pools/{address}/volume/history.

Parameters:

Name	Type	Description	Default
`address`	`str`	The pool (LB pair) address, base58.	required

Returns:

Name	Type	Description
`A`	`VolumeHistoryResponse`	class:`meteora.models.VolumeHistoryResponse` with per-bucket
	`VolumeHistoryResponse`	volume, fees, and protocol fees.

Raises:

Type	Description
`MeteoraAPIError`	If the pool is unknown or the address is malformed.

`CumulativeMetrics`

Bases: _Model

All-time cumulative volume and fees for a single pool.

`OhlcvCandle`

Bases: _Model

A single OHLCV candle for a pool's price over one timeframe bucket.

`OhlcvResponse`

Bases: _Model

Response of GET /pools/{address}/ohlcv — candles over a time range.

`Pool`

Bases: _Model

A single DLMM pool from GET /pools/{address} (and /pools items).

Rolling metrics (:attr:volume, :attr:fees, :attr:protocol_fees, :attr:fee_tvl_ratio) are dicts keyed by time window ("30m" … "24h").

Example::

pool = client.get_pool("5rCf1DM8LjKTw4YqhnoLcngyZYeNnQqztScTogYHAS6")
print(pool.token_x.symbol, pool.token_y.symbol)  # 'SOL' 'USDC'
print(pool.tvl, pool.apr, pool.apy)
print(pool.volume["24h"], pool.fees["24h"])

`PoolConfig`

Bases: _Model

A DLMM pool's static fee/bin configuration.

`PoolGroup`

Bases: _Model

A token-pair pool group: aggregated stats across all pools for one pair.

`PoolGroupsPage`

Bases: _Model

A page of pool groups from GET /pools/groups.

`PoolsPage`

Bases: _Model

A page of pools from GET /pools (offset pagination envelope).

`ProtocolMetrics`

Bases: _Model

Aggregated protocol-level metrics from GET /stats/protocol_metrics.

`TokenInfo`

Bases: _Model

Metadata for one side of a pool's token pair.

`VolumeHistoryPoint`

Bases: _Model

A single historical bucket of volume and fees for a pool.

`VolumeHistoryResponse`

Bases: _Model

Response of GET /pools/{address}/volume/history — volume/fees over time.

API reference

meteora

MeteoraAPIError

MeteoraError

AsyncMeteoraClient

__init__(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)

aclose() async

__aenter__() async

__aexit__(exc_type, exc, tb) async

get_protocol_metrics() async

get_pools(*, page=1, page_size=50, query=None, sort_by=None, filter_by=None) async

get_pool(address) async

get_pool_groups(*, page=1, page_size=50) async

get_pool_ohlcv(address, *, from_=None, to=None, resolution=None) async

get_pool_volume_history(address) async

MeteoraClient

__init__(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)

close()

__enter__()

__exit__(exc_type, exc, tb)

get_protocol_metrics()

get_pools(*, page=1, page_size=50, query=None, sort_by=None, filter_by=None)

get_pool(address)

get_pool_groups(*, page=1, page_size=50)

get_pool_ohlcv(address, *, from_=None, to=None, resolution=None)

get_pool_volume_history(address)

CumulativeMetrics

OhlcvCandle

OhlcvResponse

Pool

PoolConfig

PoolGroup

PoolGroupsPage

PoolsPage

ProtocolMetrics

TokenInfo

VolumeHistoryPoint

VolumeHistoryResponse

`meteora`

`MeteoraAPIError`

`MeteoraError`

`AsyncMeteoraClient`

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

`aclose()` `async`

`aenter()` `async`

`aexit(exc_type, exc, tb)` `async`

`get_protocol_metrics()` `async`

`get_pools(*, page=1, page_size=50, query=None, sort_by=None, filter_by=None)` `async`

`get_pool(address)` `async`

`get_pool_groups(*, page=1, page_size=50)` `async`

`get_pool_ohlcv(address, *, from_=None, to=None, resolution=None)` `async`

`get_pool_volume_history(address)` `async`

`MeteoraClient`

`init(base_url=DEFAULT_BASE_URL, *, timeout=30.0, client=None)`

`close()`

`enter()`

`exit(exc_type, exc, tb)`

`get_protocol_metrics()`

`get_pools(*, page=1, page_size=50, query=None, sort_by=None, filter_by=None)`

`get_pool(address)`

`get_pool_groups(*, page=1, page_size=50)`

`get_pool_ohlcv(address, *, from_=None, to=None, resolution=None)`

`get_pool_volume_history(address)`

`CumulativeMetrics`

`OhlcvCandle`

`OhlcvResponse`

`Pool`

`PoolConfig`

`PoolGroup`

`PoolGroupsPage`

`PoolsPage`

`ProtocolMetrics`

`TokenInfo`

`VolumeHistoryPoint`

`VolumeHistoryResponse`