Prepared staking API

Starkscan serves staking from a prepared, finalized read model. Requests do not call an RPC provider, scan raw events, fetch historical prices, or enumerate the complete chain at request time. Every response declares source: finalized_prepared_staking_snapshot and typed coverage.

Routes

Use these plural canonical routes. Singular /staking/validator... paths are compatibility surfaces and are not the preferred client contract.

Paged routes default to limit=25 and cap it at 100. nextCursor is opaque: pass it back unchanged and restart pagination when filters change.

The validator directory is ordered across the complete prepared snapshot by exact STRK stake descending, with unavailable STRK amounts last and stable address/generation ties. This is not cross-asset staking power: BTC and other assets are never added to STRK. Cursors bind the ordering and snapshot; restart when a cursor expires.

The directory refuses snapshots exceeding its 4,096-validator ranking bound with HTTP 503, code staking_directory_capacity_exceeded, and Retry-After: 60 rather than returning a partially ranked population. This requires operator review; retrying does not expand capacity. Invalid cursor anchors return HTTP 400, not an empty end-of-directory page.

Validator names may come from reviewed public identity metadata, separately from finalized protocol facts. The mainnet registry records full validator (not pool or reward) addresses, source links, and review dates. Names and logos are not ownership verification or endorsements. Unknown identities remain unlabeled in the API; the frontend shows “Unknown validator” and the address. Commission, balances, APR and liveness are never imported from a public name directory.

Coverage is part of the result

coverage.status is prepared, catching_up, or unavailable. Inspect reasonCode, materializedThroughBlock, sourceLatestFinalizedBlock, lagBlocks, gapIntervals, outstandingMaterializationIntervals, metricDefinitionVersion, and lastSuccessfulRunAtIso before making a completeness claim.

All staking facts are finalized-only. A successful HTTP response does not turn catching_up, a declared gap, or an unavailable metric into complete data.

Amounts, ratios, and unavailable metrics

• Token amounts are decimal raw-unit strings. Apply the accompanying decimals only for display.
• Ratios are exact { numeratorRaw, denominatorRaw } values. Do not convert to floating point before business logic.
• A null liveness, effectiveness, concentration, reward, or stake value is not zero. Read its adjacent metricValueReason, liveness reason, accounting reason, or yield reason.
• tokensTruncated, addressHistoryTruncated, and positionsTruncated are explicit bounds, not display hints.
• Reward accounting can be unavailable when stake-time coverage, reward-token scope, or position history is incomplete.

TypeScript SDK

import { createExplorerApi } from '@starkscan/sdk';

const api = createExplorerApi({
  baseUrl: 'https://api.starkscan.co',
  apiKey: process.env.STARKSCAN_API_KEY,
});

const summary = await api.getStakingSummary('SN_MAIN');
if (summary.coverage.status !== 'prepared') {
  throw new Error(`staking coverage: ${summary.coverage.reasonCode}`);
}

const page = await api.getStakingValidators('SN_MAIN', undefined, 25);

The SDK also provides getStakingValidator, getStakingDelegators, getStakingActivity, and getStakingAddress. It validates the prepared source, coverage shape, raw integer strings, and mutually exclusive call-path availability states.

Use the API reference for exact schemas and API discovery for the current caller-specific route and rate-limit contract.