API v1 Overview

Base URL

Use the hosted Tokens API:

• https://api.tokens.xyz/v1

Developers should call Tokens servers directly. You do not deploy your own Tokens API.

If you prefer, you can add your own backend proxy for key management or caching. In that setup, your proxy still calls https://api.tokens.xyz/v1/... upstream.

Public path vs internal implementation

The public contract is /v1/... on api.tokens.xyz.

If you see /api/v1/... in some internal apps, that’s an implementation detail of a proxy/gateway layer (for example, a Next.js app route namespace). External integrations should treat /v1/... as canonical.

What this documentation covers

This section documents the public, stable v1 endpoints only.

Authentication (at a glance)

Most v1 endpoints are Platform API endpoints and require:

• x-api-key: <your_api_key>

Newly created or regenerated dashboard keys can be revealed/copied because they are stored encrypted. Older legacy hash-only keys may not be revealable, but they still authenticate requests and can still run the API Manager Playground while active.

Some endpoints are public or session-authenticated; see Meta endpoints.

Route matrix

Error format (at a glance)

Platform endpoints return errors in a standard JSON envelope:

{
    "error": {
        "_tag": "BadRequestError",
        "message": "mint is required"
    }
}

Status codes you should expect: 400, 401, 403, 404, 429, 500.

What’s possible in v1 right now

v1 is currently focused on assets (canonical asset groups) and variants (chain-specific mints), plus market/risk primitives.

• Discover assets: search by query, then fetch a canonical asset group by assetId.
• Resolve an asset reference to canonical: map a Solana mint / solana-<mint> ref / alias / assetId to its canonical assetId + variant info.
• Group token balances: use the resolved assetId as the grouping key for mints that represent the same asset, such as USD stablecoins or tokenized equities.
• Fallback singleton assets: unknown or ungrouped Solana mints use deterministic IDs of the form solana-<mint>.
• Curated lists: pull paginated curated assets (and optionally group by asset vs mint). The lsts list is backed by the same dynamic Solana yield-variant set used by the variants API, with low-liquidity LST rows filtered by default.
• Market primitives: variant market snapshots, markets list, tickers, and cached trending market rows.
• Canonical volume stats: asset stats can include volume24hUSD and nullable volume30dUSD; use volume30dUSD instead of summing candles yourself when it is populated.
• ClickHouse-derived Solana trade metrics: when cached, variant market snapshots can include metricsSource="clickhouse_trades", 1h/24h volume, trade counts, wallet counts, lastTradeAt, and asOf.
• Charts (OHLCV): canonical price chart and per-mint OHLCV.
• Risk summary: a quick market-based risk/quality score.
• Descriptions: optional cached per-mint summary text (when available).
• News feed: filterable global or token-specific market activity with CoinGecko news and matching @tokens posts.

Endpoint inventory

Meta

• GET /v1/health (public)
• GET /v1/whoami (Clerk session; not API-key)

Assets (collection)

• GET /v1/assets/search
• GET /v1/assets/resolve
• GET /v1/assets/curated
• GET /v1/assets/trending
• POST /v1/assets/market-snapshots
• GET /v1/assets/variant-markets
• GET /v1/assets/risk-summary

Assets (by assetId)

• GET /v1/assets/:assetId
• GET /v1/assets/:assetId/variants
• GET /v1/assets/:assetId/variant-market
• GET /v1/assets/:assetId/markets
• GET /v1/assets/:assetId/tickers
• GET /v1/assets/:assetId/profile
• GET /v1/assets/:assetId/description
• GET /v1/assets/:assetId/risk-summary
• GET /v1/assets/:assetId/risk-details
• GET /v1/assets/:assetId/ohlcv
• GET /v1/assets/:assetId/price-chart

News

• GET /v1/news/feed

Recommended exploration flow

If you’re new, start here:

1. Quickstart
2. Authentication
3. Rate Limits & Errors
4. Assets endpoints
5. Asset-by-id endpoints