Wallet Stats API - Whop Docs

The Wallet Stats API gives you access to financial analytics powered by your Fragment ledger — the same data that powers the Whop dashboard charts. The wallet is resolved automatically from your API key’s auth context. See the API Reference for the full list of parameters and allowed values.

The time_series endpoint requires the company:balance:read permission. See Permissions to learn how to request permissions for your app.

Discover available filters

Before building queries, call the schema endpoint to get the full taxonomy of reporting categories, groupings, and line categories with human-readable descriptions. No authentication required.

curl "https://api.whop.com/api/v1/stats/schema?resource_type=wallet"

The response tells you:

reporting_categories — predefined report scopes (e.g. gross_income, net_activity) and which line categories each one includes
groupings — logical buckets (e.g. payments, refunds, disputes) and their line categories
line_categories — every active transaction type with its description, grouping, and which reports it belongs to

Use this to understand what filters to pass to the time_series endpoint. See the Schema API Reference for the full response schema.

Time Series

GET https://api.whop.com/api/v1/stats/time_series?resource_type=wallet

Returns total amount and line_count per period. Filter with reporting_category, grouping, or line_category to narrow results. The wallet is resolved from your API key’s auth context — no account ID needed in the URL.

Parameters

Parameter	Type	Default	Required	Description
`resource_type`	string	—	yes	Must be `wallet`
`account_id`	string	—	no	Query a sub-account’s wallet (e.g. `biz_xxx`). Pass `global` for platform-wide queries (admin only). Omit to use the caller’s own wallet.
`from`	date	—	yes	Start date, ISO 8601 (e.g. `2025-01-01`)
`to`	date	—	yes	End date, ISO 8601 (e.g. `2025-12-31`)
`group_by`	string	`month`	no	Granularity: `day`, `week`, or `month`
`reporting_category`	string	all	no	Filter to a reporting category: `net_activity`, `gtv`, `gross_income`, `net_income`, `payment_processing_fees`
`grouping`	string[]	all	no	Filter by grouping(s): `payments`, `refunds`, `fees`, `disputes`, `withdrawals`, etc.
`line_category`	string[]	all	no	Filter by transaction type(s) (e.g. `payment_gross`, `payment_refund`)
`currency`	string	all	no	Filter to a single currency (e.g. `usd`)
`convert_currency`	string	—	no	Convert all amounts to this currency using historical exchange rates
`timezone`	string	`UTC`	no	IANA timezone for period boundaries

Example

curl "https://api.whop.com/api/v1/stats/time_series?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&convert_currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"

{
  "data": [
    {
      "period": "2025-01-01",
      "amount": 14550.35,
      "line_count": 342
    }
  ],
  "metadata": {
    "wallet_id": "ldgr_xxx",
    "from": "2025-01-01",
    "to": "2025-06-01",
    "group_by": "month",
    "convert_currency": "usd",
    "timezone": "UTC"
  }
}

Filtering

Use reporting_category to scope to a predefined set of line categories (e.g. only income-related activity):

curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&reporting_category=gross_income" \
  -H "Authorization: Bearer $WHOP_API_KEY"

Use grouping to narrow to specific groupings (e.g. only payments and refunds):

curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&grouping[]=payments&grouping[]=refunds" \
  -H "Authorization: Bearer $WHOP_API_KEY"

Use line_category for the most granular filtering:

curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&line_category[]=payment_gross&line_category[]=payment_refund" \
  -H "Authorization: Bearer $WHOP_API_KEY"

All three filters can be combined — they are applied in order: reporting_category first, then grouping, then line_category.

Global queries

Pass account_id=global to query aggregated data across all wallets. This requires admin access.

curl "https://api.whop.com/api/v1/stats/time_series?resource_type=wallet&account_id=global&from=2025-01-01&to=2025-06-01&group_by=month&convert_currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"

Global queries omit wallet_id from the response metadata since data spans all wallets.

Currency handling

There are two separate currency controls: filter and convert. Filter — currency restricts rows to a single currency:

curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"

Convert — convert_currency converts all amounts to a target currency using historical exchange rates, collapsing multi-currency rows into one per period:

curl "...?resource_type=wallet&from=2025-01-01&to=2025-06-01&group_by=month&convert_currency=usd" \
  -H "Authorization: Bearer $WHOP_API_KEY"

When neither is set, rows include a currency field and you may get multiple rows per period (one per currency):

{
  "data": [
    { "period": "2025-01-01", "currency": "usd", "amount": 14550.35, "line_count": 300 },
    { "period": "2025-01-01", "currency": "eur", "amount": 3200.00, "line_count": 42 }
  ]
}

You can combine both: currency=eur&convert_currency=usd filters to EUR rows then converts them to USD.

Errors

Status	Cause
400	Missing or invalid parameters (including missing `resource_type`)
401	Missing or invalid API key
403	API key lacks `company:balance:read` permission, or `account_id=global` without admin access

​Discover available filters

​Time Series

​Parameters

​Example

​Filtering

​Global queries

​Currency handling

​Errors

Discover available filters

Time Series

Parameters

Example

Filtering

Global queries

Currency handling

Errors