Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.whop.com/llms.txt

Use this file to discover all available pages before exploring further.

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 describe 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/wallets/time_series/describe"
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 Describe API Reference for the full response schema.

​
Time Series

GET https://api.whop.com/api/v1/stats/wallets/time_series
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

ParameterTypeDefaultRequiredDescription
account_idstring—noQuery a sub-account’s wallet (e.g. biz_xxx). Omit to use the caller’s own wallet.
fromdate—yesStart date, ISO 8601 (e.g. 2025-01-01)
todate—yesEnd date, ISO 8601 (e.g. 2025-12-31)
group_bystringmonthnoGranularity: day, week, or month
reporting_categorystringallnoFilter to a reporting category: net_activity, gtv, gross_income, net_income, payment_processing_fees
groupingstring[]allnoFilter by grouping(s): payments, refunds, fees, disputes, withdrawals, etc.
line_categorystring[]allnoFilter by transaction type(s) (e.g. payment_gross, payment_refund)
currencystringallnoFilter to a single currency (e.g. usd)
convert_currencystring—noConvert all amounts to this currency using historical exchange rates
timezonestringUTCnoIANA timezone for period boundaries

​
Example

curl "https://api.whop.com/api/v1/stats/wallets/time_series?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 "...?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 "...?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 "...?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. There are two separate currency controls: filter and convert. Filter — currency restricts rows to a single currency: 
curl "...?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 "...?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

StatusCause
400Missing or invalid parameters
401Missing or invalid API key
403API key lacks company:balance:read permission

​
Statement

GET https://api.whop.com/api/v1/stats/wallets/statement
Returns a financial statement — the same data that powers the Reports page in the Whop dashboard. Rows are broken down by period, grouping, and line category. See the Statement API Reference for the full response schema.

​
Report Types

report_typeWhat it shows
balance_activityCash inflows/outflows by category over time
income_statementIncome and expenses over time
balance_summaryAccount balances at period end, with beginning and ending balance totals

​
Example

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

{
  "data": {
    "report_type": "balance_activity",
    "rows": [
      { "period": "2025-01-01", "grouping": "payments", "line_category": "payment_gross", "amount": 14550.35 },
      { "period": "2025-01-01", "grouping": "refunds", "line_category": "payment_refund", "amount": -500.00 }
    ],
    "total": 14050.35
  },
  "metadata": {
    "wallet_id": "ldgr_xxx",
    "report_type": "balance_activity",
    "from": "2025-01-01",
    "to": "2025-06-01",
    "group_by": "month",
    "convert_currency": "usd"
  }
}