Start a new Plaid Link session. Returns a URL the user opens in their browser to authenticate with their bank. After they finish, call complete_linking with the returned link_token.

Finalize a Link session once the user has completed it in their browser. Exchanges the public_token for a permanent access_token and caches accounts.

List every institution currently linked, with account counts and any errors.

Unlink an institution (Plaid item) and delete its local data.

List every account across every linked institution (from the local cache).

Live balance lookup (hits Plaid, not cached). Filter by account_id if given.

Pull the latest transactions from Plaid into the local cache. Idempotent and incremental — uses cursors from the last sync.

Plaid's first sync after linking an institution runs asynchronously; when wait_for_ready is True (default), this tool blocks briefly until the historical pull reports HISTORICAL_UPDATE_COMPLETE. Returned status field surfaces that state per item.

Nudge Plaid to pull fresh transactions from the bank right now.

Use when a user just made a purchase and wants to see it, or when transactions look stale. Plaid normally refreshes on its own every few hours; this forces an immediate pull. Asynchronous — wait 30-60s then call sync_transactions to ingest any new data.

Pass item_id to refresh one institution, or leave empty to refresh everything. Some smaller banks don't support on-demand refresh.

Query cached transactions. Dates are YYYY-MM-DD. Run sync_transactions first to refresh. Positive amounts = spend.

Fuzzy search across transaction description and merchant name.

Aggregate spending by category | subcategory | merchant | account.

Current investment positions (tickers, quantities, market value, cost basis).

Brokerage transactions: buys, sells, dividends, fees.

Credit cards, student loans, mortgages with APRs, balances, due dates.

Account holder names, emails, phones, addresses as reported by the institution.

Bank-detected income streams. Requires Income product enabled in your Plaid dashboard.

Annotate a linked card with the real APR when Plaid misses it.

Common case: Citi doesn't consistently report 0% intro / balance-transfer promos through /liabilities/get. Use this to record the true effective APR and (optionally) a promo expiration date so summarize_debt_tool can reason honestly. After the promo_expires date, payoff analysis reverts to Plaid's reported purchase APR.

Remove any APR override for an account.

List every account APR override the user has recorded.

Track a debt that isn't behind a linked Plaid account.

Use for BNPL (Affirm, Klarna), medical bills, 401(k) loans, or debts at non-linkable lenders. apr is a percentage (e.g. 18.5 for 18.5%, not 0.185). Returns the assigned debt_id.

Update any subset of fields on an existing external debt.

Delete an external debt entry.

List every external (non-Plaid-linked) debt the user has recorded.

Rank every debt and project payoff timelines.

Merges Plaid-reported credit cards with user APR overrides and any external debts, then ranks by strategy:

• avalanche (default): highest effective APR first — minimizes interest paid.

• snowball: lowest balance first — fastest sense of progress.

extra_monthly_payment is dollars above the priority debt's minimum you'd put toward it each month. Returns total balance, monthly interest accrual at current rates, priority debt, amortized payoff projections (minimum-only vs. with-extra), and warnings for promos expiring soon.