> ## Documentation Index > Fetch the complete documentation index at: https://docs.0xmonaco.com/llms.txt > Use this file to discover all available pages before exploring further. # Analytics > Exchange-wide totals, series, market volume, treasury net fees, builders, wallets, custody and vault flows The analytics endpoints serve the exchange-wide figures the Monaco explorer shows. They are **public** — no authentication is required — and each client IP has a read budget (`429` with `Retry-After` when it runs out). ```typescript theme={null} import { MonacoSDK } from "@0xmonaco/core"; // Public — works without a wallet or session const day = await sdk.analytics.getProtocolTotals(); ``` ## Windows Every windowed method takes `{ window, startTime, endTime }`: * `window`: `24h` (default), `7d`, `30d`, `all` or `custom`. * `endTime`: the window's end as Unix milliseconds; defaults to now. Any window may end in the past, so the previous 7 days are `{ window: "7d", endTime: current.window.startTime - 1 }`: both ends are inclusive, and ending at `startTime` itself would count a bucket twice whenever the start falls on a bucket boundary. A window counted in hours (2.5 days or shorter) must start within the last 90 days, the history hourly active-taker counts are kept for; an older one is refused with `400`. * `startTime`: the start of a `custom` window, as Unix milliseconds. It is required with `custom` and rejected with any other window. A custom window may span at most 3,660 days. The server picks the bucket size from the window's length — hour up to 2.5 days, day up to 45 days, week beyond — and counts every bucket whose start lies in `[startTime, endTime]`. Buckets are UTC and weeks start Monday. The bucket holding `endTime` is included and is usually partial. Every response echoes the resolved `window` (`startTime`, `endTime`, `granularity`). ## Which trades each figure counts * **Displayed builders only:** `volumeUsd`, `spotVolumeUsd`, `perpVolumeUsd` and `tradesCount`. A trade routed by a builder the explorer hides is not counted. * **Every trade:** `protocolFeesUsd` (the protocol taker fee; no builder add-ons or maker fees), `activeTakers` (distinct taker wallets, each counted once across the window), `newTraders` (wallets whose first trade on the protocol falls in the window, each counted once however many builders it traded through), and every figure of `listMarketVolumes`. * **New accounts:** `newAccounts` counts sign-ups: accounts registered in the window under any application, whether or not they ever traded, hidden builders included. `newTraders` counts first trades instead. Every sign-up counts, in buckets without a trade too, and `window: "all"` starts where the analytics history does, like every other figure. * **USDC custody:** `depositsUsd`, `withdrawalsUsd`, `netFlowUsd` and the total value locked (`tvlUsd`, `openingTvlUsd`) count USDC only, at 1 USD; other tokens are unvalued. A withdrawal counts when it is initiated, not when the vault pays it out. Total value locked is a balance: the USDC the vault held when the explorer's history starts, plus the USDC deposited less the USDC withdrawals initiated since, never below zero, and `null` before any custody is known. Where the history starts at the exchange's first event (mainnet) that opening is zero; development and staging start later and carry in the balance the vault held then, so their figures match the vault on-chain. USD amounts are decimal strings (USDC counts 1:1). Figures are cached for up to 30 seconds, and the display rules for another 30, so a builder an operator hides leaves the public volume within about a minute. ## Get Protocol Totals **getProtocolTotals** `(params?: AnalyticsWindowParams) =\> Promise\` Protocol totals over a window. **Returns:** `GetProtocolTotalsResponse`: `window`, `volumeUsd`, `spotVolumeUsd`, `perpVolumeUsd`, `tradesCount`, `protocolFeesUsd`, `activeTakers`, `newTraders`, `newAccounts`, `depositsUsd`, `withdrawalsUsd`, `netFlowUsd`, `activeAccounts` (distinct wallets that took a trade, received a deposit or were paid out a withdrawal initiated in the window, by payout address), `tvlUsd` (at the end of the window's last bucket) and `openingTvlUsd` (at the start of its first). `tvlUsd` less `openingTvlUsd` is the window's change in total value locked. **Example:** ```typescript theme={null} const week = await sdk.analytics.getProtocolTotals({ window: "7d" }); // Both ends are inclusive: end 1 ms before this window starts. const previous = await sdk.analytics.getProtocolTotals({ window: "7d", endTime: week.window.startTime - 1 }); ``` ## Get Protocol Series **getProtocolSeries** `(params?: AnalyticsWindowParams) =\> Promise\` The same figures per bucket, oldest first. Every bucket of the window has a point; a bucket without trades carries zeros. `activeTakers` is distinct within each bucket, so the points' active takers do not sum to the window's. Each point's `tvlUsd` is the total value locked at the end of its bucket, carried across buckets where custody did not move; `depositsUsd`, `withdrawalsUsd` and `netFlowUsd` are the bucket's own. **Returns:** `GetProtocolSeriesResponse`: `window` and `points`, each with `bucketStart` (Unix milliseconds) and the totals' figures. **Example:** ```typescript theme={null} const { window, points } = await sdk.analytics.getProtocolSeries({ window: "30d" }); console.log(window.granularity); // "day" ``` ## List Market Volumes **listMarketVolumes** `(params?: ListMarketVolumesParams) =\> Promise\` Volume per market over a window, every trade counted, largest first. `limit` is 1 to 100 (default 25). Resolve each market's symbol from the trading pairs listing. **Returns:** `ListMarketVolumesResponse`: `window` and `markets`, each with `tradingPairId`, `volumeUsd`, `protocolFeesUsd` and `tradesCount`. **Example:** ```typescript theme={null} const { markets } = await sdk.analytics.listMarketVolumes({ window: "24h", limit: 10 }); ``` ## Get Treasury Net Fees **getTreasuryNetFees** `() =\> Promise\` Monaco's all-time net fees, after the rewards it pays out. Not windowed. The definition may widen to more fee sources without a contract change. **Returns:** `GetTreasuryNetFeesResponse`: `netFeesUsd` (negative when payouts exceed fees; `"0"` before any fee) and `countingSince` (Unix milliseconds of the first counted fee; `null` before any). ## Builders A builder is an application, or a display group that shows several applications as one. Each `Builder` carries `id`, `kind` (`application` or `group`), `name`, `code`, `color`, `verified`, `applications` (each with `clientId`, `active`, `archived`, `additionalTakerFeeBps` and `additionalMakerFeeBps`) and, for an application shown under a display group, `group` (`id`, `name`, `code`). A builder key is an application or group uuid, an application or group code, or an application client id. An application key answers that application, grouped or not; a group key answers the group over its displayed applications. A builder the explorer hides answers `404`, exactly as an unknown key, and is left out of every list. Builder fees are the builder's own add-ons, never the protocol taker fee: `feesUsd` is `takerFeesUsd` (on the trades its applications took) plus `makerFeesUsd` (on the trades they made, whoever took them). `volumeUsd`, the spot/perp split and `tradesCount` count the trades its applications took; `activeTakers` counts each wallet once across them; `newTraders` counts first trades per application and wallet; `newAccounts` counts the accounts registered under its applications, summed over a group's applications. **listBuilders** `() =\> Promise\` Every displayed builder once, by name. Archived applications are left out. **Example:** ```typescript theme={null} const { builders } = await sdk.analytics.listBuilders(); ``` **getBuilder** `(builder: string) =\> Promise\` One builder by key. **Example:** ```typescript theme={null} const { builder } = await sdk.analytics.getBuilder("MON"); ``` **getBuilderTotals** `(builder: string, params?: AnalyticsWindowParams) =\> Promise\` One builder's figures over a window: `window`, `builder`, `volumeUsd`, `spotVolumeUsd`, `perpVolumeUsd`, `tradesCount`, `feesUsd`, `takerFeesUsd`, `makerFeesUsd`, `activeTakers`, `newTraders`, `newAccounts`, `depositsUsd` (USDC deposited through its applications, leaving out deposits to the insurance fund), `withdrawalsUsd` (USDC withdrawals its applications initiated) and `netFlowUsd`. Withdrawals are attributed to the application that initiated them. A window counted in hours must start within the last 90 days. **Example:** ```typescript theme={null} const week = await sdk.analytics.getBuilderTotals("MON", { window: "7d" }); ``` **getBuilderSeries** `(builder: string, params?: AnalyticsWindowParams) =\> Promise\` The same figures per bucket, oldest first, one point per bucket (zeros where nothing traded). A running sum of `newTraders` gives the builder's cumulative traders over the window. **listBuilderLeaderboard** `(params?: ListBuilderLeaderboardParams) =\> Promise\` Displayed builders ranked by volume over a window, a display group as one row; `limit` is 1 to 100 (default 25). Each row has `builder` and the totals' figures. `activeTakers` is distinct per builder; with `window: "all"` it is every wallet that ever traded through the builder, and it is `null` for a window counted in hours that starts more than 90 days ago (the rest of the row is still answered). A builder that only took deposits or only registered accounts ranks with zero volume. A builder's share is its `volumeUsd` over `getProtocolTotals` `volumeUsd`, which counts the same displayed builders. **Example:** ```typescript theme={null} const { rows } = await sdk.analytics.listBuilderLeaderboard({ window: "30d", limit: 10 }); ``` ## Wallets, custody and vault flows These reads are not windowed. Wallet figures are all-time **taker** volume, so a wallet that only made markets has no totals. Custody counts a withdrawal when it is **initiated**, not when the vault pays it out on-chain. `pendingWithdrawalsRaw` is what was initiated but not yet executed and is still physically in the vault, so the vault's balance is `custodyRaw` plus `pendingWithdrawalsRaw`. `custodyRaw` is `openingRaw` (what the vault held when the explorer's history starts: `"0"` on mainnet) plus `depositedRaw` less `withdrawnRaw`, which count only what happened since. Custody is updated asynchronously while pending withdrawals are read live, so the two can disagree for a moment. Only USDC is valued (1 USD); every other token's `referencePriceUsd` and `custodyUsd` are `null`, and only USDC counts toward `tvlUsd`. Raw amounts are integer strings in the token's smallest unit. Builder attribution follows the explorer's display rules: a display group's applications report as one builder (`kind: "group"`), and a hidden builder is not named. Attribution sends each builder's `applications` empty. ## List Wallet Leaderboard **listWalletLeaderboard** `(params?: ListWalletLeaderboardParams) =\> Promise\` Wallets ranked by all-time taker volume, largest first, every builder counted. `limit` is 1 to 100 (default 25). **Returns:** `ListWalletLeaderboardResponse`: `wallets`, each with `wallet`, `volumeUsd`, `tradesCount`, `firstTradedAt` and `lastTradedAt` (Unix milliseconds). **Example:** ```typescript theme={null} const { wallets } = await sdk.analytics.listWalletLeaderboard({ limit: 50 }); ``` ## Get Wallet Summary **getWalletSummary** `(wallet: string) =\> Promise\` One wallet's all-time totals, its volume per displayed builder, and its liquidations. The address may be in any case; anything that is not a `0x` 20- or 32-byte hex address is refused with `400`. A wallet that never traded answers with `totals: null` and no builders. **Returns:** `GetWalletSummaryResponse`: `wallet` (lowercase), `totals`, `builders` (largest first, each with its `builder` and figures), `unattributed` (what hidden builders carried, so the rows reconcile with `totals`; `null` when nothing), `liquidationsCount` and `liquidationsNotional` (each event's size times its event-time mark, in each market's quote units; every market is USDC-quoted today). **Example:** ```typescript theme={null} const summary = await sdk.analytics.getWalletSummary("0x1234567890abcdef1234567890abcdef12345678"); for (const row of summary.builders) console.log(row.builder.name, row.volumeUsd); ``` ## List Wallet Liquidations **listWalletLiquidations** `(wallet: string, params?: ListWalletLiquidationsParams) =\> Promise\` One wallet's liquidation events across every market, newest first, in the shape of `market.listAllLiquidationEvents`. `pageSize` is 1 to 1000 (default 50); pass `nextPageToken` back as `pageToken`. A token only resumes the wallet it was issued for. **Returns:** `ListWalletLiquidationsResponse`: `events`, `pageSize` and `nextPageToken` (empty at the end). ## List Token Custody **listTokenCustody** `() =\> Promise\` What the vault holds of every token: listed assets by symbol, then tokens with custody flow that no asset lists. **Returns:** `ListTokenCustodyResponse`: `tokens` and `tvlUsd`. Each token has its asset metadata (`null` when unlisted), `contractAddress`, `depositedRaw`, `withdrawnRaw`, `depositsCount`, `withdrawalsCount`, `openingRaw`, `custodyRaw` (`null` when not positive), `pendingWithdrawalsRaw`, `referencePriceUsd`, `custodyUsd` and `countsTowardTvl`. ## Get Token Custody **getTokenCustody** `(token: string) =\> Promise\` One token's custody, looked up by symbol (any case), asset UUID or contract address. Unknown tokens fail with `404`. **Example:** ```typescript theme={null} const { token } = await sdk.analytics.getTokenCustody("USDC"); ``` ## List Vault Deposits **listVaultDeposits** `(params?: VaultFeedParams) =\> Promise\` Deposits into the vault, newest first by on-chain index. `pageSize` is 1 to 1000 (default 50). `token` (symbol, asset UUID or contract address) lists one token's deposits and `wallet` one credited account's; a token nothing answers to lists nothing, and a malformed wallet fails with `400`. A `pageToken` is bound to the filters it was minted under. **Returns:** `ListVaultDepositsResponse`: `deposits` (each with `onChainIndex`, `txHash`, `blockNumber`, `token`, `assetId`, `symbol`, `amountRaw`, `destination`, `targetAccountType`, `depositedAt` and `builder`, which is `null` on a deposit with `targetAccountType` `INSURANCE_FUND`), `pageSize` and `nextPageToken`. ## List Vault Withdrawals **listVaultWithdrawals** `(params?: VaultFeedParams) =\> Promise\` Withdrawals from the vault, newest first by withdrawal index, from initiation on. `token` and `wallet` filter as on `listVaultDeposits`; `wallet` matches the payout address. `status` is `pending` (initiated), `confirmed` (its proof is ready) or `executed` (paid out on-chain). Withdrawals carry no transaction hash. **Returns:** `ListVaultWithdrawalsResponse`: `withdrawals` (each with `withdrawalIndex`, `token`, `assetId`, `symbol`, `amountRaw`, `destination`, `status`, `initiatedAt` and `builder`), `pageSize` and `nextPageToken`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.