Tribulnation Catalogue
A typed, open catalogue of crypto assets, trading platforms, instrument mappings, and name translations — built to resolve the inconsistent IDs and symbols that exchanges, wallets, chains, and market data APIs throw at you.
API
Every record in this catalogue is available as a static JSON API — no auth, no rate limits, served from GitHub Pages.
Browse: catalogue.tribulnation.com
GET /api/v1/stats.json
GET /api/v1/assets.json
GET /api/v1/assets/{id}.json
GET /api/v1/platforms.json
GET /api/v1/platforms/{id}.json
GET /api/v1/instruments/spot/{platform}.json
GET /api/v1/instruments/perpetual/{platform}.json
GET /api/v1/instruments/index/{asset}.json
GET /api/v1/indexes/symbols.json
GET /api/v1/indexes/external/coingecko.json
GET /api/v1/openapi.json
Full route list and interactive 'try it' at catalogue.tribulnation.com/api.
Download everything at once:
| Archive | Contents |
|---|
data.zip | Raw catalogue data (JSON) |
icons.zip | SVG icons for assets, platforms, networks |
Clients
JavaScript / TypeScript
npm install @tribulnation/catalogue
import { Catalogue } from '@tribulnation/catalogue';
const client = new Catalogue();
const matches = await client.findBySymbol('BTC');
return (
matches.map((match) => (
<div>
<p>{match.display_name}</p>
<img src={match.icon} alt={`Image of ${match.id}`} />
</div>
))
)
// Fetch individual records
const bitcoin = await client.fetchAsset('bitcoin');
const pairs = await client.getSpotInstruments('mexc');
Python
pip install tribulnation-catalogue
from tribulnation.catalogue import Catalogue
catalogue = Catalogue.load()
btc = catalogue.assets['bitcoin']
binance = catalogue.platforms['binance']
Catalogue.load() downloads the public catalogue on first use and caches it locally. It checks for changes at most once a day with a conditional request, re-downloads only when the data changed, and keeps the last good copy if the site is unreachable.
catalogue = Catalogue.load() # use cache, refresh daily
catalogue = Catalogue.load(refresh=True) # force fresh download
catalogue = Catalogue.load('data') # explicit local folder
catalogue = catalogue.maybe_refresh() # long-running processes: cheap, returns self when unchanged
catalogue.digest # sha256 of the loaded data.zip
catalogue.asset_for('hyperliquid', 150) # 'hyperliquid'
catalogue.perpetual_for('dydx', 'BTC-USD').base # 'bitcoin'
catalogue.format_correlation('cctp', source_domain=4, nonce=12345) # 'cctp:4:12345'
catalogue.parse_correlation('ibc:dydx:channel-0:42') # ('ibc', {'sending_chain': 'dydx', ...})
catalogue.network_for_domain('cctp', 3) # 'arbitrum'
Pricing
MarketData fetches prices and market caps for catalogue assets using one or more external providers. Requests are batched per provider and run in parallel. If a provider fails, assets fall back to the next configured provider that covers them.
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))
Assets with a pegged_to field (e.g. XAUT → gold, cbBTC → bitcoin) automatically inherit the pegged asset's price if no direct price is found.
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 | US stocks, USD forex, energy & agricultural commodities |
| ECB | 'iso4217' | — | Daily euro reference rates for ~30 fiat currencies (ISO 4217 codes) |
† XAG requires a paid Twelve Data plan.
Provider IDs have provider-specific semantics, especially for forex, commodities, and stock symbols. See External IDs for the conventions.
What's inside
Assets
Canonical records keyed by slug (e.g. bitcoin, usd-coin). Each asset has a display_name, symbol, optional icon, tags, peg information for stablecoins and wrapped tokens, and external IDs mapping to third-party providers:
| Field | Provider |
|---|
coingecko | CoinGecko asset ID |
coinmarketcap | CoinMarketCap asset ID |
twelvedata | Twelve Data symbol (e.g. XAU/USD) |
alphavantage | Alpha Vantage typed ID (e.g. stock:TSLA, forex:EUR, commodity:WTI) |
fred | FRED series ID (e.g. DEXUSEU, inverse:DEXJPUS) |
yahoo | Yahoo Finance symbol (e.g. AAPL, EURUSD=X) |
iso4217 | ISO 4217 code of a fiat currency or precious metal (e.g. CHF, XAU) |
Platforms
Trading venues and networks keyed by slug (e.g. binance, ethereum). Covers CEX, DEX, and blockchain platforms. Blockchains carry namespace, chain_id, native_asset, and EVM/SVM category.
Instruments
Spot pairs, perpetual futures, debt positions, and liquidity pools — each referencing canonical asset IDs. Maps exchange-specific tickers to the catalogue's canonical identifiers.
Translations
Per-platform display-name mappings for assets and networks. Resolves what a given exchange calls BTC/USDT into ('bitcoin', 'tether').
Icons
SVG icons for assets, platforms, and networks, organized under icons/asset/, icons/platform/, and icons/network/. All icons are square and maskable — they include a full square background and are designed to be displayed cropped to a circle or rounded square. API responses include absolute icon URLs.
Spam
Known spam token addresses per chain, with optional source and reported timestamp.
Protocols
Cross-chain protocols (cctp, ibc, hlbridge, gofast, relay, lighter) keyed by id. Each defines a correlation key: a template such as cctp:{source_domain}:{nonce} with typed fields, which both sides of one cross-chain movement can compute independently so they can be linked. Protocol data stays in the entry, e.g. CCTP's domain → network table. Keys are built and checked with format_correlation / parse_correlation.
Contributing
Contributions are welcome — new assets, platforms, icons, translations, and corrections.
git clone https://github.com/tribulnation/catalogue.git
cd catalogue
python -m venv .venv && .venv/bin/pip install -r requirements.txt
Add or edit files under data/ and icons/, then validate:
.venv/bin/python scripts/validate.py
See CONTRIBUTING.md for the full data layout and field reference.
