Investment Trade Entry#

Manual buy/sell trade entry is available for any account where Account#supports_trades? returns true — all Investment subtypes and Crypto exchange accounts. Trades are stored as Entry records whose entryable is a Trade model.

Entry Form#

The UI form (app/views/trades/_form.html.erb) presents a type selector with six options 1:

For buy/sell, the security field is a combobox backed by SecuritiesController#index, which delegates to Security.search_provider — a concurrent multi-provider search with an 8-second per-provider timeout and 5-minute result cache 2. If no price providers are configured, a plain manual_ticker text field is shown instead 3.

Qty must be positive; the sign is applied by the form object (+qty for buy, -qty for sell) 4. The entry amount is computed as signed_qty × price + fee 4.

Create Flow#

Both the web UI (TradesController) and the REST API (Api::V1::TradesController) delegate to Trade::CreateForm:

1. Security resolution — Trade::CreateForm calls Security::Resolver to find or create the security from the parsed combobox ID (SYMBOL|EXCHANGE|PROVIDER format) or the raw manual ticker 4.
2. Record creation — saves an Entry with a nested Trade, setting investment_activity_label to "Buy" or "Sell" automatically 4.
3. Post-save hooks — Entry#lock_saved_attributes! and mark_user_modified! protect the record from being overwritten by a subsequent provider sync; account.sync_later queues an async balance/holding recalculation 5.

The API controller additionally validates that the target account supports_trades? and allows optional investment_activity_label and category_id overrides post-creation 6 7.

Permitted create params (API): account_id, date, qty, price, currency, security_id, ticker, manual_ticker, investment_activity_label, category_id, fee, type, amount, transfer_account_id 8.

Trade Model Validations#

Trade validates:

• qty and price + currency presence 9
• investment_activity_label must be one of ACTIVITY_LABELS (shared with Transaction) or nil 10
• exchange_rate must be a finite positive number when present 11

buy? / sell? check the sign of qty. Trades are always excluded from expense budgets via excluded_from_budget?.

Cost Basis & Gain/Loss Tracking#

Holding cost basis is materialized on sync, not computed on-demand. After a trade is saved, account.sync_later triggers Holding::Materializer, which calls either:

• Holding::ForwardCalculator (manual accounts) — iterates chronologically, accumulating weighted-average cost from buy trades 12.
• Holding::ReverseCalculator (linked/synced accounts) — works backward; pre-computes cost basis snapshots and uses binary search for lookups 13.

The resulting avg_cost on each Holding record is the weighted average purchase price in account currency 14. Cost basis has a source priority: manual (user-locked) > calculated (from trades) > provider 15; the Holding::CostBasisReconciler never overwrites a higher-priority source 16.

Unrealized gain/loss is computed in Trade#unrealized_gain_loss: (current_price × qty) - (entry_price × qty).

Realized gain/loss is computed in Trade#realized_gain_loss for sell trades: sale_proceeds - (holding.avg_cost × qty.abs). It uses a preloaded holdings array when set by the reports controller to avoid N+1 queries 17.

Key Files#