Stats

The stats endpoint returns aggregate figures for your finances: balances, income, expenses, and derived measures like net cash flow and savings rate. It requires a bearer token and lives under /api/v1.

Endpoint

Method	Path	Action
GET	/api/v1/stats	Get aggregate statistics

Query parameters

Parameter	Type	Notes
start_date	string	Start of the range.
end_date	string	End of the range.
wallet_ids	string	Comma-separated wallet IDs to include.
period	string	day, week, month, or year. Defaults to month.
preset	string	all_time, current_week, current_month, or last_3_months.

Request

curl "https://api.your-domain.example/api/v1/stats?preset=current_month" \
  -H "Authorization: Bearer your-token-here"

Response shape

{
  "success": true,
  "message": "Stats retrieved",
  "data": {
    "currency": "USD",
    "overview": {
      "total_balance": 4210.55,
      "net_worth": 4210.55,
      "total_income": 3200.0,
      "total_expenses": 1875.4,
      "net_cash_flow": 1324.6,
      "avg_monthly_income": 3100.0,
      "avg_monthly_expenses": 1800.0,
      "savings_rate": 41.39
    }
  }
}

The overview block carries the headline figures. net_cash_flow is income minus expenses for the period; savings_rate is expressed as a percentage.