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.

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.