> ## 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.

# AnalyticsService

> Exchange-wide totals, series, market volume, treasury net fees, builders, wallets, custody and vault flows

Package: `monaco.api.analytics`

Source: `protos/api/analytics.proto`

Use `AnalyticsService` for the exchange-wide figures the Monaco explorer shows. Every RPC is public — no auth — and serves the same data as its `GET /api/v1/analytics/...` route. Each client IP has a read budget; over it, an RPC fails with `RESOURCE_EXHAUSTED`.

```protobuf theme={null}
service AnalyticsService {
  rpc GetProtocolTotals(GetProtocolTotalsRequest) returns (GetProtocolTotalsResponse);
  rpc GetProtocolSeries(GetProtocolSeriesRequest) returns (GetProtocolSeriesResponse);
  rpc ListMarketVolumes(ListMarketVolumesRequest) returns (ListMarketVolumesResponse);
  rpc GetTreasuryNetFees(GetTreasuryNetFeesRequest) returns (GetTreasuryNetFeesResponse);
  rpc ListBuilders(ListBuildersRequest) returns (ListBuildersResponse);
  rpc GetBuilder(GetBuilderRequest) returns (GetBuilderResponse);
  rpc GetBuilderTotals(GetBuilderTotalsRequest) returns (GetBuilderTotalsResponse);
  rpc GetBuilderSeries(GetBuilderSeriesRequest) returns (GetBuilderSeriesResponse);
  rpc ListBuilderLeaderboard(ListBuilderLeaderboardRequest) returns (ListBuilderLeaderboardResponse);
  rpc ListWalletLeaderboard(ListWalletLeaderboardRequest) returns (ListWalletLeaderboardResponse);
  rpc GetWalletSummary(GetWalletSummaryRequest) returns (GetWalletSummaryResponse);
  rpc ListWalletLiquidations(ListWalletLiquidationsRequest) returns (ListWalletLiquidationsResponse);
  rpc ListTokenCustody(ListTokenCustodyRequest) returns (ListTokenCustodyResponse);
  rpc GetTokenCustody(GetTokenCustodyRequest) returns (GetTokenCustodyResponse);
  rpc ListVaultDeposits(ListVaultDepositsRequest) returns (ListVaultDepositsResponse);
  rpc ListVaultWithdrawals(ListVaultWithdrawalsRequest) returns (ListVaultWithdrawalsResponse);
}
```

## Notes

* Windowed requests take `window` (`24h` default, `7d`, `30d`, `all`, `custom`), `start_time` (Unix ms; required with `custom`, rejected otherwise) and `end_time` (Unix ms; default now). An invalid window fails with `INVALID_ARGUMENT`, as does a window counted in hours that starts more than 90 days ago.
* 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 `[start_time, end_time]`. Buckets are UTC; weeks start Monday. Each response echoes the resolved `AnalyticsWindow`.
* `volume_usd`, `spot_volume_usd`, `perp_volume_usd` and `trades_count` count the builders the explorer displays only. `protocol_fees_usd`, `active_takers` (distinct across the window), `new_traders` (first trade on the protocol, each wallet once however many builders it traded through) and every `MarketVolume` figure count every trade. `new_accounts` counts sign-ups: accounts registered in the window under any application, whether or not they traded, hidden builders included; every sign-up counts, in buckets without a trade too.
* `GetProtocolSeries` returns one `ProtocolSeriesPoint` per bucket, zeros where nothing traded.
* `ListMarketVolumes` takes `limit` 1 to 100 (default 25).
* Custody: `deposits_usd`, `withdrawals_usd`, `net_flow_usd`, `tvl_usd` and (on totals) `opening_tvl_usd` count USDC only, at 1 USD. A withdrawal counts when initiated. `tvl_usd` is the USDC custody (the opening custody plus deposits less initiated withdrawals, never below zero) at the end of the window or bucket, carried across buckets without movement; it and `opening_tvl_usd` are unset before any custody was folded. `GetProtocolTotalsResponse.active_accounts` counts each wallet once that took a trade, received a deposit, or was paid out a withdrawal initiated in the window (by payout address).
* `GetTreasuryNetFees` is all-time, not windowed: `net_fees_usd` is Monaco's all-time net fees, after the rewards it pays out; `counting_since` is unset before any fee.
* USD amounts are decimal strings (USDC 1:1).

## Builders

* A `Builder` is an application (`kind` `application`) or a display group that shows several applications as one (`kind` `group`). It carries `name`, `code`, `color`, `verified`, `applications` (each with `client_id`, `active`, `archived` and its add-on fee bps) and, for an application shown under a group, `group`.
* `GetBuilder`, `GetBuilderTotals` and `GetBuilderSeries` take `builder`: 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 fails with `NOT_FOUND`, exactly as one that does not exist.
* `ListBuilders` lists every displayed builder once, by name; archived applications are left out.
* Builder figures: `volume_usd`, the spot/perp split and `trades_count` count the trades the builder's applications took; `fees_usd` is its add-on revenue, `taker_fees_usd` plus `maker_fees_usd` (maker add-ons on trades it made, whoever took them), never the protocol taker fee; `active_takers` is distinct across the builder's applications; `new_traders` counts first trades per application and wallet; `new_accounts` counts the accounts registered under its applications, summed over a group's applications; `deposits_usd` is the USDC deposited through its applications, `withdrawals_usd` the USDC withdrawals they initiated (attributed by the initiating application), and `net_flow_usd` the difference. `BuilderApplication.is_default` marks the exchange's default application. Totals and series read hourly active-taker sets, so they share the 90-day limit on windows counted in hours.
* `ListBuilderLeaderboard` ranks displayed builders by volume, a group as one row, with `limit` 1 to 100 (default 25); a builder that only took deposits or only registered accounts ranks with zero volume. It answers windows of any age: `active_takers` is unset for a window counted in hours that starts before the 90 days hourly sets are kept, and with `window` `all` it counts every wallet that ever traded through the builder.

## Wallets, custody and vault flows

* `ListWalletLeaderboard` ranks wallets by all-time taker volume over every builder; `limit` 1 to 100 (default 25).
* `GetWalletSummary` takes a `0x` 20- or 32-byte hex `wallet` in any case (anything else is `INVALID_ARGUMENT`) and returns its totals, one `WalletBuilderVolume` per displayed builder (a display group's applications fold into one row under the group), `unattributed` for what hidden builders carried, and its liquidation count and notional (in each market's quote units; every market is USDC-quoted today). A wallet that never traded returns empty figures, not `NOT_FOUND`.
* `ListWalletLiquidations` pages the wallet's `monaco.api.market.LiquidationEvent`s newest first; `page_size` 1 to 1000 (default 50); a `page_token` resumes only the wallet it was issued for.
* `ListTokenCustody` / `GetTokenCustody`: custody per token is `opening_raw` (what the vault held before the explorer's history starts) plus `deposited_raw` less `withdrawn_raw`, which count flows since then, withdrawals at initiation; `pending_withdrawals_raw` is initiated but not yet executed on-chain; custody is folded asynchronously while pending is read live, so they can disagree briefly while the fold lags. Only USDC is valued (1:1) and counts toward `tvl_usd`. `GetTokenCustody` finds a token by symbol, asset UUID or contract address, and fails with `NOT_FOUND` otherwise.
* `ListVaultDeposits` (by on-chain index, with `tx_hash`) and `ListVaultWithdrawals` (by withdrawal index, every status, no transaction hash) page newest first; `page_size` 1 to 1000 (default 50). `token` (symbol, asset UUID or contract address) and `wallet` (a deposit's credited account, a withdrawal's payout address) filter them; a token nothing answers to returns an empty page, a malformed wallet is `INVALID_ARGUMENT`, and a `page_token` is bound to its filters. A row's `builder` is its displayed builder and is unset for a hidden one and for a deposit with `target_account_type` `INSURANCE_FUND`; `applications` is sent empty.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.