# 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`) |

***

## **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' \
--header 'Accept-Encoding: application/json' \
--header 'x-api-key: YOUR_API_KEY'
```

***

## **Response**

### 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                                  |
| ------------------- | ------- | -------- | -------------------------------------------- |
| `coin_type`         | string  | No       | The unique identifier of the coin.           |
| `symbol`            | string  | No       | The coin's symbol/ticker.                    |
| `decimals`          | number  | No       | Number of decimal places for the coin.       |
| `icon_url`          | string  | Yes      | URL to the coin's icon image.                |
| `verified`          | boolean | No       | Whether the coin is verified.                |
| `dex_liquidity`     | array   | No       | Array of DEX liquidity pool objects.         |
| `lending_liquidity` | array   | No       | Array of lending protocol liquidity objects. |

### 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`       | object | Information about the first coin in the pair.                    |
| `coin_b`       | object | Information about 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 Object (within DEX pools)

| 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`        | object | Information about 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).     |

### Success Response Example

```json
{
    "code": 200,
    "message": "OK",
    "data": {
        "coin_type": "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP",
        "symbol": "UP",
        "decimals": 6,
        "icon_url": "https://www.doubleup.fun/Diamond_Only.png",
        "verified": true,
        "dex_liquidity": [
            {
                "pool_id": "0x3b4589a67fb75a9cbbaa8e90980ae02961c24a86638649450ca4b0278d64f538",
                "protocol": "aftermath-cpmm",
                "coin_a": {
                    "coin_type": "0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI",
                    "symbol": "SUI",
                    "decimals": 9,
                    "icon_url": "https://imagedelivery.net/cBNDGgkrsEA-b_ixIp9SkQ/sui-coin.svg/public",
                    "verified": true
                },
                "coin_b": {
                    "coin_type": "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP",
                    "symbol": "UP",
                    "decimals": 6,
                    "icon_url": "https://www.doubleup.fun/Diamond_Only.png",
                    "verified": true
                },
                "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": [
            {
                "pool_id": "0x8c1fad2fe2217fe64c579809a1d855127c81afe158d4d9124f9914d17a748eb1",
                "protocol": "suilend",
                "coin": {
                    "coin_type": "0x87dfe1248a1dc4ce473bd9cb2937d66cdc6c30fee63f3fe0dbb55c7a09d35dec::up::UP",
                    "symbol": "UP",
                    "decimals": 6,
                    "icon_url": "https://www.doubleup.fun/Diamond_Only.png",
                    "verified": true
                },
                "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
            }
        ]
    }
}
```

***
