> For the complete documentation index, see [llms.txt](https://noodles-finance.gitbook.io/docs.noodles.fi/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://noodles-finance.gitbook.io/docs.noodles.fi/dex-pools/pool-liquidity-event.md).

# Pool Liquidity Event

Retrieve the liquidity history (join/exit events) of a specific liquidity pool, with pagination support.

***

## **Endpoint**

```
GET /api/v1/partner/pool/event/liquidity
```

***

## **Request Parameters**

| Name              | Type   | Required | Description                                                                                                         |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------- |
| `pool_address`    | string | No       | The address of the liquidity pool.                                                                                  |
| `protocols`       | string | No       | Comma-separated list of protocol identifiers (e.g., `cetus-clmm,aftermath-cpmm`). Maximum 20 protocols per request. |
| `action`          | string | No       | Filter by action: `join`, `exit`, or multiple values separated by comma (e.g., `join,exit`).                        |
| `limit`           | int    | No       | Number of records to return (default: 20, max: see backend config).                                                 |
| `desc`            | bool   | No       | Fetch order: `true` for descending (default), `false` for ascending.                                                |
| `cursor`          | int64  | No       | Cursor for pagination.                                                                                              |
| `timestamp`       | int64  | No       | **Deprecated:** Timestamp for pagination.                                                                           |
| `from`            | int64  | No       | Start time filter (Unix millisecond timestamp). Must be used with `to`.                                             |
| `to`              | int64  | No       | End time filter (Unix millisecond timestamp). Must be used with `from`.                                             |
| `from_checkpoint` | int64  | No       | Start checkpoint filter. Must be used with `to_checkpoint`.                                                         |
| `to_checkpoint`   | int64  | No       | End checkpoint filter. Must be used with `from_checkpoint`.                                                         |

#### List of Supported Protocols

See [Pool Data Supported Protocol](https://github.com/NoodlesFi/docs/blob/main/api/supported-protocols.md#pool-data-supported-protocol) for the complete list of protocol identifiers and their names.

* If `desc=false`, `cursor` must be provided.
* If `desc=true`, `cursor` can be omitted for the first page.
* If `action` is omitted, all actions are returned.

**Pagination Notes:**

* If you want to fetch the latest events, you can omit `cursor`, just provide `pool_address` and `limit`.
* If you want to fetch the next page, you must provide `cursor`.
* If you want to fetch the previous page, you must provide `cursor` with `desc=false`.

**Filter Notes:**

* **Time Range**: Both `from` and `to` must be provided together. Maximum range is 60 days.
* **Checkpoint Range**: Both `from_checkpoint` and `to_checkpoint` must be provided together. Maximum range is 2 million checkpoints.
* Time and checkpoint filters can be used independently or together with other parameters.

***

## **Headers**

| Header      | Required | Description                |
| ----------- | -------- | -------------------------- |
| `x-api-key` | No       | API key for authorization. |

***

## **cURL Examples**

### Get Liquidity Events

```bash
curl --location 'https://api.noodles.fi/api/v1/partner/pool/event/liquidity?pool_address=0x682f4b17874ec47723bb527cf21e18b630eba0699d10781740cd0a7964dc6b19&cursor=865526449' \
--header 'x-api-key: YOUR_API_KEY'
```

### Filter by Time Range

```bash
curl --location 'https://api.noodles.fi/api/v1/partner/pool/event/liquidity?pool_address=0x682f4b17874ec47723bb527cf21e18b630eba0699d10781740cd0a7964dc6b19&from=1765118000000&to=1765120000000&limit=20' \
--header 'x-api-key: YOUR_API_KEY'
```

### Filter by Checkpoint Range

```bash
curl --location 'https://api.noodles.fi/api/v1/partner/pool/event/liquidity?pool_address=0x682f4b17874ec47723bb527cf21e18b630eba0699d10781740cd0a7964dc6b19&from_checkpoint=1000000&to_checkpoint=1050000&limit=20' \
--header 'x-api-key: YOUR_API_KEY'
```

### Filter by Protocols

```bash
curl --location 'https://api.noodles.fi/api/v1/partner/pool/event/liquidity?protocols=cetus-clmm,aftermath-cpmm,bluefin-clmm&limit=20' \
--header 'x-api-key: YOUR_API_KEY'
```

### Filter by Protocols and Actions

```bash
curl --location 'https://api.noodles.fi/api/v1/partner/pool/event/liquidity?protocols=cetus-clmm,aftermath-cpmm&action=join,exit&limit=20' \
--header 'x-api-key: YOUR_API_KEY'
```

***

## **Response**

### Fields

| Field        | Type     | Nullable | Description                         |
| ------------ | -------- | -------- | ----------------------------------- |
| `code`       | `number` | No       | HTTP status code (200 for success). |
| `message`    | `string` | No       | Status message.                     |
| `data`       | `array`  | No       | Array of liquidity history objects. |
| `pagination` | `object` | No       | Pagination info for next page.      |

#### Liquidity History Object

| Field           | Type   | Nullable | Description                       |
| --------------- | ------ | -------- | --------------------------------- |
| `id`            | int64  | No       | Unique event ID.                  |
| `timestamp`     | int64  | No       | Event timestamp (ms since epoch). |
| `action`        | string | No       | Event type: `join` or `exit`.     |
| `pool_address`  | string | No       | Pool address.                     |
| `coin_a_type`   | string | No       | Coin A type.                      |
| `coin_b_type`   | string | No       | Coin B type.                      |
| `coin_a_symbol` | string | No       | Coin A symbol.                    |
| `coin_b_symbol` | string | No       | Coin B symbol.                    |
| `amount_a`      | float  | No       | Amount of coin A.                 |
| `amount_b`      | float  | No       | Amount of coin B.                 |
| `amount_a_usd`  | float  | No       | USD value of amount A.            |
| `amount_b_usd`  | float  | No       | USD value of amount B.            |
| `tx_digest`     | string | No       | Transaction digest.               |
| `sender`        | string | No       | Sender address.                   |

#### Pagination Object

| Field            | Type  | Nullable | Description                              |
| ---------------- | ----- | -------- | ---------------------------------------- |
| `last_cursor`    | int64 | Yes      | Cursor for next page.                    |
| `last_timestamp` | int64 | Yes      | **Deprecated:** Timestamp for next page. |
| `limit`          | int64 | Yes      | Page size.                               |

### Success Response

```json
{
    "code": 200,
    "message": "OK",
    "data": [
        {
            "id": 148000398,
            "timestamp": 1748388384263,
            "action": "join",
            "pool_address": "0x682f4b17874ec47723bb527cf21e18b630eba0699d10781740cd0a7964dc6b19",
            "coin_a_type": "0xe1b45a0e641b9955a20aa0ad1c1f4ad86aad8afb07296d4085e349a50e90bdca::blue::BLUE",
            "coin_b_type": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
            "coin_a_symbol": "BLUE",
            "coin_b_symbol": "USDC",
            "amount_a": 0,
            "amount_b": 14365.010042,
            "amount_a_usd": 0,
            "amount_b_usd": 14365.010042,
            "tx_digest": "EFbNBD1G7PHarq1i9YQj4Dgu4cMqDZubTeUJtKT8iPaM",
            "sender": "266e250ee6c71ec6883b282fa986a6a18f96131952f93fb4addcafe530a3396f"
        },
        {
            "id": 148000274,
            "timestamp": 1748388208314,
            "action": "join",
            "pool_address": "0x682f4b17874ec47723bb527cf21e18b630eba0699d10781740cd0a7964dc6b19",
            "coin_a_type": "0xe1b45a0e641b9955a20aa0ad1c1f4ad86aad8afb07296d4085e349a50e90bdca::blue::BLUE",
            "coin_b_type": "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC",
            "coin_a_symbol": "BLUE",
            "coin_b_symbol": "USDC",
            "amount_a": 2730370.730181823,
            "amount_b": 497692.275162,
            "amount_a_usd": 497692.275162,
            "amount_b_usd": 497692.275162,
            "tx_digest": "NFVFknbZyLNC9gAbWDhpQfhNXWbHtFqW28nJ9eTY1BE",
            "sender": "b2e6286dad58b03231709402a3094a10886dd22ffb3751e7b59e709f5df77492"
        },
    ],
    "message": "OK",
    "pagination": {
        "last_cursor": 147807480,
        "last_timestamp": 1748184968134,
        "limit": 20
    }
}
```

### Response when no data is available

```json
{
    "code": 200,
    "message": "OK",
    "data": [],
    "pagination": {
        "last_cursor": null,
        "last_timestamp": null,
        "limit": 10
    }
}
```

***

> **See also:** [Environment Setup](/docs.noodles.fi/environment-setup/environment.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://noodles-finance.gitbook.io/docs.noodles.fi/dex-pools/pool-liquidity-event.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.