Quickstart

You need an API key from the dashboard. Keep it on your server; the examples below read it from an environment variable.

export API_BASE_URL="https://api.tokens.xyz"
export API_KEY="..."

Every request sends the key in the x-api-key header. POST requests also send Content-Type: application/json.

1. Check the API is upCopy Anchor Link

The health route needs no key:

curl -sS "$API_BASE_URL/v1/health"

{ "ok": true }

2. Search for an assetCopy Anchor Link

curl -sS "$API_BASE_URL/v1/assets/search?q=bitcoin&limit=5" \
  -H "x-api-key: $API_KEY"

Each result is a canonical asset with its assetId, aggregate stats, and the primaryVariant (the Solana mint the API would route to). Reference: Search and resolve.

3. Resolve what the user gave youCopy Anchor Link

Start from an assetId, an alias or a raw mint and get back the registered asset:

curl -sS "$API_BASE_URL/v1/assets/resolve?ref=btc" \
  -H "x-api-key: $API_KEY"

MINT="EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
curl -sS "$API_BASE_URL/v1/assets/resolve?mint=$MINT" \
  -H "x-api-key: $API_KEY"

The USDC mint resolves to assetId: "usd". A mint that is not a variant of a registered asset returns 404 with details.code: "asset_not_registered"; see Registered assets only.

4. Read one asset with includesCopy Anchor Link

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

The response carries the asset and an includes map. Each include is best-effort: { ok: true, data } or { ok: false, reason, message }, so render what is available. Reference: Asset detail.

5. List the asset's variantsCopy Anchor Link

curl -sS "$API_BASE_URL/v1/assets/usd/variants" \
  -H "x-api-key: $API_KEY"

Every Solana mint that represents the asset, each with its own market snapshot and advisory. Reference: Variants and markets.

6. Score a mintCopy Anchor Link

curl -sS "$API_BASE_URL/v1/assets/risk-summary?mint=$MINT" \
  -H "x-api-key: $API_KEY"

Check hasInsufficientData before you show the grade. Reference: Risk.

NextCopy Anchor Link

• Assets and variants explains the two ids you just used.
• Workflows chains these calls into search pages, wallet grouping and watchlists.
• Authentication covers scopes and key safety.
• Errors and limits covers the error envelope and retries.