🎩 You're Invited:Meet the Socket team at Black Hat in Las Vegas, August 3-6.RSVP →
@starkscan/sdk
Advanced tools
@starkscan/sdk - npm Package Compare versions
+1
-1
| { | ||
| "name": "@starkscan/sdk", | ||
| "private": false, | ||
| "version": "0.1.0-beta.1", | ||
| "version": "0.1.0", | ||
| "description": "TypeScript SDK for the Starkscan Starknet block explorer API.", | ||
@@ -6,0 +6,0 @@ "license": "MIT", |
+58
-118
| # @starkscan/sdk | ||
| TypeScript SDK for the Starkscan Starknet block explorer API. | ||
| TypeScript SDK for the Starkscan Starknet explorer API. | ||
| Status: public beta. Use an exact `0.1.0-beta.x` version for unattended | ||
| agents or production services. | ||
| Status: public `0.1.0` stable release. The npm `latest` tag points to the real | ||
| SDK package. Use the untagged install for normal setup and pin `0.1.0` for | ||
| unattended agents or production services that need reproducible installs. | ||
| ## Install | ||
| Preferred public channel: | ||
| ```bash | ||
| npm install @starkscan/sdk@beta | ||
| npm install @starkscan/sdk | ||
| ``` | ||
| For unattended agents or production services, pin a smoked exact version instead | ||
| of floating on `@beta`. | ||
| Exact pin for unattended services: | ||
| ## What it does | ||
| - Calls the hosted Starkscan REST API with typed responses. | ||
| - Sends `X-Starkscan-Api-Key` and request metadata consistently. | ||
| - Keeps API keys in your process environment or secret manager. | ||
| - Supports agent workflows that need stable JSON, request IDs, and route-class | ||
| headers for debugging. | ||
| ## Trust status | ||
| - npm: <https://www.npmjs.com/package/@starkscan/sdk> | ||
| - public trust docs: <https://starkscan.co/docs/build/package-trust> | ||
| - machine-readable 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 formal Starkscan security | ||
| certificate. Starkscan package promotion also requires packed-tarball smoke, | ||
| manual passkey or Trusted Publishing/OIDC publish control, and the launch gates | ||
| documented at the public package trust page. The canonical source repository is | ||
| private, so public package trust links intentionally point to Starkscan docs | ||
| instead of GitHub. | ||
| Fallback release artifact: | ||
| ```bash | ||
| npm install ./starkscan-sdk-<version>.tgz | ||
| npm install @starkscan/sdk@0.1.0 | ||
| ``` | ||
| ## Minimal example | ||
| The `@beta` tag remains a prerelease channel only. Do not use it for unattended | ||
| production services unless a maintainer explicitly asks you to test a | ||
| prerelease. | ||
| ## First request | ||
| ```ts | ||
@@ -61,6 +39,8 @@ import { createStarkscanClient } from '@starkscan/sdk'; | ||
| `STARKSCAN_API_KEY` is required for protected routes. `STARKSCAN_BASE_URL` is | ||
| only needed when targeting preview or a custom Starkscan host; production should | ||
| use the default `https://api.starkscan.co`. The HTTP client sends | ||
| `X-Starkscan-Api-Key`. | ||
| 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. | ||
@@ -70,25 +50,22 @@ The package is ESM-only and supports Node.js 18 or newer. CommonJS consumers | ||
| ## Migration notes | ||
| ## Why use it | ||
| The public `HttpClient` low-level JSON helpers now require a `JsonResponseValidator` | ||
| when callers want typed responses from `getJson<T>()`, `postJson<T>()`, or | ||
| `putJson<T>()`. Calls without a validator still work, but return `unknown` so | ||
| consumers must narrow the response before use. Prefer the high-level | ||
| `createStarkscanClient()` and explorer API helpers when possible; they attach | ||
| the SDK validators automatically. When using `HttpClient` directly, define your | ||
| own `JsonResponseValidator<T>` and pass it in one of these forms: | ||
| - 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')`. | ||
| ```ts | ||
| await http.getJson<MyEnvelope>(path, undefined, validateMyEnvelope); | ||
| await http.postJson<MyEnvelope>(path, body, validateMyEnvelope); | ||
| await http.putJson<MyEnvelope>(path, body, validateMyEnvelope); | ||
| ``` | ||
| ## Useful reads | ||
| ## Useful calls | ||
| ```ts | ||
| 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, | ||
| }); | ||
| ``` | ||
@@ -99,4 +76,4 @@ | ||
| Starkscan responses expose freshness, exactness, pagination, and truncation | ||
| signals directly in the typed payloads. For agents and unattended services, use | ||
| the helper functions instead of memorizing every endpoint-specific field: | ||
| signals directly. Use helper functions instead of guessing whether a response is | ||
| complete: | ||
@@ -121,74 +98,37 @@ ```ts | ||
| `getCompleteness()` also reports `scanTruncated` when the local helper stops its | ||
| bounded scan early. In that case, `exact` will not be reported as `true` unless | ||
| an inexact signal was already found. | ||
| ## Low-level HTTP client | ||
| Common honesty fields: | ||
| 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. | ||
| - `nextCursor`: non-null means the result is a bounded page and callers should | ||
| paginate before claiming a complete set. | ||
| - `lagBlocks`: indexed data freshness relative to the current chain head. | ||
| - `exact` / `truncated`: explicit exactness and cap signals for indexed | ||
| aggregates such as address token holdings. | ||
| - `metadataCompleteness`: contract metadata is indexed, but some optional | ||
| metadata fields may still be missing. | ||
| - `messagesCoverage.status`: protocol-message coverage is `exact`, `partial`, | ||
| or `unavailable`. | ||
| - `logsTruncated`, `payloadTruncated`, `tokenTransfersTruncated`: detail views | ||
| contain a bounded nested slice. | ||
| - `sourceTier`: item came from `head` or `finalized` indexed data. | ||
| - `confidence`: classification confidence for transfer actions and bridge | ||
| intent; values such as `partial`, `heuristic`, and `unknown` should not be | ||
| reported as exact classifications. | ||
| Per-view honesty map: | ||
| | SDK view or endpoint family | Honesty fields to inspect | | ||
| | --- | --- | | ||
| | `status()` / `liveFeedSnapshot().status` | `lagBlocks`, `latestIndexedBlockNumber`, `finalizedBlockNumber`, `latestL1AcceptedBlockNumber` | | ||
| | `blockTransactions`, `contractEvents`, `addressActivity`, `addressTransactions`, `addressTransfers`, `tokenTransfers`, STRKBTC pages | `nextCursor` | | ||
| | `transaction()` | `logsTruncated`, `messagesCoverage.status`, `messagesCoverage.reasonCode`, `messages[].payloadTruncated`, `messages[].sourceTier`, `bridgeIntent.confidence` | | ||
| | `txDetails()` previews | `logsTruncated`, `tokenTransfersTruncated`, `tokenTransfers[].actionContext.confidence`, `bridgeIntent.confidence` | | ||
| | `addressTokenHoldings()` | `exact`, `truncated` | | ||
| | `contractMetadata()` | `metadataCompleteness` | | ||
| | `addressTransfers()` global transfer rows | `nextCursor`, `items[].sourceTier`, `items[].actionContext.confidence` | | ||
| | `tokenTransfers()` rows | `nextCursor`, `items[].actionContext.confidence` | | ||
| | `search()`, `block()`, `addressSummary()`, contract verification/entrypoint/read/write helpers, token supply/balance helpers | no dedicated honesty flag in the current payload; use thrown validation errors and the surrounding `status()` freshness when needed | | ||
| ## Monitor 10 wallets | ||
| For the canonical multi-wallet starter across REST, SDK, and CLI, use: | ||
| - `/docs/getting-started/monitor-10-wallets` on your deployed Starkscan host | ||
| The SDK flow there covers: | ||
| - `addressActivity` | ||
| - `addressTransactions` | ||
| - `addressTokenHoldings` | ||
| - `tokenTransfers` | ||
| ## Block reads | ||
| Use block reads when the workflow starts from a block number or hash and then drills into canonical block contents: | ||
| ```ts | ||
| const block = await starkscan.block(8279910, 5); | ||
| const txs = await starkscan.blockTransactions(8279910, undefined, 25); | ||
| for (const item of txs.items) { | ||
| console.log(item.txIndex, item.txHash, item.finalityStatus); | ||
| } | ||
| await http.getJson<MyEnvelope>(path, undefined, validateMyEnvelope); | ||
| await http.postJson<MyEnvelope>(path, body, validateMyEnvelope); | ||
| await http.putJson<MyEnvelope>(path, body, validateMyEnvelope); | ||
| ``` | ||
| The hosted SDK does not expose per-block event or receipt pages. Resolve the block transaction list first, then use transaction detail reads for receipt/log context. | ||
| ## Trust and safety | ||
| `block` accepts a block number, block hash, or `"latest"`. `blockTransactions` requires a concrete block number; resolve `"latest"` or a block hash with `block(...)` first, then pass the returned `blockNumber` with `nextCursor`. | ||
| - 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 | ||
| - `beta`: current public prerelease channel after beta publish | ||
| - `alpha`: historical fast-moving prerelease channel; use only when directed | ||
| - `latest`: fail-closed placeholder until a stable release is promoted | ||
| - `latest`: default public `0.1.0` release. | ||
| - `beta`: prerelease channel for explicit tests only. | ||
| - `alpha`: historical prerelease channel; use only when directed during rollback. | ||
| Server-side key tiers still control what each user can access. The package stays the same; entitlements do not. | ||
| Server-side key tiers control route access. The package stays the same; | ||
| entitlements do not. |
No alert changes
Worsened metrics
- Total package byte prevSize
216559
-1.5%- Number of lines in readme file
131
-31.41%No dependency changes