Broker Activity Import#

When a brokerage account syncs, raw activities from the provider API are processed by a per-provider ActivitiesProcessor class that classifies each activity and routes it to one of two record types:

• Trade (entry with Trade entryable) — for security-level activity with a quantity: buys, sells, reinvestments, option events.
• Transaction (entry with Transaction entryable) — for pure cash flows: dividends, contributions, withdrawals, fees, transfers, interest.

Both record types share the same investment_activity_label field drawn from a canonical set defined in Transaction::ACTIVITY_LABELS 1. See Investment Activity Labels for label semantics, analytics impact, and UI badge behavior.

Supported Providers and Processors#

Three providers each have their own ActivitiesProcessor:

Each processor is called as part of the account's sync pipeline. For SnapTrade, activities are often fetched asynchronously via SnaptradeActivitiesFetchJob due to brokerage sync delays of 30–60+ seconds on fresh connections 2.

Trade vs. Transaction Split#

Each processor separates incoming activity into Trade and Transaction records at a defined boundary.

SnapTrade uses two explicit constants 3:

• TRADE_TYPES — BUY, SELL, REI, REINVEST, OPTION_BUY, OPTION_SELL, EXERCISED, ASSIGNED → import_trade
• CASH_TYPES — DIVIDEND, DIV, CONTRIBUTION, WITHDRAWAL, TRANSFER_*, INTEREST, FEE, TAX, CASH → import_transaction
• Unknown types default to "Other" label and go through process_cash_activity 4.

IBKR receives data pre-split: the payload has a trades key (buy/sell equity trades → import_trade) and a cash_transactions key (dividends, deposits/withdrawals → import_transaction) 5. Only DEPOSITS/WITHDRAWALS and DIVIDENDS cash types are supported; others are skipped 6. Commission/fee for each trade is imported as a separate Transaction with label "Fee" 7.

Trading212 separates at the payload level 8:

• raw_orders_payload (filled order records) → import_trade
• raw_dividends_payload (dividend records) → import_transaction with label "Dividend"
• raw_transactions_payload (cash events: DEPOSIT, WITHDRAW, INTEREST, FEE) → import_transaction

Label Mapping Per Provider#

Each processor maps provider-native type strings to Sure's canonical investment_activity_label values.

SnapTrade uses SNAPTRADE_TYPE_TO_LABEL, a hash covering 25+ types. Notable non-obvious mappings: TAX → "Fee", STOCK_DIVIDEND → "Dividend", CASH → "Contribution", SPLIT/MERGER/SPIN_OFF → "Other" 9. Cash amount sign is normalized in normalize_cash_amount: income flows are stored as negative amounts; outflows as positive.

IBKR classifies cash at classify_cash_transaction:

• DEPOSITS/WITHDRAWALS with positive amount → "Contribution", negative → "Withdrawal" 10
• DIVIDENDS → "Dividend" (stored as -amount.abs) 11
• Trades are always "Buy" or "Sell" based on the buy_sell field 12

Trading212 classifies via classify_transaction:

• DEPOSIT → "Contribution", WITHDRAW → "Withdrawal", INTEREST → "Interest", FEE → "Fee" 13
• Orders use order[:side] (BUY/SELL) to set "Buy" or "Sell" 14
• Dividends are always "Dividend" 15

Shared Import Interface: Account::ProviderImportAdapter#

All processors delegate to Account::ProviderImportAdapter, which provides two methods used across all providers:

• import_trade — creates a Trade-type Entry for security activity
• import_transaction — creates a Transaction-type Entry for cash flows

Both methods use find_or_initialize_by(external_id:, source:) for idempotent deduplication 16: re-importing the same activity updates the existing record rather than creating a duplicate. The external_id is provider-namespaced (e.g., ibkr_trade_<trade_id>, trading212_order_<order_id>) to avoid cross-provider collisions 17 18.

If a matching external_id exists but with a different entryable type (e.g., a Trade where a Transaction is expected), the adapter raises an ArgumentError to prevent type collisions 19. Records flagged as user-modified or import-locked are not overwritten.

Key Source Files#