MarketService

Financial market data from Finnhub, Yahoo Finance, and CoinGecko

The MarketService provides APIs for accessing stock quotes, cryptocurrency prices, commodity data, sector performance, stablecoin markets, ETF flows, and country stock indices.

Base Path

/api/market/v1

ListMarketQuotes

Retrieves stock and index quotes from Finnhub and Yahoo Finance.

Endpoint: GET /api/market/v1/list-market-quotes

Request Parameters

symbols · string[]

Ticker symbols to retrieve (e.g., ["AAPL", "^GSPC"]). Empty returns defaults.

Response

quotes · MarketQuote[]

The list of market quotes

Show MarketQuote

symbol · string · required

Ticker symbol (e.g., “AAPL”, “^GSPC”)

name · string

Human-readable name

display · string

Display label

price · double

Current price

change · double

Percentage change from previous close

sparkline · double[]

Sparkline data points (recent price history)

finnhub_skipped · bool

True when the Finnhub API key is not configured and stock quotes were skipped

skip_reason · string

Human-readable reason when Finnhub was skipped (e.g., “FINNHUB_API_KEY not configured”)

rate_limited · bool

True when the upstream API rate-limited the request

Example Request

curl "https://your-domain.com/api/market/v1/list-market-quotes?symbols=AAPL&symbols=MSFT&symbols=%5EGSPC"

Example Response

{
  "quotes": [
    {
      "symbol": "AAPL",
      "name": "Apple Inc.",
      "display": "AAPL",
      "price": 178.42,
      "change": 1.23,
      "sparkline": [175.2, 176.8, 177.1, 178.0, 178.42]
    },
    {
      "symbol": "^GSPC",
      "name": "S&P 500",
      "display": "S&P 500",
      "price": 5234.18,
      "change": 0.67,
      "sparkline": [5198.3, 5210.5, 5223.7, 5229.1, 5234.18]
    }
  ],
  "finnhub_skipped": false,
  "skip_reason": "",
  "rate_limited": false
}

---

ListCryptoQuotes

Retrieves cryptocurrency quotes from CoinGecko.

Endpoint: GET /api/market/v1/list-crypto-quotes

Request Parameters

ids · string[]

Cryptocurrency IDs to retrieve (CoinGecko IDs). Empty returns defaults.

Response

quotes · CryptoQuote[]

The list of cryptocurrency quotes

Show CryptoQuote

name · string

Cryptocurrency name (e.g., “Bitcoin”)

symbol · string · required

Ticker symbol (e.g., “BTC”)

price · double

Current price in USD

change · double

24-hour percentage change

sparkline · double[]

Sparkline data points (recent price history)

Example Request

curl "https://your-domain.com/api/market/v1/list-crypto-quotes?ids=bitcoin&ids=ethereum&ids=solana"

Example Response

{
  "quotes": [
    {
      "name": "Bitcoin",
      "symbol": "BTC",
      "price": 68432.50,
      "change": 3.42,
      "sparkline": [66100, 66800, 67200, 67900, 68432.50]
    },
    {
      "name": "Ethereum",
      "symbol": "ETH",
      "price": 3842.18,
      "change": 2.87,
      "sparkline": [3720, 3760, 3800, 3825, 3842.18]
    }
  ]
}

---

ListCommodityQuotes

Retrieves commodity price quotes from Yahoo Finance.

Endpoint: GET /api/market/v1/list-commodity-quotes

Request Parameters

No parameters required. Returns default commodity set.

Response

quotes · CommodityQuote[]

The list of commodity quotes

Show CommodityQuote

symbol · string · required

Commodity symbol (e.g., “CL=F” for crude oil)

name · string

Human-readable name

display · string

Display label

price · double

Current price

change · double

Percentage change from previous close

sparkline · double[]

Sparkline data points

Example Request

curl "https://your-domain.com/api/market/v1/list-commodity-quotes"

---

GetSectorSummary

Retrieves market sector performance data from Finnhub.

Endpoint: GET /api/market/v1/get-sector-summary

Request Parameters

No parameters required.

Response

sectors · SectorPerformance[]

Sector performance data

Show SectorPerformance

symbol · string · required

Sector symbol

name · string

Sector name (e.g., “Technology”, “Energy”)

change · double

Percentage change over the measured period

Example Request

curl "https://your-domain.com/api/market/v1/get-sector-summary"

Example Response

{
  "sectors": [
    {
      "symbol": "XLK",
      "name": "Technology",
      "change": 2.34
    },
    {
      "symbol": "XLE",
      "name": "Energy",
      "change": -1.12
    },
    {
      "symbol": "XLF",
      "name": "Financials",
      "change": 0.87
    }
  ]
}

---

ListStablecoinMarkets

Retrieves stablecoin peg health and market data from CoinGecko.

Endpoint: GET /api/market/v1/list-stablecoin-markets

Request Parameters

No parameters required.

Response

markets · StablecoinMarket[]

Stablecoin market data including peg deviation

Example Request

curl "https://your-domain.com/api/market/v1/list-stablecoin-markets"

---

ListEtfFlows

Retrieves BTC spot ETF flow estimates from Yahoo Finance.

Endpoint: GET /api/market/v1/list-etf-flows

Request Parameters

No parameters required.

Response

flows · EtfFlow[]

Bitcoin spot ETF flow data

Example Request

curl "https://your-domain.com/api/market/v1/list-etf-flows"

---

GetCountryStockIndex

Retrieves the primary stock index for a country from Yahoo Finance.

Endpoint: GET /api/market/v1/get-country-stock-index

Request Parameters

country_code · string · required

ISO 3166-1 alpha-2 country code

Response

quote · MarketQuote

The primary stock index quote for the country

country_code · string

ISO 3166-1 alpha-2 country code

country_name · string

Country name

Example Request

curl "https://your-domain.com/api/market/v1/get-country-stock-index?country_code=JP"

Example Response

{
  "quote": {
    "symbol": "^N225",
    "name": "Nikkei 225",
    "display": "Nikkei 225",
    "price": 39428.75,
    "change": 1.23,
    "sparkline": [38950, 39100, 39250, 39350, 39428.75]
  },
  "country_code": "JP",
  "country_name": "Japan"
}

Data Sources

• Finnhub: Real-time stock quotes and sector performance (requires API key)
• Yahoo Finance: Commodity prices, ETF flows, country indices
• CoinGecko: Cryptocurrency prices and stablecoin data

Rate Limiting

Finnhub has rate limits on the free tier. When rate-limited, the response will include rate_limited: true. Consider caching responses or upgrading to a paid Finnhub plan for production use.