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

# Get Market History

> Read indexed time series of pool state, rates and volumes

Returns a bucketed time series for the market, built from on-chain snapshots read through the subgraph. Use it to chart liquidity, utilization, rates and collateral price over time.

History is an enhancement rather than a dependency, so an indexing outage never fails the request. The call returns `200` with `available: false` and a `reason` instead, and callers should branch on `available` before reading `points`.

## Path Parameters

<ParamField path="marketId" type="string" required>Market ID.</ParamField>

## Query Parameters

<ParamField query="range" type="string" default="30d">
  Window to cover. One of `24h`, `7d`, `30d`, `90d`, `1y`, `all`. Any other value is rejected with `VALIDATION_ERROR`.
</ParamField>

<ParamField query="resolution" type="string">
  Bucket size, `hour` or `day`. Defaults to the natural resolution for the range: `hour` for `24h` and `7d`, `day` for everything else.
</ParamField>

## Response Fields

<ResponseField name="data" type="object">
  <Expandable>
    <ResponseField name="marketId" type="string">Market ID.</ResponseField>
    <ResponseField name="marketAddress" type="string">Market contract address.</ResponseField>
    <ResponseField name="borrowAssetSymbol" type="string">Settlement token (stablecoin) symbol.</ResponseField>
    <ResponseField name="collateralTokenSymbol" type="string">Collateral token symbol, or null.</ResponseField>
    <ResponseField name="available" type="boolean">Whether indexed history could be read at all. When `false`, only `reason` and `message` accompany it.</ResponseField>
    <ResponseField name="indexed" type="boolean">Whether this market has produced at least one snapshot.</ResponseField>
    <ResponseField name="reason" type="string">`MARKET_NOT_INDEXED` or `AWAITING_FIRST_SNAPSHOT` when `indexed` is false, otherwise null. When `available` is false, one of `NOT_CONFIGURED`, `NO_MARKET_ADDRESS`, `INDEX_STALE`, `INDEXING_ERRORS`, `UPSTREAM_ERROR`, `QUERY_ERROR`, `EMPTY_RESPONSE`.</ResponseField>
    <ResponseField name="message" type="string">Human-readable explanation accompanying `reason`, otherwise null.</ResponseField>
    <ResponseField name="range" type="string">Applied range.</ResponseField>
    <ResponseField name="resolution" type="string">Applied resolution.</ResponseField>
    <ResponseField name="borrowAssetDecimals" type="integer">Decimals used to format settlement amounts.</ResponseField>
    <ResponseField name="collateralDecimals" type="integer">Decimals used to format collateral amounts.</ResponseField>
    <ResponseField name="snapshotCount" type="integer">Total snapshots recorded for this market.</ResponseField>
    <ResponseField name="firstIndexedAt" type="string">ISO 8601 timestamp of the first point returned, or null.</ResponseField>
    <ResponseField name="lastIndexedAt" type="string">ISO 8601 timestamp of the most recent snapshot, or null.</ResponseField>
    <ResponseField name="truncated" type="boolean">`true` when the window held more than 1000 buckets and the series was cut.</ResponseField>

    <ResponseField name="points" type="array">
      Buckets ordered oldest first.

      <Expandable>
        <ResponseField name="timestamp" type="integer">Bucket start, milliseconds since epoch.</ResponseField>
        <ResponseField name="date" type="string">Bucket start as an ISO 8601 timestamp.</ResponseField>
        <ResponseField name="totalLiquidity" type="string">Liquidity supplied to the pool.</ResponseField>
        <ResponseField name="totalBorrowed" type="string">Principal outstanding.</ResponseField>
        <ResponseField name="availableLiquidity" type="string">Uncommitted liquidity.</ResponseField>
        <ResponseField name="poolValue" type="string">Pool value including accrued interest.</ResponseField>
        <ResponseField name="pendingLiquidationDebt" type="string">Debt sitting in unsettled liquidations.</ResponseField>
        <ResponseField name="totalCollateral" type="string">Collateral locked, in collateral units.</ResponseField>
        <ResponseField name="collateralValue" type="string">Collateral locked, valued in the borrow asset.</ResponseField>
        <ResponseField name="collateralPrice" type="string">Collateral price at the bucket.</ResponseField>
        <ResponseField name="utilizationRate" type="integer">Utilization in basis points.</ResponseField>
        <ResponseField name="borrowRate" type="integer">Borrow rate in basis points.</ResponseField>
        <ResponseField name="supplyRate" type="integer">Supply rate in basis points.</ResponseField>
        <ResponseField name="exchangeRate" type="string">LP share exchange rate, 18 decimals.</ResponseField>
        <ResponseField name="openLiquidity" type="string">Liquidity at bucket open. `highLiquidity` and `lowLiquidity` accompany it.</ResponseField>
        <ResponseField name="openBorrowed" type="string">Borrowings at bucket open. `highBorrowed` and `lowBorrowed` accompany it.</ResponseField>
        <ResponseField name="depositVolume" type="string">Flow during the bucket. `withdrawVolume`, `borrowVolume`, `repayVolume` and `liquidationVolume` accompany it.</ResponseField>
        <ResponseField name="carriedForward" type="boolean">Present and `true` on a synthesized opening point that carries pre-window state onto the left edge. Its flow volumes are zeroed because they belong to an earlier window.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="totals" type="object">
      Lifetime aggregates for the market, or null before the first snapshot. Carries `totalLiquidity`, `totalBorrowed`, `poolValue`, `pendingLiquidationDebt`, `totalCollateral`, `collateralValue`, `collateralPrice`, `utilizationRate`, `borrowRate`, `supplyRate`, `cumulativeDeposited`, `cumulativeWithdrawn`, `cumulativeBorrowed`, `cumulativePrincipalRepaid`, `cumulativeInterestPaid`, `cumulativeBadDebt`, `loanCount`, `activeLoanCount`, `liquidationCount` and `liquidityProviderCount`.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  Buckets exist only where something happened. Gaps are filled by carrying the previous bucket forward, which is exact for pool state because balances genuinely do not change between mutations.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.trusset.org/lending-external-securities/api/markets/{marketId}/history?range=7d&resolution=hour" \
    -H "X-API-Key: trusset_your_key_here"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    `https://api.trusset.org/lending-external-securities/api/markets/${marketId}/history?range=30d`,
    { headers: { 'X-API-Key': 'trusset_your_key_here' } }
  );
  const { data } = await res.json();
  if (data.available && data.indexed) {
    chart(data.points);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "marketId": "clx_secmarket_001",
      "marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
      "borrowAssetSymbol": "USDC",
      "collateralTokenSymbol": "ACME",
      "available": true,
      "indexed": true,
      "reason": null,
      "message": null,
      "range": "7d",
      "resolution": "hour",
      "borrowAsset": "0x98ad0ca091552e23c564b41c74282e5343d03e8a",
      "borrowAssetDecimals": 6,
      "collateralToken": "0x9f8c1d4b2e7a3056c1b8f4d29e0a7c3518b6d24f",
      "collateralDecimals": 18,
      "snapshotCount": 412,
      "firstIndexedAt": "2025-06-08T12:00:00.000Z",
      "lastIndexedAt": "2025-06-15T11:00:00.000Z",
      "truncated": false,
      "points": [
        {
          "timestamp": 1749384000000,
          "date": "2025-06-08T12:00:00.000Z",
          "totalLiquidity": "250000.000000",
          "totalBorrowed": "112500.000000",
          "availableLiquidity": "137500.000000",
          "poolValue": "250412.881000",
          "pendingLiquidationDebt": "0.000000",
          "totalCollateral": "1500.000000000000000000",
          "collateralValue": "157230.000000",
          "collateralPrice": "104.820000",
          "utilizationRate": 4500,
          "borrowRate": 620,
          "supplyRate": 279,
          "exchangeRate": "1.001651524000000000",
          "openLiquidity": "250000.000000",
          "highLiquidity": "250000.000000",
          "lowLiquidity": "250000.000000",
          "openBorrowed": "112500.000000",
          "highBorrowed": "112500.000000",
          "lowBorrowed": "112500.000000",
          "depositVolume": "0.000000",
          "withdrawVolume": "0.000000",
          "borrowVolume": "0.000000",
          "repayVolume": "0.000000",
          "liquidationVolume": "0.000000",
          "carriedForward": true
        }
      ],
      "totals": {
        "totalLiquidity": "250000.000000",
        "totalBorrowed": "112500.000000",
        "poolValue": "250412.881000",
        "pendingLiquidationDebt": "0.000000",
        "totalCollateral": "1500.000000000000000000",
        "collateralValue": "157230.000000",
        "collateralPrice": "104.820000",
        "utilizationRate": 4500,
        "borrowRate": 620,
        "supplyRate": 279,
        "cumulativeDeposited": "400000.000000",
        "cumulativeWithdrawn": "150000.000000",
        "cumulativeBorrowed": "212500.000000",
        "cumulativePrincipalRepaid": "100000.000000",
        "cumulativeInterestPaid": "412.881000",
        "cumulativeBadDebt": "0.000000",
        "loanCount": 9,
        "activeLoanCount": 3,
        "liquidationCount": 1,
        "liquidityProviderCount": 4
      }
    }
  }
  ```

  ```json Response - Not Indexed theme={null}
  {
    "success": true,
    "data": {
      "marketId": "clx_secmarket_002",
      "marketAddress": "0x1c74f9a2b0e63d581a47c02f9b8de3517a604c2b",
      "borrowAssetSymbol": "USDC",
      "collateralTokenSymbol": "ACME",
      "available": true,
      "indexed": false,
      "reason": "MARKET_NOT_INDEXED",
      "message": "This market has not been indexed yet",
      "range": "30d",
      "resolution": "day",
      "borrowAssetDecimals": 6,
      "collateralDecimals": 18,
      "snapshotCount": 0,
      "points": [],
      "totals": null
    }
  }
  ```

  ```json Response - Unavailable theme={null}
  {
    "success": true,
    "data": {
      "marketId": "clx_secmarket_001",
      "marketAddress": "0x70a0e25c7b768b87e658348b3b577678a173e038",
      "borrowAssetSymbol": "USDC",
      "collateralTokenSymbol": "ACME",
      "available": false,
      "reason": "NOT_CONFIGURED",
      "message": "Historical indexing is not configured for this network"
    }
  }
  ```
</ResponseExample>

## Error Codes

| Code               | HTTP  | Cause                                                     |
| ------------------ | ----- | --------------------------------------------------------- |
| `VALIDATION_ERROR` | `400` | `range` or `resolution` is not one of the accepted values |
| `MARKET_NOT_FOUND` | `404` | No market with this ID on your instance                   |