Mercury

Fetch transactions from Mercury business banking accounts.

Setup

Generate an API token at Mercury Dashboard > Settings > API tokens.

export MERCURY_API_KEY=secret-token:mercury_...

Usage

vgrid fetch mercury --from 2026-01-01 --to 2026-02-01 --out mercury.csv

If you have multiple active accounts, specify one with --account:

vgrid fetch mercury --account acc_1234 --from 2026-01-01 --to 2026-02-01 --out mercury.csv

Options

Flag	Description	Default
--from	Start date inclusive (YYYY-MM-DD)	required
--to	End date exclusive (YYYY-MM-DD)	required
--api-key	Mercury API token	MERCURY_API_KEY env
--account	Mercury account ID (acc_...)	auto-detected
--out	Output CSV path	stdout
-q / --quiet	Suppress progress messages	off

Type mapping

Mercury kind	Canonical type
externalTransfer	deposit (positive) or withdrawal (negative)
internalTransfer	transfer
outgoingPayment	withdrawal
incomingDomesticWire, incomingInternationalWire	deposit
debitCardTransaction, cardTransaction	expense
fee	fee
check	withdrawal (negative) or deposit (positive)
anything else	sign-based: deposit or withdrawal

Date handling

• effective_date — createdAt truncated to YYYY-MM-DD
• posted_date — postedAt if present, otherwise falls back to createdAt

Notes

Account auto-detection. If --account is omitted, VisiGrid lists all accounts and selects the single active one. If there are zero or multiple active accounts, it errors with a list of account names and IDs.

Status filtering. Only transactions with status sent or pending are included. Cancelled and failed transactions are excluded.

Description priority. bankDescription > counterpartyName > note.

Pagination. Offset-based (500 items per page) with stuck-pagination detection.

Sort order. createdAt ascending, then source_id ascending.