API v1Endpoints

Asset by ID

Endpoints under /assets/:assetId for variants, markets, OHLCV, and more.

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.
  • 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 or clickhouse_stock. clickhouse_stock is used for mapped public equities. Passing mint keeps variant-specific include computations, including include=ohlcv, on the on-chain mint.
  • 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"
    }
}

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.
  • 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

Assets (collection)

Search, curated lists, mint resolution, snapshots, and aggregate risk.

News feed

Filterable market news and @tokens posts for global or token-specific feeds.

On this page

Asset (canonical or singleton): GET /v1/assets/:assetIdQuery paramsohlcv paramsmarkets paramsNotesExampleVariants: GET /v1/assets/:assetId/variantsQuery paramsNotesExampleVariant top markets (canonical): GET /v1/assets/:assetId/variant-top-marketsQuery paramsNotesVariant market (single): GET /v1/assets/:assetId/variant-marketQuery paramsExampleMarkets: GET /v1/assets/:assetId/marketsQuery paramsNotesOHLCV (by mint): GET /v1/assets/:assetId/ohlcvQuery paramsNotesPrice chart (canonical): GET /v1/assets/:assetId/price-chartBehaviorProfile: GET /v1/assets/:assetId/profileNotesTickers: GET /v1/assets/:assetId/tickersQuery paramsRisk summary/details: GET /v1/assets/:assetId/risk-summary and /risk-detailsQuery paramsNotesDescription: GET /v1/assets/:assetId/descriptionQuery params