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>

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 assets) and variants (chain-specific mints), plus market/risk primitives.

• Discover assets: search by query, then fetch a canonical asset by assetId.
• Resolve an asset reference to canonical: map a Solana mint / alias / assetId to its canonical assetId + variant info.
• Curated lists: pull curated assets (and optionally group by asset vs mint).
• Market primitives: variant market snapshots, markets list, tickers.
• 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).

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

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