@starkscan/sdk

@starkscan/sdk

TypeScript SDK for the Starkscan Starknet explorer API.

Status: public 0.1.2 stable release. The npm latest tag points to the real SDK package. Use the untagged install for normal setup and pin 0.1.2 for unattended agents or production services that need reproducible installs.

Install

npm install @starkscan/sdk

Exact pin for unattended services:

npm install @starkscan/sdk@0.1.2

Prerelease tags such as @beta are maintainer-directed test channels only. Normal users and agents should use the default package or the exact 0.1.2 pin above.

First request

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

const starkscan = createStarkscanClient({
  apiKey: process.env.STARKSCAN_API_KEY!,
  chainId: 'SN_MAIN',
});

const status = await starkscan.status();
console.log(status.chainId, status.headBlockNumber ?? status.latestIndexedBlockNumber);

The SDK defaults to https://api.starkscan.co, sends X-Starkscan-Api-Key, and uses the same REST contract as the CLI. MCP uses a separate transport: POST https://api.starkscan.co/mcp on the API domain, or POST {appBaseUrl}/api/mcp on app-origin deployments. Set STARKSCAN_BASE_URL only for preview or self-hosted Starkscan hosts, and map STARKSCAN_CHAIN to the SDK chainId option when you want env-driven clients.

The package is ESM-only and supports Node.js 18 or newer. CommonJS consumers should use dynamic import('@starkscan/sdk').

Why use it

• Typed helpers over Starkscan REST routes.
• Centralized API-key and request metadata handling.
• Runtime response validation on high-level client calls.
• Data-honesty helpers for pagination, exactness, lag, and truncation flags.
• Chain-bound clients with withChain('SN_SEPOLIA').

Useful reads

const block = await starkscan.block(8279910, 5);
const txs = await starkscan.blockTransactions(8279910, undefined, 25);
const tx = await starkscan.transaction('0x...');
const activity = await starkscan.addressActivity('0x...');
const holdings = await starkscan.addressTokenHoldings('0x...');
const transfers = await starkscan.tokenTransfers('0xtoken', {
  addresses: ['0xwalletA', '0xwalletB'],
  limit: 100,
});

Data honesty helpers

Starkscan responses expose freshness, exactness, pagination, and truncation signals directly. Use helper functions instead of guessing whether a response is complete:

import { getCompleteness, getLagBlocks, hasMorePages, isExact } from '@starkscan/sdk';

const holdings = await starkscan.addressTokenHoldings('0x...');
const completeness = getCompleteness(holdings);

if (isExact(holdings) === false) {
  console.warn('Holdings are bounded or partial', completeness.flags);
}

if (hasMorePages(await starkscan.addressActivity('0x...'))) {
  console.log('Continue with nextCursor before summarizing totals');
}

const status = await starkscan.status();
console.log('index lag', getLagBlocks(status));

Low-level HTTP client

Prefer createStarkscanClient() for application code. If you use HttpClient directly, generic calls such as getJson<T>(), postJson<T>(), or putJson<T>() return unknown unless you pass a JsonResponseValidator<T>. That keeps network-boundary validation explicit.

await http.getJson<MyEnvelope>(path, undefined, validateMyEnvelope);
await http.postJson<MyEnvelope>(path, body, validateMyEnvelope);
await http.putJson<MyEnvelope>(path, body, validateMyEnvelope);

Trust and safety

• npm package: https://www.npmjs.com/package/@starkscan/sdk
• SDK docs: https://starkscan.co/docs/sdk/typescript
• API docs: https://starkscan.co/docs/api
• Package trust: https://starkscan.co/docs/build/package-trust
• Machine-readable launch matrix: https://starkscan.co/public-client-surface-matrix.json
• Socket signal: https://socket.dev/npm/package/@starkscan/sdk

Socket is an external package-risk signal, not a Starkscan security certificate. The public trust source is Starkscan docs because the canonical engineering repository is private. Package promotion also requires checked release scripts, packed-tarball smoke, npm Trusted Publishing/OIDC for CI publishes, and live API smoke proof.

Release channels

• latest: default public 0.1.2 release.
• beta: prerelease channel for explicit tests only.
• alpha: historical prerelease channel; use only when directed during rollback.

Server-side key tiers control route access. The package stays the same; entitlements do not.