Read transactions

1. Find an approved account

Transaction reads are paginated. To answer a spending question, first find the approved account, choose a date range, then read every page before calculating a total.

Call agent_list_accounts in MCP or agent accounts in the CLI. Match the account name and mask, take its account ID and select a current grant from its grantIds array. Only accounts approved for this installation are returned.

If the card is missing, request human approval for that account.

2. Choose a date range

Use UTC dates in YYYY-MM-DD format. from includes the start of its date; to excludes the start of its date. The range must fit within the snapshot’s rolling 90-day window.

{
  "grantId": "11111111-1111-4111-8111-111111111111",
  "accountId": "22222222-2222-4222-8222-222222222222",
  "from": "2026-09-21",
  "to": "2026-09-28",
  "limit": 50
}

For the latest available records, omit to. The query ends at projection.windowEnd. If you omit both bounds, Vantage uses projection.windowStart and projection.windowEnd.

3. Read every page

CLI and MCP responses contain transactions, nextCursor and projection metadata. Pages default to 50 transactions, with a maximum of 100. Pass nextCursor to the next request, keeping the grant, account, dates and page size unchanged.

pnpm --silent vantage agent transactions --grant-id GRANT_UUID --account-id ACCOUNT_UUID --from 2026-09-21 --to 2026-09-28 --limit 50
pnpm --silent vantage agent transactions --grant-id GRANT_UUID --account-id ACCOUNT_UUID --from 2026-09-21 --to 2026-09-28 --limit 50 --cursor NEXT_CURSOR

4. Calculate and explain the answer

• Use decimal arithmetic for amount strings and calculate each currency separately.
• Use direction to distinguish debits from credits and refunds. Explain how you handled unknown directions.
• State whether you included pending transactions.
• Check projection.projectedAt, windowStart, windowEnd and each account’s sync status and syncedAt.
• Report the account, UTC date range and complete page coverage. Explain any stale or incomplete data.

projection.projectedAt is when Vantage published the snapshot. Each entry in projection.sync includes the account’s bank sync status and syncedAt. Use both to explain how current the data is.

Base spending totals on a complete, successful read. Explain any missing permission, unavailable data or incomplete sync. The human can check readiness and refresh in Accounts.