# History & Events

> Markdown export of the Gearbox Protocol documentation page for agents and retrieval systems.

Canonical page: https://docs.gearbox.finance/developers/gm-markets-history
Source file: content/developers/gm-markets-history.mdx
Section router: https://docs.gearbox.finance/developers/llms.txt
Section full export: https://docs.gearbox.finance/developers/llms-full.txt

Query historical time-series data and track parameter changes across Gearbox Markets using the SDK vNext. History and event feeds require the backend enrichment service but degrade gracefully when it is unavailable.

## Historical Metrics

Use `sdk.history.getMetric()` to retrieve time-series data for any pool or strategy metric.

```typescript
import { GearboxSDK } from "@gearbox-protocol/sdk/official";

const sdk = await GearboxSDK.init({
  chains: [1, 42161],
  startFromCache: true,
});

// APY history for a pool over the last 90 days
const apyHistory = await sdk.history.getMetric({
  entity: poolAddress,
  chainId: 1,
  metric: "apy",
  period: "90d",
});

for (const point of apyHistory.data) {
  console.log(`${point.date}: ${point.value}%`);
}
```

### Available Metrics

| Metric | Entity Type | Description |
|---|---|---|
| `"apy"` | Pool | Composite supply APY (organic + incentives) |
| `"utilization"` | Pool | Pool utilization rate (0-1) |
| `"tvl"` | Pool | Total value locked in underlying token |
| `"borrow_rate"` | Pool | Current borrow rate for the pool |
| `"share_price"` | Pool | Diesel token price in underlying — drops indicate bad debt |
| `"oracle_price"` | Token | Oracle price history for a collateral token |

### Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `entity` | `string` | Yes | Pool address, strategy ID, or token address |
| `chainId` | `number` | Yes | Chain ID for the entity |
| `metric` | `string` | Yes | One of the metrics listed above |
| `period` | `string` | No | Time window: `"7d"`, `"30d"`, `"90d"`, `"1y"`. Default `"90d"` |
| `resolution` | `string` | No | Data point interval: `"1h"`, `"1d"`, `"1w"`. Default `"1d"` |

### Multi-Metric Query

Fetch several metrics at once for a single entity:

```typescript
const [apy, utilization, tvl] = await Promise.all([
  sdk.history.getMetric({ entity: poolAddress, chainId: 1, metric: "apy", period: "90d" }),
  sdk.history.getMetric({ entity: poolAddress, chainId: 1, metric: "utilization", period: "90d" }),
  sdk.history.getMetric({ entity: poolAddress, chainId: 1, metric: "tvl", period: "90d" }),
]);
```

### Share Price Monitoring

Share price is the primary indicator for bad debt socialization. A drop in share price means losses were distributed to LPs:

```typescript
const sharePrice = await sdk.history.getMetric({
  entity: poolAddress,
  chainId: 1,
  metric: "share_price",
  period: "90d",
  resolution: "1d",
});

// Detect any drops
for (let i = 1; i < sharePrice.data.length; i++) {
  const prev = sharePrice.data[i - 1].value;
  const curr = sharePrice.data[i].value;
  if (curr < prev) {
    console.warn(`Share price dropped on ${sharePrice.data[i].date}: ${prev} → ${curr}`);
  }
}
```

## Event Feed

Use `sdk.events.getFeed()` to retrieve a log of parameter changes — both past governance actions and pending scheduled changes.

```typescript
const feed = await sdk.events.getFeed({
  entity: poolAddress,
  chainId: 1,
  since: "2025-01-01T00:00:00Z",
});

for (const event of feed.events) {
  console.log(`[${event.timestamp}] ${event.type}: ${event.description}`);
}
```

### Event Types

| Event Type | Description |
|---|---|
| `"collateral_added"` | New collateral token added to a credit manager |
| `"collateral_removed"` | Token forbidden or removed |
| `"lt_changed"` | Liquidation threshold updated |
| `"debt_limit_changed"` | Credit manager debt limit adjusted |
| `"irm_updated"` | Interest rate model parameters changed |
| `"cm_added"` | New credit manager connected to pool |
| `"quota_rate_changed"` | Token quota rate adjusted |
| `"curator_changed"` | Pool curator address updated |
| `"oracle_changed"` | Oracle feed updated for a collateral token |

### Feed Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `entity` | `string` | Yes | Pool address or credit manager address |
| `chainId` | `number` | Yes | Chain ID |
| `since` | `string` | No | ISO timestamp — only events after this time |
| `includeProjected` | `boolean` | No | Include pending/scheduled changes. Default `true` |

## State Projections

Instead of abstract event labels, the SDK provides concrete before/after snapshots through State Projections. This lets you see exactly how a pending governance change will affect parameters.

### PoolStateProjection

```typescript
const projection = await sdk.events.getProjection({
  entity: poolAddress,
  chainId: 1,
});

// Current state
console.log("Current parameters:", projection.current);

// Projected state after pending changes
if (projection.projected) {
  console.log("Projected parameters:", projection.projected);

  // See individual parameter diffs
  for (const diff of projection.changes) {
    console.log(`${diff.parameter}: ${diff.from} → ${diff.to} (ETA: ${diff.eta})`);
  }
}
```

### Projection Fields

| Field | Type | Description |
|---|---|---|
| `current` | `ParameterSnapshot` | Current on-chain parameter values |
| `projected` | `ParameterSnapshot \| null` | Parameters after all pending changes apply. `null` when backend unavailable |
| `changes` | `ParameterDiff[]` | List of individual parameter diffs |

### ParameterDiff

Each diff in `changes` is a concrete before/after comparison:

| Field | Type | Description |
|---|---|---|
| `parameter` | `string` | Parameter name (e.g. `"quotaRate"`, `"debtLimit"`, `"liquidationThreshold"`) |
| `token` | `string \| null` | Affected token address, if parameter is token-scoped |
| `from` | `string \| number` | Current value |
| `to` | `string \| number` | Value after change applies |
| `eta` | `string` | ISO timestamp when the change takes effect |
| `status` | `"pending" \| "queued" \| "executed"` | Current status of the change |

### Example: Quota Rate Change

```typescript
const projection = await sdk.events.getProjection({
  entity: poolAddress,
  chainId: 1,
});

// Find quota rate changes
const quotaChanges = projection.changes.filter(d => d.parameter === "quotaRate");

for (const change of quotaChanges) {
  console.log(
    `${change.token} quota rate: ${change.from}% → ${change.to}% (ETA: ${change.eta})`
  );
  // Output: "USDC quota rate: 3% → 4% (ETA: 2025-04-20T12:00:00Z)"
}
```

## Graceful Degradation

History and event data come from the Gearbox backend (`GET /v2/history/:metric`, `GET /v2/events`). When the backend is unavailable, the SDK degrades gracefully:

| Feature | Backend Available | Backend Unavailable |
|---|---|---|
| `sdk.history.getMetric()` | Full time-series data | Throws or returns empty `data[]` |
| `sdk.events.getFeed()` | Past + pending events | On-chain events only, no pending |
| `projection.projected` | Concrete snapshot | `null` |
| `projection.changes` | Full diff list | `[]` (empty array) |

Check backend availability before relying on enriched data:

```typescript
const result = await sdk.history.getMetric({
  entity: poolAddress,
  chainId: 1,
  metric: "apy",
});

if (!result.meta.backendAvailable) {
  console.warn("Backend unavailable — historical data may be incomplete");
}
```

## Backend Endpoints

The SDK vNext communicates with these backend endpoints for history and events:

| Endpoint | SDK Method | Description |
|---|---|---|
| `GET /v2/history/:metric` | `sdk.history.getMetric()` | Time-series metric data |
| `GET /v2/events` | `sdk.events.getFeed()` | Parameter change feed |

## Learn More

- [Opportunities](https://docs.gearbox.finance/developers/gm-markets-opportunities) — discovering yield opportunities
- [Markets Data](https://docs.gearbox.finance/developers/gm-markets-data) — reading current pool metrics and credit manager state
- [Interest Rates](https://docs.gearbox.finance/developers/gm-markets-rates) — understanding the interest rate model
- [Positions](https://docs.gearbox.finance/developers/gm-accounts-positions) — managing positions with prepare/preview/execute