Cryptocurrency Account Management#

Sure models crypto holdings as a Crypto accountable type — one of the 9 types registered in the Accountable concern — classified as an asset 1. The core model is app/models/crypto.rb.

Subtypes: Wallet vs. Exchange#

Crypto accounts have exactly two subtypes 2:

The key behavioral difference is supports_trades?: only exchange accounts return true, enabling manual trade entry and investment activity labels. wallet accounts are sync-only — they receive transaction data from the provider but do not expose a trade entry UI.

Account#supports_trades? delegates this check to the Crypto accountable, treating exchange crypto accounts the same as all Investment subtypes for trade-related features.

Account#manual_crypto_exchange? identifies the specific case of a manually-managed exchange account (no live provider attached), which affects sync and balance calculation behavior.

Provider Integration (Linked Accounts)#

Crypto accounts are connected to external providers at the Account level. Factory methods create exchange accounts with cash_balance: 0 (all value is in holdings) and tax_treatment: :taxable by default 3.

Supported providers with dedicated factory methods:

• Coinbase — Account.create_from_coinbase_account: creates subtype: "exchange"
• Kraken — Account.create_from_kraken_account: delegates to the shared create_from_crypto_exchange_account private method
• Binance — Account.create_from_binance_account: same pattern, plus sets an opening anchor balance of 0
• CoinStats — syncs wallet and portfolio data via CoinstatsEntry::Processor

All provider-created accounts skip the initial sync; the provider sync itself handles balance and holdings creation once the correct currency is known 4.

CoinStats Sync (Wallet & Portfolio)#

CoinstatsEntry::Processor processes individual CoinStats API transactions into local records. Its branching logic is the key point of differentiation:

• Exchange trades (buy, sell, swap, trade, convert, fill types) on non-fiat assets → calls import_adapter.import_trade(...) to create a Trade entry 5.
• All other transactions (receives, sends, rewards, fees, swaps on fiat accounts) → calls import_adapter.import_transaction(...) with an investment_activity_label derived from the transaction type 6.

The exchange_trade? predicate 7 guards trade creation: it requires exchange_source?, a non-fiat asset, nonzero quantity/price, and a recognized trade type.

Transaction metadata stored in extra includes: transaction_hash, explorer_url, transaction_type, coin symbol/count, profit/loss, and fee details 8. A legacy migration path exists: if a prior Transaction entry exists for the same external_id, the processor either migrates it to a Trade or skips it (preserving user modifications) 9.

Trade Entry (Exchange Accounts Only)#

Manual trade entry for exchange accounts flows through Trade::CreateForm, which handles six entry types 10:

For buy/sell, security is resolved via Security::Resolver from a combobox ID (SYMBOL|EXCHANGE|PROVIDER format) or a manual ticker. The investment_activity_label is set to "Buy" or "Sell" automatically on save 11. After saving, lock_saved_attributes! prevents provider syncs from overwriting the manual entry, and account.sync_later queues a holdings/balance recalculation 12.

Activity Labels & Spending Categorization#

Exchange crypto accounts use investment activity labels instead of standard expense categories 13. The full label set is shared with investment accounts via Trade::ACTIVITY_LABELS = Transaction::ACTIVITY_LABELS.dup.freeze 14.

Key labels for crypto:

• Exchange — classified as INTERNAL_MOVEMENT_LABELS; excluded from income/expense totals 13
• Buy / Sell — assigned automatically; never reach expense budgets because Trade#excluded_from_budget? always returns true
• Interest / Dividend — income labels; read-only in the quick-edit badge UI

For CoinStats-synced wallet transactions, the processor maps raw transaction types to labels: received/deposit → "Transfer", reward/interest → "Interest", fee → "Fee", etc. 15.

Portfolio & Cost Basis#

Both crypto subtypes share the balance_type: :investment path 16, meaning balance calculations include both cash and holdings components.

For exchange accounts with trade history, cost basis is materialized on sync via Holding::Materializer. Manual accounts use Holding::ForwardCalculator (weighted average from buy trades); linked/synced accounts use Holding::ReverseCalculator 17. Unrealized and realized gain/loss are computed in Trade#unrealized_gain_loss and Trade#realized_gain_loss respectively.

Crypto is taxable by default (tax_treatment: :taxable), though the model supports tax_deferred and tax_exempt for edge cases like self-directed IRAs 18.

Key Source Files#