feat(api): expose balance history (#1641)

* feat(api): expose balance history

* fix(api): address balance history review

* fix(api): address balance history review

* fix(api): tighten balance history docs

* fix(exports): preserve balance chronology

* fix(api): guard nullable balance account type

* test(api): align balances api key helper

* fix(api): use shared pagination clamp

* test(export): set explicit balance flows factor

app/controllers/api/v1/base_controller.rb

@@ -6,6 +6,8 @@ class Api::V1::BaseController < ApplicationController
   UUID_PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
   private_constant :UUID_PATTERN
 
+  InvalidFilterError = Class.new(StandardError)
+
   # Skip regular session-based authentication for API
   skip_authentication
 
@@ -254,6 +256,12 @@ class Api::V1::BaseController < ApplicationController
       render_json({ error: "bad_request", message: "Required parameters are missing or invalid" }, status: :bad_request)
     end
 
+    def parse_date_param(key)
+      Date.iso8601(params[key].to_s)
+    rescue ArgumentError
+      raise InvalidFilterError, "#{key} must be an ISO 8601 date"
+    end
+
     # Log API access for monitoring and debugging
     def log_api_access
       return unless current_resource_owner