> 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/coin/coin-liquidity.md).

# Coin Liquidity

Retrieve the liquidity information for a specific coin across decentralized exchanges (DEXs) and lending protocols.

***

## **Endpoint**

```
GET /api/v1/partner/coin/liquidity
```

## **Request Parameters**

| Name        | Type    | Required | Description                                                                             |
| ----------- | ------- | -------- | --------------------------------------------------------------------------------------- |
| `coin_type` | string  | **Yes**  | The unique identifier of the coin (e.g., `0x...::module::COIN`).                        |
| `pool_type` | string  | **Yes**  | Type of liquidity pools to retrieve. Must be either `dex` or `lending`.                 |
| `protocols` | string  | No       | Comma-separated list of protocol identifiers to include (e.g. `flowx-clmm,flowx-cpmm`). |
| `offset`    | integer | No       | Number of records to skip. Default: 0.                                                  |
| `limit`     | integer | No       | Maximum number of records to return. Default and max: 100.                              |

#### List of Supported Protocols

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

***

## **Headers**

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

***

## **cURL Example**

```bash
curl --location 'https://api.noodles.fi/api/v1/partner/coin/liquidity?coin_type=0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec%3A%3Aup%3A%3AUP&pool_type=dex&protocols=cetus-clmm,aftermath-cpmm&limit=10&offset=0' \
--header 'Accept-Encoding: application/json' \
--header 'x-api-key: YOUR_API_KEY'
```

***

## **Response**

### Success Response Example

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "dex_liquidity": [
            {
                "pool_id": "0x3b4589a67fb75a9cbbaa8e90980ae02961c24a86638649450ca4b0278d64f538",
                "protocol": "aftermath-cpmm",
                "coin_a": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
                "coin_b": "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP",
                "amount_a": 34015.584592142,
                "amount_b": 1108644.380496,
                "amount_a_usd": 110635.69,
                "amount_b_usd": 442542.76,
                "price_a": 3.252,
                "price_b": 0.399,
                "price_ab": 8.148,
                "tvl_usd": 553178.44,
                "fee_rate": 1
            }
        ],
        "lending_liquidity": [],
        "coin_info_map": {
            "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI": {
                "coin_type": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
                "symbol": "SUI",
                "decimals": 9,
                "icon_url": "https://imagedelivery.net/cBNDGgkrsEA-b_ixIp9SkQ/sui-coin.svg/public",
                "verified": true
            },
            "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP": {
                "coin_type": "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP",
                "symbol": "UP",
                "decimals": 6,
                "icon_url": "https://www.doubleup.fun/Diamond_Only.png",
                "verified": true
            }
        },
        "pagination": {
            "offset": 0,
            "limit": 10
        }
    }
}
```

***

### Response Example for Lending Pools

When `pool_type=lending`:

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "dex_liquidity": [],
        "lending_liquidity": [
            {
                "pool_id": "0x8c1fad2fe2217fe64c579809a1d855127c81afe158d4d9124f9914d17a748eb1",
                "protocol": "suilend",
                "coin": "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP",
                "deposit": 1228023.407651,
                "deposit_usd": 496507.33,
                "borrow": 16.961583,
                "borrow_usd": 6.86,
                "deposit_apr": 0.0002071900957212765,
                "borrow_apr": 20.000828726043544,
                "utilization": 0.001381210072570573
            }
        ],
        "coin_info_map": {
            "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP": {
                "coin_type": "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP",
                "symbol": "UP",
                "decimals": 6,
                "icon_url": "https://www.doubleup.fun/Diamond_Only.png",
                "verified": true
            }
        },
        "pagination": {
            "offset": 0,
            "limit": 10
        }
    }
}
```

### Response Fields

| Field     | Type   | Nullable | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `code`    | number | No       | HTTP status code.           |
| `message` | string | No       | Response message.           |
| `data`    | object | No       | Coin liquidity data object. |

### Data Object Fields

| Field               | Type   | Nullable | Description                                                                     |
| ------------------- | ------ | -------- | ------------------------------------------------------------------------------- |
| `dex_liquidity`     | array  | No       | Array of DEX liquidity pool objects (only when `pool_type=dex`).                |
| `lending_liquidity` | array  | No       | Array of lending protocol liquidity objects (only when `pool_type=lending`).    |
| `coin_info_map`     | object | No       | Map of coin type to coin information. Key is the standardized coin type string. |
| `pagination`        | object | No       | Pagination information with `offset` and `limit`.                               |

### DEX Liquidity Pool Object

| Field          | Type   | Description                                                      |
| -------------- | ------ | ---------------------------------------------------------------- |
| `pool_id`      | string | Unique identifier of the liquidity pool.                         |
| `protocol`     | string | Name of the DEX protocol (e.g., "cetus-clmm", "aftermath-cpmm"). |
| `coin_a`       | string | Coin type identifier for the first coin in the pair.             |
| `coin_b`       | string | Coin type identifier for the second coin in the pair.            |
| `amount_a`     | number | Amount of coin A in the pool.                                    |
| `amount_b`     | number | Amount of coin B in the pool.                                    |
| `amount_a_usd` | number | USD value of coin A amount.                                      |
| `amount_b_usd` | number | USD value of coin B amount.                                      |
| `price_a`      | number | Current price of coin A.                                         |
| `price_b`      | number | Current price of coin B.                                         |
| `price_ab`     | number | Price ratio between coin A and coin B.                           |
| `tvl_usd`      | number | Total Value Locked in USD.                                       |
| `fee_rate`     | number | Fee rate for the pool (in percentage).                           |

### Coin Info Map Object

The `coin_info_map` is an object where keys are standardized coin type strings and values contain:

| Field       | Type    | Description                            |
| ----------- | ------- | -------------------------------------- |
| `coin_type` | string  | The unique identifier of the coin.     |
| `symbol`    | string  | The coin's symbol/ticker.              |
| `decimals`  | number  | Number of decimal places for the coin. |
| `icon_url`  | string  | URL to the coin's icon image.          |
| `verified`  | boolean | Whether the coin is verified.          |

### Lending Liquidity Object

| Field         | Type   | Description                                            |
| ------------- | ------ | ------------------------------------------------------ |
| `pool_id`     | string | Unique identifier of the lending pool.                 |
| `protocol`    | string | Name of the lending protocol (e.g., "suilend").        |
| `coin`        | string | Coin type identifier for the coin in the lending pool. |
| `deposit`     | number | Total amount deposited in the pool.                    |
| `deposit_usd` | number | USD value of total deposits.                           |
| `borrow`      | number | Total amount borrowed from the pool.                   |
| `borrow_usd`  | number | USD value of total borrows.                            |
| `deposit_apr` | number | Annual Percentage Rate for deposits.                   |
| `borrow_apr`  | number | Annual Percentage Rate for borrows.                    |
| `utilization` | number | Pool utilization rate (borrowed/deposited).            |


---

# 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/coin/coin-liquidity.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.