# Checkpoints

List the signed-in account's frozen testnet season checkpoints, with trading, funding, and portfolio recaps.

`client.checkpoints` reads the signed-in account's testnet season checkpoints. A checkpoint is a frozen recap of one season for the root account and all of its subaccounts: trading activity, order tools, funding flows, balances, VIP tier, badges, and the season result. Every method needs a session JWT; API keys are refused with `PermissionError`.

USD values and ratios are decimal strings. A USD value that could not be computed is `undefined`, never `"0"`. Timestamps are epoch milliseconds, and dates are UTC `YYYY-MM-DD` strings.

## Methods

| Method | Summary                                       |
| ------ | --------------------------------------------- |
| `list` | List the account's checkpoints, newest first. |

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

Returns a `Checkpoint[]`, newest first, at most one per season. An account without checkpoints gets `[]`. Input is optional.

A checkpoint covers the root account and all of its subaccounts, so `subaccountId` reads the checkpoints of the subaccount's root account, which must be the caller's own. A `subaccountId` that decodes to zero throws `ValidationError` before the request is sent.

```ts
const checkpoints = await client.checkpoints.list();
const [latest] = checkpoints;
if (latest) {
	console.log(latest.number, latest.volumeUsd, latest.trades, latest.seasonResultUsd);
}
```

```ts
interface ListCheckpointsInput {
	subaccountId?: string;
}
```

## `Checkpoint`

| Group    | Fields                                                                                                                                                                                   |
| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Season   | `number` (1 and up), `seasonStart`, `seasonEnd`, `takenAt`                                                                                                                               |
| Activity | `volumeUsd`, `trades`, `orders`, `daysActive`, `longestStreak`, `marketsTraded`, `makerTrades`, `takerTrades`, `selfTrades`, `firstTradeAt?`, `busiestDay?`, `mostActiveHourUtc?`        |
| Markets  | `topPairs`, `dailyVolume`, `tradesByWeekdayHour`, `biggestTradeUsd`, `biggestTrade?`                                                                                                     |
| Orders   | `orderTypes`, `timeInForce`, `tools`, `postOnly`, `amends`, `filledOrders`, `partiallyFilledOrders`, `canceledOrders`, `rejectedOrders`, `fillRate`, `cancelRatio`, `medianLimitRestMs?` |
| VIP      | `vipTierAtCheckpoint`, `peakVipTier`, `vipTimeline`                                                                                                                                      |
| Badges   | `badges`                                                                                                                                                                                 |
| Balances | `portfolioValue`, `tradingBalances`, `fundingBalances`                                                                                                                                   |
| Funding  | `deposits`, `withdrawals`, `fundingByDay`, `transfersIn`, `transfersOut`, `internalTransfers`                                                                                            |
| Claims   | `dailyClaims`, `dailyClaimAmounts`                                                                                                                                                       |
| Result   | `inflowUsd?`, `outflowUsd?`, `netInflowUsd?`, `finalValueUsd?`, `seasonResultUsd?`                                                                                                       |
| Other    | `subaccounts`, `incomplete`                                                                                                                                                              |

Counts are `number`. `fillRate` and `cancelRatio` are decimal strings from `"0"` to `"1"`. `tradesByWeekdayHour` is 7 rows, Monday first, of 24 UTC-hour trade counts. `orderTypes` counts `limit` and `market`; `timeInForce` counts `gtc`, `ioc`, `fok`, and `gtd`; `tools` counts `stopLoss`, `takeProfit`, `trailingStop`, `twap`, and `ladder`.

`incomplete` lists the values computed from partial evidence. Show them with an approximation marker. Its labels are `"volume"`, `"top_pairs"`, `"order_types"`, `"time_in_force"`, `"order_status"`, `"tools"`, `"median_limit_rest"`, `"deposits"`, `"withdrawals"`, `"internal_transfers"`, `"daily_claim_amounts"`, `"portfolio_value"`, `"trading_balances"`, `"funding_balances"`, `"transfers"`, and `"season_result"`. Points in `dailyVolume` and `portfolioValue` carry their own `approximate` flag.

Each badge is `{ badge, earnedAt }`, where `badge` is `"first_trade"`, `"seven_day_streak"`, `"three_markets"`, `"volume_1000_usd"`, `"hundred_trades"`, `"ten_markets"`, `"thirty_day_streak"`, or `"every_order_tool"`.

### Asset amounts

`tradingBalances`, `fundingBalances`, `dailyClaimAmounts`, and the `amounts` of `deposits` and `withdrawals` are `CheckpointAssetAmount[]`.

```ts
interface CheckpointAssetAmount {
	asset: string;
	amount: string; // signed decimal
	usd?: string; // absent when unpriced, and always absent when excludedFromValue
	excludedFromValue: boolean;
}
```

When `excludedFromValue` is `true`, the asset is not account equity, such as a testnet faucet token. It is listed by amount only, has no `usd`, and counts toward no USD total. A missing `usd` on such an asset is not a pricing gap. A response that gives one a `usd` value is rejected with `ValidationError`.

### Nested shapes

```ts
interface CheckpointPairActivity {
	symbolId: number;
	symbol: string;
	volumeUsd: string;
	trades: number;
}

interface CheckpointVolumePoint {
	day: number; // epoch ms
	usd: string;
	approximate: boolean;
	trades: number;
}

interface CheckpointPortfolioValuePoint {
	hour: number; // epoch ms
	usd: string; // signed
	approximate: boolean;
}

interface CheckpointBiggestTrade {
	symbolId: number;
	symbol: string;
	side: "buy" | "sell" | "unspecified";
	at: number; // epoch ms
}

interface CheckpointFundingFlowSummary {
	count: number;
	chains: { polyesterChainId: number; chainName: string; total: CheckpointFlowTotal }[];
	amounts: CheckpointAssetAmount[];
}

interface CheckpointFlowTotal {
	count: number;
	usd?: string; // absent when any operation had no USD value
}

interface CheckpointFundingDay {
	date: string; // UTC YYYY-MM-DD
	depositUsd?: string;
	withdrawalUsd?: string;
}

interface CheckpointVipTierChange {
	date: string; // UTC YYYY-MM-DD
	tier: number; // 0 through 10
}
```

## Related

- [VIP](https://testnet.polyester.com/docs/sdk/typescript/reference/vip) for the live tier behind `vipTierAtCheckpoint`.
- [Balances](https://testnet.polyester.com/docs/sdk/typescript/reference/balances) for current balances and equity history.
- [Account services](https://testnet.polyester.com/docs/sdk/typescript/reference/account-services) for the other account-level services.