Workflows

These recipes show which endpoints to call in which order. Parameter and response details are in the reference pages linked from each step.

Search box to asset pageCopy Anchor Link

1. Search as the user types:

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

2. On selection, fetch the asset with the blocks the page needs:

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

Includes are independent and best-effort, so render each block from its own ok flag. Reference: Search and resolve, Asset detail.

Any reference to a canonical assetCopy Anchor Link

Wallet holdings, swap inputs and on-chain events give you mints; users give you tickers and names. resolve accepts all of them:

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

Branch on the status:

• 200: use assetId for everything downstream. resolvedBy tells you how the match was made.
• 404 with details.code: "asset_not_registered": the mint is not a variant of a registered asset. Expect this branch for wallet contents. Keep the token as its own row, or track it through a Token List in API v2.

Group wallet balances by assetCopy Anchor Link

Resolve each mint and use the returned assetId as the grouping key, so USDC, USDT and PYUSD roll up into usd and the Tesla tokens into tesla. When you need the other mints in a group, list them:

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

Balances whose mint returned 404 have no grouping asset in v1. Reference: Variants and markets.

Watchlist snapshots for many mintsCopy Anchor Link

Two batch endpoints return one row per input mint, in input order, and never fail on an unregistered mint:

• GET /v1/assets/variant-markets?mints=... for up to 50 mints in the query string. Unregistered mints come back with assetId, chain, market and executionQuality set to null.
• POST /v1/assets/market-snapshots with a JSON body for up to 250 mints. Unregistered mints come back as token: null, hasMarket: false.

curl -sS "$API_BASE_URL/v1/assets/market-snapshots" \
  -H "x-api-key: $API_KEY" \
  -H "content-type: application/json" \
  -d '{"mints":["MINT1","MINT2","MINT3"]}'

Both return per-mint figures. Canonical figures for the asset as a whole (reference price, market cap, canonical supply) are on asset detail. Reference: Batch snapshots.

"Where can I trade this?"Copy Anchor Link

1. DEX markets for a mint of the asset:

curl -sS "$API_BASE_URL/v1/assets/$ASSET_ID/markets?limit=20" \
  -H "x-api-key: $API_KEY"

2. Centralised exchange tickers, when the asset has an external listing:

curl -sS "$API_BASE_URL/v1/assets/$ASSET_ID/tickers?limit=20" \
  -H "x-api-key: $API_KEY"

To compare the asset's variants at a glance, GET /v1/assets/{assetId}/variant-top-markets returns the best market per variant. Reference: Variants and markets.

A one-year chartCopy Anchor Link

NOW=$(date +%s)
curl -sS "$API_BASE_URL/v1/assets/$ASSET_ID/price-chart?interval=1D&from=$((NOW - 365*86400))&to=$NOW" \
  -H "x-api-key: $API_KEY"

price-chart serves the canonical series for the asset (stock-market candles for equities, provider candles for listed crypto) and falls back to the primary variant's on-chain candles. Use /ohlcv?mint= when you want one specific token. Always pass from for anything other than the default week. Reference: Charts.

A risk badge for a mintCopy Anchor Link

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

• 404 asset_not_registered: no score exists and retrying will not change that. Show no badge or an "unlisted" state.
• 200 with hasInsufficientData: true: the token is unscored and grade is a placeholder. Show "Insufficient data", not the grade.
• Otherwise show grade and label, and caps as the reasons the score was limited.

For stablecoins, pair the badge with pegHealth from GET /v1/assets/{assetId}/risk-summary. Reference: Risk.

Honour advisoriesCopy Anchor Link

Every variant object you receive carries advisory. Before enabling a trade action, check it:

const advisory = variant.advisory;
if (advisory?.status === 'compromised' || advisory?.status === 'blocked') {
  disableTrading(advisory.reason, advisory.url);
}

Direct lookups never hide a flagged mint, so a shared link always lands on the warning. Details: Advisories.