Rate Hub MCP Server

Catalog lookup (GET /v1/assets); use it to turn tickers or names into uids. Filters: q (free text), symbol, symbols (several tickers in one call), candidate (the uid of a candidates entry; registers that coin on demand; use alone), chain+contract (an unknown Solana mint can be registered on demand; mints are case-sensitive). Size: about 0.4 KB per asset (both copies of the result). Without any filter the default limit is 50 (the whole catalog is hundreds of assets); page with limit (1..1000) and after (next_after of the previous page). An explicit limit of 0 is an error. For a q lookup with few catalog hits, candidates lists at most 5 unregistered coins (not yet priced); pass a candidate's uid as candidate to register it and make it priceable. Dynamic coins expire after 7 days without use and may get a new uid after expiry or a server reset, so do not store a dynamic uid as identity; asset.icon is a placeholder image for an asset with no image source. Edge cases: read resource ratehub://docs/behavior (behaviour notes).

Coin categories (GET /v1/categories): each category id and name with the catalog uids that belong to it, for example layer-1 or stablecoins. Join it with uids from get_rates or search_assets to group holdings. It changes about once a day; as_of says when it was refreshed. A coin can be in several categories, and only the larger coins of a category are listed. Categories without a catalog member are omitted. The result grows with the catalog (one uid list per category, both copies of the result). not_ready (503) before the first daily refresh; not_found when the server has categories switched off.

Immutable daily rates for uids and UTC days (POST /v1/rates/daily). Days are UTC calendar dates (YYYY-MM-DD) in the past. Crypto history older than about a year is served at daily granularity from daily candles (source s8) back to the earliest day each asset has; an asset with no such history is out_of_range. Each item carries a status: ok = exact immutable rate; out_of_range = the day is before the archive start, after today UTC, before the first available day of a crypto asset, or before the asset was listed (final, do not retry); pending = transient upstream miss, retry after retry_after seconds; unsupported = unknown uid. Limits (assets, quotes, assets times days) are in get_meta. Edge cases: read resource ratehub://docs/behavior (behaviour notes).

API limits, supported quote currencies, and build info (GET /v1/meta).

Batch indicative prices for catalog uids (POST /v1/rates). Prices are decimal strings. Uids are class-ranged (uid = class*1e8+seq; 1=fiat e.g. usd 100000001, 2=crypto e.g. btc 200000001). Use search_assets to find uids. Per-rate status: ok = fresh price; stale = last known price, upstream is late (see as_of); pending = in the catalog but not priced yet, wait retry_after seconds for that asset and ask again; unsupported = the uid is not in the catalog (a dynamic coin may have expired; look it up again). Size: about 0.4 KB per asset and quote without include (the result is sent twice, as text and as structuredContent; sizes here count both); sparkline adds a long price array per asset, so request it only when needed. Limits (max assets, max quote currencies) are in get_meta. Optional source (a code such as s1) returns that source's own price instead of the server's choice: source_code equals it, and an asset the source has no reading for is unsupported, never another source's price; exchange codes only answer when the deployment runs multi-source aggregation. A dynamic coin expires after 7 days without use and may get a new uid when registered again (also after a server reset): match it by symbol or a new search, not by a stored uid. Edge cases: read resource ratehub://docs/behavior (behaviour notes).

Price history of one asset for charts (GET /v1/rates/series). Crypto: every range. Fiat: 1d and 7d from rate-hub's own readings taken about every 30 minutes; 30d, 90d, 1y and max one point per UTC day from the daily archive (it has a start day, days without a document are skipped, a cold range fills over a few retries, so an early answer may have fewer points). A fiat with no reading in the range, or an unknown uid, answers status unsupported with empty points, not an error. status: ok = fresh series; stale = last cached series, upstream failed (see fetched_at); pending = not ready, retry after retry_after seconds; unsupported = unknown uid, an asset no upstream knows, or a fiat with no reading in the range. Size: about 110 bytes per point (both copies of the result). max_points (2..500, default 100) downsamples evenly and keeps the first and last point; pass 500 for full detail. A non-USD fiat quote clips the series at the start of the fiat archive (range max only), and with a dynamic coin an unsupported answer may mean its uid expired. Edge cases: read resource ratehub://docs/behavior (behaviour notes).

Top crypto assets by market rank (GET /v1/top), with change and, by default, the market block (rank, market cap, volume, supply). Size: about 1 KB per asset with market (both copies of the result), smaller without. Default limit is 20 (max 250); pass include_market=false for a compact list. Items that cannot be priced in the requested quote are skipped. Edge cases: read resource ratehub://docs/behavior (behaviour notes).