Crypto

What's inside#

• Quotes and universe. A live quote for one pair from the real-time market-data feed (439 pairs), and the full liquid universe ranked by 24-hour dollar volume, with stablecoins excluded.
• Derivatives positioning. Cross-venue perpetual funding normalised to an 8-hour rate, open interest in USD, perpetual basis in basis points, and the BTC or ETH options volatility surface.
• Exchange events and on-chain flows. Listing, delisting and trading-caution notices taken from seven exchanges' own announcement APIs, breaking crypto-native headlines classified by event type, and stablecoin supply and lending liquidations read from Ethereum logs.
• Market data (Pro). Coin profiles with supply and all-time highs and lows, daily history back to each coin's first day, the whole market's size and dominance, sector (category) performance, top movers with a volume floor, where each coin trades, exchanges, public-company treasuries and decentralised-exchange pools.
• Recorded history (Pro). The derivatives, events and on-chain readings above as history: funding, open interest and basis per asset and per venue, the BTC and ETH volatility surface, the exchange-announcement and headline archive, and on-chain flows, one row per 15-minute recording cycle.
• News, sentiment and whale flow. A crypto newswire with per-coin and market-wide sentiment rollups, trending headlines, clustered events, an evening digest, delayed prices, and large on-chain and exchange transactions.

The derivatives, events and on-chain routes are data context. Their responses carry not_a_score: true and not_a_forecast: true: they report what the venues and the chain published, not a trading view.

For historical crypto OHLCV bars, or a snapshot with an is_stale flag, pass asset_class=crypto to /api/v3/fundamentals/prices or /api/v3/fundamentals/price_snapshot on Market Data. Bars run on the UTC day, and a bar still forming (today's day bar, the open week's bar) carries partial: true, with as_of, as_of_basis, last_bar_partial, data_through and session_complete on the response; see Bars still forming. Without it, a symbol such as BTC or LINK returns the US-listed equity of the same ticker. No other Market Data route takes asset_class: prices/history, prices/corporate_actions and intel/chart read BTC as the US-listed ticker.

Access#

This page spans several products. Each row in the tables below states its plan and credit cost.

Failed requests are not billed. When no upstream source answers, the derivatives, events and on-chain routes return 503 with error: "upstream_unavailable", an error_code such as crypto_derivatives_unavailable and a Retry-After, instead of an empty 200. On the derivatives routes, a ticker the venues list as a security (such as NVDA) answers 422 not_a_crypto_asset, and a symbol no venue lists answers 404 symbol_not_listed. Neither is retryable. See Pricing & credits.

The universe, derivatives, events and on-chain routes also accept asset_class=crypto. It is optional and crypto is its only value.

Endpoints#

Prices and universe#

Market data (Pro)#

Every answer states when its figures were fetched (fetched_at, age_s), whether they are older than their refresh window (stale) and the unit of each number (units). Nothing is served older than 24 hours. Tools that take a coin accept symbol or id: when several coins share a symbol, the one with the best market-cap rank is used and symbol_resolution names it and the other candidates. An unknown parameter answers 422 with the accepted list, and when the source cannot answer the route returns 503 with error: "upstream_unavailable" and a Retry-After.

Derivatives positioning#

Exchange events and on-chain flows#

Recorded history (Pro)#

The live derivatives, events and on-chain routes answer only for the present. These five read the recording Wealthnow keeps of them, one row per 15-minute cycle, newest first. Every route requires date or start (with optional end): at most 31 days per call, 7 on derivatives_venues, and a window before the recording began is a 422. Each answer carries as_of (the newest observation), gaps (stretches of more than an hour with no recording) and freshness (how old the newest row is). Like the live routes, they are data context, not a score.

News, sentiment and whale flow#

All routes in this table bill as news_sentiment: Starter and up, 2 credits per call.

A coin filter a news_crypto route does not take is refused, not dropped: a non-blank ticker, tickers, symbol, symbols, sector, sectors, industry, topic or topics that the route does not declare answers 422 with error: "unsupported_filter", not billed, and detail names the crypto parameter or route to use (for example news_crypto/latest?tickers=BTC, or news_crypto/ticker_only?ticker=BTC for articles about one coin alone). news_crypto/latest takes tickers, not ticker. Market-wide routes such as by_category, market_sentiment and top_mentions take no coin filter at all.

Reading the responses#

Quotes#

/api/crypto/{ticker} returns pair (the normalised X:<BASE><QUOTE> form), a quote block, day and prev_day OHLC bars with vwap, the last_trade, and series_daily when series=true.

• quote.change_24h and quote.change_pct_24h compare the price with the previous UTC day's close (change_basis: "vs_prev_utc_day_close"), not a rolling 24 hours.
• quote.volume_24h is the volume of the current UTC day so far (volume_basis: "utc_day"), the same figure as day.volume. Until the new UTC day's bar has data, just after midnight UTC, it is the previous UTC day's full volume instead: volume_basis is prev_utc_day and day is null.
• quote.market_cap is always null: the feed carries no supply data.
• as_of and quote.as_of_ts are the feed's observation time. last_trade.ts is the time of the last print.

Universe#

/api/crypto/universe reports the size of the book it ranked alongside the rows: priced (pairs the feed priced), excluded_quote, excluded_stable, below_floor, and liquid (pairs above the floor). Each row in universe has symbol, pair, price, dollar_volume_24h, change_pct_24h and rank. Ranks are assigned on the whole liquid book, so a page that starts at offset=50 begins at rank 51. Walk the book with has_more and next_offset.

This is a liquidity ranking: it tells you which pairs trade enough to be tradeable, not which will move.

Market data#

Every /api/v3/crypto/market/* answer wraps its payload in the same fields:

• ok and tool, the tool that answered (for example tengu_v3_crypto_market_profile).
• source, always "market-data:crypto".
• as_of and fetched_at: when the data was read from the source, in UTC. age_s is its age in seconds, and max_age_s (86400) is the oldest it can be.
• cache: hit (a stored copy still fresh for this route), miss (read on this call) or stale. stale: true means the source could not be read and a copy under 24 hours old was served in its place.
• units: what each number in data is measured in. On the chart routes, for example, prices are [timestamp ms epoch UTC, price in vs_currency].
• data: the route's payload.
• parts, on an answer built from more than one read: each read's fetched_at, age_s, stale and cache. as_of is then the oldest read, age_s the largest, and stale is true if any read was.

Reading the payloads:

• One coin, by symbol or id. The coin routes take symbol (BTC) or id (bitcoin), exactly one of them: neither is 422 missing_param, both is 422 invalid_param. When several coins share a symbol, the one with the best market-cap rank is used. The answer names it in coin (id, name, symbol) and shows the choice in symbol_resolution: chosen_id, the basis, up to 10 candidates with their market_cap_rank, and candidates_total. To get a different coin, pass its id.
• Several coins. profile (up to 50 coins) and price (up to 50 symbols or 250 ids) take symbols and ids lists, and symbol_resolution is keyed by symbol. profile returns data.coins and data.not_found. Each coin has its price, market cap and rank, fully diluted valuation, volume, circulating, total and max supply, all-time high and low with their dates, and price_change_percentage_1h to price_change_percentage_1y. price returns data keyed by coin id, beside coins (what each requested symbol or id resolved to, with priced: false where no price came back) and not_found. Either call is 404 coin_not_found only when none of the coins matched.
• History. history returns one row per UTC day in data.rows: date, t_ms, close, market_cap and volume_24h, with the window's from and to in unix seconds. days=max reaches back to the coin's first day. on_date answers for one past day (from 2009-01-03 to today), and chart/range takes from and to in unix seconds, from first.
• Ids. Ids are lowercase: coins (bitcoin), exchanges (binance), derivatives exchanges (binance_futures) and categories (from categories/list). The on-chain routes name a chain by network id (eth, solana, base); contract names it by platform id (ethereum, binance-smart-chain), which asset_platforms lists.
• Errors. An unknown parameter is 422 unknown_param, with the route's parameters in accepted. A malformed value is 422 invalid_param. An id that is malformed or unknown is 404 with a typed code: coin_not_found, exchange_not_found, platform_not_found, category_not_found, network_not_found or address_not_found. When the source cannot answer, the route returns 503 with error: "upstream_unavailable", a Retry-After header and an error_code: vendor_unavailable, rate_limited, budget_exhausted (today's allowance for all API customers is used up; it resets at 00:00 UTC), key_budget_exhausted (this key's share of that allowance is used up) or not_enabled. Answers already cached are still served meanwhile. No refusal is billed.

Derivatives, events and on-chain#

These routes share one envelope: kind, purpose: "data_context", not_a_score, not_a_forecast, asset_class, as_of, status, rows, count and a sources block that states each venue's status.

• Missing is typed, never zero. A symbol or venue with no data comes back with status: "missing" and a reason. A venue that cannot be reached from the API's region is reported as geo_blocked, and a venue in back-off as circuit_open.
• Freshness. Funding, open interest and basis responses carry freshness_seconds and stale_after_seconds (600), and status is stale when the newest row is older than that. Every venue row carries its own as_of.
• Funding. Each row has funding_rate_8h with funding_rate_basis, funding_apr (the 8-hour rate × 3 × 365), oi_weighted_rate_8h, mean_rate_8h_verified, dispersion_bps, funding_z_30d with funding_z_status, coverage and a venues map. The venues are first-party: OKX, Deribit, Kraken, dYdX, Bitget, Gate and Coinbase International, each marked tier: "verified" in sources. funding_rate_8h is the open-interest-weighted rate across verified venues (funding_rate_basis: "oi_weighted_verified"), or their median when a verified venue has no open interest; the plain mean is mean_rate_8h_verified. Binance and Bybit report status: "geo_blocked": their APIs are blocked from the API's region, and Wealthnow never reaches them another way. Deribit reports not_applicable when a request names neither BTC nor ETH, the only perpetuals it lists. The aggregator tier reports unavailable while no licensed key is configured; fields ending _all add aggregator rows that passed its quality gates.
• Open interest. Each row has oi_usd_total, per-venue oi_usd, n_venues and dominant_venue. USD is the only unit summed across venues; contract counts are never served.
• Basis. Each row has perp_premium_bps (the cross-venue mean) and per-venue premium_bps.
• Vol surface. The single row has spot, a term list (per expiry: expiry, days, n_strikes, atm_iv, pc_oi_ratio, max_pain), atm_iv_7d, atm_iv_30d, atm_iv_90d, term_slope_90d_7d, skew_10pct_30d, pc_oi_ratio_total, and dvol, realized_vol and vol_risk_premium blocks. IV is in vol points (38.3 means 38.3%). The skew is a moneyness proxy, labelled as such in skew_method, not a delta-space skew. An expiry with fewer than 6 strikes is typed missing. vol_risk_premium.iv_rv_ratio below 1 means the market is pricing less movement than it is realising. realized_vol ends at the last completed hour: the venue stamps the hour in progress with its end time, and that partial point is never served. vol_risk_premium carries iv_as_of and rv_as_of, the time of each leg, because the two come from different series and a premium is only as current as its older leg.
• Announcements and headlines. Each row has event_type, symbols, title, url, origin_ts (the venue's or post's own time), detected_ts and lag_ms. Announcement rows add venues and n_venues; headline rows add handle and tier. The event type is a classification, never a direction.
• On-chain flows. rows holds one block per metric. stablecoin_flows has mint_usd, burn_usd, net_usd, net_status and a per_event breakdown. net_usd is null with net_status: "partial" unless every mint and burn query answered, because one failed leg would otherwise report a large false contraction. aave_liquidations has liquidations beside pool_logs and feed_live, so a quiet market (zero liquidations, live pool) can be told apart from a dead feed. Until 2026-09-25 this route answered 503 with error_code: "crypto_onchain_unavailable" on every call, because the server could not compute the event hashes it filters the chain logs by; it now computes them itself and answers.

News and sentiment#

The news routes wrap the news vendor's records: items holds article lists, stats the per-coin and leaderboard sentiment rollups, and market, mentions, digest, prices and summary the market sentiment, top mentions, sundown, ticker price and whale summary payloads. summary/{ticker} returns recent_news, sentiment_stats, trending and news_count_24h. Treat the per-article sentiment label as unverified. When the response includes a sentiment_label_policy note, the label is served as vendor_sentiment_label_untrusted and should not be used as a signal. For what an exchange or the chain actually did, use the events and on-chain routes above. When the crypto news feed fails and returns nothing, the news_crypto routes answer 503 with error: "upstream_unavailable", not billed, instead of a 200 with an empty list: error_code names the failure (for example upstream_quota_exhausted, or upstream_not_configured when no feed is configured), upstream_error summarises it, and Retry-After says when to retry. The body has no data field. A feed that answered with nothing is still a 200, and a partial failure keeps its rows beside a vendor_error block. When the feed is out of quota and states when its quota resets, upstream_error adds quota_resets_at (UTC) and quota_resets_at_basis, and the body adds retry_after_basis: "firm_recheck": Retry-After is when Wealthnow next checks the feed, not when the quota returns.

Examples#

Quote Bitcoin (1 credit)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/crypto/BTC?series=false"

Live response captured 2026-09-23, abbreviated:

{  "ok": true,  "timestamp": "2026-09-23T05:00:17.284033+00:00",  "ticker": "BTC",  "pair": "X:BTCUSD",  "vs": "USD",  "quote": {    "price": 87125.0,    "as_of_ts": "2026-09-23T05:00:00+00:00",    "change_pct_24h": 1.075372354711037,    "change_24h": 926.9499999999971,    "change_basis": "vs_prev_utc_day_close",    "volume_24h": 2006.02328534,    "volume_basis": "utc_day",    "market_cap": null  },  "day": { "open": 86201.35, "high": 87379.7, "low": 86108, "close": 87159.93, "volume": 2006.02328534, "vwap": 86697.8829 },  "prev_day": { "open": 86594.94, "high": 86752, "low": 85059.28, "close": 86198.05, "volume": 16565.86870454, "vwap": 86060.7417 },  "last_trade": { "price": 87125, "size": 3e-08, "exchange": 1, "ts": "2026-09-23T05:00:17.057000+00:00" },  "source": "vendor:market-data",  "as_of": "2026-09-23T05:00:00+00:00"}

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/crypto/BTC",    params={"vs": "USD", "series": True},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()data = r.json()quote = data["quote"]print(f"{data['pair']}: {quote['price']:,.2f} ({quote['change_pct_24h']:+.2f}% vs prior UTC close)")bars = data.get("series_daily") or []if bars:    print(f"Lowest low in the last {len(bars)} daily bars: {min(b['low'] for b in bars):,.2f}")

Is the BTC perp market crowded? (1 credit)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/crypto/derivatives/funding?symbols=BTC,ETH"

Live response captured 2026-09-26, abbreviated to one symbol, two venues and three sources. With several symbols and the default detail=auto, venues is a compact {venue: rate_8h} map, and detail reports the level auto resolved to:

{  "ok": true,  "kind": "crypto_derivatives_funding",  "purpose": "data_context",  "not_a_score": true,  "not_a_forecast": true,  "asset_class": "crypto",  "as_of": "2026-09-26T23:17:23.517000+00:00",  "stale_after_seconds": 600.0,  "status": "ok",  "rows": [    {      "symbol": "BTC",      "funding_rate_8h": 1.1619e-06,      "funding_rate_basis": "oi_weighted_verified",      "funding_apr": 0.001272,      "oi_weighted_rate_8h": 1.1619e-06,      "mean_rate_8h_verified": 5.0381e-06,      "dispersion_bps": 0.63,      "funding_z_30d": -1.97,      "funding_z_status": "ok",      "venues": {        "okx": -8.305e-06,        "deribit": 1.21e-06      },      "n_venues": 7,      "status": "ok"    }  ],  "count": 2,  "count_ok": 2,  "sources": {    "okx": {      "status": "ok",      "tier": "verified"    },    "binance": {      "status": "geo_blocked",      "reason": "venue API is geo-blocked from the serving host; FIRM never routes around it",      "funding": "unavailable",      "oi": "unavailable"    },    "coingecko": {      "status": "unavailable",      "tier": "aggregator",      "mode": "disabled",      "reason": "no licensed key"    }  },  "units": {    "funding_rate_8h": "fraction per 8h, venue-interval normalised; headline = OI-weighted over VERIFIED (first-party) venues (funding_rate_basis names it)",    "funding_apr": "fraction, rate_8h×3×365",    "dispersion_bps": "(max−min venue rate_8h) × 1e4"  },  "detail": "summary",  "shape": "compact"}

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/crypto/derivatives/funding",    params={"symbols": "BTC,ETH,SOL"},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()for row in r.json()["rows"]:    if row.get("status") != "ok":        print(f"{row['symbol']}: {row.get('reason', 'missing')}")        continue    z = row["funding_z_30d"] if row.get("funding_z_status") == "ok" else None    print(f"{row['symbol']}: {row['funding_apr']:.1%} APR across {row['n_venues']} venues, 30d z = {z}")

What listed in the last 24 hours? (1 credit)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/crypto/events/announcements?hours=24&event_type=listing"

Read origin_ts for when the venue published and lag_ms for how late the API saw it. Check sources before concluding nothing was listed: a venue marked geo_blocked or missing did not answer.

Is stablecoin supply expanding? (1 credit)#

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/crypto/onchain/flows",    params={"hours": 24},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()blocks = {row["metric"]: row for row in r.json()["rows"]}flows = blocks.get("stablecoin_flows")if flows and flows.get("net_status") == "ok":    print(f"Net stablecoin supply change: ${flows['net_usd']:,.0f}")else:    print("Net supply withheld: not every mint and burn query answered.")liq = blocks.get("aave_liquidations")if liq:    print(f"Liquidations: {liq['liquidations']} (pool logs: {liq['pool_logs']}, feed live: {liq['feed_live']})")

Crypto news for one coin (2 credits, Starter and up)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/news_crypto/summary/ETH"

Related#