Skip to main content
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
​
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

​
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

​
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

​
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us