Ensure the Financial Connections Session was created with 'balances' in the permissions array, otherwise balance refresh will be unauthorized
POST to /v1/financial_connections/accounts/:account_id/refresh with features=['balance'] in the request body
The refresh is asynchronous; the account's balance_refresh.status transitions from 'pending' to 'succeeded' or 'failed'
Subscribe to the financial_connections.account.refreshed_balance webhook event to be notified when the refresh completes
After status is 'succeeded', retrieve the account via GET /v1/financial_connections/accounts/:account_id and read balance.current and balance.available from the response
Balance data is also updated automatically once per day for active accounts when subscriptions are enabled
Known gotchas
Calling refresh when a refresh is already pending returns the in-progress refresh rather than starting a new one; poll status rather than hammering the endpoint
Balance data returned reflects the institution's reported values at the time of refresh and may lag real-time by the institution's own caching window
Some institutions do not support balance retrieval; check balance_refresh.last_attempted_at and status before treating a null balance as an error
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?