Market Data

Fetch current prices, historical prices, and market caps for any catalogue asset — crypto, forex, commodities — via third-party providers. MarketData batches requests per provider and runs them in parallel. If a provider fails, assets fall back to the next configured source automatically.

Installation

pip install tribulnation-catalogue

Quick start

from tribulnation.catalogue import Catalogue, MarketData

catalogue = Catalogue.load()
sdk = MarketData.new('coingecko', 'twelvedata', quote='usd')

# Fetch all assets in one batched call
stats, errors = await sdk.current_stats(catalogue.assets)

btc = stats.get('bitcoin')  # Stats(price=Decimal('...'), market_cap=Decimal('...'))
xau = stats.get('gold')     # Stats(price=Decimal('...')) — via Twelve Data

# Historical price for a single asset
price, errors = await sdk.historical_price(catalogue.assets['bitcoin'], datetime(2024, 1, 1))

Providers

Each provider reads its API key from the environment:

Provider	Source	Env var	Covers
CoinGecko	`'coingecko'`	`COINGECKO_PRO_API_KEY` or `COINGECKO_DEMO_API_KEY`	Crypto — price, market cap, history
CoinMarketCap	`'coinmarketcap'`	`COINMARKETCAP_API_KEY`	Crypto — price, market cap, history
Twelve Data	`'twelvedata'`	`TWELVEDATA_API_KEY`	Precious metals (XAU, XAG†), forex
Alpha Vantage	`'alphavantage'`	`ALPHAVANTAGE_API_KEY`	Energy & agricultural commodities (WTI, BRENT, …), forex

† XAG requires a paid Twelve Data plan.

External IDs

Each asset carries external IDs that map to provider-specific symbols. These are used automatically by MarketData to route requests to the right provider.

# data/assets/bitcoin.json
{ "external": { "coingecko": "bitcoin", "coinmarketcap": "1" } }

# data/assets/gold.json
{ "external": { "twelvedata": "XAU/USD" } }

# data/assets/west-texas-intermediate.json
{ "external": { "alphavantage": "WTI" } }

Browse the asset catalogue to see which external IDs each asset carries.