Asset by ID

All endpoints on this page are Platform API endpoints.

Asset (canonical or singleton): GET /v1/assets/:assetId

Fetch an asset and, optionally, attach additional “include” blocks in one request.

• assetId may be a canonical slug (for example: solana, usd, tesla), an alias, a raw Solana mint, or a deterministic singleton ref of the form solana-<mint>.

• Known mint refs return the canonical asset group. For example, /v1/assets/solana-EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v returns asset.assetId: "usd".

• Unknown mints still return singleton assets with IDs of the form solana-<mint>.

• Auth: x-api-key

• Scope: assets:read

Query params

• include (optional): comma-separated list of:
  • profile
  • risk
  • ohlcv
  • markets
• mint (optional): pick a specific variant mint for include computations; must be a variant of this asset.
• variantsMode (optional): set to all to disable server-side capping of large variant sets.
• primaryVariantStrategy (optional): liquidity (default), execution_quality, or stock_redeemability.

When using includes, additional params apply:

ohlcv params

• ohlcvInterval (default 1H): one of 1m, 5m, 15m, 1H, 4H, 1D, 1W
• ohlcvFrom / ohlcvTo (unix seconds): default to last 7 days

markets params

• marketsOffset (default 0)
• marketsLimit (default 10, clamped to 1–50)

Notes

• Includes are best-effort and returned as { ok: true, data } or { ok: false, reason, message } per include key.
• When the path is a known mint ref and mint is not provided as a query param, that path mint is used for variant include computations. For mapped public equities, the detail include=ohlcv block still uses canonical stock-market candles unless you pass mint explicitly.
• Responses can include top-level resolution metadata when the request path was resolved from an alias or mint ref.
• This endpoint may trigger background cache warming if data is missing/stale.
• asset.imageUrl is curated canonical imagery (storage-backed where configured). asset.primaryVariant.market.logoURI is a best-effort per-token icon from indexed/cache sources and may be null (the server may fall back to asset.imageUrl when missing).
• asset.primaryVariant is chosen deterministically from the asset’s spot-like variants (native, wrapped, bridged, stablecoin, lst, tokenized_equity, basket) by highest liquidity, then trust tier, then 24h volume, then curated mint rank unless an opt-in primary strategy applies. Variants flagged compromised or blocked are skipped by every strategy (see Advisories).
• asset.primaryVariant.advisory and every variant object under asset.variantGroups.*[] carry advisory: { status, reason, url, since } | null. The key is always present; null means the mint is not flagged.
• asset.advisories is always present: an array of { mint, variantId, status, reason, url, since } for every flagged variant of the asset ([] when none). It includes variants that list surfaces hide, so a page can show a “sibling flagged” notice even when the primary variant is fine.
• primaryVariantStrategy=stock_redeemability applies to equities and tokenized equities. It favors share_redeemable over cash_redeemable over not_redeemable or missing stock tiers when the higher-tier variant has zero/unknown liquidity on both sides or is within 5x of the more liquid variant.
• asset.primaryVariant.stockVariantTier and asset.variantGroups.tokenizedEquity[].stockVariantTier may be present with share_redeemable, cash_redeemable, or not_redeemable. This is informational API metadata, not legal, tax, accounting, or investment advice.
• Variant market blocks may include source, metricsSource, volume1hUSD, trade1h, trade24h, uniqueWallet1h, uniqueWallet24h, lastTradeAt, and asOf when those fields are available in the Convex cache. metricsSource="clickhouse_trades" means market metrics were materialized from successful direct USD-stable Solana trades. Public API routes still read these fields from Convex/cache only.
• When present, asset.stats.liquidity, asset.stats.volume24hUSD, and asset.stats.volume30dUSD are canonical on-chain aggregates across variants. volume30dUSD is a nullable rolling 30-day USD volume sum from cached daily candles, so clients do not need to sum candles themselves when it is populated. For mapped public equities, asset.stats.price, asset.stats.volume24hUSD, and asset.stats.priceChange24hPercent come from canonical stock-market data; otherwise price fields come from the primary variant or external canonical provider.
• asset.canonicalMarket.source can be coingecko, clickhouse_stock, or prestocks. clickhouse_stock is used for mapped public equities. prestocks is used for tokenized pre-IPO equities backed by PreStocks reference data (e.g. Anduril, OpenAI, Anthropic); consumers with exhaustive switch(source) handling should add a default branch. Passing mint keeps variant-specific include computations, including include=ohlcv, on the on-chain mint.
• For canonicalMarket.source="prestocks", marketCap is the implied company valuation (PreStocks reference valuation × token price ÷ reference mark price), not the tokenized float value — mirroring how clickhouse_stock reports the underlying company's market cap. The arm also carries markPriceUsd, markValuationUsd, impliedValuationUsd, premiumToMarkPercent (token premium/discount vs the PreStocks mark), and mint. PreStocks provides no data timestamp, so asOf/providerLastUpdatedAt mirror our fetch time; the block is omitted when the reference feed is stale (>24h).
• Variant objects whose mint is a PreStocks token (including spacex/openai PreStocks variants) may carry a preStocks block: { symbol, markPriceUsd, markValuationUsd, impliedValuationUsd, premiumToMarkPercent, lastFetchedAt }, derived from that variant's own on-chain price.
• For assetId=solana, yield variants can be very large; the server may cap the returned yield variant set by default to keep responses fast. Use variantsMode=all to request the full set.

Example

curl -sS "$API_BASE_URL/v1/assets/$ASSET_ID?include=profile,risk,ohlcv,markets" \
  -H "x-api-key: $API_KEY"

{
    "asset": {
        "assetId": "usd"
    },
    "resolution": {
        "ref": "solana-EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        "resolvedBy": "singletonMint",
        "assetId": "usd",
        "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
    }
}

Advisories

An advisory is an operator-set flag on a variant mint (never on the canonical asset) for situations such as an issuer exploit, a depegged wrapper, or a contract the issuer has told holders not to interact with. It is stored server-side and takes effect across the API without a deploy, so integrators should read it from the payload they already fetch rather than maintain their own denylist.

type AdvisoryStatus = 'caution' | 'compromised' | 'blocked';

// On every variant object: asset.primaryVariant, asset.variantGroups.*[],
// and rows from /variants and /variant-markets.
type VariantAdvisory = {
    status: AdvisoryStatus;
    reason: string; // operator-written, safe to show verbatim
    url: string | null; // issuer statement or other source, when available
    since: number; // unix ms the current status was set
} | null;

// asset.advisories[] — one entry per flagged variant, [] when none.
interface AssetAdvisoryEntry {
    mint: string;
    variantId: string;
    status: AdvisoryStatus;
    reason: string;
    url: string | null;
    since: number;
}

Statuses

• caution — informational. The variant is served and ranked normally; show reason as a notice.
• compromised — the variant stays visible everywhere it would normally appear, but it is excluded from primary-variant selection (another spot-like variant becomes primaryVariant when one exists) and from /v1/assets/trending. Execution endpoints refuse the mint. Clients should refuse to trade it.
• blocked — everything compromised does, and additionally the variant is omitted from /v1/assets/search, /v1/assets/curated, /v1/assets/trending, and v2 list hydration. Direct lookups still work (below).

Guarantees

• This endpoint never 404s a flagged mint. GET /v1/assets/:assetId, GET /v1/assets/:assetId?mint=<flagged>, GET /v1/assets/solana-<flagged>, and /variants keep returning blocked and compromised variants with advisory populated, so a shared link to the token still lands on the warning rather than on “not found”. Hard removals use a different mechanism (inactive variants and deletion tombstones) and are the only things that 404.
• A compromised or blocked variant is never chosen as primaryVariant while another eligible variant exists. When every variant of an asset is flagged, the API falls back to the normal ranking instead of returning null, and primaryVariant.advisory tells you why you should not use it.
• asset.advisories reflects the full asset, including variants a list surface hid; advisory on each variant object reflects only that mint.
• Advisory changes propagate to this endpoint within roughly a minute (server-side cache plus HTTP max-age); /curated and /trending are similar or faster.

Guidance

Treat compromised and blocked as do-not-trade: disable buy/sell/swap actions for that mint, surface reason, and link to url when present. caution is display-only. Do not branch on reason text; branch on status and add a default arm so a future status degrades to a warning rather than to silence.

Variants: GET /v1/assets/:assetId/variants

List variants for an asset (canonical or singleton), optionally filtered.

• Auth: x-api-key
• Scope: assets:read

Query params

• kind (optional): one of
  • native, wrapped, bridged, etf, yield, leveraged, basket, lst, stablecoin, tokenized_equity
• liquidityTier (optional): one of tier1, tier2, tier3
• trustTier (optional, deprecated alias): one of tier1, tier2, tier3
• stockVariantTier (optional): one of share_redeemable, cash_redeemable, not_redeemable
• sortBy (optional): liquidity (default), execution_quality, or stock_redeemability
• mint (optional): ensure a specific variant mint is included in the response (even if server-side capping is active).
• variantsMode (optional): set to all to disable server-side capping of large variant sets.

Notes

• Each returned variant includes a market snapshot when available; the server may derive a fallback market snapshot from cached DEX markets.
• Stock-token variants include stockVariantTier when present.
• sortBy=stock_redeemability sorts share_redeemable first, then cash_redeemable, then not_redeemable or missing tiers, with liquidity fallbacks inside each tier.
• trustTier is currently mirrored from liquidityTier for backward compatibility.
• Legacy trustTier=experimental is still accepted and treated as tier3.
• Every row carries advisory (null when the mint is not flagged). Flagged variants, including blocked, are not filtered out here — this is a direct lookup, so the warning must be reachable. See Advisories.
• For assetId=solana, yield variants can be very large; the server may cap the returned yield variant set by default. Use variantsMode=all to request the full set.

Example

curl -sS "$API_BASE_URL/v1/assets/$ASSET_ID/variants?liquidityTier=tier1" \
  -H "x-api-key: $API_KEY"

curl -sS "$API_BASE_URL/v1/assets/spacex/variants?stockVariantTier=share_redeemable&sortBy=stock_redeemability" \
  -H "x-api-key: $API_KEY"

Variant top markets (canonical): GET /v1/assets/:assetId/variant-top-markets

Return the top DEX market for each variant of an asset (best-effort; some variants may have no cached market yet).

• Auth: x-api-key
• Scope: assets:read

Query params

• offset (default 0)
• limit (default 10, clamped to 1–100)
• variantsMode (optional): set to all to disable server-side capping of large variant sets.

Notes

• Results are sorted by market liquidity (descending).
• For assetId=solana, the server may cap the yield variant set by default. Use variantsMode=all to request the full set.

Variant market (single): GET /v1/assets/:assetId/variant-market

Fetch the cached “variant market” snapshot for a single mint of the asset.

• Auth: x-api-key
• Scope: assets:read

Query params

• mint (optional): defaults to the asset’s primary variant mint

Example

curl -sS "$API_BASE_URL/v1/assets/$ASSET_ID/variant-market" \
  -H "x-api-key: $API_KEY"

Markets: GET /v1/assets/:assetId/markets

List cached DEX markets for a mint of the asset.

• Auth: x-api-key
• Scope: assets:read

Query params

• mint (optional): defaults to the asset’s primary variant mint
• offset (default 0)
• limit (default 10, clamped to 1–50)

Notes

• Response includes protocolTokensByMarket for certain pools to help identify protocol-owned tokens.
• This endpoint may trigger background cache warming when markets are missing/stale.

OHLCV (by mint): GET /v1/assets/:assetId/ohlcv

Return OHLCV candles for a specific mint (variant).

• Auth: x-api-key
• Scope: assets:read

Query params

• mint (optional): defaults to primary variant mint
• interval (default 1H): one of 1m, 5m, 15m, 1H, 4H, 1D, 1W
• from / to (unix seconds): default to last 7 days

Notes

• When stale/missing, the server may trigger cache warming.
• Candles are served from Convex/cache only. When source="clickhouse_trades" exists on cached candles internally, the candle was materialized from successful direct USD-stable Solana trades.
• Cached ClickHouse-derived candles can also carry a per-candle tradeCount internally. The public OHLCV response remains backward compatible with the existing OHLCV fields.

Price chart (canonical): GET /v1/assets/:assetId/price-chart

Return canonical price candles.

• Auth: x-api-key
• Scope: assets:read

Behavior

• If the asset has an external listing ID, this endpoint serves external provider candles (and may warm cache).
• For mapped public equities, this endpoint serves canonical ClickHouse stock candles first.
• Otherwise it falls back to mint-based OHLCV using the primary variant (or mint query param).

Profile: GET /v1/assets/:assetId/profile

Return cached external profile/market stats when the asset has an external listing ID.

• Auth: x-api-key
• Scope: assets:read

Notes

• If no external listing ID is available, response includes profile: { ok: false, reason: "not_available" }.
• When stale/missing, the server may trigger background cache warming.

Tickers: GET /v1/assets/:assetId/tickers

Return cached exchange tickers for the canonical asset (when it has an external listing ID).

• Auth: x-api-key
• Scope: assets:read

Query params

• offset (default 0)
• limit (default 10, clamped to 1–50)
• order (optional): accepted values include volume_desc etc; currently served from cached order.

Risk summary/details: GET /v1/assets/:assetId/risk-summary and /risk-details

Return a market-based score derived from cached market snapshots.

• Auth: x-api-key
• Scope: assets:read

Query params

• mint (optional): defaults to primary variant mint

Notes

• risk-details includes more inputs in the response (for debugging/scoring transparency).

Description: GET /v1/assets/:assetId/description

Return a cached per-mint description summary when available.

• Auth: x-api-key
• Scope: assets:read

Query params

• mint (optional): defaults to primary variant mint