Tokens and Market Data

Every operation on this page is anonymous. No API key, no scope, no wallet. They are public reads and they are cached at the edge. All of them except the two wallet reads support conditional requests.

Operation	HTTP	SDK
`listTokens`	`GET /tokens`	`blank.tokens.list()` / `blank.tokens.iterate()`
`getToken`	`GET /tokens/{mint}`	`blank.tokens.get(mint)`
`getTokenMarketSnapshot`	`GET /tokens/{mint}/market`	`blank.marketData.snapshot(mint)`
`listTokenCandles`	`GET /tokens/{mint}/candles`	`blank.marketData.candles(mint, query)`
`listTokenTrades`	`GET /tokens/{mint}/trades`	`blank.marketData.trades(mint, query)`
`getTokenHolderStats`	`GET /tokens/{mint}/holders`	`blank.marketData.holders(mint)`
`listWalletTrades`	`GET /wallets/{address}/trades`	`blank.wallets.trades(address, query)`
`listWalletHoldings`	`GET /wallets/{address}/holdings`	`blank.wallets.holdings(address)`

Setup

import { BlankClient } from "@blankdotbuild/sdk";

const blank = new BlankClient();

The base URL defaults to https://api.blank.build/api/v2. Every call returns { data, metadata, response }, and metadata.requestId is the X-Request-Id you should log alongside failures.

Numbers are strings

Every monetary value, price, and amount is a canonical decimal string. Raw on-chain amounts are unsigned integer strings. Nothing is a JSON number, so nothing loses precision in transit.

Do not parse these with Number or parseFloat. Token supplies and lamport amounts exceed the safe integer range, and binary floats cannot represent decimal prices exactly. Use a decimal library, or BigInt for raw integer strings.

Integer counts (holderCount, activeStakers, trades, rank) and token decimals are real JSON numbers. Timestamps are RFC 3339 strings.

List tokens

Returns tokens in reverse launch order.

const { data } = await blank.tokens.list({ status: "bonding", limit: 25 });

for (const token of data.data) {
  console.log(token.symbol, token.currentPriceInSol);
}

Query	Type	Notes
`cursor`	string	Opaque. Pass back `page.nextCursor` verbatim.
`limit`	integer	1–100. Defaults to 50.
`status`	`TokenStatus`	Filter by lifecycle status.
`launchType`	`dbc` \| `pre_raise`	Filter by launch mechanism.
`creator`	string	Only tokens launched by this creator wallet.

The response is { data: [...], page: { nextCursor, hasMore } }. See Conventions for the full pagination contract.

Token fields

Field	Type	Notes
`mintAddress`	string	The token mint.
`name`	string
`symbol`	string
`description`	string \| null
`imageUrl`	string \| null
`status`	`TokenStatus`	See below.
`launchType`	`dbc` \| `pre_raise`
`creatorWallet`	string
`currentPriceInSol`	decimal string
`solCollectedInSol`	decimal string
`totalSupply`	decimal string
`launchedAt`	RFC 3339
`graduatedAt`	RFC 3339 \| null	Null until graduation completes.
`decimals`	integer	Mint decimals. Every Blank mint uses 6.
`marketCapInSol`	decimal string	`currentPriceInSol` × `totalSupply`, the same value as the market snapshot’s `marketCapInSol`.
`links`	object	`website`, `twitter`, `telegram`. See below.

Token links

links holds the creator’s website, X and Telegram links as https URLs. Each is null when the creator left it empty or entered something that is not a valid link. A bare X handle becomes https://x.com/<handle> and a bare Telegram handle becomes https://t.me/<handle>. A website that is not an https:// URL is null. To list every token one creator launched, pass creator:

const { data } = await blank.tokens.list({ creator: creatorWallet });

for (const token of data.data) {
  console.log(token.symbol, token.marketCapInSol, token.links.twitter);
}

TokenStatus

pending, pending_launch_init, pending_escrows, pending_finalization, bonding, pre_raise_pending, pre_raising, pre_raise_settling, pre_raise_refunding, pre_raise_failed, graduating_migration_pending, graduated, graduation_failed, expired, cancelled, failed. Treat this as an open enum in your own code. Match the statuses you care about and fall through on the rest.

Get one token

const { data: token } = await blank.tokens.get(mint);

Same fields as the list entries. Unknown mints return 404 token_not_found. To learn about new launches without polling, subscribe a webhook endpoint to build.blank.launch.created.v1 or build.blank.launch.confirmed.v1. Their data is this same Token object. See Webhooks.

Paginate the full set

blank.tokens.iterate() handles cursors for you and yields tokens one at a time. maxPages is a required safety bound in practice — it defaults to 100 and throws if the walk runs past it.

const graduated: string[] = [];

for await (const token of blank.tokens.iterate(
  { status: "graduated", limit: 100 },
  { maxPages: 5 }
)) {
  graduated.push(token.mintAddress);
}

Market snapshot

The current price, cap, and liquidity for one token.

const { data: market } = await blank.marketData.snapshot(mint);

Field	Type
`mintAddress`	string
`priceInSol`	decimal string
`marketCapInSol`	decimal string
`liquidityInSol`	decimal string
`totalSupply`	decimal string
`holderCount`	integer \| null
`asOf`	RFC 3339
`provenance`	`"blank-indexer"`

asOf is when the indexer computed the snapshot, not when you called. Show it if your UI implies live pricing.

Candles

const { data: series } = await blank.marketData.candles(mint, {
  from: "2026-08-01T00:00:00Z",
  to: "2026-08-02T00:00:00Z",
  interval: "1h",
});

from, to, and interval are all required. Timestamps are RFC 3339 with an offset, and from must be strictly before to. The range is half-open: from is inclusive, to is exclusive. Intervals: 1m, 5m, 15m, 1h, 4h, 1d. The CandleSeries response carries data, interval, from, to, and provenance ("blank-indexer"). Each candle has time, open, high, low, close, volumeInSol (decimal strings) and trades (integer).

A series is capped at 1000 candles. A window that would exceed the cap, or that is otherwise out of range, returns 422 market_time_range_invalid. Split long ranges into consecutive windows, or step up to a coarser interval.

Trades

Newest first, cursor paginated with cursor and limit.

const { data } = await blank.marketData.trades(mint, { limit: 50 });

Field	Type
`id`	uuid
`type`	`buy` \| `sell`
`traderWallet`	string
`mintAddress`	string
`tokenAmount`	decimal string
`solAmount`	decimal string
`pricePerTokenInSol`	decimal string
`transactionSignature`	string
`slot`	numeric string \| null
`blockTime`	RFC 3339

To get new trades pushed instead of polling, subscribe a webhook endpoint to build.blank.trade.confirmed.v1. Its data is this same Trade object. See Webhooks.

A wallet’s trades

Every indexed trade a wallet made across visible Blank tokens, newest first. Pass mint to narrow it to one token.

const { data } = await blank.wallets.trades(walletAddress, { mint, limit: 50 });

for (const trade of data.data) {
  console.log(trade.mintAddress, trade.type, trade.solAmount);
}

Each item has the same fields as Trades; mintAddress tells you which token it was. A wallet with no trades, or a mint that is unknown or hidden, returns 200 with an empty page, never 404. Cursor paginated with cursor and limit; a cursor is bound to the wallet and mint it was issued for.

A wallet’s holdings

The Blank tokens a wallet holds right now, highest value first.

const { data } = await blank.wallets.holdings(walletAddress);

for (const holding of data.data) {
  console.log(holding.symbol, holding.amountRaw, holding.valueInSol);
}

Balances come from chain, not from the trade index: the Worker reads every SPL Token and Token-2022 account the wallet owns, sums the balance per mint, drops zero balances, and keeps only visible Blank tokens. Transfers and airdrops therefore show up even though they are not trades.

Field	Type	Notes
`mintAddress`	string
`symbol`	string
`name`	string
`imageUrl`	string \| null
`amountRaw`	unsigned integer string	Base units, summed across the wallet’s token accounts.
`decimals`	integer	Every Blank mint uses 6.
`valueInSol`	decimal string	`amountRaw` / 10^`decimals` × the token’s current price in SOL.

The response is { data: [...], asOf }, where asOf is when the balances were read. It is not paginated and holds at most 500 holdings, sorted by valueInSol descending, then by mint. A wallet without Blank tokens returns an empty data. When the chain read fails the operation returns 503 market_data_unavailable rather than a partial list. Results are cached for 15 seconds per wallet.

Holder stats

const { data: holders } = await blank.marketData.holders(mint);

Returns mintAddress, holderCount (integer), slot (numeric string or null), asOf, and provenance. provenance tells you how the count was derived: live_trade_index (running index, freshest), trade_replay (rebuilt from trade history), or onchain_snapshot (read from chain state). A token with no computed stats returns 404 holder_stats_not_found.

Caching and conditional requests

Every response except the two wallet reads carries an ETag. Send it back as If-None-Match and you get 304 Not Modified with no body when nothing changed.

Operation	`Cache-Control`
`listTokens`, `getToken`	`public, max-age=10, stale-while-revalidate=30`
`getTokenMarketSnapshot`	`public, max-age=2, stale-while-revalidate=10`
`listTokenCandles`	`public, max-age=30, stale-while-revalidate=120`
`listTokenTrades`	`public, max-age=2, stale-while-revalidate=10`
`getTokenHolderStats`	`public, max-age=10, stale-while-revalidate=30`
`listWalletTrades`	`public, max-age=10, stale-while-revalidate=30`
`listWalletHoldings`	`public, max-age=15, stale-while-revalidate=30`

Polling faster than max-age gains you nothing but rate-limit budget. Candles and wallet holdings use the public-read-expensive rate policy; the others use public-read-cheap. Both are documented in Conventions.

curl -sS -D - -o /dev/null \
  -H 'If-None-Match: "8SdM3s0Xh2Q0oRr1kq8m3wYt7vB2cN5pL9aZ1fJ4uKk"' \
  https://api.blank.build/api/v2/tokens/So11111111111111111111111111111111111111112/market

No Authorization header — these endpoints are anonymous, so this request is safe to make from anywhere.

Errors

Code	Status	Meaning
`cursor_invalid`	400	The cursor is malformed or no longer valid. Restart the walk.
`token_not_found`	404	No public token exists for that mint.
`holder_stats_not_found`	404	The token exists, but no holder snapshot has been indexed.
`market_time_range_invalid`	422	The candle window is out of range.
`token_index_unavailable`	503	The token index is temporarily unavailable. Retry.
`market_data_unavailable`	503	Market data, or a wallet’s on-chain balances, is temporarily unavailable. Retry.

Full problem-details shape and retry guidance live in Errors.

Fees — fee state and distribution history.
Staking — pools, leaderboards, positions.
Conventions — pagination, rate limits, idempotency.

Start Here

Features

For Developers

Reference

API Reference

Endpoints

Tokens and Market Data

Tokens and Market Data

Setup

Numbers are strings

List tokens

Token fields

Token links

TokenStatus

Get one token

Paginate the full set

Market snapshot

Candles

Trades

A wallet’s trades

A wallet’s holdings

Holder stats

Caching and conditional requests

Errors

Next

​Tokens and Market Data

​Setup

​Numbers are strings

​List tokens

​Token fields

​Token links

​TokenStatus

​Get one token

​Paginate the full set

​Market snapshot

​Candles

​Trades

​A wallet’s trades

​A wallet’s holdings

​Holder stats

​Caching and conditional requests

​Errors

​Next

Tokens and Market Data

Setup

Numbers are strings

List tokens

Token fields

Token links

TokenStatus

Get one token

Paginate the full set

Market snapshot

Candles

Trades

A wallet’s trades

A wallet’s holdings

Holder stats

Caching and conditional requests

Errors

Next