> For the complete documentation index, see [llms.txt](https://docs.kumbaya.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kumbaya.xyz/developers/apis/exchange-api/pools.md).

# Pools endpoints

Reading pool data without running your own indexer. All endpoints are `GET` and **public** (no auth).

## Low-level (paginated, raw)

| Endpoint                     | Purpose                                                         |
| ---------------------------- | --------------------------------------------------------------- |
| `GET /api/v1/pools/list`     | Paginated pool directory with filters (chain, fee tier, tokens) |
| `GET /api/v1/pools/admitted` | Admitted-pool lookups for a trading pair                        |

## UI-curated

| Endpoint                                | Purpose                           |
| --------------------------------------- | --------------------------------- |
| `GET /api/v1/pools`                     | Pool summary with metrics         |
| `GET /api/v1/pools/metrics`             | Aggregate metrics across pools    |
| `GET /api/v1/pools/{poolId}`            | Single pool detail                |
| `GET /api/v1/pools/{poolId}/timeseries` | Historical metrics by hour/day    |
| `GET /api/v1/pools/{poolId}/activity`   | Recent swaps, mints, burns        |
| `GET /api/v1/pools/{poolId}/ticks`      | Tick-level liquidity distribution |
| `GET /api/v1/pools/{poolId}/positions`  | Active LPs (paginated)            |
| `GET /api/v1/pools/{poolId}/swaps`      | Swap history                      |

`poolId` is the indexer's `address-chainId` composite (e.g. `0xabc...-4326`).

## When to use these vs. the indexer directly

* **Use the API** for typical UI needs: a paginated pool list, recent swaps, headline metrics. Cached and rate-limit friendly.
* **Use the** [**Hasura indexer**](/developers/resources/indexer.md) **directly** for custom analytics, historical aggregations, joins, or anything outside the curated endpoints. The indexer also supports GraphQL subscriptions.

For exact request/response shapes consult the Swagger UI at [**`exchange.kumbaya.xyz/docs`**](https://exchange.kumbaya.xyz/docs).