> ## Documentation Index
> Fetch the complete documentation index at: https://docs.exponent.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# User balance history

> Returns historical balance records for a user and vault. Results are sorted by `created_at` descending.

export const ApiResponse = ({children, errors = {}}) => {
  const [status, setStatus] = useState("200");
  const statuses = ["200", ...Object.keys(errors)];
  return <section className="api-response" aria-label="Response">
      <div className="api-response-header not-prose">
        <h2>Response</h2>
        <div className="api-response-format">
          {statuses.length > 1 ? <select aria-label="Response status" value={status} onChange={event => setStatus(event.target.value)}>
              {statuses.map(code => <option key={code} value={code}>{code}</option>)}
            </select> : <span>200</span>}
          <span className="api-response-mime">application/json</span>
        </div>
      </div>
      <div hidden={status !== "200"}>{children}</div>
      {status !== "200" && <div aria-live="polite">
          {Object.entries(errors[status]).map(([name, value]) => <ResponseField key={name} name={name} type={value === null ? "null" : Array.isArray(value) ? "array" : typeof value}>
              {name === "error" ? "Error message describing why the request failed." : "Additional error details."}
            </ResponseField>)}
        </div>}
    </section>;
};

## Path parameters

<ParamField path="userAddress" type="string" required>
  User wallet address.
</ParamField>

## Query parameters

<ParamField query="type" type="string" required>
  Balance type: `clmm_lp`, `legacy_lp`, `yt`, `pt`, or `sy`.
</ParamField>

<ParamField query="vault" type="string" required>
  Vault address.
</ParamField>

<ParamField query="startDate" type="string">
  Inclusive start date or ISO timestamp.
</ParamField>

<ParamField query="endDate" type="string">
  Inclusive end date or ISO timestamp.
</ParamField>

<ParamField query="page" type="number" default="1">
  Positive page number (1-indexed).
</ParamField>

<ParamField query="limit" type="number" default="500">
  Records per page. Maximum: `500`.
</ParamField>

<ParamField query="market" type="string">
  CLMM market address. Used with `type=clmm_lp`.
</ParamField>

<ParamField query="position" type="string">
  CLMM position address. Used with `type=clmm_lp`.
</ParamField>

<Note>
  Date-only values use UTC day boundaries. For example, `endDate=2026-06-10` includes records through `2026-06-10T23:59:59.999Z`.
</Note>

<RequestExample dropdown>
  ```bash cURL theme={null}
  curl 'https://api.exponent.finance/balances/historical/user/DWN3omNW69jEG3Z6yJM4PqhtpJt4UnhnoACNecvfpKb3?type=clmm_lp&vault=78MLjMXyKyjwXtHXCuZHnBUH5wMh89KwBpvoFvcBzxN1&page=1&limit=2'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get("https://api.exponent.finance/balances/historical/user/DWN3omNW69jEG3Z6yJM4PqhtpJt4UnhnoACNecvfpKb3?type=clmm_lp&vault=78MLjMXyKyjwXtHXCuZHnBUH5wMh89KwBpvoFvcBzxN1&page=1&limit=2", timeout=30)
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.exponent.finance/balances/historical/user/DWN3omNW69jEG3Z6yJM4PqhtpJt4UnhnoACNecvfpKb3?type=clmm_lp&vault=78MLjMXyKyjwXtHXCuZHnBUH5wMh89KwBpvoFvcBzxN1&page=1&limit=2");
  if (!response.ok) {
    throw new Error(`Request failed: ${response.status}`);
  }
  const data = await response.json();
  console.log(data);
  ```
</RequestExample>

### Record fields

<ApiResponse errors={{"400": {"error": "<message>"}, "500": {"error": "<message>"}}}>
  | Field | Description |
  | - | - |
  | `type`, `user_address` | Balance type and wallet address. |
  | `vault_address` | Present for `legacy_lp`, `yt`, `pt`, and `sy`. |
  | `core_balance` | Core balance for `legacy_lp`, `yt`, and `pt`. SY has no tracked core balance. |
  | `orderbook_open`, `orderbook_filled` | Open and filled orderbook balances for `yt`, `pt`, and `sy`. |
  | `market_address`, `position_address` | CLMM market and position identity. |
  | `lp_balance` | CLMM liquidity balance. |
  | `sy_balance`, `pt_balance` | Estimated SY and PT principal represented by a CLMM position. |
  | `lower_tick`, `upper_tick` | CLMM position bounds. |
  | `tokens_owed_sy`, `tokens_owed_pt` | Uncollected CLMM fees. |
  | `fee_inside_last_sy`, `fee_inside_last_pt`, `farms` | CLMM fee checkpoints and farm tracker data. |
  | `needs_recalc` | If `true`, derived CLMM SY/PT balances await recalculation and may be updated in place. |
  | `tx_signature` | Transaction associated with the change, when available. |
  | `created_at` | History timestamp; current rows use `last_updated_at`. |
</ApiResponse>

### Pagination

`pagination` contains `page`, `limit`, `total_count`, `total_pages`, `has_next`, and `has_prev`. Counts include current balance rows when included. Follow `has_next` to export subsequent pages.

#

<ResponseExample>
  ```json 200 theme={null}
  {
    "pagination": {
      "page": 1,
      "limit": 2,
      "total_count": 25,
      "total_pages": 13,
      "has_next": true,
      "has_prev": false
    },
    "data": [
      {
        "type": "clmm_lp",
        "user_address": "DWN3omNW69jEG3Z6yJM4PqhtpJt4UnhnoACNecvfpKb3",
        "market_address": "36g7SJ6HddnnJZGgWoUccTVKHn4PXKHYrZGYcMvikKvF",
        "position_address": "76KNK8XsX83xQMWjKa6U3vQwTKpbYSUdwZcLo2rcs7fQ",
        "created_at": "2026-07-08T17:28:31+00:00",
        "lp_balance": "0",
        "sy_balance": "0",
        "pt_balance": "0",
        "lower_tick": 120000,
        "upper_tick": 190000,
        "tokens_owed_sy": "0",
        "tokens_owed_pt": "0",
        "fee_inside_last_sy": "151909677609810",
        "fee_inside_last_pt": "347860915148728",
        "farms": [
          {
            "staged": "0",
            "lastSeenIndex": "0"
          },
          {
            "staged": "0",
            "lastSeenIndex": "0"
          }
        ],
        "tx_signature": "2QwU9RpbxzjoT7gd2ffu4QxrVco5LRXG8uvbp46JnWGWeFKzKqVreyink7UQ2w2ZSg6rQFpwBWb1jWxGYHk5Psuf",
        "recorded_at": "2026-07-08T17:28:32.334318+00:00",
        "needs_recalc": false
      },
      {
        "type": "clmm_lp",
        "user_address": "DWN3omNW69jEG3Z6yJM4PqhtpJt4UnhnoACNecvfpKb3",
        "market_address": "36g7SJ6HddnnJZGgWoUccTVKHn4PXKHYrZGYcMvikKvF",
        "position_address": "76KNK8XsX83xQMWjKa6U3vQwTKpbYSUdwZcLo2rcs7fQ",
        "created_at": "2026-07-08T17:26:56+00:00",
        "lp_balance": "43094463988",
        "sy_balance": "0",
        "pt_balance": "3001203229",
        "lower_tick": 120000,
        "upper_tick": 190000,
        "tokens_owed_sy": "0",
        "tokens_owed_pt": "0",
        "fee_inside_last_sy": "151909677609810",
        "fee_inside_last_pt": "347860915148728",
        "farms": [
          {
            "staged": "0",
            "lastSeenIndex": "0"
          },
          {
            "staged": "0",
            "lastSeenIndex": "0"
          }
        ],
        "tx_signature": "ybjMERMtpCCNpwE2NkCypoW6diKWjEpfcxuyAo35CV8AZ1Qw1Sb4ZiwzP4dkpGyWWp81KfxGpnTacha2SMJ7p6F",
        "recorded_at": "2026-07-08T17:26:56.883247+00:00",
        "needs_recalc": false
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "error": "<message>"
  }
  ```

  ```json 500 theme={null}
  {
    "error": "<message>"
  }
  ```
</ResponseExample>

Returns paginated historical balance records for the requested user, vault, and balance type.

<ResponseField name="pagination" type="object">
  Pagination metadata.

  <Expandable title="child attributes">
    <ResponseField name="page" type="integer">
      Current one-based page.
    </ResponseField>

    <ResponseField name="limit" type="integer">
      Records per page.
    </ResponseField>

    <ResponseField name="total_count" type="integer">
      Total matching records.
    </ResponseField>

    <ResponseField name="total_pages" type="integer">
      Total page count.
    </ResponseField>

    <ResponseField name="has_next" type="boolean">
      Whether another page exists.
    </ResponseField>

    <ResponseField name="has_prev" type="boolean">
      Whether a previous page exists.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data" type="object[]">
  Balance changes; fields vary by the requested `type`.

  <Expandable title="child attributes">
    <ResponseField name="type" type="string">
      Requested balance type.
    </ResponseField>

    <ResponseField name="user_address" type="string">
      Wallet address.
    </ResponseField>

    <ResponseField name="vault_address" type="string">
      Vault identity for non-CLMM records.
    </ResponseField>

    <ResponseField name="market_address" type="string">
      Market identity for CLMM records.
    </ResponseField>

    <ResponseField name="position_address" type="string">
      Position identity for CLMM records.
    </ResponseField>

    <ResponseField name="core_balance" type="string">
      Raw core balance for PT, YT, or legacy LP.
    </ResponseField>

    <ResponseField name="orderbook_open" type="string">
      Raw open orderbook balance for PT, YT, or SY.
    </ResponseField>

    <ResponseField name="orderbook_filled" type="string">
      Raw filled orderbook balance for PT, YT, or SY.
    </ResponseField>

    <ResponseField name="lp_balance" type="string">
      Raw CLMM liquidity.
    </ResponseField>

    <ResponseField name="sy_balance" type="string">
      Raw estimated CLMM SY principal.
    </ResponseField>

    <ResponseField name="pt_balance" type="string">
      Raw estimated CLMM PT principal.
    </ResponseField>

    <ResponseField name="needs_recalc" type="boolean">
      CLMM derived balances await recalculation when true.
    </ResponseField>

    <ResponseField name="tx_signature" type="string | null">
      Transaction associated with this change.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      History observation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.