add_txn
Add single or bulk financial transactions (buy, sell, deposit, dividend, tax) with automatic currency conversion and reason capture for investment thesis tracking.
Instructions
Insert one or more transactions in a single call. transactions is an array — pass one entry for a single trade, many for a CSV / brokerage export / paste import. Rows are sorted by date ascending before insertion (average cost depends on insertion order). For bulk imports: first show the user your detected column mapping and total row count, wait for their confirmation, then call this once with all rows. Types: buy/sell move shares; deposit adds shares (set price=0 for grants/transfers, or actual cost basis); dividend/tax record cash events (price = total amount, shares = 1).
Reason capture (critical for thesis tracking): For NEW buy/sell trades — not historical bulk imports — the reason field is the single highest-leverage input you can capture for the user's long-term self-feedback loop (powers show_thesis_track later). When the user logs a NEW single buy/sell without supplying a reason, ALWAYS ask before calling: "What's your reason for this trade? Even one short sentence — 'earnings beat thesis', 'rebalancing toward defensive', 'avg-down on dip' — is enough." Then include their answer in reason. Skip the ask only when (a) the user is explicitly migrating historical data, or (b) the trade type is deposit/dividend/tax (no investment decision).
Each row carries its own asset_type (default 'stock'), which splits two flows:
stock:
priceis in the market's native currency (US→USD, KRX/KOSDAQ→KRW, JP→JPY, HK→HKD, LSE→GBP, XETRA→EUR, NSE→INR, TW→TWD) —marketdetermines it, thecurrencyparam is ignored. Non-US holdings must setmarketto the listing exchange;tickerstays the bare local code (e.g. market: "KRX", ticker: "005930").crypto / commodity / real_estate / other: there is no market or price provider — these are priced manually (not auto-synced).
marketis ignored and stored null,tickeris a free-form name (e.g. "Bitcoin", "Seoul apartment"), andpriceis in thecurrencyparam (default USD).
In both cases price is converted to USD at the transaction date before storing — every stored price is USD.
A single-entry call returns the inserted transaction; a multi-entry call returns a per-ticker / per-type summary.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| transactions | Yes | One or more transactions to insert |