finance

README

Go module for unified finance service provider access

Provided services

The go-finance module provides the following services via different providers:

• FX service: Query currency exchange rates.
• SymbolResolver service: Search Symbols
• Equity service: Query Quotes

The following providers are available:

Provider	FX	SymbolResolver	Equity	Comment
Alpha Vantage	✓	✓	✓	API key required
Consorsbank TAPI	✓	✓	✓	Requires Consorsbank depot and Active Trader
Frankfurter	✓			Free
OpenFIGI		✓		API key optional
Twelve Data	✓	✓	✓	API key required

License

This project is subject to the the Apache License, Version 2.0. See LICENSE information for details.

Important Disclaimer

This project is an independent open-source software library for accessing financial data from third-party providers.

Provider Terms

Each provider may impose specific licensing, redistribution, attribution, commercial use, and rate-limit requirements.

Users are responsible for reviewing and complying with the terms of the providers they choose to use.

No Financial Advice

This software and any data obtained through it are provided solely for informational and technical purposes. Nothing in this project constitutes investment advice, financial advice, tax advice, legal advice, or a recommendation to buy, sell, or hold any financial instrument.

Third-Party Data

All market data, exchange rates, stock prices, and related information are provided by external services. The maintainers of this project do not create, verify, audit, or guarantee the accuracy, completeness, timeliness, or availability of such data.

No Warranty

This project is provided "AS IS", without warranties or conditions of any kind, express or implied, including but not limited to warranties of accuracy, reliability, merchantability, fitness for a particular purpose, or non-infringement.

User Responsibility

Users are solely responsible for:

• Verifying the correctness of any data before relying on it.
• Complying with the terms of service and licensing conditions of any underlying data provider.
• Evaluating whether the software is suitable for their intended use.

Not for Mission-Critical Financial Decisions

This software is not intended for use as the sole basis for investment decisions, automated trading systems, regulatory reporting, risk management, or any other activity where inaccurate, delayed, or unavailable data could result in financial loss or legal liability.

No Affiliation

This project is not affiliated with, endorsed by, sponsored by, or otherwise associated with any financial data provider unless explicitly stated.

Documentation

Overview

Package finance provides financial services backed up by a pluggable provider system.

Index

• Variables
• func IsFIGI(s string) bool
• func IsISIN(s string) bool
• func IsWKN(s string) bool
• type APIProvider
• type Currency
• type Equity
• type ExchangeRate
• type FX
• type Quote
• type SecurityType
  • func MapSecurityType(s string, aliasMap map[string]string) SecurityType
• type Symbol
  • func NewFIGISymbol(figi string) Symbol
  • func NewISINSymbol(isin string) Symbol
  • func NewTickerSymbol(exchange, ticker string) Symbol
  • func NewWKNSymbol(wkn string) Symbol
  • func (s *Symbol) HasExchange() bool
  • func (s *Symbol) HasFIGI() bool
  • func (s *Symbol) HasISIN() bool
  • func (s *Symbol) HasTicker() bool
  • func (s *Symbol) HasWKN() bool
  • func (s *Symbol) IsEmpty() bool
  • func (s *Symbol) Match(other *Symbol) SymbolMatch
  • func (s *Symbol) Merge(other *Symbol)
• type SymbolMatch
• type SymbolResolver
• type Symbols
  • func (ss Symbols) Match(other *Symbol) (*Symbol, SymbolMatch)

Variables

var (
	// ErrInsufficientSymbol indicates a symbol does not contain
	// the necessary information required for a provider.
	ErrInsufficientSymbol error = errors.New("insufficient symbol")
	// ErrQuoteNotAvailable indicates a provider is not able to
	// provide a quote for the given [Symbol]. This is a permanent
	// error due to missing Symbol ids required by the provider.
	ErrQuoteNotAvailable error = errors.New("quote not available")
)

var (
	// ErrRateLimitReached indicates a provider will not respond
	// to further queries after a cool-down period.
	ErrRateLimitReached error = errors.New("rate limit reached")
	// ErrRequestPending indicates a request will be served
	// asynchronously and future calls may return the requested
	// data.
	ErrRequestPending error = errors.New("request pending")
)

var (
	// ErrSymbolNotAvailable indicates a [Symbol] is not known by a provider.
	ErrSymbolNotAvailable error = errors.New("symbol not available")
	// ErrSymbolSearchRestricted indicates a provider is not able to provide
	// a free-text search, but only for defined identifiers (e.g. ISINs).
	ErrSymbolSearchRestricted error = errors.New("symbol search restricted")
)

var (
	// ErrExchangeRateNotAvailable indicates an exchange rate is not available.
	ErrExchangeRateNotAvailable error = errors.New("exchange rate not available")
)

Functions

func IsFIGI

func IsFIGI(s string) bool

IsFIGI checks whether the given string represents a FIGI. This only verfies whether this a syntactically correct FIGI, but not whether this FIGI really exists.

func IsISIN

func IsISIN(s string) bool

IsISIN checks whether the given string represents an ISIN. This only verfies whether this a syntactically correct ISIN, but not whether this ISIN really exists.

func IsWKN

func IsWKN(s string) bool

IsWKN checks whether the given string represents a WKN. This only verfies whether this a syntactically correct WKN, but not whether this WKN really exists.

Types

type APIProvider

type APIProvider interface {
	// ProviderName gets the provider name.
	ProviderName() string
}

APIProvider is the interface common to all providers.

type Currency

type Currency string

Currency type.

const (
	CurrencyAED Currency = "AED"
	CurrencyAFN Currency = "AFN"
	CurrencyALL Currency = "ALL"
	CurrencyAMD Currency = "AMD"
	CurrencyANG Currency = "ANG"
	CurrencyAOA Currency = "AOA"
	CurrencyARS Currency = "ARS"
	CurrencyAUD Currency = "AUD"
	CurrencyAWG Currency = "AWG"
	CurrencyAZN Currency = "AZN"

	CurrencyBAM Currency = "BAM"
	CurrencyBBD Currency = "BBD"
	CurrencyBDT Currency = "BDT"
	CurrencyBHD Currency = "BHD"
	CurrencyBIF Currency = "BIF"
	CurrencyBMD Currency = "BMD"
	CurrencyBND Currency = "BND"
	CurrencyBOB Currency = "BOB"
	CurrencyBRL Currency = "BRL"
	CurrencyBSD Currency = "BSD"
	CurrencyBTN Currency = "BTN"
	CurrencyBWP Currency = "BWP"
	CurrencyBYN Currency = "BYN"
	CurrencyBZD Currency = "BZD"

	CurrencyCAD Currency = "CAD"
	CurrencyCDF Currency = "CDF"
	CurrencyCHF Currency = "CHF"
	CurrencyCLP Currency = "CLP"
	CurrencyCNH Currency = "CNH"
	CurrencyCNY Currency = "CNY"
	CurrencyCOP Currency = "COP"
	CurrencyCRC Currency = "CRC"
	CurrencyCUP Currency = "CUP"
	CurrencyCVE Currency = "CVE"
	CurrencyCZK Currency = "CZK"

	CurrencyDJF Currency = "DJF"
	CurrencyDKK Currency = "DKK"
	CurrencyDOP Currency = "DOP"
	CurrencyDZD Currency = "DZD"

	CurrencyEGP Currency = "EGP"
	CurrencyERN Currency = "ERN"
	CurrencyETB Currency = "ETB"
	CurrencyEUR Currency = "EUR"

	CurrencyFJD Currency = "FJD"
	CurrencyFKP Currency = "FKP"

	CurrencyGBP Currency = "GBP"
	CurrencyGEL Currency = "GEL"
	CurrencyGGP Currency = "GGP"
	CurrencyGHS Currency = "GHS"
	CurrencyGIP Currency = "GIP"
	CurrencyGMD Currency = "GMD"
	CurrencyGNF Currency = "GNF"
	CurrencyGTQ Currency = "GTQ"
	CurrencyGYD Currency = "GYD"

	CurrencyHKD Currency = "HKD"
	CurrencyHNL Currency = "HNL"
	CurrencyHTG Currency = "HTG"
	CurrencyHUF Currency = "HUF"

	CurrencyIDR Currency = "IDR"
	CurrencyILS Currency = "ILS"
	CurrencyIMP Currency = "IMP"
	CurrencyINR Currency = "INR"
	CurrencyIQD Currency = "IQD"
	CurrencyIRR Currency = "IRR"
	CurrencyISK Currency = "ISK"

	CurrencyJEP Currency = "JEP"
	CurrencyJMD Currency = "JMD"
	CurrencyJOD Currency = "JOD"
	CurrencyJPY Currency = "JPY"

	CurrencyKES Currency = "KES"
	CurrencyKGS Currency = "KGS"
	CurrencyKHR Currency = "KHR"
	CurrencyKMF Currency = "KMF"
	CurrencyKPW Currency = "KPW"
	CurrencyKRW Currency = "KRW"
	CurrencyKWD Currency = "KWD"
	CurrencyKYD Currency = "KYD"
	CurrencyKZT Currency = "KZT"

	CurrencyLAK Currency = "LAK"
	CurrencyLBP Currency = "LBP"
	CurrencyLKR Currency = "LKR"
	CurrencyLRD Currency = "LRD"
	CurrencyLSL Currency = "LSL"
	CurrencyLYD Currency = "LYD"

	CurrencyMAD Currency = "MAD"
	CurrencyMDL Currency = "MDL"
	CurrencyMGA Currency = "MGA"
	CurrencyMKD Currency = "MKD"
	CurrencyMMK Currency = "MMK"
	CurrencyMNT Currency = "MNT"
	CurrencyMOP Currency = "MOP"
	CurrencyMRO Currency = "MRO"
	CurrencyMRU Currency = "MRU"
	CurrencyMUR Currency = "MUR"
	CurrencyMVR Currency = "MVR"
	CurrencyMWK Currency = "MWK"
	CurrencyMXN Currency = "MXN"
	CurrencyMYR Currency = "MYR"
	CurrencyMZN Currency = "MZN"

	CurrencyNAD Currency = "NAD"
	CurrencyNGN Currency = "NGN"
	CurrencyNIO Currency = "NIO"
	CurrencyNOK Currency = "NOK"
	CurrencyNPR Currency = "NPR"
	CurrencyNZD Currency = "NZD"

	CurrencyOMR Currency = "OMR"

	CurrencyPAB Currency = "PAB"
	CurrencyPEN Currency = "PEN"
	CurrencyPGK Currency = "PGK"
	CurrencyPHP Currency = "PHP"
	CurrencyPKR Currency = "PKR"
	CurrencyPLN Currency = "PLN"
	CurrencyPYG Currency = "PYG"

	CurrencyQAR Currency = "QAR"

	CurrencyRON Currency = "RON"
	CurrencyRSD Currency = "RSD"
	CurrencyRUB Currency = "RUB"
	CurrencyRWF Currency = "RWF"

	CurrencySAR Currency = "SAR"
	CurrencySBD Currency = "SBD"
	CurrencySCR Currency = "SCR"
	CurrencySDG Currency = "SDG"
	CurrencySEK Currency = "SEK"
	CurrencySGD Currency = "SGD"
	CurrencySHP Currency = "SHP"
	CurrencySLE Currency = "SLE"
	CurrencySOS Currency = "SOS"
	CurrencySRD Currency = "SRD"
	CurrencySSP Currency = "SSP"
	CurrencySTN Currency = "STN"
	CurrencySVC Currency = "SVC"
	CurrencySYP Currency = "SYP"
	CurrencySZL Currency = "SZL"

	CurrencyTHB Currency = "THB"
	CurrencyTJS Currency = "TJS"
	CurrencyTMT Currency = "TMT"
	CurrencyTND Currency = "TND"
	CurrencyTOP Currency = "TOP"
	CurrencyTRY Currency = "TRY"
	CurrencyTTD Currency = "TTD"
	CurrencyTWD Currency = "TWD"
	CurrencyTZS Currency = "TZS"

	CurrencyUAH Currency = "UAH"
	CurrencyUGX Currency = "UGX"
	CurrencyUSD Currency = "USD"
	CurrencyUYU Currency = "UYU"
	CurrencyUZS Currency = "UZS"

	CurrencyVES Currency = "VES"
	CurrencyVND Currency = "VND"
	CurrencyVUV Currency = "VUV"

	CurrencyWST Currency = "WST"

	CurrencyXAF Currency = "XAF"
	CurrencyXAG Currency = "XAG"
	CurrencyXAU Currency = "XAU"
	CurrencyXCD Currency = "XCD"
	CurrencyXCG Currency = "XCG"
	CurrencyXDR Currency = "XDR"
	CurrencyXOF Currency = "XOF"
	CurrencyXPD Currency = "XPD"
	CurrencyXPF Currency = "XPF"
	CurrencyXPT Currency = "XPT"

	CurrencyYER Currency = "YER"

	CurrencyZAR Currency = "ZAR"
	CurrencyZMW Currency = "ZMW"
	CurrencyZWG Currency = "ZWG"
)

type Equity

type Equity interface {
	APIProvider

	// ResolveSymbol resolves the given symbol to ensure it contains the
	// necessary information to invoke [QueryQuote]. This function does
	// nothing if the necessary information is already contained in the
	// symbol.
	ResolveSymbol(ctx context.Context, symbol Symbol) (*Symbol, error)

	// QueryQuote returns the latest quote for a symbol.
	// Returns ErrQuoteNotAvailable if the provider cannot handle the given symbol
	// (e.g. because it requires a ticker but none was provided).
	QueryQuote(ctx context.Context, symbol Symbol) (*Quote, error)
}

Equity provides quote data for equities, ETFs, and similar instruments.

type ExchangeRate

type ExchangeRate struct {
	// Timestamp defines the point in time this exchange rate
	// was current according to the provider.
	Timestamp time.Time `json:"timestamp"`
	// Base defines the base currency for this exchange rate.
	Base Currency `json:"base"`
	// Quote defines the quoted currency for this exchange rate.
	Quote Currency `json:"quote"`
	// Rate defines the rate for base to quoted currency.
	Rate float64 `json:"rate"`
	// Sources defines the provider this exchange rate has been
	// queried from.
	Source string `json:"source"`
	// SourceTimestamp defines the time this exchange rate has
	// been queried.
	SourceTimestamp time.Time `json:"source_timestamp"`
}

ExchangeRate defines a currency exchange rate at a current point in time and sourced from a specific provider.

type FX

type FX interface {
	APIProvider
	// QueryExchangeRate queries the exchange rate for the given base and quote
	// currency.
	QueryExchangeRate(ctx context.Context, base, quote Currency) (*ExchangeRate, error)
}

FX interface provides functions for querying exchange rates.

type Quote

type Quote struct {
	// Symbol identifies the financial instrument by various ids.
	Symbol Symbol `json:"symbol"`
	// Timestamp gives the point in time this quote was current
	// according to the sourcing provider.
	Timestamp time.Time `json:"timestamp"`
	// Open gives the open price at the trading day identified by Timestamp.
	Open float64 `json:"open"`
	// High gives the high price at the trading day identified by Timestamp.
	High float64 `json:"high"`
	// Low gives the low price at the trading day identified by Timestamp.
	Low float64 `json:"low"`
	// Close gives the close price of the day before the trading day identified by Timestamp.
	Close float64 `json:"close"`
	// Price gives the current price at the trading day identified by Timestamp.
	Price float64 `json:"price"`
	// Volume gives the order volume at the trading day identified by Timestamp.
	Volume int64 `json:"volume"`
	// Currency gives the currency the given values.
	Currency Currency `json:"currency"`
	// Sources defines the provider this quote has been
	// queried from.
	Source string `json:"source"`
	// SourceTimestamp defines the time this quote has
	// been queried.
	SourceTimestamp time.Time `json:"source_timestamp"`
}

Quote represents a single price data point for a financial instrument.

type SecurityType

type SecurityType string

SecurityType classifies a financial instrument.

const (
	// SecurityTypeUnknown indicates an unknown financial instrument.
	SecurityTypeUnknown SecurityType = ""
	// SecurityTypeEquity indicates an equity (e.g. Common Stock).
	SecurityTypeEquity SecurityType = "equity"
	// SecurityTypeETF indicates an ETF.
	SecurityTypeETF SecurityType = "etf"
)

func MapSecurityType

func MapSecurityType(s string, aliasMap map[string]string) SecurityType

MapSecurityType maps a string to an existing SecurityType using the given alias map (if avaialable). SecurityTypeUnknown is returned in case no specific SecurityType could be identified.

type Symbol

type Symbol struct {
	// Exchange gives the MIC-Code of the exchange this Symbols refers to.
	Exchange string `json:"exchange"` // MIC-Code, e.g. "XNAS"
	// Ticker gives the ticker symbol this Symbol refers to.
	Ticker string `json:"ticker"` // e.g. "AAPL"
	// ISIN gives the ISIN id this Symbol refers to.
	ISIN string `json:"isin"` // e.g. "US0378331005"
	// WKN gives the ISIN id this Symbol refers to.
	WKN string `json:"wkn"` // e.g. "865985"
	// FIGI gives the ISIN id this Symbol refers to.
	FIGI string `json:"figi"` // e.g. "BBG000B9Y6W2"
	// Name gives the human-readable name of this financial instrument.
	Name string `json:"name"` // e.g. "Apple Inc."
	// Type gives the type of the financial instrument this Symbol refers to.
	Type SecurityType `json:"type"` // e.g. equity
}

Symbol identifies a financial instrument. It is a composite of identifiers from different naming systems. Not all fields are guaranteed to be populated; a provider fills whichever identifiers it supports. Callers should check with the Has* methods before relying on a specific field.

func NewFIGISymbol

func NewFIGISymbol(figi string) Symbol

func NewISINSymbol

func NewISINSymbol(isin string) Symbol

func NewTickerSymbol

func NewTickerSymbol(exchange, ticker string) Symbol

func NewWKNSymbol

func NewWKNSymbol(wkn string) Symbol

func (*Symbol) HasExchange

func (s *Symbol) HasExchange() bool

HasExchange indicates whether the Symbols Exchange attribute is set.

func (*Symbol) HasFIGI

func (s *Symbol) HasFIGI() bool

HasFIGI indicates whether the Symbols FIGI attribute is set.

func (*Symbol) HasISIN

func (s *Symbol) HasISIN() bool

HasISIN indicates whether the Symbols ISIN attribute is set.

func (*Symbol) HasTicker

func (s *Symbol) HasTicker() bool

HasTicker indicates whether the Symbols Ticker attribute is set.

func (*Symbol) HasWKN

func (s *Symbol) HasWKN() bool

HasWKN indicates whether the Symbols WKN attribute is set.

func (*Symbol) IsEmpty

func (s *Symbol) IsEmpty() bool

IsEmpty determines if a Symbol has any ids set.

func (*Symbol) Match

func (s *Symbol) Match(other *Symbol) SymbolMatch

func (*Symbol) Merge

func (s *Symbol) Merge(other *Symbol)

type SymbolMatch

type SymbolMatch int

const (
	SymbolMatchNone  SymbolMatch = 0
	SymbolMatchSoft  SymbolMatch = 1
	SymbolMatchEqual SymbolMatch = 2
)

type SymbolResolver

type SymbolResolver interface {
	APIProvider

	// SearchSymbol looks up symbols matching the given free-text query (name, ticker, ISIN, WKN, etc.).
	// Providers may restrict search to specific code types (e.g. ISIN/WKN only); such providers return
	// ErrSymbolSearchRestricted when the query contains no code they can resolve.
	SearchSymbol(ctx context.Context, query string) (Symbols, error)
}

SymbolResolver searches for financial instruments.

type Symbols

type Symbols []Symbol

Symbols defines an array of [Symbol]s.

func (Symbols) Match

func (ss Symbols) Match(other *Symbol) (*Symbol, SymbolMatch)