# Chain analytics

Public chain chart series (zToken supply and unified balances) as columnar time windows.

`client.chainAnalytics` reads public chain chart series: zToken supply and unified asset balances over time. It uses the public transport, so no authentication is required.

Every response is columnar: a single value array plus a time window (`startTsSec`, `endTsSec`, `points`). Values are decimal strings scaled to the asset. The window is evenly spaced, so you derive per-point timestamps with the helpers below rather than reading a timestamp column.

Each request takes a window: a `range` (default `"1d"`, one of `1d`, `7d`, `30d`, `90d`, `180d`, `365d`), an optional `bucket`, and optional `startTsSec` / `endTsSec` overrides.

## Methods

| Method                      | Summary                                          |
| --------------------------- | ------------------------------------------------ |
| `getZippedAssetSupply`      | zToken supply series for one zipped asset.       |
| `getZippedAssetSupplyGroup` | Supply series for every zipped asset in a group. |
| `getUnifiedAssetBalances`   | Total public unified-asset balance series.       |

### `getZippedAssetSupply(input, options?)`

Returns a `ZippedAssetSupplyResponse` for one zipped asset.

```ts
const supply = await client.chainAnalytics.getZippedAssetSupply({
	zippedAssetId: 1,
	range: "30d",
});

console.log(supply.points, supply.totalSupply.at(-1));
```

### `getZippedAssetSupplyGroup(input, options?)`

Returns a `ZippedAssetSupplyGroupResponse` with one supply series per zipped asset in the group.

```ts
const group = await client.chainAnalytics.getZippedAssetSupplyGroup({
	groupId: "stables",
	range: "90d",
});

for (const series of group.series) {
	console.log(series.zippedAssetId, series.totalSupply.at(-1));
}
```

### `getUnifiedAssetBalances(input, options?)`

Returns a `UnifiedAssetBalancesResponse`: the total public balance of one unified asset over time.

```ts
const balances = await client.chainAnalytics.getUnifiedAssetBalances({
	assetId: 1,
	range: "7d",
});

console.log(balances.points, balances.totalBalance.at(-1));
```

## Reading the time window

Responses do not carry a timestamp column. Use `columnarTimestampSecAt(window, index)` for one point, or `expandColumnarTimestampsSec(window)` for the full array. Both take a `{ startTsSec, endTsSec, points }` window, which each response already satisfies.

```ts
import { expandColumnarTimestampsSec, columnarTimestampSecAt } from "@polyester/sdk";

const supply = await client.chainAnalytics.getZippedAssetSupply({ zippedAssetId: 1, range: "30d" });

const times = expandColumnarTimestampsSec(supply); // number[] of epoch seconds
const points = times.map((tsSec, i) => ({ tsSec, value: supply.totalSupply[i] }));

const lastTs = columnarTimestampSecAt(supply, supply.points - 1);
```

## Shapes

```ts
interface ZippedAssetSupplyResponse {
	zippedAssetId: number;
	range: "1d" | "7d" | "30d" | "90d" | "180d" | "365d" | "unspecified";
	bucket: string;
	startTsSec: number;
	endTsSec: number;
	points: number;
	totalSupply: string[]; // decimal strings, length === points
}

interface ZippedAssetSupplyGroupResponse {
	groupId: string;
	range: "1d" | "7d" | "30d" | "90d" | "180d" | "365d" | "unspecified";
	bucket: string;
	startTsSec: number;
	endTsSec: number;
	points: number;
	series: Array<{ zippedAssetId: number; totalSupply: string[] }>;
}

interface UnifiedAssetBalancesResponse {
	assetId: number;
	range: "1d" | "7d" | "30d" | "90d" | "180d" | "365d" | "unspecified";
	bucket: string;
	startTsSec: number;
	endTsSec: number;
	points: number;
	totalBalance: string[]; // decimal strings, length === points
}
```

## Related

- [Market data guide](https://testnet.polyester.com/docs/sdk/typescript/guides/market-data) for the task-oriented walkthrough.
- [Streaming guide](https://testnet.polyester.com/docs/sdk/typescript/guides/streaming) for the subscription model.
- [Candles](https://testnet.polyester.com/docs/sdk/typescript/reference/candles) for OHLCV series.
- [Catalog reference](https://testnet.polyester.com/docs/sdk/typescript/reference/catalog) for asset and pair metadata.