API v1
Endpoints at a glance
A quick map of every v1 endpoint, what it does, and what it returns.
Base URL: https://api.tokens.xyz/v1
All Platform endpoints require x-api-key and typically assets:read unless noted.
| Method | Path | Auth | What it does | Returns (top-level) |
|---|---|---|---|---|
| GET | /v1/health | none | Health check | { ok: true } |
| GET | /v1/whoami | Clerk session | First-party session identity | { userId, sessionId, primaryEmail } |
| GET | /v1/assets/search | API key | Search canonical assets | { query, category, results[] } |
| GET | /v1/assets/resolve | API key | Mint → canonical asset mapping | { assetId, asset, variant } |
| GET | /v1/assets/curated | API key | Curated asset lists | { listId, assets[] } |
| POST | /v1/assets/market-snapshots | API key | Batch lookup cached market snapshots | Array<...> |
| GET | /v1/assets/variant-markets | API key | Batch lookup per-mint variant market snapshots | { variants[] } |
| GET | /v1/assets/risk-summary | API key (any of assets:read or assets:risk:read) | Quick risk/quality summary for a mint | { score, grade, label, ... } |
| GET | /v1/assets/:assetId | API key | Canonical asset detail (+ optional includes) | { asset, includes? } |
| GET | /v1/assets/:assetId/variants | API key | List asset variants (+ per-variant market) | { assetId, variants[] } |
| GET | /v1/assets/:assetId/variant-market | API key | Variant market snapshot for one mint | { assetId, mint, market, lastUpdatedAt } |
| GET | /v1/assets/:assetId/markets | API key | DEX markets for one mint | { assetId, mint, markets[], protocolTokensByMarket, ... } |
| GET | /v1/assets/:assetId/ohlcv | API key | Mint OHLCV candles | { assetId, mint, interval, from, to, candles[] } |
| GET | /v1/assets/:assetId/price-chart | API key | Canonical price candles (external provider when available) | { assetId, interval, from, to, candles[] } |
| GET | /v1/assets/:assetId/profile | API key | Asset profile + stats (external provider when available) | { assetId, profile } |
| GET | /v1/assets/:assetId/tickers | API key | Exchange tickers (external provider when available) | { assetId, tickers } |
| GET | /v1/assets/:assetId/description | API key | Cached per-mint description summary | { assetId, mint, description } |
| GET | /v1/assets/:assetId/risk-summary | API key | Risk summary (simple) for a mint of the asset | { assetId, mint, risk } |
| GET | /v1/assets/:assetId/risk-details | API key | Risk summary (detailed inputs) for a mint | { assetId, mint, risk } |
Notes:
- Many endpoints are backed by cached upstream data. Some responses include
lastUpdatedAtor may return empty arrays/nulls when data isn’t cached yet. - Some endpoints trigger best-effort cache warming in the background.