get_balance
Retrieve current account balances including booked and expected amounts from financial institutions. Use this tool to check balances for specific accounts or all linked accounts.
Instructions
Get current account balance(s). Returns closing booked balance and expected balance when available.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| connectionId | No | ||
| accountId | No | Account UID. If omitted, returns balances for all accounts. |
Implementation Reference
- src/tools/get-balance.ts:12-49 (handler)Main handler function that executes the get_balance tool logic. It accepts connectionId and accountId parameters, loads connections, iterates through them and accounts, uses caching, and calls provider.getBalance() for each account.export async function getBalance( args: z.infer<typeof getBalanceSchema>, ): Promise<Balance[]> { const config = loadConfig(); const connections = args.connectionId ? [getConnection(config, args.connectionId)] : getAllConnections(config); const allBalances: Balance[] = []; for (const conn of connections) { const provider = getProvider(conn.provider); let accountIds: string[]; if (args.accountId) { accountIds = [args.accountId]; } else { const accounts = await provider.listAccounts(conn.config); accountIds = accounts.map((a) => a.uid); } for (const accId of accountIds) { const cacheKey = `bal:${conn.id}:${accId}`; const cached = cache.get<Balance[]>(cacheKey); if (cached) { allBalances.push(...cached); continue; } const balances = await provider.getBalance(conn.config, accId); cache.set(cacheKey, balances, TTL.BALANCES); allBalances.push(...balances); } } return allBalances; }
- src/tools/get-balance.ts:7-10 (schema)Zod schema defining input validation for the get_balance tool. Accepts optional connectionId and accountId parameters, where accountId defaults to returning balances for all accounts if omitted.export const getBalanceSchema = z.object({ connectionId: z.string().optional(), accountId: z.string().optional().describe("Account UID. If omitted, returns balances for all accounts."), });
- src/server.ts:44-48 (registration)Tool registration in the TOOLS array, defining the tool name 'get_balance', description, and input schema reference.name: "get_balance", description: "Get current account balance(s). Returns closing booked balance and expected balance when available.", inputSchema: z.toJSONSchema(getBalanceSchema), },
- src/server.ts:65-65 (registration)Handler mapping that connects the 'get_balance' tool name to the getBalance function with schema parsing.get_balance: (args) => getBalance(getBalanceSchema.parse(args)),
- src/types.ts:27-32 (schema)Type definition for the Balance interface, defining the structure of balance objects returned by the tool including accountId, amount, currency, and type fields.export interface Balance { accountId: string; amount: number; currency: string; type: string; // "closingBooked" | "expected" | etc. }