fundamentalista 0.1.0

data/lib/fundamentalista/providers/edgar/facts.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Providers
+    class Edgar
+      # Reads a companyfacts document. Every concept carries every value
+      # ever filed, including restatements, so a line item is looked up by
+      # the period it describes and the most recently filed value wins,
+      # while the fiscal year label comes from the original filing.
+      #
+      # Quarterly flows are not always reported as such: cash flow
+      # statements in 10-Q filings are year to date, and the fourth quarter
+      # only exists as the annual figure. A quarter is read directly when a
+      # three month value exists, and derived otherwise as the difference
+      # between two year to date values that share a fiscal year start.
+      class Facts # :nodoc:
+        ANNUAL = (350..380)
+        QUARTER = (80..100)
+        ANNUAL_FORMS = %w[10-K 20-F 40-F].freeze
+        QUARTERLY_FORMS = %w[10-K 10-Q].freeze
+        QUARTERS = { 'Q1' => 1, 'Q2' => 2, 'Q3' => 3, 'FY' => 4 }.freeze
+        TAXONOMIES = %w[us-gaap ifrs-full dei].freeze
+
+        def initialize(document)
+          facts = document.fetch('facts', {})
+          @facts = TAXONOMIES.map { |taxonomy| facts.fetch(taxonomy, {}) }
+        end
+
+        # The ISO code of the currency revenue is reported in.
+        def currency
+          Tags::INCOME[:revenue].each do |concept|
+            unit = units(concept).keys.find { |candidate| candidate.match?(/\A[A-Z]{3}\z/) }
+            return unit if unit
+          end
+          'USD'
+        end
+
+        # The fiscal years on file, newest first, as [year, ended_on] pairs.
+        def fiscal_years
+          balance_dates(ANNUAL_FORMS).map { |original, ended_on| [original['fy'], ended_on] }
+        end
+
+        # The quarters on file, newest first, as [year, quarter, ended_on]
+        # triples. The fourth quarter is the fiscal year end.
+        def quarters
+          balance_dates(QUARTERLY_FORMS).map { |original, ended_on| [original['fy'], QUARTERS.fetch(original['fp']), ended_on] }
+        end
+
+        # The annual line items of +tags+ for the fiscal year +year+ ending
+        # on +ended_on+, as [value, Source] pairs keyed by item. Cover page
+        # facts fill in what the statements lack.
+        def annual(tags, ended_on, year = nil)
+          tags.to_h do |item, alternatives|
+            found = first_reported(alternatives) do |concept|
+              instant?(item) ? instant(concept, ended_on, ANNUAL_FORMS) : yearly(concept, ended_on)
+            end
+            [item, found || cover(item, year)]
+          end
+        end
+
+        # The quarterly line items of +tags+ for the quarter ending on
+        # +ended_on+, the one before it having ended on +previous+, as
+        # [value, Source] pairs keyed by item.
+        def quarterly(tags, ended_on, previous)
+          tags.to_h do |item, alternatives|
+            [item, first_reported(alternatives) do |concept|
+              instant?(item) ? instant(concept, ended_on) : three_months(concept, ended_on, previous)
+            end]
+          end
+        end
+
+        private
+
+        def cover(item, year)
+          concept = Tags::COVER[item]
+          return nil unless concept && year
+
+          latest(concept, entries(concept).select { |entry| entry['fy'] == year && ANNUAL_FORMS.include?(entry['form']) })
+        end
+
+        def balance_dates(forms)
+          entries('Assets').select { |entry| balance_at?(entry, forms) }
+                           .group_by { |entry| entry['end'] }
+                           .map do |ended_on, group|
+            [group.min_by do |entry|
+              [entry['fy'], entry['filed']]
+            end, Date.parse(ended_on)]
+          end
+                           .sort_by(&:last).reverse
+        end
+
+        def balance_at?(entry, forms)
+          entry['start'].nil? && entry['fp'] && forms.include?(entry['form'])
+        end
+
+        def first_reported(alternatives, &block)
+          alternatives.each do |alternative|
+            found = Array(alternative).filter_map(&block)
+            return combine(found) if found.any?
+          end
+          nil
+        end
+
+        def combine(found)
+          return found.first if found.one?
+
+          source = Source.new(concept: found.map { |_, source| source.concept }.join('+'), form: found.first.last.form,
+                              filed: found.map { |_, source| source.filed }.max, derivation: :summed)
+          [found.sum { |value, _| value }, source]
+        end
+
+        def instant?(item)
+          Tags::INSTANT.include?(item)
+        end
+
+        def instant(concept, ended_on, forms = nil)
+          latest(concept, ending(concept, ended_on).select do |entry|
+            entry['start'].nil? && (forms.nil? || forms.include?(entry['form']))
+          end)
+        end
+
+        def yearly(concept, ended_on)
+          latest(concept, ending(concept, ended_on).select do |entry|
+            ANNUAL_FORMS.include?(entry['form']) && ANNUAL.cover?(duration_of(entry))
+          end)
+        end
+
+        def three_months(concept, ended_on, previous)
+          spans = ending(concept, ended_on).select { |entry| entry['start'] }
+          latest(concept, spans.select do |entry|
+            QUARTER.cover?(duration_of(entry))
+          end) || derived_quarter(concept, spans, previous)
+        end
+
+        def derived_quarter(concept, spans, previous)
+          year_to_date = spans.max_by { |entry| [duration_of(entry), entry['filed']] }
+          return nil unless year_to_date && previous
+
+          earlier = latest(concept, ending(concept, previous).select { |entry| entry['start'] == year_to_date['start'] })
+          earlier && [year_to_date['val'] - earlier.first, source_of(concept, year_to_date, :derived)]
+        end
+
+        def latest(concept, candidates)
+          entry = candidates.max_by { |candidate| candidate['filed'] }
+          entry && [entry['val'], source_of(concept, entry)]
+        end
+
+        def source_of(concept, entry, derivation = :reported)
+          Source.new(concept: concept, form: entry['form'], filed: Date.parse(entry['filed']), derivation: derivation)
+        end
+
+        def ending(concept, ended_on)
+          entries(concept).select { |entry| entry['end'] == ended_on.iso8601 }
+        end
+
+        def duration_of(entry)
+          return -1 unless entry['start']
+
+          (Date.parse(entry['end']) - Date.parse(entry['start'])).to_i
+        end
+
+        def entries(concept)
+          units(concept).values.flatten
+        end
+
+        def units(concept)
+          @facts.flat_map { |taxonomy| taxonomy.dig(concept, 'units').to_a }.to_h
+        end
+      end
+    end
+  end
+end

data/lib/fundamentalista/providers/edgar/tags.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Providers
+    class Edgar
+      # The XBRL concepts behind each line item, in order of preference,
+      # from the US GAAP taxonomy of 10-K filers and the IFRS taxonomy of
+      # 20-F filers. Companies tag the same idea differently, so each item
+      # lists the alternatives that express it and the first one reported
+      # wins. An alternative given as an array is the sum of the concepts
+      # it names, for items companies split, such as current debt and
+      # commercial paper. Duration concepts describe a period, instant
+      # concepts a date.
+      module Tags
+        INCOME = {
+          revenue: %w[RevenueFromContractWithCustomerExcludingAssessedTax Revenues SalesRevenueNet
+                      RevenueFromContractWithCustomerIncludingAssessedTax RevenuesNetOfInterestExpense Revenue
+                      RevenueFromContractsWithCustomers],
+          cost_of_revenue: %w[CostOfRevenue CostOfGoodsAndServicesSold CostOfGoodsSold CostOfSales
+                              CostOfGoodsAndServiceExcludingDepreciationDepletionAndAmortization],
+          gross_profit: %w[GrossProfit],
+          sga: ['SellingGeneralAndAdministrativeExpense', %w[GeneralAndAdministrativeExpense SellingAndMarketingExpense]],
+          operating_income: %w[OperatingIncomeLoss ProfitLossFromOperatingActivities],
+          interest_expense: %w[InterestExpense InterestExpenseNonoperating InterestExpenseDebt FinanceCosts
+                               InterestExpenseOperating InterestAndDebtExpense InterestExpenseLongTermDebt
+                               InterestExpenseBorrowings InterestPaidNet],
+          income_before_tax: %w[
+            IncomeLossFromContinuingOperationsBeforeIncomeTaxesExtraordinaryItemsNoncontrollingInterest
+            IncomeLossFromContinuingOperationsBeforeIncomeTaxesMinorityInterestAndIncomeLossFromEquityMethodInvestments
+            ProfitLossBeforeTax
+          ],
+          income_tax: %w[IncomeTaxExpenseBenefit IncomeTaxExpenseContinuingOperations],
+          net_income: %w[NetIncomeLoss ProfitLossAttributableToOwnersOfParent ProfitLoss],
+          depreciation_amortization: ['DepreciationDepletionAndAmortization', 'DepreciationAndAmortization',
+                                      'DepreciationAmortizationAndAccretionNet', 'DepreciationAmortizationAndOther',
+                                      'DepreciationAndAmortisationExpense',
+                                      %w[DepreciationPropertyPlantAndEquipment AmortisationIntangibleAssetsOtherThanGoodwill],
+                                      %w[Depreciation AmortizationOfIntangibleAssets], 'Depreciation'],
+          eps_diluted: %w[EarningsPerShareDiluted DilutedEarningsLossPerShare],
+          diluted_shares: %w[WeightedAverageNumberOfDilutedSharesOutstanding AdjustedWeightedAverageShares]
+        }.freeze
+
+        BALANCE = {
+          cash: %w[CashAndCashEquivalentsAtCarryingValue CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents
+                   CashAndCashEquivalents],
+          short_term_investments: %w[ShortTermInvestments MarketableSecuritiesCurrent
+                                     AvailableForSaleSecuritiesDebtSecuritiesCurrent OtherCurrentFinancialAssets
+                                     CurrentFinancialAssetsAtAmortisedCost],
+          receivables: %w[AccountsReceivableNetCurrent ReceivablesNetCurrent CurrentTradeReceivables
+                          TradeAndOtherCurrentReceivables AccountsNotesAndLoansReceivableNetCurrent AccountsReceivableNet],
+          inventory: %w[InventoryNet Inventories],
+          current_assets: %w[AssetsCurrent CurrentAssets],
+          ppe: %w[PropertyPlantAndEquipmentNet
+                  PropertyPlantAndEquipmentAndFinanceLeaseRightOfUseAssetAfterAccumulatedDepreciationAndAmortization
+                  PropertyPlantAndEquipment],
+          total_assets: %w[Assets],
+          payables: %w[AccountsPayableCurrent AccountsPayableTradeCurrent TradeAndOtherCurrentPayables
+                       TradeAndOtherCurrentPayablesToTradeSuppliers AccountsPayableAndAccruedLiabilitiesCurrent
+                       AccountsPayableAndAccruedLiabilitiesCurrentAndNoncurrent],
+          current_liabilities: %w[LiabilitiesCurrent CurrentLiabilities],
+          total_liabilities: %w[Liabilities],
+          short_term_debt: ['DebtCurrent',
+                            %w[LongTermDebtCurrent CommercialPaper ShortTermBorrowings OtherShortTermBorrowings
+                               ConvertibleDebtCurrent NotesPayableCurrent],
+                            'ShorttermBorrowings', 'CurrentBorrowings'],
+          long_term_debt: %w[LongTermDebtNoncurrent LongTermDebtAndCapitalLeaseObligations LongTermDebt LongTermNotesPayable
+                             LongTermNotesAndLoans LongtermBorrowings NoncurrentBorrowings
+                             LongTermDebtAndCapitalLeaseObligationsIncludingCurrentMaturities],
+          equity: %w[StockholdersEquity StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest
+                     EquityAttributableToOwnersOfParent Equity],
+          retained_earnings: %w[RetainedEarningsAccumulatedDeficit RetainedEarnings],
+          shares_outstanding: %w[CommonStockSharesOutstanding NumberOfSharesOutstanding NumberOfSharesIssued
+                                 NumberOfSharesIssuedAndFullyPaid]
+        }.freeze
+
+        CASH_FLOW = {
+          operating_cash_flow: %w[NetCashProvidedByUsedInOperatingActivities
+                                  NetCashProvidedByUsedInOperatingActivitiesContinuingOperations
+                                  CashFlowsFromUsedInOperatingActivities],
+          capital_expenditure: %w[
+            PaymentsToAcquirePropertyPlantAndEquipment PaymentsToAcquireProductiveAssets
+            PurchaseOfPropertyPlantAndEquipmentClassifiedAsInvestingActivities
+            PurchaseOfPropertyPlantAndEquipmentIntangibleAssetsOtherThanGoodwillInvestmentPropertyAndOtherNoncurrentAssets
+            PaymentsToAcquireOtherPropertyPlantAndEquipment PaymentsToAcquireOtherProductiveAssets
+          ],
+          dividends_paid: %w[PaymentsOfDividends PaymentsOfDividendsCommonStock PaymentsOfOrdinaryDividends
+                             DividendsCommonStockCash DividendsPaidClassifiedAsFinancingActivities
+                             DividendsPaidToEquityHoldersOfParentClassifiedAsFinancingActivities DividendsPaid],
+          share_repurchases: %w[PaymentsForRepurchaseOfCommonStock PaymentsForRepurchaseOfEquity
+                                TreasuryStockValueAcquiredCostMethod PaymentsForPurchaseOfTreasuryShares]
+        }.freeze
+
+        BANKING = {
+          net_interest_income: %w[InterestIncomeExpenseNet],
+          interest_income: %w[InterestAndDividendIncomeOperating InterestIncome InterestAndFeeIncomeLoansAndLeases],
+          provision_for_credit_losses: %w[ProvisionForLoanLeaseAndOtherLosses ProvisionForLoanAndLeaseLosses
+                                          ProvisionForCreditLosses ProvisionForLoanLossesExpensed],
+          noninterest_income: %w[NoninterestIncome],
+          noninterest_expense: %w[NoninterestExpense],
+          loans: %w[FinancingReceivableExcludingAccruedInterestAfterAllowanceForCreditLoss
+                    LoansAndLeasesReceivableNetReportedAmount NotesReceivableNet LoansAndLeasesReceivableNetOfDeferredIncome],
+          deposits: %w[Deposits],
+          allowance_for_credit_losses: %w[FinancingReceivableAllowanceForCreditLossExcludingAccruedInterest
+                                          FinancingReceivableAllowanceForCreditLosses],
+          tier1_capital_ratio: %w[TierOneRiskBasedCapitalToRiskWeightedAssets]
+        }.freeze
+
+        # Cover page facts from the DEI taxonomy, dated by filing rather than
+        # by fiscal year end, used when the balance sheet lacks the item.
+        COVER = { shares_outstanding: 'EntityCommonStockSharesOutstanding' }.freeze
+
+        INSTANT = (BALANCE.keys + Banking::INSTANT).freeze
+      end
+    end
+  end
+end

data/lib/fundamentalista/providers/edgar.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Providers
+    # The SEC's EDGAR XBRL API. Free and keyless, but the SEC requires a
+    # User-Agent naming the application and a contact email, set through
+    # Configuration#edgar_user_agent. Serves annual periods from 10-K
+    # filings and quarterly ones from 10-Q filings, with fourth quarters
+    # derived from the annual figures; foreign filers reporting under IFRS
+    # in 20-F and 40-F filings get their annual periods in their own
+    # currency. It has no market data, so quotes come from the price you
+    # pass to Company#valuation. Requests are spaced to respect the SEC's
+    # rate limit, see Configuration#edgar_requests_per_second.
+    class Edgar < Provider
+      TICKERS_URL = 'https://www.sec.gov/files/company_tickers.json'
+      FACTS_URL = 'https://data.sec.gov/api/xbrl/companyfacts/CIK%010d.json'
+
+      def company(ticker)
+        symbol = ticker.to_s.upcase.tr('.', '-')
+        entry = tickers[symbol] || raise(CompanyNotFoundError, "EDGAR lists no company under #{ticker.inspect}")
+        Company.new(ticker: symbol, name: entry['title'], cik: entry['cik_str'], provider: self)
+      end
+
+      def financials(company, period: :annual, limit: 5)
+        facts = Facts.new(company_facts(company))
+        @currency = facts.currency
+        periods = case period
+                  when :annual then facts.fiscal_years.first(limit).map { |year, ended_on| annual_period(facts, year, ended_on) }
+                  when :quarterly then quarterly_periods(facts, limit)
+                  else raise UnsupportedPeriodError, "EDGAR serves :annual and :quarterly periods, not #{period.inspect}"
+                  end
+        Financials.new(periods)
+      end
+
+      def quote(_company)
+        nil
+      end
+
+      def estimates(_company)
+        []
+      end
+
+      private
+
+      STATEMENTS = { income: [IncomeStatement, Tags::INCOME], balance: [BalanceSheet, Tags::BALANCE],
+                     cash_flow: [CashFlowStatement, Tags::CASH_FLOW], banking: [Banking, Tags::BANKING] }.freeze
+      private_constant :STATEMENTS
+
+      def annual_period(facts, year, ended_on)
+        build_period(year, ended_on) { |tags| facts.annual(tags, ended_on, year) }
+      end
+
+      def quarterly_periods(facts, limit)
+        quarters = facts.quarters
+        quarters.first(limit).each_with_index.map do |(year, quarter, ended_on), index|
+          previous = quarters[index + 1]&.last
+          build_period(year, ended_on, type: :quarterly, quarter: quarter) { |tags| facts.quarterly(tags, ended_on, previous) }
+        end
+      end
+
+      def build_period(year, ended_on, type: :annual, quarter: nil)
+        sources = {}
+        statements = STATEMENTS.transform_values do |klass, tags|
+          found = yield(tags)
+          found.each { |item, pair| sources[item] = pair.last if pair }
+          klass.new(**found.transform_values { |pair| pair&.first })
+        end
+        Period.new(fiscal_year: year, ended_on: ended_on, type: type, quarter: quarter, currency: @currency,
+                   sources: sources, **statements)
+      end
+
+      def company_facts(company)
+        get(format(FACTS_URL, company.cik), headers: headers)
+      rescue CompanyNotFoundError => e
+        raise CompanyNotFoundError.new("EDGAR has no XBRL facts for #{company.ticker}; it may not file financial statements",
+                                       response: e.response)
+      end
+
+      def tickers
+        @tickers ||= get(TICKERS_URL, headers: headers).values.to_h { |entry| [entry['ticker'], entry] }
+      end
+
+      def fetch_json(url, params, headers)
+        self.class.throttle(config.edgar_requests_per_second)
+        super
+      end
+
+      class << self
+        # Spaces requests out to at most +per_second+ across the process.
+        def throttle(per_second)
+          @mutex ||= Mutex.new
+          @mutex.synchronize do
+            now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+            wait = @last_request_at ? (@last_request_at + (1.0 / per_second)) - now : 0
+            sleep(wait) if wait.positive?
+            @last_request_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          end
+        end
+      end
+
+      def headers
+        agent = config.edgar_user_agent
+        raise ConfigurationError, 'The SEC requires config.edgar_user_agent, an app name and a contact email' unless agent
+
+        { 'User-Agent' => agent }
+      end
+    end
+  end
+end

data/lib/fundamentalista/providers/fmp.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Providers
+    # Financial Modeling Prep. Needs Configuration#fmp_api_key. Serves
+    # annual and quarterly periods, company profiles, live quotes and
+    # analyst estimates.
+    class FMP < Provider
+      BASE_URL = 'https://financialmodelingprep.com/stable/'
+
+      def company(ticker)
+        profile = get_first('profile', symbol: ticker)
+        raise CompanyNotFoundError, "FMP lists no company under #{ticker.inspect}" unless profile
+
+        Company.new(ticker: profile['symbol'], name: profile['companyName'], cik: profile['cik']&.to_i,
+                    currency: profile['currency'], provider: self)
+      end
+
+      def financials(company, period: :annual, limit: 5)
+        params = { symbol: company.ticker, period: period == :quarterly ? 'quarter' : 'annual', limit: limit }
+        statements = %w[income-statement balance-sheet-statement cash-flow-statement].map do |endpoint|
+          by_date(fetch(endpoint, params))
+        end
+        Financials.new(statements.first.keys.map { |date| build_period(date, *statements.map { |rows| rows[date] || {} }) })
+      end
+
+      def quote(company)
+        row = get_first('quote', symbol: company.ticker)
+        raise QuoteUnavailableError, "FMP has no quote for #{company.ticker}" unless row
+
+        Quote.new(price: row['price'], market_cap: row['marketCap'], currency: company.currency,
+                  as_of: row['timestamp'] && Time.at(row['timestamp']))
+      end
+
+      def estimates(company)
+        fetch('analyst-estimates', symbol: company.ticker, period: 'annual', limit: 10).map do |row|
+          Estimate.new(fiscal_year_end: Date.parse(row['date']), eps: row['epsAvg'], eps_low: row['epsLow'],
+                       eps_high: row['epsHigh'], revenue: row['revenueAvg'], ebitda: row['ebitdaAvg'],
+                       net_income: row['netIncomeAvg'], analysts: row['numAnalystsEps'])
+        end
+      end
+
+      private
+
+      def build_period(date, income, balance, cash_flow)
+        Period.new(
+          fiscal_year: income['fiscalYear'].to_i,
+          ended_on: Date.parse(date),
+          type: income['period'] == 'FY' ? :annual : :quarterly,
+          quarter: income['period'][/\AQ(\d)\z/, 1]&.to_i,
+          currency: income['reportedCurrency'] || 'USD',
+          income: income_statement(income),
+          balance: balance_sheet(balance),
+          cash_flow: cash_flow_statement(cash_flow),
+          banking: Banking.new(net_interest_income: income['netInterestIncome'], interest_income: income['interestIncome'])
+        )
+      end
+
+      def income_statement(row)
+        IncomeStatement.new(
+          revenue: row['revenue'], cost_of_revenue: row['costOfRevenue'], gross_profit: row['grossProfit'],
+          sga: row['sellingGeneralAndAdministrativeExpenses'],
+          operating_income: row['operatingIncome'], interest_expense: row['interestExpense'],
+          income_before_tax: row['incomeBeforeTax'], income_tax: row['incomeTaxExpense'],
+          net_income: row['netIncome'], depreciation_amortization: row['depreciationAndAmortization'],
+          ebitda: row['ebitda'], eps_diluted: row['epsDiluted'], diluted_shares: row['weightedAverageShsOutDil']
+        )
+      end
+
+      def balance_sheet(row)
+        BalanceSheet.new(
+          cash: row['cashAndCashEquivalents'], short_term_investments: row['shortTermInvestments'],
+          receivables: row['netReceivables'], inventory: row['inventory'],
+          current_assets: row['totalCurrentAssets'], ppe: row['propertyPlantEquipmentNet'], total_assets: row['totalAssets'],
+          payables: row['accountPayables'],
+          current_liabilities: row['totalCurrentLiabilities'], total_liabilities: row['totalLiabilities'],
+          short_term_debt: row['shortTermDebt'], long_term_debt: row['longTermDebt'],
+          total_debt: row['totalDebt'], equity: row['totalStockholdersEquity'],
+          retained_earnings: row['retainedEarnings']
+        )
+      end
+
+      def cash_flow_statement(row)
+        CashFlowStatement.new(
+          operating_cash_flow: row['operatingCashFlow'], capital_expenditure: outflow(row['capitalExpenditure']),
+          free_cash_flow: row['freeCashFlow'], dividends_paid: outflow(row['netDividendsPaid']),
+          share_repurchases: outflow(row['commonStockRepurchased'])
+        )
+      end
+
+      def outflow(value)
+        value&.abs
+      end
+
+      def by_date(rows)
+        rows.to_h { |row| [row['date'], row] }
+      end
+
+      def get_first(endpoint, params)
+        fetch(endpoint, params).first
+      end
+
+      def fetch(endpoint, params)
+        key = config.fmp_api_key || raise(ConfigurationError, 'Set config.fmp_api_key to use Financial Modeling Prep')
+        Array(get("#{BASE_URL}#{endpoint}", params.merge(apikey: key)))
+      end
+    end
+  end
+end

data/lib/fundamentalista/quote.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # A market snapshot: price, shares outstanding and market capitalization.
+  # Any two of them imply the third.
+  class Quote
+    include Inspectable
+    include Serializable
+
+    attr_reader :price, :currency, :as_of
+
+    def initialize(price:, shares_outstanding: nil, market_cap: nil, currency: 'USD', as_of: nil)
+      @price = Decimal.wrap(price)
+      @shares_outstanding = Decimal.wrap(shares_outstanding)
+      @market_cap = Decimal.wrap(market_cap)
+      @currency = currency
+      @as_of = as_of
+    end
+
+    def shares_outstanding
+      @shares_outstanding || Decimal.ratio(@market_cap, price)
+    end
+
+    def market_cap
+      @market_cap || (@shares_outstanding && price && (@shares_outstanding * price))
+    end
+
+    def inspect_attributes # :nodoc:
+      { price: price, market_cap: market_cap, currency: currency, as_of: as_of }
+    end
+  end
+end