# REST API

REST API for LiquidCore: list pools, get swap quotes, and fetch pool stats.

**Base URL:** `https://api.liqd.ag/liquidcore`

## List pools

`GET /liquidcore/pools`

Returns all LiquidCore pools with token pairs, reserves, fees, volume, and pricing data.

**Response:**

```json
{
  "success": true,
  "data": [
    {
      "poolAddress": "0x...",
      "token0": { "address": "0x...", "symbol": "USDC", "name": "USDC", "decimals": 6 },
      "token1": { "address": "0x...", "symbol": "WHYPE", "name": "Wrapped HYPE", "decimals": 18 },
      "poolFees": { "token0In": "0.0100", "token1In": "0.0180" },
      "exchangeRates": { "token1PerToken0": "0.022799", "token0PerToken1": "43.860000" },
      "usdPrices": { "token0": "1.000000", "token1": "43.860000" },
      "reserves": { "token0": "18312.64", "token1": "619.59" },
      "reservesUSD": { "token0": "18312.64", "token1": "27175.35" },
      "tvlUSD": "45487.99",
      "fees24h": { "token0": "108.096785", "token1": "2.339040", "usd": "210.69" },
      "volume24h": { "token0": "1160611.93", "token1": "13745.31", "usd": "1178968.36" },
      "apr": "169.06"
    }
  ],
  "totalTVL": "96186.44",
  "totals24h": {
    "fees": { "token0": "182.326824", "token1": "4.427937", "usd": "391.97" },
    "volume": { "token0": "2043693.89", "token1": "23626.71", "usd": "2076213.20" }
  }
}
```

| Field                      | Description                                                           |
| -------------------------- | --------------------------------------------------------------------- |
| `poolAddress`              | Pool contract address                                                 |
| `token0`, `token1`         | Token metadata: `address`, `symbol`, `name`, `decimals`               |
| `poolFees`                 | Current dynamic fee rates per direction (decimal, e.g. `0.0100` = 1%) |
| `exchangeRates`            | Spot exchange rates between the two tokens                            |
| `usdPrices`                | USD price per token                                                   |
| `reserves` / `reservesUSD` | Pool reserves in token units and USD                                  |
| `tvlUSD`                   | Total value locked in the pool                                        |
| `fees24h`                  | Fees collected in the last 24h (token0, token1, USD)                  |
| `volume24h`                | Trading volume in the last 24h (token0, token1, USD)                  |
| `apr`                      | Annualized fee yield as a percentage                                  |
| `totalTVL`                 | Sum of TVL across all pools                                           |
| `totals24h`                | Aggregate 24h fees and volume across all pools                        |

***

## Get quote

Get on-chain swap quotes from LiquidCore pools, with optional ready-to-broadcast calldata.

**Endpoint**

`GET /liquidcore/quote`

**Query parameters**

| Name              | Type                          | Required | Description                                                                                                                                                                      |
| ----------------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tokenIn`         | `address` (`0x…`)             | yes      | Input token address.                                                                                                                                                             |
| `tokenOut`        | `address` (`0x…`)             | yes      | Output token address.                                                                                                                                                            |
| `amountIn`        | `uint256` or CSV of `uint256` | yes      | Input amount(s) in base units (raw `uint256`, no decimals). Pass a comma-separated list for batch quoting (e.g. `1000000,5000000,10000000`).                                     |
| `includeCalldata` | `bool`                        | no       | If truthy (anything except `false`/`0`/empty), each quote includes `minAmountOut` and `calldata` ready to send to the router.                                                    |
| `slippageBps`     | `int` `[0, 10000)`            | no       | Slippage tolerance in basis points used to compute `minAmountOut` when `includeCalldata` is set. Default `100` (1%).                                                             |
| `refCode`         | `string` or `bytes32`         | no       | Referral code. If a 32-byte hex string it's used directly; otherwise it's hashed via `keccak256` (`ethers.utils.id`). When present, the calldata uses the 5-arg `swap` overload. |

The endpoint resolves the pool for `(tokenIn, tokenOut)` on the router and returns a quote per `amountIn`. If no LiquidCore pool exists for the pair, the endpoint returns `404`.

**Success response — `200 OK`**

```json
{
  "success": true,
  "data": {
    "tokenIn": "0x...",
    "tokenOut": "0x...",
    "routerAddress": "0x625aC1D165c776121A52ff158e76e3544B4a0b8B",
    "reserveOut": "12345678901234567890",
    "blockNumber": "1234567",
    "blockTimestamp": "1713369600",
    "functionSignature": "swap(address,address,uint256,uint256)",
    "refCode": "0x<bytes32>",
    "slippageBps": "100",
    "quotes": [
      {
        "amountIn": "1000000",
        "amountOut": "998765",
        "minAmountOut": "988777",
        "calldata": "0x..."
      }
    ]
  }
}
```

**Field notes**

* `routerAddress`: Contract to send the transaction to.
* `reserveOut`: Reserve of the `tokenOut` side of the pool (base units), useful for price-impact checks.
* `blockNumber` / `blockTimestamp`: Block at which the quote was computed.
* `functionSignature`: `swap(address,address,uint256,uint256)`, or the 5-arg overload with `bytes32` when `refCode` is provided.
* `refCode` / `slippageBps`: Echoed in the response only when supplied / applicable. `refCode` is normalized to a `bytes32` hex.
* `quotes[].amountIn`, `quotes[].amountOut`: always returned as base-unit strings.
* `quotes[].minAmountOut`, `quotes[].calldata`: only present when `includeCalldata` is set. `minAmountOut = amountOut * (10000 - slippageBps) / 10000`.

**Error responses**

| Status | `error`                                                                        | When                                             |
| ------ | ------------------------------------------------------------------------------ | ------------------------------------------------ |
| `400`  | `Missing required parameters: tokenIn, tokenOut, amountIn`                     | A required param is missing.                     |
| `400`  | `Invalid slippageBps: must be an integer in [0, 10000)`                        | Bad `slippageBps` when `includeCalldata` is set. |
| `400`  | `Invalid amountIn: must be a raw uint256 (base units) or comma-separated list` | Non-integer or unparseable amounts.              |
| `400`  | `Invalid address: <param>`                                                     | `tokenIn` or `tokenOut` is not a valid address.  |
| `404`  | `No LiquidCore pool found for this token pair`                                 | Router returns zero address or reverts.          |
| `500`  | `Failed to fetch quote` (or error message)                                     | Unexpected server error.                         |

All errors share the shape:

```json
{ "success": false, "error": "<message>" }
```

**Examples**

Single quote:

```
GET /liquidcore/quote
  ?tokenIn=0xb88339CB7199b77E23DB6E890353E22632Ba630f
  &tokenOut=0x5555555555555555555555555555555555555555
  &amountIn=1000000
```

Batch quote:

```
GET /liquidcore/quote?tokenIn=0x...&tokenOut=0x...&amountIn=1000000,5000000,10000000
```

Quote with calldata (2% slippage) and referral code:

```
GET /liquidcore/quote
  ?tokenIn=0x...
  &tokenOut=0x...
  &amountIn=1000000000000000000
  &includeCalldata=true
  &slippageBps=200
  &refCode=myapp
```

**Executing the swap**

Send the returned `calldata` as transaction data to `routerAddress`. The router swap functions (see [Contract Reference](/liquidcore-integration/api-reference.md#router)):

```solidity
function swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 minAmountOut) external returns (uint256);
function swap(address tokenIn, address tokenOut, uint256 amountIn, uint256 minAmountOut, bytes32 refCode) external returns (uint256);
```

The caller must first approve the router to spend `amountIn` of `tokenIn`.

***

## Get pool data

`GET /liquidcore/pool/:address`

**Path:**

| Parameter | Description           |
| --------- | --------------------- |
| `address` | Pool contract address |

**Response:**

```json
{
  "success": true,
  "data": {
    "poolAddress": "0x...",
    "reserves": {
      "token0": { "address": "0x...", "symbol": "USDC", "decimals": 6, "amount": "18312.64", "usd": "18312.64" },
      "token1": { "address": "0x...", "symbol": "WHYPE", "decimals": 18, "amount": "619.59", "usd": "27175.35" },
      "totalUSD": "45487.99"
    },
    "volumeToday": { "token0": "1160611.93", "token1": "13745.31", "usd": "1178968.36" },
    "feesToday": { "token0": "108.096785", "token1": "2.339040", "usd": "210.69" },
    "poolFees": { "token0In": "0.0100", "token1In": "0.0180" },
    "price": {
      "token1PerToken0": "0.022799",
      "token0PerToken1": "43.860000",
      "token0Usd": "1.000000",
      "token1Usd": "43.860000"
    },
    "apr": "169.06",
    "swapsToday": 2906,
    "totalSwaps": 2906,
    "lastUpdated": 1777991882
  }
}
```

| Field                       | Description                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `reserves`                  | Per-token reserves with address, symbol, decimals, amount, USD value, and `totalUSD` |
| `volumeToday` / `feesToday` | Rolling 24h volume and fees (token0, token1, USD)                                    |
| `poolFees`                  | Current dynamic fee rates per direction (decimal)                                    |
| `price`                     | Exchange rates and USD prices for both tokens                                        |
| `apr`                       | Annualized fee yield as a percentage                                                 |
| `swapsToday` / `totalSwaps` | Swap counts (rolling 24h and all-time)                                               |
| `lastUpdated`               | Unix timestamp of last data refresh                                                  |


---

# Agent Instructions: 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:

```
GET https://docs.liqd.ag/liquidcore-integration/api-endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.