openapi: 3.1.0 info: title: Starkscan Explorer API version: 2.1.0 description: Starkscan public explorer contract for external integrators, SDKs, CLI workflows, and direct API integrations, including beta Privacy Pool activity, evidence, metrics, and finalized public-flow routes. Operation-level certification and stability metadata define the support boundary. servers: - url: https://api.starkscan.co description: Hosted external Starkscan API base. Requests execute against /v1/* on the API host; app-host /api/v1/* remains compatibility. security: - StarkscanApiKey: [] paths: /v1/{chain}/verification-jobs: post: operationId: createVerificationJob summary: Create an asynchronous exact-source verification job description: Creates one workspace-owned SN_MAIN job from bounded Package V1 metadata. Source bytes are uploaded separately and never stored in PostgreSQL. Requires the verify scope and an Idempotency-Key. Other chain values fail closed until they have their own canonical data-owner controller. parameters: - $ref: "#/components/parameters/ChainParam" - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 pattern: ^[A-Za-z0-9_.:-]{1,128}$ example: verify_release_20260908 - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/VerificationPackageV1" example: selectedClassHash: "0x1234" uploadDigest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef uploadByteLength: 4096 toolchainPolicyId: starkscan-exact-v25 packageName: privacy_pool buildProfile: release targetName: privacy_pool targetKind: starknet-contract artifactId: privacy_pool_contract modulePath: privacy_pool::PrivacyPool sourceVisibility: private retentionPolicyId: private-24h-v1 responses: "200": description: Idempotent replay of the existing job content: application/json: schema: $ref: "#/components/schemas/VerificationJob" "202": description: Job created content: application/json: schema: $ref: "#/components/schemas/VerificationJob" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "413": description: Verification Package V1 metadata exceeds the 64 KiB request-body limit. headers: X-Request-Id: $ref: "#/components/headers/RequestId" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: verify security: - StarkscanApiKey: [] tags: - Verification /v1/{chain}/verification-jobs/{job_id}: get: operationId: getVerificationJob summary: Read an owner-visible verification job parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/VerificationJobId" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Current append-only job state content: application/json: schema: $ref: "#/components/schemas/VerificationJob" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": $ref: "#/components/responses/NotFound" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: verify security: - StarkscanApiKey: [] tags: - Verification /v1/{chain}/verification-jobs/{job_id}/source: put: operationId: uploadVerificationSource summary: Stream the exact source archive to private quarantine description: Requires an exact Content-Length matching Package V1. The body is hashed while streaming to encrypted private object storage and is never buffered into PostgreSQL. parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/VerificationJobId" - name: Content-Length in: header required: true schema: type: integer minimum: 1 maximum: 67108864 example: 4096 - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/gzip: schema: type: string format: binary maxLength: 67108864 responses: "200": description: Idempotent replay of the already accepted upload content: application/json: schema: $ref: "#/components/schemas/VerificationJob" "202": description: Upload committed and job queued content: application/json: schema: $ref: "#/components/schemas/VerificationJob" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "411": description: Exact Content-Length is required headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "413": description: Verification bundle exceeds the 64 MiB request-body limit. headers: X-Request-Id: $ref: "#/components/headers/RequestId" "415": description: Content-Type must be application/gzip and Content-Encoding must be absent headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": description: Body length or digest differs from Package V1 headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/VerificationUploadRateLimited" "503": $ref: "#/components/responses/VerificationUploadServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: verify security: - StarkscanApiKey: [] tags: - Verification /v1/{chain}/verification-jobs/{job_id}/cancel: post: operationId: cancelVerificationJob summary: Request best-effort cancellation description: Cancellation wins before receipt admission; an already admitted immutable receipt wins a race with cancellation. parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/VerificationJobId" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Cancellation recorded or terminal state returned content: application/json: schema: $ref: "#/components/schemas/VerificationJob" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": $ref: "#/components/responses/NotFound" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: verify security: - StarkscanApiKey: [] tags: - Verification /v1/{chain}/verification-jobs/{job_id}/receipt: get: operationId: getVerificationReceipt summary: Download a portable signed exact-verification receipt parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/VerificationJobId" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Ed25519-signed source-free mainnet receipt content: application/json: schema: $ref: "#/components/schemas/HostedPortableVerificationReceipt" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": $ref: "#/components/responses/NotFound" "409": $ref: "#/components/responses/Conflict" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: verify security: - StarkscanApiKey: [] tags: - Verification /v1/{chain}/staking: get: operationId: getStakingSummary summary: Prepared finalized staking summary description: DB-only prepared staking facts; no RPC, provider, raw-event, historical-price, or request-time complete-set scan. externalDocs: description: Prepared staking integration and coverage guide url: https://starkscan.co/docs/api/staking parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Prepared summary with typed coverage content: application/json: schema: $ref: "#/components/schemas/StakingSummaryPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /v1/{chain}/staking/metrics/series: get: operationId: getStakingMetricSeries summary: Finalized staking stock history description: Per-asset end-of-bucket staking stock from sealed prepared snapshots, extended before the first snapshot by source-anchored replayed validator self/delegated position activity on SN_MAIN. sourceKind distinguishes each point. Pool-member balances are not counted twice. Omitting token returns every asset within the 20000-row fail-closed bound. Hourly responses require token; all-time responses require week granularity; unfiltered YTD requires week granularity. stakedInRaw and stakedOutRaw are net stock-change components, not gross deposits and withdrawals. Exit intent does not remove stake. Historical USD valuation uses an exact direct provider quote no later than the effective boundary (bucket end for completed buckets, request time for an in-progress bucket) and is null when unavailable; current prices and underlying-token estimates are never substituted. No request-time chain or provider call is made. parameters: - $ref: "#/components/parameters/ChainParam" - name: range in: query schema: type: string enum: - 30d - 90d - ytd - all default: 30d - name: granularity in: query schema: type: string enum: - hour - day - week default: day - name: token in: query schema: type: string description: Optional canonical staking-token address. Omit for bounded day/week multi-asset series, including all-time at week granularity. - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Bounded staking series with typed history and materialization coverage content: application/json: schema: $ref: "#/components/schemas/StakingMetricSeriesPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /v1/{chain}/staking/validators: get: operationId: listStakingValidators summary: Page prepared finalized validators description: Snapshot-wide exact STRK stake descending, unavailable STRK stake last, with stable address/generation ties. Other assets are not added to STRK or treated as staking power. Cursors bind this order and snapshot; restart after a cursor-expired response. Invalid anchors are rejected. Snapshots above the 4096-validator ranking bound fail closed rather than return a partial ranking. Names may be reviewed public metadata rather than on-chain facts and are not endorsements. parameters: - $ref: "#/components/parameters/ChainParam" - name: cursor in: query schema: type: string maxLength: 1024 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Bounded keyset page content: application/json: schema: $ref: "#/components/schemas/StakingValidatorPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/StakingDirectoryCapacityExceeded" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /v1/{chain}/staking/validators/{address}: get: operationId: getStakingValidator summary: Prepared validator detail with per-token pools and address histories parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true example: "0x0123456789abcdef" schema: type: string - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Prepared validator detail content: application/json: schema: $ref: "#/components/schemas/StakingValidatorDetail" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": $ref: "#/components/responses/NotFound" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /v1/{chain}/staking/validators/{address}/liveness: get: operationId: listStakingValidatorLiveness summary: Page exact finalized per-epoch validator liveness evidence description: DB-only, snapshot-pinned eligible duties. Missing or unavailable eligibility is never emitted as a miss. Cursors bind the prepared snapshot, validator, exact-liveness coverage revision, and rolling coverage cutoff; a coverage change expires the cursor even before a new prepared snapshot is published. parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true example: "0x0123456789abcdef" schema: type: string - name: cursor in: query schema: type: string maxLength: 1024 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Exact finalized per-epoch evidence page content: application/json: schema: $ref: "#/components/schemas/StakingLivenessHistoryPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /v1/{chain}/staking/validators/{address}/delegators: get: operationId: listStakingDelegators summary: Page prepared finalized delegators parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true example: "0x0123456789abcdef" schema: type: string - name: cursor in: query schema: type: string maxLength: 1024 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Bounded delegator page content: application/json: schema: $ref: "#/components/schemas/StakingDelegatorPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /v1/{chain}/staking/activity: get: operationId: listStakingActivity summary: Page prepared transaction-linked staking activity parameters: - $ref: "#/components/parameters/ChainParam" - name: validator in: query schema: type: string - name: cursor in: query schema: type: string maxLength: 1024 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Bounded activity page content: application/json: schema: $ref: "#/components/schemas/StakingActivityPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /v1/{chain}/staking/address/{address}: get: operationId: getAddressStaking summary: Prepared address staking positions and history parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true example: "0x0123456789abcdef" schema: type: string - name: cursor in: query schema: type: string maxLength: 1024 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Prepared positions and bounded history content: application/json: schema: $ref: "#/components/schemas/StakingAddressView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read security: - StarkscanApiKey: [] tags: - Reference /.well-known/starkscan-agent.json: get: summary: Agent-readable Starkscan memory contract description: |- Public machine-readable discovery document for agents. It points agents at the authenticated meta routes, route families, operating rules, and typed artifact contract without requiring chat history. servers: - url: / description: Same-host public well-known discovery root security: - {} responses: "200": description: Agent-readable discovery and operating contract content: application/json: schema: $ref: "#/components/schemas/AgentMemoryContract" x-starkscan-audience: public-core x-starkscan-certification: certified x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: public parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/meta/capabilities: get: summary: Agent-readable API capabilities description: Authenticated route-family catalog for agents and developers. Hosted external clients call `/v1/meta/capabilities` with `X-Starkscan-Api-Key`. Same-origin explorer traffic uses this `/v1` route through the trusted edge. Use this before selecting the smallest route set for a task. A chain-specific token-holder registry is omitted with `policy_registry_chain_mismatch` when it does not match the deployment's default chain. externalDocs: description: Discovery workflow and published JSON Schema url: https://starkscan.co/docs/api/discovery security: - StarkscanApiKey: [] responses: "200": description: Capability and route-family catalog content: application/json: schema: $ref: "#/components/schemas/MetaCapabilitiesView" examples: trustedSameOrigin: summary: Bounded representative trusted same-origin response without credential identity value: kind: starkscan.meta.capabilities schemaVersion: '2026-08-17' defaultChain: SN_MAIN authHeader: X-Starkscan-Api-Key externalBasePath: /v1 firstCalls: - method: GET path: /v1/meta/chains purpose: Discover supported chains. documentation: &a1 openapiUrl: https://starkscan.co/starkscan-openapi.yaml openapiPath: /starkscan-openapi.yaml openapiFormat: OpenAPI 3.1 operationReferenceFormat: URI-encoded JSON Pointer fragment operationLookup: Percent-decode the URI fragment once, then resolve the JSON Pointer in the fetched OpenAPI document. rateLimit: &a2 responseHeaders: routeClass: X-Starkscan-Route-Class limit: x-ratelimit-limit remaining: x-ratelimit-remaining policy: x-ratelimit-policy retryAfter: Retry-After classes: - light - heavy - batch operationDisclosure: Route-family operations disclose their response rate-limit class for class-specific backoff. retryRule: On 429, honor Retry-After before retrying the same route class; rate limits are not credential revocation. routeFamilies: - name: status tier: read routes: - GET /v1/{chain}/status operations: - method: GET path: /v1/{chain}/status openapiPath: /v1/{chain}/status openapiMethod: get openapiOperationRef: "#/paths/~1v1~1%7Bchain%7D~1status/get" rateLimitClass: light summary: Read bounded service and indexing status. useWhen: Check service readiness and indexed progress. sessionControl: &a3 status: separate_dashboard_session_control_plane pathPrefix: /v1/me apiKeyAccess: not_supported safeReadAuth: - better_auth_session_cookie - bearer_session_token mutationAuth: bearer_session_token documentationPath: /docs/api/self-serve apiKeyLifecycle: &a4 inactiveKeyResponse: generic_401_invalid_token inactiveKeyWwwAuthenticate: Bearer realm="starkscan", error="invalid_token" rateLimitResponse: 429_with_retry_after ownerInspectionPath: /v1/me/api-keys internalObservability: sanitized_lifecycle_reason_metrics caller: authenticated: true authType: internal keyClass: internal scopes: [] scopeDisclosure: operator_internal routeFamilyDisclosure: global_operator_view workspacePlan: null rateLimit: null eventSearch: &a5 chain: SN_MAIN positions: minimum: 0 maximum: 15 bounded: enabled: true maximumBlocksInclusive: 10000 fullRange: entitled: false requiredWorkspacePlan: wallet coverageContract: certified_per_selector_position unsupportedResponse: 422_full_range_selector_not_supported unavailableResponse: 503_event_key_index_coverage_unavailable coverageAvailability: unavailable selectorCoverage: [] tokenHolders: &a6 status: available chainId: SN_MAIN identity: canonical_chain_and_token_address routeTemplate: /v1/{chain}/token/{token}/holders screeningRouteTemplate: /v1/{chain}/token/{token}/holders/screening publicPageLimit: 100 ordering: - balanceRaw_desc - canonical_address_asc cursor: opaque_generation_bound screeningTopNDoesNotTruncatePopulation: true snapshotFreshness: immutableFields: - updatedAt - lagBlocks updatedAt: generation_publication_time lagBlocks: indexed_finalized_head_minus_snapshot_block exactnessRequires: - complete_canonical_transfer_coverage - qualified_token_adapter - generation_bound_exact_block_certification unqualifiedTokenPolicy: httpStatus: 422 reasonCode: unqualified_token_policy retryable: false meaning: token holder routes require an explicit address-keyed policy review requestPathExternalCalls: false policyRegistry: schemaVersion: 1 registryId: starkscan-token-holder-policy-v1 chainId: SN_MAIN identity: canonical_chain_and_token_address defaultPolicy: qualification: unqualified_unknown_erc20 behaviorClass: unsupported adapter: unsupported certificationPolicy: policy_review_required items: - symbol: STRK tokenAddress: "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 10 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: Starknet Token netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: ETH tokenAddress: "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7" qualification: qualified_native_fee_token behaviorClass: native_fee_token adapter: starknet_eth_transfer_ledger_v1 priority: 11 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: Ether netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: USDC tokenAddress: "0x33068f6539f8e6e6b131e6b2b814e6c34a5224bc66947c47dab9dfee93b35fb" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 12 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: USD Coin (native) netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: WBTC tokenAddress: "0x3fe2b97c1fd336e750087d68b9b867997fd64a2661ff3ca5a7c771641e8e7ac" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 13 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: Wrapped BTC netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: EKUBO tokenAddress: "0x75afe6402ad5a5c20dd25e10ec3b3986acaa647b77e4ae24b0cbc9a54a27a87" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 20 screeningTopN: 100 freshnessSloSeconds: 7200 completeGenerationSloSeconds: 172800 certificationPolicy: coverage_and_exact_block_samples_required name: Ekubo Protocol netWorthEligible: true holderScreeningEnabled: true priorityTier: B adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: USDT tokenAddress: "0x68f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 21 screeningTopN: 100 freshnessSloSeconds: 7200 completeGenerationSloSeconds: 172800 certificationPolicy: coverage_and_exact_block_samples_required name: Tether USD netWorthEligible: true holderScreeningEnabled: true priorityTier: B adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: strkBTC tokenAddress: "0x787150e306e6eae6e3f79dea881770e8bbff2c1b8eb490f969669ee945b3135" qualification: qualified_wrapper behaviorClass: wrapper adapter: wrapper_share_transfer_ledger_v1 priority: 30 screeningTopN: 50 freshnessSloSeconds: 14400 completeGenerationSloSeconds: 259200 certificationPolicy: coverage_and_exact_block_samples_required name: strkBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: C adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: SolvBTC tokenAddress: "0x593e034dda23eea82d2ba9a30960ed42cf4a01502cc2351dc9b9881f9931a68" qualification: qualified_wrapper behaviorClass: wrapper adapter: wrapper_share_transfer_ledger_v1 priority: 40 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Solv BTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: tBTC tokenAddress: "0x4daa17763b286d1e59b97c283c0b8c949994c361e426a28f743c67bdfe9a32f" qualification: qualified_wrapper behaviorClass: wrapper adapter: wrapper_share_transfer_ledger_v1 priority: 41 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: tBTC v2 netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xstrkBTC tokenAddress: "0x47751b3532fabca89b0f2e35ca1cb45e5a7b11d5e3d3663dfa1f4406b45fd88" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 42 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xstrkBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xWBTC tokenAddress: "0x6a567e68c805323525fe1649adb80b03cddf92c23d2629a6779f54192dffc13" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 43 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xWBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xtBTC tokenAddress: "0x43a35c1425a0125ef8c171f1a75c6f31ef8648edcc8324b55ce1917db3f9b91" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 44 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xtBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xsBTC tokenAddress: "0x580f3dc564a7b82f21d40d404b3842d490ae7205e6ac07b1b7af2b4a5183dc9" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 45 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xsBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. registryDigest: sha256:ffa8e206b991a6d1e3156606da77c6127cabca3c4b0fe230c622a0fcdcfc0b18 rpcProvider: status: enrolled_http_beta endpoint: /v1/SN_MAIN/rpc endpointTemplate: /v1/{chain}/rpc authHeader: X-Starkscan-Api-Key minimumSpecVersion: 0.10.2 publicSpecVersion: 0.10.2 specVersionContract: gateway_declared_compatibility specVersionMethod: starknet_specVersion supportedBlockTags: &a7 - latest - pre_confirmed conditionalBlockTags: &a8 l1_accepted: advertised: false evidence: indexed_canonical_l1_accepted_watermark batch: &a9 supported: true maxItems: 50 maxResponseBytes: 16777216 accounting: Each JSON-RPC child request is classified and rate-limited independently. storageProofBeta: &a10 enabled: true status: bounded_upstream_passthrough availability: upstream_dependent method: starknet_getStorageProof quotaClass: rpc_read_state acceptedBlockIds: - latest - block_number - block_hash rejectedBlockTags: - pending - pre_confirmed limits: maxClassHashes: 8 maxContractAddresses: 8 maxContractStoragePairs: 8 maxStorageKeysPerContract: 16 maxTotalTargets: 32 totalTargetCounting: class_hashes_plus_contract_addresses_plus_individual_storage_keys maxResponseBytes: 1048576 historicalHorizon: advertised: false status: not_certified guaranteedBlocksBehindHead: null certificationTargetBlocksBehindHead: 50000 policy: Fixed historical block requests are forwarded to the configured upstream without an advertised archive guarantee. stateDiffCommitment: advertised: false guaranteed: false status: not_in_starknet_openrpc_0_10_2 passthroughPolicy: preserved_if_returned_by_upstream_not_synthesized_or_certified policy: State-diff commitment is not synthesized or certified. responseValidation: opaque_upstream_result_size_bounded writeBeta: &a11 enabled: false status: disabled_until_operator_enabled openToAllApiKeys: false methods: [] payloadPolicy: Signed payloads only when explicitly enabled. quotaClass: rpc_write traceBeta: &a12 status: operator_scoped scope: trace methods: - starknet_traceTransaction - starknet_traceBlockTransactions quotaClass: rpc_trace maxResponseBytes: 16777216 stateDiffPolicy: omitted_use_starknet_getStateUpdate incompleteResponsePolicy: fail_closed_trace_response_incomplete policy: Available only to configured trace-scoped keys. quotaClasses: &a13 rpc_read_light: - starknet_blockNumber rpc_read_state: - starknet_call rpc_read_history: - starknet_getTransactionByHash rpc_simulation: - starknet_estimateFee rpc_write: - starknet_addInvokeTransaction rpc_trace: - starknet_traceTransaction unsupportedUntilCertified: &a14 - websocket_subscriptions - archive_history_full_provider - no_key_public_rpc walletInteraction: &a15 enabled: false status: disabled_until_operator_enabled supportedChains: [] contractAllowlist: [] transactionPolicy: maxCalls: 0 entryPointNameRequired: true rawCalldataEnabled: false mainnet: disabled limits: maxCalls: 1 maxCalldataFelts: 256 maxArguments: 64 maxStringBytes: 4096 simulation: status: not_certified required: false operatingRules: &a16 - Use only operations advertised for the current caller. issueReportContract: &a17 requiredFields: - route - queryParams - requestBody - responseStatus - responseSnippet - xRequestId rule: Include exact request details and X-Request-Id; redact credentials and secrets. configuredReadKey: summary: Bounded representative configured read-only key response without credential identity value: kind: starkscan.meta.capabilities schemaVersion: '2026-08-17' defaultChain: SN_MAIN authHeader: X-Starkscan-Api-Key externalBasePath: /api/v1 firstCalls: - method: GET path: /api/v1/meta/chains purpose: Discover supported chains. documentation: *a1 rateLimit: *a2 routeFamilies: - name: status tier: read routes: - GET /api/v1/{chain}/status operations: - method: GET path: /api/v1/{chain}/status openapiPath: /v1/{chain}/status openapiMethod: get openapiOperationRef: "#/paths/~1v1~1%7Bchain%7D~1status/get" rateLimitClass: light summary: Read bounded service and indexing status. useWhen: Check service readiness and indexed progress. sessionControl: *a3 apiKeyLifecycle: *a4 caller: authenticated: true authType: tester keyClass: configured scopes: - read scopeDisclosure: exact_for_api_key routeFamilyDisclosure: exact_for_api_key workspacePlan: null rateLimit: loadClass: light limitPerMinute: 120 remaining: 120 retryAfterSeconds: 0 bucketScope: key eventSearch: *a5 tokenHolders: *a6 rpcProvider: status: authenticated_http_beta endpoint: /api/v1/SN_MAIN/rpc endpointTemplate: /api/v1/{chain}/rpc authHeader: X-Starkscan-Api-Key minimumSpecVersion: 0.10.2 publicSpecVersion: 0.10.2 specVersionContract: gateway_declared_compatibility specVersionMethod: starknet_specVersion supportedBlockTags: *a7 conditionalBlockTags: *a8 batch: *a9 storageProofBeta: *a10 writeBeta: *a11 traceBeta: *a12 quotaClasses: *a13 unsupportedUntilCertified: *a14 walletInteraction: *a15 operatingRules: *a16 issueReportContract: *a17 "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/meta/chains: get: summary: Supported chain ids for this deployment description: Authenticated chain catalog. Hosted external clients call `/v1/meta/chains` with `X-Starkscan-Api-Key`. Same-origin explorer traffic uses this `/v1` route through the trusted edge. security: - StarkscanApiKey: [] responses: "200": description: Supported chain metadata content: application/json: schema: $ref: "#/components/schemas/MetaChainsView" examples: boundedResponse: summary: Supported-chain discovery response value: kind: starkscan.meta.chains schemaVersion: '2026-05-02' defaultChain: SN_MAIN chains: - chainId: SN_MAIN statusPath: /v1/SN_MAIN/status statusPathTemplate: /v1/{chain}/status selectionRule: Select a chain returned by this endpoint. "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/meta/agent-context: get: summary: Full agent context contract description: Authenticated context document that combines the public agent-memory contract with handoff artifact guidance. Hosted external clients call `/v1/meta/agent-context` with `X-Starkscan-Api-Key`. Same-origin explorer traffic uses this `/v1` route through the trusted edge. security: - StarkscanApiKey: [] responses: "200": description: Full agent context contract content: application/json: schema: $ref: "#/components/schemas/MetaAgentContextView" examples: boundedResponse: summary: Agent context with source-owned handoff guidance value: kind: starkscan.meta.agent_context schemaVersion: '2026-08-10' agentMemory: kind: starkscan.agent_memory schemaVersion: '2026-05-02' generatedFor: agents auth: header: X-Starkscan-Api-Key externalBasePath: /v1 defaultChain: SN_MAIN firstCalls: - method: GET path: /v1/meta/capabilities purpose: Discover caller-safe operations. routeFamilies: - name: status tier: read routes: - GET /v1/{chain}/status useWhen: Check service and indexing status. workspaceMemory: &a18 status: no_public_write_api publicWriteApi: false serverStoredArtifacts: not available in this deployment writeSurface: not exposed in this deployment localWorkspace: status: internal_local_only defaultDirectory: .codex/handoffs/ artifactPattern: .codex/handoffs/{taskId}.jsonl schemaPath: docs/maintainers/schemas/agent-handoff-artifact.schema.json schemaUrl: /agent-handoff-artifact.schema.json guideUrl: /agent-workspace.md validatorCommand: python3 scripts/ci/agent-handoff.py validate .codex/handoffs/{taskId}.jsonl sampleCommand: python3 scripts/ci/agent-handoff.py sample --task-id example --created-by agent handoffContract: sourceOfTruth: typed JSON/JSONL artifacts, not chat history artifactKinds: - summary - claim - next_step requiredFields: - kind - schemaVersion - artifactId evidenceRule: Claims point to a route, file, issue, PR, or request ID. formats: - application/json - application/jsonl rules: - Never store credentials in a handoff artifact. operatingRules: - Use typed handoff artifacts for durable state. issueReportContract: requiredFields: - route - queryParams - requestBody - responseStatus - responseSnippet - xRequestId rule: Include exact request details and X-Request-Id; redact credentials and secrets. workspaceMemory: *a18 preferredArtifactFormat: application/jsonl "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/meta/status: get: summary: Reject the non-chain meta status alias description: "`meta` is a discovery namespace, not a Starknet chain. This route always returns a typed HTTP 404 so agents cannot mistake an all-null pseudo-chain payload for a health check. Read `/v1/meta/chains`, then request `/v1/{chain}/status` for a supported chain. The trusted app-host `/v1/*` lane supplies internal authentication; direct API-host callers retain the normal Starkscan API-key boundary." security: - StarkscanApiKey: [] responses: "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: The meta namespace is not a chain. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: invalidChain: value: code: invalid_chain message: meta is not a chain; use /v1/{chain}/status with a chain returned by /v1/meta/chains docSlug: api/errors requestId: req_meta_status_example "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Reference /v1/{chain}/status: get: summary: Chain status description: Current indexed, finalized, and L1 evidence status for a supported Starknet chain. `meta` is a discovery namespace, not a chain; `/v1/meta/status` returns a typed HTTP 404. Read `/v1/meta/chains`, then use one of the returned chain ids here. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Current indexed and finalized head status content: application/json: schema: $ref: "#/components/schemas/ExplorerStatusView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: certified x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Status /v1/{chain}/archive-lookup: post: summary: Verify one missing Sepolia object through Starkscan's archive source description: Closed, bounded fallback for a known transaction, contract, class, or block that is absent from Starkscan's local Sepolia read model. The server selects the RPC method and block references; callers cannot provide an upstream URL, method, or arbitrary parameters. Positive evidence is classified relative to the fixed Explorer boundary and current indexed watermark. Upstream errors remain archive_unavailable and never become negative chain facts. Each upstream response is capped at 4 MiB before decoding. Class validation accepts at most 65,536 Sierra program felts and 4,096 entry points per category. Over-budget evidence is inconclusive, never not-found. Parsing and class validation run away from async workers within the five-second operation deadline. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SepoliaArchiveLookupRequest" example: kind: block reference: "0" responses: "200": description: Normalized archive verification result. content: application/json: schema: $ref: "#/components/schemas/SepoliaArchiveLookupView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": description: The bounded archive resolver is at capacity or temporarily unavailable. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string Retry-After: schema: type: integer content: application/json: schema: oneOf: - $ref: "#/components/schemas/SepoliaArchiveLookupView" - $ref: "#/components/schemas/ErrorResponse" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/status/indexing-freshness: get: summary: Indexing freshness health description: Fail-closed semantic health check for external monitoring. Compares one bounded live Starknet RPC head lookup with Starkscan's indexed read-model watermark. Returns HTTP 200 only when both facts are available, internally consistent, and no more than 20 blocks apart; otherwise returns HTTP 503. This endpoint evaluates Starkscan indexing freshness only and does not attribute a failure to Starknet or an upstream provider. The chain path parameter must match the chain served by the deployment; other chains return HTTP 404 without querying an RPC. security: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Starkscan indexing is within the monitored freshness threshold content: application/json: schema: $ref: "#/components/schemas/IndexingFreshnessHealthView" "404": description: Chain is not served by this deployment. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/IndexingFreshnessDegraded" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: public tags: - Status /v1/{chain}/status/contract-verification: get: summary: Contract verification service health description: Secret-free, fail-closed health signal for the public exact-verification service. Returns HTTP 200 only when intake is enabled, the restricted ledger can be read, the isolated controller heartbeat is no more than 90 seconds old, queue and staged-success ages remain within their operational bounds, no retained source is overdue for deletion, and no terminal exact match is waiting for its receipt. Active-state evidence is read through a bounded 50-job window; a sentinel row makes the response HTTP 503 rather than presenting partial counts or state-derived ages as exact. Terminal receipt-lag evidence has a separate bounded 100-row window; when it is truncated, HTTP 503 likewise prevents a lower bound from being treated as complete evidence. Truncation is `evidence_incomplete` unless disabled, unavailable, or inconsistent evidence takes precedence, as documented in the response schema. It never submits source, invokes a compiler, or exposes a job, workspace, object key, or receipt. The chain path parameter must match the chain served by the deployment. security: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Public contract verification is within its operational bounds. content: application/json: schema: $ref: "#/components/schemas/ContractVerificationHealthView" "404": description: Chain is not served by this deployment. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ContractVerificationDegraded" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: public tags: - Status /v1/{chain}/status/l1-finality-quorum: get: summary: L1 finality quorum health description: Fail-closed semantic health check for external monitoring. Reads only Starkscan's materialized status facts and returns HTTP 200 when every L1 evidence component required for the served chain has a complete, agreeing quorum from at least two configured endpoints and the oldest observation is no more than five minutes old. Missing, stale, failed, degraded, diverged, or inconsistent evidence returns HTTP 503. This route does not call Ethereum and does not identify or blame an upstream provider or Starknet. The credential-free status monitor uses the trusted app-host `/v1/*` lane; direct API-host callers retain the normal Starkscan API-key boundary. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Starkscan has a fresh, complete, agreeing L1 evidence quorum. content: application/json: schema: $ref: "#/components/schemas/L1FinalityQuorumHealthView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Chain is not served by this deployment. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/L1FinalityQuorumDegraded" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Status /v1/{chain}/status/l1-finality-freshness: get: summary: L1 finality freshness health description: Fail-closed semantic health check for external monitoring. Reads only Starkscan's materialized L1 accepted proof, an optional matching confirmed state-update checkpoint revalidation, current indexed block timestamps, and the strict L1 materialization quorum. A matching revalidation can refresh the informational materialization age only when it covers the proof's L1 block and matches its chain, StarknetCore address, and filter revision; it never changes the served proof block. Returns HTTP 200 when the complete L1 materialization guard pipeline is healthy within five minutes. The response independently classifies settlement as within the three-hour target or delayed versus target; normal SHARP train batching and temporary frontier holes do not become a pipeline outage. Missing, stale, unhealthy, or inconsistent evidence returns HTTP 503. This route does not call Ethereum and does not identify or blame an upstream provider or Starknet. The credential-free status monitor uses the trusted app-host `/v1/*` lane; direct API-host callers retain the normal Starkscan API-key boundary. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Starkscan's complete L1 materialization pipeline is healthy; settlement may be within target or delayed versus target. content: application/json: schema: $ref: "#/components/schemas/L1FinalityFreshnessHealthView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Chain is not served by this deployment. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/L1FinalityFreshnessDegraded" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Status /v1/{chain}/rpc: post: summary: Starknet JSON-RPC gateway description: "Bounded Starknet JSON-RPC gateway. Read methods are forwarded through Starkscan's rate-limited upstream pool; write methods remain gated by the RPC pilot controls. Accepts a single JSON-RPC request object or a batch of up to 50 request objects. The serialized aggregate batch response is capped at 16 MiB and fails closed with per-request `batch_response_too_large` JSON-RPC errors when that cap is exceeded. JSON parse errors, invalid JSON-RPC payloads, and authentication failures are returned as JSON-RPC error envelopes so clients can keep standard JSON-RPC handling. Authentication failures retain their HTTP 400, 401, 403, or 503 status. HTTP 401 and 403 responses preserve the WWW-Authenticate challenge; retryable 503 responses preserve Retry-After. For read and simulation methods, a Starknet spec error that the requested method lists is returned as the spec defines it: the spec's canonical message and only the spec-defined `data`, rebuilt field by field with the upstream endpoint's identity redacted. An outage, overload, or rate limit reported under a spec code, or code 32 (no blocks) from a head query, returns the retryable `-32005` `upstream_unavailable` error instead. Write submission rejections keep their numeric code with the redacted `upstream_write_rejected` envelope, because their data can echo signatures and calldata. Every other upstream JSON-RPC error keeps its numeric code with a typed, correlated, sanitized error envelope. Upstream provider messages and other data are never forwarded." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: oneOf: - $ref: "#/components/schemas/JsonRpcRequest" - $ref: "#/components/schemas/JsonRpcBatchRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: jsonrpc: "2.0" method: starknet_blockNumber params: [] id: 1 responses: "200": description: JSON-RPC response or JSON-RPC error envelope forwarded from the gateway headers: X-Request-Id: $ref: "#/components/headers/RequestId" X-Starkscan-Rpc-Class: description: Quota and routing class applied to this JSON-RPC response. schema: type: string content: application/json: schema: oneOf: - $ref: "#/components/schemas/JsonRpcResponse" - $ref: "#/components/schemas/JsonRpcBatchResponse" "400": description: Malformed or conflicting authentication credential as a JSON-RPC error envelope. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/JsonRpcResponse" "401": description: Missing or invalid credential as a JSON-RPC error envelope. headers: WWW-Authenticate: schema: type: string X-Request-Id: schema: type: string content: application/json: schema: $ref: "#/components/schemas/JsonRpcResponse" "403": description: Valid credential lacks the required scope; returned as a JSON-RPC error envelope. headers: WWW-Authenticate: schema: type: string X-Request-Id: schema: type: string content: application/json: schema: $ref: "#/components/schemas/JsonRpcResponse" "429": $ref: "#/components/responses/RateLimited" "503": description: Authentication lookup or authorization provider temporarily unavailable as a JSON-RPC error envelope. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string Retry-After: description: Seconds to wait before retrying when the unavailable path supplies a retry delay. schema: type: integer format: int64 content: application/json: schema: $ref: "#/components/schemas/JsonRpcResponse" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: advanced-utility x-starkscan-key-tier: utility tags: - Reference /v1/{chain}/rpc/ws: get: summary: Starknet JSON-RPC WebSocket proxy description: Beta WebSocket upgrade route for Starknet JSON-RPC subscription clients. The route is disabled unless the deployment explicitly enables `RPC_WSS_ENABLED` and configures a Starknet WebSocket upstream. After a successful protocol upgrade, clients send and receive Starknet JSON-RPC subscription messages over the WebSocket connection. This lane is certified separately from the HTTP JSON-RPC gateway. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "101": description: WebSocket protocol upgrade accepted. "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Chain is not served by this deployment. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: advanced-utility x-starkscan-key-tier: utility tags: - Reference /v1/{chain}/block/{number_or_hash}: get: summary: Block detail by number or hash security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: number_or_hash in: path required: true schema: type: string example: "7550747" - name: tx_limit in: query description: Max block transactions returned (clamped to 1..200). Defaults to `50` when omitted. schema: type: integer format: int32 default: 50 minimum: 1 maximum: 200 example: 50 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Block detail with transaction preview content: application/json: schema: $ref: "#/components/schemas/BlockView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Block not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": description: The requested Sepolia block was intentionally removed by the rolling indexed-history policy. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/HistoryExpiredErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: certified x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Blocks /v1/{chain}/block-at-timestamp: get: summary: Resolve timestamp to indexed block description: Resolve a Unix seconds or RFC3339 timestamp to the closest indexed Starknet block. `closest=before` is the default and is the right choice for accounting "as of" balance snapshots such as calendar close. The route is served from indexed block facts only; RPC is used by the correctness gate, not by the request path. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: timestamp in: query required: true description: Unix seconds or RFC3339 timestamp with timezone. schema: oneOf: - type: string pattern: ^[0-9]{1,19}$ description: Unix seconds. - type: string format: date-time maxLength: 96 description: RFC3339 timestamp with timezone. example: '2025-12-31T23:59:59Z' - name: closest in: query description: | Direction for the selected block. `before` returns the last indexed block at or before the timestamp; `after` returns the first indexed block at or after the timestamp. schema: type: string enum: - before - after default: before example: before - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Timestamp resolution with inclusive indexed bounds content: application/json: schema: $ref: "#/components/schemas/BlockAtTimestampView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: No indexed block exists in the requested closest direction headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: certified x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Blocks /v1/{chain}/blocks: get: summary: Paginated latest blocks feed security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: cursor in: query description: Optional block number cursor for reverse pagination. schema: type: integer format: int64 minimum: 0 example: 8279910 - name: limit in: query description: Page size (clamped to 1..200). Defaults to `25` when omitted. schema: type: integer format: int32 default: 25 minimum: 1 maximum: 200 example: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Chain blocks page content: application/json: schema: $ref: "#/components/schemas/ChainBlockListPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Blocks /v1/{chain}/block/{number}/txs: get: summary: Paginated transactions for one block security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: number in: path required: true schema: type: integer format: int64 example: 8279910 - name: cursor in: query description: Optional transaction index cursor for reverse pagination. schema: type: integer format: int32 minimum: 0 example: 0 - name: limit in: query description: Page size (clamped to 1..100). Defaults to `25` when omitted. schema: type: integer format: int32 default: 25 minimum: 1 maximum: 100 example: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Block transaction page content: application/json: schema: $ref: "#/components/schemas/BlockTransactionPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Block not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Blocks /v1/{chain}/tx/previews: post: summary: Batch transaction previews by hash security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/TransactionPreviewBatchRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: hashes: - "0x054bfd961fb8b156c77ffa0f7882b8fcc1836753c2d3d88435b640d6300c8bd9" includeLogs: false includeLogCounts: true logLimitPerTx: 16 responses: "200": description: Ordered transaction preview results content: application/json: schema: $ref: "#/components/schemas/TransactionPreviewBatchView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: advanced-utility x-starkscan-key-tier: utility description: Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations. tags: - Utilities /v1/{chain}/tx/{tx_hash}: get: summary: Transaction detail by hash security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: tx_hash in: path required: true schema: type: string example: "0x054bfd961fb8b156c77ffa0f7882b8fcc1836753c2d3d88435b640d6300c8bd9" - name: logLimit in: query description: Maximum number of event logs returned in the transaction detail payload. Defaults to `96` when omitted. schema: type: integer format: int32 default: 96 minimum: 1 maximum: 256 example: 96 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Transaction detail content: application/json: schema: $ref: "#/components/schemas/TransactionDetailView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Transaction not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": description: The requested Sepolia transaction was intentionally removed by the rolling indexed-history policy. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/HistoryExpiredErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: certified x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Transactions /v1/{chain}/txs: get: summary: Paginated latest transactions feed security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: cursor in: query description: Optional cursor encoded as `block:tx`. schema: type: string - name: limit in: query description: Page size (clamped to 1..200). schema: type: integer format: int32 minimum: 1 maximum: 200 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Chain transactions page content: application/json: schema: $ref: "#/components/schemas/ChainTransactionListPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Transactions /v1/{chain}/bridge/starkgate/resolve: get: summary: Resolve StarkGate bridge activity description: Resolves StarkGate lifecycle rows from indexed L1/L2 protocol message and bridge facts. At least one of `txHash`, `messageHash`, `address`, `token`, or `bridge` is required. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: txHash in: query description: Optional Starknet transaction hash to resolve. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: messageHash in: query description: Optional protocol message hash to resolve. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: address in: query description: Optional sender or recipient address filter. schema: type: string - name: token in: query description: Optional token address filter. schema: type: string - name: bridge in: query description: Optional L1 or L2 bridge contract address filter. schema: type: string - name: direction in: query description: Optional message direction filter. schema: type: string enum: - all - l1_to_l2 - l2_to_l1 default: all - name: limit in: query description: Page size for resolver matches (clamped to 1..25). schema: type: integer format: int32 minimum: 1 maximum: 25 default: 10 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: StarkGate transfer resolution content: application/json: schema: $ref: "#/components/schemas/StarkgateTransferResolutionView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/bridge/starkgate/transfers: get: summary: Paginated StarkGate bridge transfers security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: messageHash in: query description: Optional exact protocol message hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: address in: query description: Optional sender or recipient address filter. schema: type: string - name: token in: query description: Optional token address filter. schema: type: string - name: bridge in: query description: Optional L1 or L2 bridge contract address filter. schema: type: string - name: status in: query description: Optional transfer status filter. `pending_l1_claim` is retained as a compatibility filter for uncleared withdrawals. Claimability is sourced from a finalized StarknetCore registry snapshot; missing evidence returns `claimability_unavailable` and snapshots older than five minutes return `claimability_stale` rather than being reused as current readiness. schema: type: string enum: - l1_observed - consumed_on_l2 - l2_only_signal - pending_l1_claim - pending_l1_proof - claimability_ambiguous - claimability_unavailable - claimability_stale - ready_to_claim_on_l1 - cleared_on_l1 - unpaired - name: direction in: query description: Optional message direction filter. schema: type: string enum: - all - l1_to_l2 - l2_to_l1 default: all - name: cursor in: query description: Optional opaque StarkGate transfer cursor returned from `nextCursor`. New cursors are integrity-protected, expire after five minutes, and pin both the L1 accepted watermark and registry-freshness cutoff for stable claimability pagination. Clients must return the value unchanged and restart pagination after `400`; legacy position-only cursors remain accepted, while unsigned snapshot-bound cursors fail closed. schema: type: string maxLength: 1024 - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: StarkGate transfer page content: application/json: schema: $ref: "#/components/schemas/StarkgateTransferPageView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/bridge/starkgate/transfer/{message_hash}: get: summary: Resolve StarkGate bridge transfers by message hash description: Resolver endpoint for one protocol message hash. Returns the indexed resolution view, which may contain zero or more matching transfer rows and explicit coverage metadata. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: message_hash in: path required: true description: Protocol message hash. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ example: "0x0123456789abcdef0123456789abcdef" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: StarkGate transfer resolver results for one message hash content: application/json: schema: $ref: "#/components/schemas/StarkgateTransferResolutionView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/messages: get: summary: Paginated canonical cross-layer messages description: Global cross-layer message feed served only from indexed StarknetCore protocol message facts. Rows are keyed by protocol message hash, not token-transfer or bridge-adapter activity. Coverage metadata is explicit because a data plane may still be backfilling protocol message facts. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: direction in: query description: Optional message direction filter. schema: type: string enum: - all - l1_to_l2 - l2_to_l1 - name: txHash in: query description: Optional transaction hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: messageHash in: query description: Optional protocol message hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: | Optional opaque cursor returned unchanged from `nextCursor`. New responses use `m1:block:tx:message:tx_hash:message_hash:direction:source_tier` so pagination remains stable when multiple messages share the same numeric tuple. Legacy `block:tx:message` cursors remain accepted for older clients. schema: type: string pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$ - name: limit in: query description: Page size (defaults to the full bounded pool directory page; clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 default: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Global message page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/MessagePage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/message/{message_hash}: get: summary: Canonical cross-layer message detail description: Message detail served only from indexed StarknetCore protocol message facts. Bridge adapter lifecycle facts and token-transfer-derived bridge activity are excluded. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: message_hash in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ example: "0x0123456789abcdef0123456789abcdef" - name: cursor in: query description: Optional opaque cursor returned from `nextCursor` when a message hash has more lifecycle rows. schema: type: string pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$ - name: limit in: query description: Page size for lifecycle rows (clamped to 1..100, default 100). schema: type: integer format: int32 default: 100 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Message detail with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/MessageDetailView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Message hash has no indexed StarknetCore protocol lifecycle rows headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/tx/{tx_hash}/trace: get: summary: Transaction Cairo trace by hash security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: tx_hash in: path required: true schema: type: string example: "0x054bfd961fb8b156c77ffa0f7882b8fcc1836753c2d3d88435b640d6300c8bd9" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Transaction trace payload content: application/json: schema: $ref: "#/components/schemas/ContractTransactionTraceView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Transaction trace not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Transactions /v1/{chain}/address/{address}: get: summary: Address aggregate summary security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address summary content: application/json: schema: $ref: "#/components/schemas/AddressSummaryView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Addresses /v1/{chain}/address/{address}/attribution: get: summary: Indexed address attribution description: Address-oriented attribution lookup backed by indexed metadata. Use this when a partner workflow starts from an address and needs a readable label/protocol attribution without calling RPC on the request path. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Indexed address attribution metadata content: application/json: schema: $ref: "#/components/schemas/AddressAttributionView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Addresses /v1/{chain}/address/summaries: post: summary: Batch address aggregate summaries description: |- Utility-tier batch helper for bounded address hydration. The route returns request-ordered indexed summary facts for up to 128 addresses and intentionally avoids raw activity scans, deployment repair, and RPC calls on the request path. `totalActivityCount=null` with `activityCountExact=false` means no trustworthy numeric statement is available; numeric zero is reserved for a certified exhaustive range. Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AddressSummaryBatchRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: addresses: - "0x0123456789abcdef" responses: "200": description: Ordered address summary results content: application/json: schema: $ref: "#/components/schemas/AddressSummaryBatchView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: advanced-utility x-starkscan-key-tier: utility tags: - Utilities /v1/{chain}/address/intelligence: post: summary: Batch address deployment, attribution, typed activity, and inbound-funds intelligence description: |- Utility-tier batch helper for wallet, paymaster, migration, and compliance-adjacent clients that need factual classification for a bounded list of up to 128 addresses. The route returns whether each address has indexed deployment evidence, optional readable attribution, whether indexed token-transfer rows show the address as a recipient, and typed activity coverage. Successful finalized account-sender, trace-backed finalized contract-call, and canonical finalized contract-emitted event evidence preserves the proved latest block while its total remains null until a success-only exhaustive aggregate is certified; unknown or unmaterialized totals are null, while a certified exhaustive genuine zero is 0; reorgable head rows are not promoted. It is backed by read-model indexes only; it does not call RPC on the request path and does not perform risk scoring or sanctions screening. Advanced utility route. This helper is externally supported, but it requires a broader utility-access key than the baseline read tier and is not the default starting point for new integrations. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AddressSummaryBatchRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: addresses: - "0x0123456789abcdef" responses: "200": description: Ordered address intelligence results content: application/json: schema: $ref: "#/components/schemas/AddressIntelligenceBatchView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: advanced-utility x-starkscan-key-tier: utility tags: - Utilities /v1/{chain}/classes: get: summary: Materialized class directory description: Pages bounded indexed class facts without request-path raw-table aggregation or live RPC. `instances_desc` is the compatibility default for observed class associations. `declared_at_desc` and `origin_asc` page the complete indexed DECLARE and legacy DEPLOY origin catalog newest or oldest first; instance and ABI fields are optional observed enrichment. `classLabel` is a reviewed class-family label when available, not exact source verification. externalDocs: description: Class origin, instance, and classification coverage guide url: https://starkscan.co/docs/api/classes security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: cursor in: query description: Opaque cursor returned from `nextCursor`; cursors are sort-specific (`c1` for `instances_desc`, `c2` for `declared_at_desc` or `origin_asc`). schema: type: string pattern: ^c(?:1:[0-9]+:0[xX][0-9a-fA-F]{1,64}|2:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]{1,64})$ - name: sort in: query description: "`instances_desc` preserves the observed-instance directory default; `declared_at_desc` and `origin_asc` return the complete indexed class-origin catalog newest or oldest first." schema: type: string enum: - instances_desc - declared_at_desc - origin_asc default: instances_desc - name: limit in: query description: Page size (clamped to 1..100, default 50). schema: type: integer format: int32 minimum: 1 maximum: 100 default: 50 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Materialized class directory page content: application/json: schema: $ref: "#/components/schemas/ClassDirectoryPageView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/class/{class_hash}: get: summary: Materialized class detail description: Returns one indexed declaration or observed class record and a bounded page of observed contract/account instances. Declaration-only classes resolve with honest zero/null observation fields. This endpoint reads indexed facts only; it does not call RPC on the request path and does not claim exact source verification unless future verification tiers say so explicitly. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: class_hash in: path required: true description: Starknet class hash. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ example: "0x0123456789abcdef" - name: instanceSort in: query description: Address order is the compatibility default; newest order exposes the latest block-backed relationship evidence first. schema: type: string enum: - address_asc - newest_desc default: address_asc - name: instanceCursor in: query description: Sort-specific cursor returned from `nextInstanceCursor`; an address for `address_asc` or a `c3` cursor for `newest_desc`. schema: type: string pattern: ^(?:0[xX][0-9a-fA-F]{1,64}|c3:(?:-1|[0-9]+):0[xX][0-9a-fA-F]{1,64})$ - name: instanceLimit in: query description: Instance page size (clamped to 1..100, default 25). schema: type: integer format: int32 minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Materialized class detail and bounded indexed instances content: application/json: schema: $ref: "#/components/schemas/ClassDetailView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Class has no indexed declaration or observed-class fact headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/query/wallet-paymaster-view: post: summary: Wallet/paymaster query bundle description: Partner Query Plane bundle for wallet and paymaster backends. The first slice returns bounded, request-ordered address identity, account state, and proof-backed L1 finality metadata for up to 32 unique addresses. It is backed by indexed read-model facts only and does not call RPC or scan raw activity on the request path. Token holdings, recent transactions, bridge/message rollups, and row-level provenance details are reserved for forward-compatible request shapes; when enabled in v1 they fail closed with `unsupported_section` instead of returning partial success. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WalletPaymasterViewRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: addresses: - "0x0123456789abcdef" include: identity: true accountState: true finality: true freshness: requireFresh: false responses: "200": description: Wallet/paymaster bundle envelope headers: X-Starkscan-Route-Class: description: Route budget class for class-specific backoff. schema: type: string enum: - batch X-Starkscan-Query-Class: description: Query Plane bundle class used for accounting and support. schema: type: string enum: - wallet_paymaster X-Starkscan-Cost-Units: description: | Cost units charged for this Query Plane request. Wallet/paymaster formula: 2 base units + 1 unit per requested address + 1 unit per 8 addresses when `accountState` is enabled + 1 unit when `finality` is enabled. Forward-compatible unsupported sections have reserved costs and fail closed in v1. schema: type: integer format: int64 x-ratelimit-limit: schema: type: integer format: int64 x-ratelimit-remaining: schema: type: integer format: int64 x-ratelimit-policy: schema: type: string content: application/json: schema: $ref: "#/components/schemas/WalletPaymasterQueryEnvelope" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "409": $ref: "#/components/responses/Conflict" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: partner x-starkscan-key-tier: partner tags: - Reference /v1/{chain}/query/wallet-state: post: summary: Verify one wallet's fungible state at one immutable block description: One bounded wallet-screen operation. Candidate discovery and balance correctness are separate contracts. Every returned balance, optional nonce, and optional class hash is read from the dedicated RPC serving pool at the same resolved block hash. The server never substitutes an indexed balance and never converts an RPC error to zero. In require_complete mode, any failed value returns HTTP 503 without a partial success payload. verified_partial mode returns typed per-item failures and walletSafe=false. The current public contract accepts at most 25 candidates. The 26-50 band remains unavailable until dedicated-pool and clean-window capacity certification plus a coordinated schema and client release. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/WalletStateRequest" examples: boundedExplicitWallet: summary: Verify one explicit token at the latest accepted L2 block value: ownerAddress: "0x0123456789abcdef" mode: require_complete scope: explicit tokenAddresses: - "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" blockPreference: latest_accepted_l2 responses: "200": description: Block-pinned complete or typed-partial wallet state headers: X-Starkscan-Query-Class: schema: type: string enum: - wallet_state X-Starkscan-Cost-Units: description: One partner operation within the bounded 1-25 token band. schema: type: integer const: 1 x-ratelimit-limit: schema: type: integer x-ratelimit-remaining: schema: type: integer content: application/json: schema: $ref: "#/components/schemas/WalletStateResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: partner x-starkscan-key-tier: partner tags: - Reference /v1/{chain}/query/defi-lending-market-view: post: summary: DeFi lending market query bundle description: Partner Query Plane bundle for Vesu-style lending markets, DeFi frontends, risk monitors, and liquidation services. The first slice returns request-ordered market selectors, bounded indexed contract identity, token address echoes, proof-backed L1 finality metadata, and simulation boundary metadata. It is backed by indexed read-model facts only and does not call RPC, scan events, compute risk, or read signed payloads on the request path. State samples, events, recent transactions, and row-level provenance details are reserved for forward-compatible request shapes; when enabled in v1 they fail closed with `unsupported_section`. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DefiLendingMarketViewRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: markets: - marketId: vesu-main contracts: - "0x0123456789abcdef" tokenAddresses: - "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" include: contractIdentity: true simulationMetadata: true freshness: requireFresh: false responses: "200": description: DeFi lending market bundle envelope headers: X-Starkscan-Route-Class: description: Route budget class for class-specific backoff. schema: type: string enum: - batch X-Starkscan-Query-Class: description: Query Plane bundle class used for accounting and support. schema: type: string enum: - defi_lending X-Starkscan-Cost-Units: description: | Cost units charged for this Query Plane request. DeFi lending formula: 5 base units + 3 units per requested market + 1 unit per 16 requested contracts when `contractIdentity` is enabled + 1 unit per requested market when `simulationMetadata` is enabled. schema: type: integer format: int64 x-ratelimit-limit: schema: type: integer format: int64 x-ratelimit-remaining: schema: type: integer format: int64 x-ratelimit-policy: schema: type: string content: application/json: schema: $ref: "#/components/schemas/DefiLendingMarketQueryEnvelope" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "409": $ref: "#/components/responses/Conflict" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: partner x-starkscan-key-tier: partner tags: - Reference /v1/{chain}/query/support-proof-bundle: post: summary: Support/proof query bundle description: Partner Query Plane bundle for support, bridge/message debugging, and customer-success proof packets. The v1 slice accepts exactly one incident selector (`txHash` or `messageHash`) and returns bounded indexed transaction detail, protocol-message lifecycle rows, StarkGate transfer resolution, and proof-backed L1 finality metadata. It is backed by indexed read-model facts only and does not call RPC, Ethereum RPC, or provider comparison endpoints on the request path. Row-level provenance details and shareable redacted proof links are reserved for forward-compatible request shapes; when enabled in v1 they fail closed with `unsupported_section`. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SupportProofBundleRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: txHash: "0x054bfd961fb8b156c77ffa0f7882b8fcc1836753c2d3d88435b640d6300c8bd9" supportCorrelationId: example-support-case-001 responses: "200": description: Support/proof bundle envelope headers: X-Starkscan-Route-Class: description: Route budget class for class-specific backoff. schema: type: string enum: - batch X-Starkscan-Query-Class: description: Query Plane bundle class used for accounting and support. schema: type: string enum: - support_proof X-Starkscan-Cost-Units: description: | Cost units charged for this Query Plane request. Support/proof formula: 8 base units + 4 units each for requested `transaction`, `protocolMessages`, and `starkgate` sections + 1 unit when `finality` is enabled. schema: type: integer format: int64 x-ratelimit-limit: schema: type: integer format: int64 x-ratelimit-remaining: schema: type: integer format: int64 x-ratelimit-policy: schema: type: string content: application/json: schema: $ref: "#/components/schemas/SupportProofBundleEnvelope" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "409": $ref: "#/components/responses/Conflict" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: partner x-starkscan-key-tier: partner tags: - Reference /v1/{chain}/address/{address}/assets/discovery: get: summary: Discover bounded fungible asset candidates for one wallet description: Returns token candidates and evidence only; it never returns or implies a current balance. Follow nextCursor while hasMore is true. Coverage describes completeness only within the declared standard-fungible discovery scope. globallyComplete remains false because non-standard or unregistered assets may not be discoverable. Use wallet-state to verify balances at one immutable block hash. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: scope in: query description: | `discovered` returns candidates observed for this wallet. The default `discovered_plus_registry` also evaluates the curated registry, which can paginate even for a wallet with no observed assets. schema: type: string enum: - discovered - discovered_plus_registry default: discovered_plus_registry - name: cursor in: query description: | Authenticated opaque nextCursor returned by the previous discovery page. It pins one candidate snapshot, expires five minutes after the first page, and must be returned unchanged with the same scope. Restart from the first page after an invalid_cursor response. schema: type: string - name: limit in: query schema: type: integer minimum: 1 maximum: 50 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Candidate page with explicit discovery coverage content: application/json: schema: $ref: "#/components/schemas/WalletAssetDiscoveryPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Addresses /v1/{chain}/address/{address}/transactions: get: summary: Paginated transaction summaries touching one address security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: cursor in: query description: Optional cursor encoded as `block:tx:log:transfer[:kind[:txHash[:source]]]`. schema: type: string - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address transaction page content: application/json: schema: $ref: "#/components/schemas/AddressTransactionPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Addresses /v1/{chain}/address/{address}/token-holdings: get: deprecated: true summary: Retired indexed-balance route description: Always returns HTTP 410 with no holdings data. The old contract mixed asset discovery with event-derived balance observations and could not satisfy wallet-grade correctness. Use assets/discovery for candidate enumeration and query/wallet-state for balances pinned to one block. The response includes Deprecation, Sunset, and successor Link headers. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - $ref: "#/components/parameters/RequestIdHeader" responses: "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": description: Route retired; migrate to discovery plus wallet-state headers: Deprecation: schema: type: string const: "true" Sunset: schema: type: string Link: schema: type: string content: application/json: schema: $ref: "#/components/schemas/RetiredTokenHoldingsResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: unsupported x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Addresses /v1/{chain}/contract/{address}: get: summary: Indexed contract metadata description: Lightweight contract metadata for migration clients. The response is composed from one stable snapshot of indexed read-model facts. A syntactically valid address with no indexed contract identity returns 404 rather than an all-null success envelope. Nullable token fields mean the contract is not currently identified as token metadata in the index, not that it is provably not a token. Class-hash provenance fields state exactly which indexed fact backs classHash. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Indexed contract metadata content: application/json: schema: $ref: "#/components/schemas/ContractMetadataView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: No indexed contract identity exists for this address headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/verification: get: summary: Legacy contract verification migration state deprecated: true description: Legacy migration state only. It is not reproducible source evidence and never establishes `verified_exact`. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Legacy migration record; not reproducible source evidence content: application/json: schema: $ref: "#/components/schemas/ContractVerificationView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract verification record not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/classes: get: summary: Observed contract class epochs description: "Bounded, newest-first class epochs from event-time ABI observations. This is partial evidence, not an exhaustive upgrade ledger: changes without an indexed ABI observation can be absent. `truncated` only reports page truncation and must not be interpreted as source coverage." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: limit in: query description: Maximum class epochs to return (clamped to 1..100; default 25). schema: type: integer format: int32 minimum: 1 maximum: 100 default: 25 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Partial, observation-backed class epochs for the contract content: application/json: schema: $ref: "#/components/schemas/ContractClassHistoryView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/entrypoints: get: summary: Contract class entrypoints description: Resolves latest, a block number, or a block hash to one canonical block hash, then reads the contract class hash and ABI at that hash. Use the returned `blockTag` for the paired contract call. Pending is rejected because it cannot be certified across separate requests. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: block_tag in: query description: latest, an explicit non-negative block number, or a 0x-prefixed block hash. The response returns the resolved canonical hash. schema: type: string default: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract entrypoint selectors grouped by type content: application/json: schema: $ref: "#/components/schemas/ContractEntrypointsView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract/class not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/events: get: summary: Paginated contract event logs description: "Canonical paginated event/log surface for one contract. Use server-side topic and block filters before applying client-side protocol interpretation. Results are returned newest first in deterministic on-chain order (`blockNumber` DESC, `txIndex` DESC, `logIndex` DESC). `topic0..topic15` address exact key positions: repeated values at one position are OR alternatives, populated positions are ANDed, and omitted positions are wildcards. Each position accepts at most 128 distinct felts and the request accepts at most 256 total. Any `topic1..topic15` filter requires a non-empty `topic0` plus explicit numeric `from_block` and `to_block` values. Ordinary read keys may span at most 10,000 blocks inclusive. For a DB-backed Wallet workspace, every numeric subrange within retained, declared, certified contiguous coverage uses the positional index, including sub-10,000-block windows; narrowing a certified request never selects the raw scan. A Wallet workspace may request a larger range only when every requested selector has certified contiguous index coverage at one common non-zero anchor position. The server chooses the populated position with the fewest requested values, breaking ties by lower position number. Additional populated later positions are applied to those anchor candidates and do not need separate coverage. A selector with no full-range declaration returns `422 full_range_selector_not_supported`; an entitled declared selector clamps an above-ceiling `to_block` to the current complete prefix and reports that clamp in `rangeCoverage`, while coverage with no complete prefix at the requested lower bound returns `503 event_key_index_coverage_unavailable`. An On Sepolia, a certified pre-Explorer archive joins retained history at block `10,692,545` only after its terminal hash matches that block's parent. An archive-only query may end at block `10,692,544`; other earlier upper bounds return `503 event_key_index_coverage_unavailable` because no arbitrary historical upper-block hash is available to pin its cursor. A genesis-to-live query uses the joined range only after the boundary check. An uncertified bounded raw scan that exceeds its fixed budget returns `503 event_positional_scan_timeout`; a certified index timeout returns `503 event_positional_index_timeout`. Neither path returns an incomplete page. `selector` aliases `topic0`; `key`/`keys` compatibility inputs fill sequential singleton positions after topic0 on this contract-scoped route only. The request `cursor` is exclusive and resumes after the last seen `(blockNumber, txIndex, logIndex)` tuple. Pass the opaque `nextCursor` from the previous response unchanged and keep the same route, chain, address, and topic filters. After the first page, clients may omit `from_block` and `to_block`; the server restores them from the cursor's pinned snapshot before validating positional filters. If a client repeats either bound, it must match the original requested bound. Full-range cursors bind both that normalized query scope and the canonical hash at the proven upper block. A changed scope returns `409 event_cursor_scope_changed`; a head reorganization or changed range returns `409 event_cursor_snapshot_changed`. In either case the client must restart without a cursor rather than risk gaps or duplicates." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: topic0 in: query description: Optional repeated exact matches for event key position 0; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic1 in: query description: Optional repeated exact matches for event key position 1; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic2 in: query description: Optional repeated exact matches for event key position 2; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic3 in: query description: Optional repeated exact matches for event key position 3; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic4 in: query description: Optional repeated exact matches for event key position 4; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic5 in: query description: Optional repeated exact matches for event key position 5; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic6 in: query description: Optional repeated exact matches for event key position 6; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic7 in: query description: Optional repeated exact matches for event key position 7; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic8 in: query description: Optional repeated exact matches for event key position 8; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic9 in: query description: Optional repeated exact matches for event key position 9; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic10 in: query description: Optional repeated exact matches for event key position 10; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic11 in: query description: Optional repeated exact matches for event key position 11; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic12 in: query description: Optional repeated exact matches for event key position 12; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic13 in: query description: Optional repeated exact matches for event key position 13; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic14 in: query description: Optional repeated exact matches for event key position 14; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic15 in: query description: Optional repeated exact matches for event key position 15; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: selector in: query description: Repeated alias for `topic0`. `topic0` and `selector` share one 128-item filter budget for key position 0 before duplicate-equivalent values are removed. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: key in: query description: Contract-route compatibility alias. Repeated values fill the next available singleton positions from `topic1` through `topic15`; `key`, `keys`, and `keys[]` share one 15-value sequential budget and cannot express positional ORs. schema: $ref: "#/components/schemas/SequentialEventKeyCompatibilityFilter" style: form explode: true - name: keys in: query description: Alias for `key`; repeated values fill sequential singleton positions from `topic1` through `topic15` and share the same 15-value budget. schema: $ref: "#/components/schemas/SequentialEventKeyCompatibilityFilter" style: form explode: true - name: keys[] in: query description: Bracket-form alias for `key`; repeated values fill sequential singleton positions from `topic1` through `topic15` and share the same 15-value budget. schema: $ref: "#/components/schemas/SequentialEventKeyCompatibilityFilter" style: form explode: true - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: Opaque nextCursor from the previous response. Legacy block:tx:log values remain accepted for ordinary bounded searches but cannot continue a full-range walk. schema: type: string maxLength: 256 - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract event page content: application/json: schema: $ref: "#/components/schemas/ContractEventPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "409": $ref: "#/components/responses/Conflict" "410": description: An explicit Sepolia block bound or cursor is outside the rolling indexed-history window. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/HistoryExpiredErrorResponse" "422": description: One or more selectors are not declared for full-range positional search. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/messages: get: summary: Paginated canonical messages for one contract description: Contract-scoped cross-layer message rows served only from indexed StarknetCore protocol message facts. Starkscan does not infer Messages rows from bridge adapter pairing facts, generic transactions, events, or token transfers. Coverage metadata is explicit because a data plane may still be backfilling protocol message facts. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ example: "0x0123456789abcdef" - name: direction in: query description: Optional message direction filter. schema: type: string enum: - all - l1_to_l2 - l2_to_l1 - name: txHash in: query description: Optional transaction hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: messageHash in: query description: Optional protocol message hash filter. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: | Optional opaque cursor returned unchanged from `nextCursor`. New responses use `m1:block:tx:message:tx_hash:message_hash:direction:source_tier` so pagination remains stable when multiple messages share the same numeric tuple. Legacy `block:tx:message` cursors remain accepted for older clients. schema: type: string pattern: ^(m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)|[0-9]+:[0-9]+:[0-9]+)$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract message page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/MessagePage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/bridge-signals: get: summary: Paginated L2 bridge signal activity for one contract description: Returns low-latency bridge rows derived from indexed L2 token-transfer bridge signals, bridge registry matches, and bridge-asset mint/burn signals. This endpoint explicitly reports `coverage.status=partial` until L1 message pairing and cross-layer completion facts are indexed; clients must not treat these rows as complete L1/L2 lifecycle records. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ example: "0x0123456789abcdef" - name: cursor in: query description: Optional cursor in `block:tx:log:transfer` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Contract bridge signal page with explicit coverage metadata content: application/json: schema: $ref: "#/components/schemas/ContractBridgeTransactionPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/read: get: summary: Read-only contract call security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: selector in: query required: true description: 0x-prefixed entrypoint selector felt schema: type: string example: "0x0123456789abcdef" - name: calldata in: query description: Optional felt/decimal calldata values (repeat key for multiple values). schema: type: array maxItems: 1024 items: type: string style: form explode: true - name: block_tag in: query description: State reference used for call execution. Use `latest` or `pending` for live reads, or pass a block number/hash for deterministic correctness checks. schema: allOf: - $ref: "#/components/schemas/BlockReference" default: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Read call result content: application/json: schema: $ref: "#/components/schemas/ContractReadResultView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract or entrypoint not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/contract/{address}/storage: get: summary: Read one raw contract storage slot description: Reads one storage slot at a validated Starknet block reference. The response echoes the normalized contract address and slot key plus the validated caller block-reference text used for the read. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: key in: query required: true description: Storage-slot key as a 0x-prefixed felt or decimal felt. schema: type: string example: "0x0" - name: block_tag in: query description: State reference used for the storage read. Use `latest` or `pending` for live reads, or pass a block number/hash for deterministic correctness checks. schema: allOf: - $ref: "#/components/schemas/BlockReference" default: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Storage-slot value content: application/json: schema: $ref: "#/components/schemas/ContractStorageResultView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract or block not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Contracts /v1/{chain}/address/{address}/activity: get: summary: Paginated address activity security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: cursor in: query description: | Optional opaque cursor returned unchanged from `nextCursor`. New responses use `block:tx:log:transfer:kind:txHash[:source]` so pagination remains stable when multiple activity rows share the same numeric tuple. Legacy `block:tx:log:transfer` cursors remain accepted for older clients. schema: type: string - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address activity page content: application/json: schema: $ref: "#/components/schemas/AddressActivityPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Addresses /v1/{chain}/address/{address}/transfers: get: summary: Paginated token transfers touching one address description: Address-scoped transfer history backed by the indexed global transfer table. Direction, token, block, cursor, and limit filters are applied before pagination. `any` returns transfers where the address is either sender or recipient; self-transfers are returned once. `in` returns recipient-side rows and `out` returns sender-side rows, so a self-transfer appears in both directional views. Rows are newest-first by `(blockNumber, txIndex, logIndex, transferIndex)`; `nextCursor` is an exclusive continuation boundary and must be passed back unchanged. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: path required: true schema: type: string example: "0x0123456789abcdef" - name: direction in: query description: | Optional direction relative to the path address: `any`, `in`, or `out`. schema: type: string enum: - any - in - out default: any - name: token in: query description: Optional repeated token-address filter. schema: type: array maxItems: 128 items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ style: form explode: true - name: type in: query description: Indexed transfer-standard filter. Friendly aliases `fungible`, `ft`, `nft`, and `multitoken` are accepted. schema: type: string enum: - erc20 - erc721 - erc1155 - unknown - fungible - ft - nft - multitoken - name: symbol in: query description: Exact case-insensitive indexed token-symbol filter. Ambiguous symbols matching more than 128 contracts fail closed. schema: type: string minLength: 1 maxLength: 64 - name: timestampFrom in: query description: Inclusive lower timestamp resolved once through the indexed block-timestamp read model before transfer pagination. schema: oneOf: - type: string format: date-time - type: integer format: int64 - name: invocationType in: query description: Case-insensitive indexed transaction-type filter for the transfer's transaction. Canonical values are `DECLARE`, `DEPLOY`, `DEPLOY_ACCOUNT`, `INVOKE`, and `L1_HANDLER`; Xverse aliases such as `execute` are normalized to `INVOKE`. schema: type: string - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: | Optional opaque continuation cursor returned by `nextCursor`. The current representation is `block:tx:log:transfer`; pass it back unchanged and do not construct or advance it client-side. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Address transfer page content: application/json: schema: $ref: "#/components/schemas/GlobalTransferPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Addresses /v1/{chain}/token/{token}: get: summary: Token aggregate summary description: "Token metadata plus versioned transfer aggregates. Read `summaryCacheStatus` before interpreting counts: `stale` aggregates can lag the independently indexed transfer feed, while `metadata_only` returns null aggregate counts and can still expose an independently known `latestTransferBlock`. Never coerce unavailable counts to zero." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token summary content: application/json: schema: $ref: "#/components/schemas/TokenSummaryView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/total-supply: get: summary: Standard-token totalSupply read security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - name: block_tag in: query description: State reference used for call execution. Use `latest` or `pending` for live reads, or pass a block number/hash for deterministic correctness checks. schema: allOf: - $ref: "#/components/schemas/BlockReference" default: latest example: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Standard-token totalSupply result content: application/json: schema: $ref: "#/components/schemas/TokenTotalSupplyView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract does not expose a supported totalSupply selector headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: certified x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/balance-of/{address}: get: summary: Standard-token balanceOf read security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - name: address in: path required: true schema: type: string example: "0x00ca1702e64c81d9a07b86bd2c540188d92a2c73cf5cc0e508d949015e7e84a7" - name: block_tag in: query description: State reference used for call execution. Use `latest` or `pending` for live reads, or pass a block number/hash for deterministic correctness checks. schema: allOf: - $ref: "#/components/schemas/BlockReference" default: latest example: latest - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Standard-token balanceOf result content: application/json: schema: $ref: "#/components/schemas/TokenBalanceOfView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Contract does not expose a supported balanceOf selector headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: certified x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/holders: get: summary: Gap-free token-holder pagination over an immutable indexed generation description: |- Partner-tier endpoint for token-contract-first holder enumeration. The first page selects a sealed finalized holder generation and v3 cursors retain that generation under concurrent transfers until `snapshot.expiresAt`. The default cursor/retired-generation retention is six hours; the response deadline is authoritative. An unchanged active generation does not expire merely because no transfer arrived. Follow `nextCursor` to null and require one stable snapshot identity plus contiguous ranks through `holderCount` for a complete walk. The offline universe records every indexed ERC-20 token discovered from finalized fungible balances or ERC-20 metadata, but discovery does not make a token eligible for holder enumeration. A token must have a current explicit address-keyed policy; otherwise this route returns terminal `422` `unqualified_token_policy`, without `Retry-After`. That is distinct from an eligible priority token's intentionally redacted `200`, and from a retryable eligible-token `503`. Results come from Starkscan's indexed ledger, not a request-time transfer scan or RPC enumeration. RPC has no all-holder enumeration method; `balanceOf` is used only for bounded deterministic certification samples at the exact snapshot block hash. Before a new reconstruction-backed complete generation can publish, its private generation-bound import must carry paired exact-block total-supply and zero-address observations for that generation's `snapshot.asOfBlockHash`. They must be U256 values that conserve `totalSupply = holderBalanceTotalRaw + zeroAddressBalance`; missing, unpaired, or non-conserving observations reject promotion. These import witnesses are not public response fields and do not alone prove adapter behavior or that no holder was omitted. For an address-keyed priority token, an unavailable, stale, or uncertified current generation is an intentional redaction. A legacy receipt without the two current count witnesses is likewise not generation certification. Any intentionally redacted public page has a zero count and empty rows only as an unavailable signal, never as an empty-population claim, and uses `Cache-Control: no-store`. Immutable rows do not make correctness authority immutable. Historical source corrections can invalidate an unexpired generation's proof: `populationComplete` and `exact` then become false, including on retained cursor pages. Recheck truth metadata on every page; an earlier certified page does not authorize a later page. Priority pages remain redacted until complete generation-bound certification is restored. Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - name: cursor in: query description: | Optional opaque v3 cursor returned unchanged from `nextCursor` in the previous response. It is scoped to one chain, token, immutable generation, block identity, row anchor, and expiry. Never parse or construct it. Invalid, cross-scope, revoked, or expired cursors return typed `400 invalid_request` restart guidance and never fall back to the first page. A temporarily unavailable holder generation returns retryable `503 service_unavailable` with `Retry-After`; retry the same cursor rather than restarting the walk. schema: type: string maxLength: 512 - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: | One immutable holder-generation page. Ordinary pagination does not set `completeness.truncated`; `nextCursor` alone describes page coverage, while `completeness.exact` and `certification` describe correctness of the full generation. A priority-token redaction is still a typed `200` page, but it is `no-store` and must not be cached or interpreted as an empty population. headers: Cache-Control: description: | `no-store` for any intentional public redaction, including a priority token without a current witnessed certificate or a terminal certification state. A non-redacted ordinary holder page uses its normal response cache policy. schema: type: string content: application/json: schema: $ref: "#/components/schemas/TokenHolderPage" examples: immutableGeneration: summary: Certified first page with more immutable rows value: chainId: SN_MAIN tokenAddress: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" snapshot: asOfBlock: 1212345 asOfBlockHash: "0x5d95f8c55a274d08af88f12d4769f89d50fd9a6efcbe3c0e9730f5c8d7c0f21" generationId: 418 rowDigest: sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa expiresAt: '2026-08-12T14:45:00Z' updatedAt: '2026-08-12T08:45:00Z' lagBlocks: 45 source: sealed_finalized_holder_generation freshness: finalized_generation holderCount: 1179667 holderBalanceTotalRaw: "10000000000000000000000000000" items: - rank: 1 address: "0x123" balanceRaw: "1472447970720000000000000000" lastUpdatedBlock: 1212300 lastUpdatedTimestampIso: '2026-08-12T08:30:00Z' nextCursor: djM6b3BhcXVlLWltbXV0YWJsZS1jdXJzb3I completeness: populationComplete: true populationReasonCode: complete_canonical_transfer_coverage exact: true truncated: false reasonCode: materialized_snapshot certification: status: certified validatedAgainst: starknet_rpc_balanceOf checkedAt: '2026-08-12T09:00:00Z' reasonCode: materialized_snapshot limits: maxPageSize: 100 tier: partner priorityRedacted: summary: Priority token withheld until its current generation is complete and certified value: chainId: SN_MAIN tokenAddress: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" snapshot: asOfBlock: 1212345 asOfBlockHash: "0x5d95f8c55a274d08af88f12d4769f89d50fd9a6efcbe3c0e9730f5c8d7c0f21" generationId: 419 rowDigest: sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb expiresAt: '2026-08-12T14:45:00Z' updatedAt: '2026-08-12T08:45:00Z' lagBlocks: 45 source: sealed_finalized_holder_generation freshness: finalized_generation holderCount: 0 holderBalanceTotalRaw: null items: [] nextCursor: null completeness: populationComplete: false populationReasonCode: population_coverage_unproven exact: false truncated: false reasonCode: certification_not_run certification: status: uncertified validatedAgainst: null checkedAt: null reasonCode: certification_not_run limits: maxPageSize: 100 tier: partner "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": $ref: "#/components/responses/TokenHolderPolicyReviewRequired" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: partner x-starkscan-key-tier: partner tags: - Tokens /v1/{chain}/token/{token}/holders/screening: get: summary: Bounded immutable top-holder screening projection description: Partner-tier whale screening backed only by an offline immutable top-K projection. K is assigned only by the current address-keyed policy (200, 100, 50, or 10 for the launch cohort); discovered tokens have no default screening depth. An unreviewed token returns terminal `422` `unqualified_token_policy`, without `Retry-After`. Page size remains at most 100. Exhausting `nextCursor` proves only that this projection is exhausted, never that the token's holder population is complete. The response therefore keeps `screening.populationComplete=false` and `screening.exact=false`. Use `/holders` and its coverage plus certification evidence for a complete exact walk. Both routes use balance-descending, canonical-address ordering and make no request-time RPC or historical scan. When no immutable screening generation is published yet, the route returns a retryable `503` with `Retry-After`. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - name: cursor in: query description: | Opaque generation-bound cursor returned by the previous screening page. Pass it back unchanged before `snapshot.expiresAt`; the service default retention is six hours, but that timestamp is authoritative. Restart from page one after expiry. schema: type: string maxLength: 512 - name: limit in: query description: Page size (clamped to 1..100); this does not change policy Top-N. schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: One immutable bounded screening page. content: application/json: schema: $ref: "#/components/schemas/TokenHolderScreeningPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "422": $ref: "#/components/responses/TokenHolderPolicyReviewRequired" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: partner x-starkscan-key-tier: partner tags: - Tokens /v1/{chain}/token/{token}/holders/analytics: get: summary: Generation-bound token holder concentration analytics description: |- Returns concentration metrics computed from the complete sealed holder generation, never from the loaded holder page. Generation-bound results repeat `generationId`, `asOfBlock`, `asOfBlockHash`, and `rowDigest` so consumers can prove that analytics and holder pages refer to the same population. `expiresAt` is a response-specific continuation deadline, not part of the durable generation identity. `computedAt` records the offline refresh time. Missing generation identity or `completeness.exact=false` is a degraded signal, not a fresh exact analytics claim. The request path performs no holder scan or RPC call. A token without a current explicit address-keyed holder policy returns terminal `422` `unqualified_token_policy`, without `Retry-After`; it is neither a degraded analytics `200` nor a retryable eligible-token `503`. Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token holder analytics snapshot content: application/json: schema: $ref: "#/components/schemas/TokenHolderAnalyticsSnapshot" examples: generationBoundAnalytics: summary: Exact analytics for the immutable holder generation value: chainId: SN_MAIN tokenAddress: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" snapshot: asOfBlock: 1212345 asOfBlockHash: "0x5d95f8c55a274d08af88f12d4769f89d50fd9a6efcbe3c0e9730f5c8d7c0f21" generationId: 418 rowDigest: sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa expiresAt: '2026-08-12T14:45:00Z' updatedAt: '2026-08-12T08:45:00Z' lagBlocks: 45 source: sealed_finalized_holder_generation freshness: finalized_generation holderCount: 1179667 computedAt: '2026-08-12T08:45:00Z' metrics: holderBalanceTotalRaw: "10000000000000000000000000000" top5BalanceRaw: "3000000000000000000000000000" top10BalanceRaw: "3800000000000000000000000000" top100BalanceRaw: "6200000000000000000000000000" top5ShareBps: 3000 top10ShareBps: 3800 top100ShareBps: 6200 whaleCount: 14 whaleShareBps: 2600 giniScorePpm: 811000 nakamoto50Count: 9 holdersAbove1Percent: 14 tierDistribution: - tier: Whale minShareBps: 100 holderCount: 14 shareBps: 2600 - tier: Shark minShareBps: 10 holderCount: 190 shareBps: 2100 - tier: Dolphin minShareBps: 1 holderCount: 4800 shareBps: 1800 - tier: Long tail minShareBps: 0 holderCount: 1174663 shareBps: 3500 thresholdCounts: - label: ">=1%" thresholdBps: 100 holderCount: 14 - label: ">=0.1%" thresholdBps: 10 holderCount: 202 - label: ">=0.01%" thresholdBps: 1 holderCount: 5002 completeness: populationComplete: true populationReasonCode: complete_canonical_transfer_coverage exact: true truncated: false reasonCode: materialized_snapshot "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "422": $ref: "#/components/responses/TokenHolderPolicyReviewRequired" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: partner x-starkscan-key-tier: partner tags: - Tokens /v1/{chain}/token/{token}/controls: get: summary: Indexed token control facts description: Returns the latest operator-materialized token control snapshot. Results are served from `token_controls_snapshot`; the request path does not run live RPC, public explorer calls, request-time ABI probes, or Account Calls. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token controls snapshot or a typed not-indexed response content: application/json: schema: $ref: "#/components/schemas/TokenControlsView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/markets/pools: get: summary: Materialized token DEX pool facts description: |- Partner-tier endpoint for token-contract-first pool facts. Rows are served from `token_market_pool_snapshot`; token-level totals are served from the materialized rollup and are not recomputed on request. The route never performs request-time DEX, RPC, transfer, or Account Calls probes. Partner-tier route backed by materialized serving tables. It is intended for bounded indexed reads and must not run request-time scans or repairs. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token market pool page content: application/json: schema: $ref: "#/components/schemas/TokenMarketPoolPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Token contract not found or not recognized as a fungible token. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Tokens /v1/{chain}/token/{token}/transfers: get: summary: Paginated token transfers with optional address and block filters description: "Rows are newest-first by `(blockNumber, txIndex, logIndex, transferIndex)`. `nextCursor` is an exclusive continuation boundary and must be passed back unchanged. List rows may intentionally omit historical USD enrichment (`historicalUsd: null`); null is not a current or zero price." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: token in: path required: true schema: type: string example: "0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" - name: address in: query description: Optional repeated wallet/address filter; matches transfers where either side is in the supplied set. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: | Optional exclusive cursor returned by `nextCursor` in `block:tx:log:transfer` numeric format. Pass it back unchanged. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Token transfer page content: application/json: schema: $ref: "#/components/schemas/TokenTransferPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Tokens /v1/{chain}/events: get: summary: Paginated raw events with optional address, positional key, and block filters description: "Protocol-neutral indexed event search. `topic0..topic15` address exact key positions: repeated values at one position are OR alternatives, populated positions are ANDed, and omitted positions are wildcards. Each position accepts at most 128 distinct felts and the request accepts at most 256 total. `key`, `keys`, and `keys[]` are intentionally rejected on this global route because they do not identify a key position. Any `topic1..topic15` filter requires a non-empty `topic0` plus explicit numeric `from_block` and `to_block` values. Ordinary read keys may span at most 10,000 blocks inclusive; DB-backed Wallet workspaces use the positional index for every numeric subrange within retained, declared, certified contiguous coverage, including sub-10,000-block windows. They may request larger ranges only when every requested selector has certified contiguous coverage at one common non-zero anchor position. The server chooses the populated position with the fewest requested values, breaking ties by lower position number. Additional populated later positions are applied to those anchor candidates and do not need separate coverage. A selector with no full-range declaration returns `422 full_range_selector_not_supported`; an entitled declared selector clamps an above-ceiling `to_block` to the current complete prefix and reports that clamp in `rangeCoverage`, while coverage with no complete prefix at the requested lower bound returns `503 event_key_index_coverage_unavailable`. On Sepolia, a certified pre-Explorer archive joins retained history at block `10,692,545` only after its terminal hash matches that block's parent. An archive-only query may end at block `10,692,544`; other earlier upper bounds return `503 event_key_index_coverage_unavailable` because no arbitrary historical upper-block hash is available to pin its cursor. A genesis-to-live query uses the joined range only after the boundary check. An uncertified bounded raw scan that exceeds its fixed budget returns `503 event_positional_scan_timeout`; a certified index timeout returns `503 event_positional_index_timeout`. Neither path returns a partial page. Full-range nextCursor values bind the normalized route, chain, address, block, and topic-filter scope plus the canonical hash at the proven upper block. Clients must keep the same route, chain, address, and topic filters, but may omit `from_block` and `to_block` after the first page; the server restores those bounds from the cursor's pinned snapshot before validating positional filters. If a client repeats either bound, it must match the original requested bound. A changed scope returns `409 event_cursor_scope_changed`; a head reorganization or changed range returns `409 event_cursor_snapshot_changed`. Clients restart without a cursor. Address filters do not replace the topic0 anchor. For later-position global searches, address-by-topic0 fanout is capped at 256 pairs after expanding accepted canonical and legacy felt spellings." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: query description: Optional repeated contract/address filter. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: contract in: query description: Alias for repeated `address` filters, matching Voyager-style `/events?contract=...` clients. `address`, `contract`, and `contractAddress` share one 128-item filter budget before duplicate-equivalent values are removed. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: contractAddress in: query description: Alias for repeated `address` filters. `address`, `contract`, and `contractAddress` share one 128-item filter budget before duplicate-equivalent values are removed. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: topic0 in: query description: Optional repeated exact matches for event key position 0; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic1 in: query description: Optional repeated exact matches for event key position 1; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic2 in: query description: Optional repeated exact matches for event key position 2; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic3 in: query description: Optional repeated exact matches for event key position 3; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic4 in: query description: Optional repeated exact matches for event key position 4; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic5 in: query description: Optional repeated exact matches for event key position 5; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic6 in: query description: Optional repeated exact matches for event key position 6; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic7 in: query description: Optional repeated exact matches for event key position 7; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic8 in: query description: Optional repeated exact matches for event key position 8; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic9 in: query description: Optional repeated exact matches for event key position 9; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic10 in: query description: Optional repeated exact matches for event key position 10; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic11 in: query description: Optional repeated exact matches for event key position 11; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic12 in: query description: Optional repeated exact matches for event key position 12; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic13 in: query description: Optional repeated exact matches for event key position 13; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic14 in: query description: Optional repeated exact matches for event key position 14; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: topic15 in: query description: Optional repeated exact matches for event key position 15; repeated values are OR, while populated positions are AND. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: selector in: query description: Repeated alias for `topic0`. `topic0` and `selector` share one 128-item filter budget for key position 0 before duplicate-equivalent values are removed. schema: $ref: "#/components/schemas/EventKeyFeltFilter" style: form explode: true - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: Opaque nextCursor from the previous response. Legacy block:tx:log values remain accepted for ordinary bounded searches but cannot continue a full-range walk. schema: type: string maxLength: 256 - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Global raw event page content: application/json: schema: $ref: "#/components/schemas/GlobalEventPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "409": $ref: "#/components/responses/Conflict" "410": $ref: "#/components/responses/HistoryExpired" "422": description: One or more selectors are not declared for full-range positional search. content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/transfers: get: summary: Paginated normalized transfers with optional address, token, and block filters description: "Rows are newest-first by `(blockNumber, txIndex, logIndex, transferIndex)`. `nextCursor` is an exclusive continuation boundary and must be passed back unchanged. List rows may intentionally omit historical USD enrichment (`historicalUsd: null`); null is not a current or zero price." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: address in: query description: Optional repeated wallet/address filter; matches transfers where either side is in the supplied set. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: token in: query description: Optional repeated token-address filter. schema: type: array maxItems: 128 items: type: string style: form explode: true - name: type in: query description: Indexed transfer-standard filter. Friendly aliases `fungible`, `ft`, `nft`, and `multitoken` are accepted. schema: type: string enum: - erc20 - erc721 - erc1155 - unknown - fungible - ft - nft - multitoken - name: symbol in: query description: Exact case-insensitive indexed token-symbol filter. Ambiguous symbols matching more than 128 contracts fail closed. schema: type: string minLength: 1 maxLength: 64 - name: timestampFrom in: query description: Inclusive lower timestamp resolved once through the indexed block-timestamp read model before transfer pagination. schema: oneOf: - type: string format: date-time - type: integer format: int64 - name: invocationType in: query description: Case-insensitive indexed transaction-type filter for the transfer's transaction. Canonical values are `DECLARE`, `DEPLOY`, `DEPLOY_ACCOUNT`, `INVOKE`, and `L1_HANDLER`; Xverse aliases such as `execute` are normalized to `INVOKE`. schema: type: string - name: direction in: query description: Optional direction relative to supplied address filters. Requires at least one `address` filter. schema: type: string enum: - any - in - out default: any - name: from_block in: query description: Optional inclusive lower block bound. schema: type: integer format: int64 minimum: 0 - name: to_block in: query description: Optional inclusive upper block bound. schema: type: integer format: int64 minimum: 0 - name: cursor in: query description: | Optional exclusive cursor returned by `nextCursor` in `block:tx:log:transfer` numeric format. Pass it back unchanged. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Global transfer page content: application/json: schema: $ref: "#/components/schemas/GlobalTransferPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/historical-pricing/coverage: get: summary: Prepared historical transaction-time USD coverage summary description: Returns one prepared finalized coverage row for the bounded historical pricing contract. The request never scans transfers, calls a price provider, or substitutes current/spot prices for missing transaction-time evidence. `pendingMaterializationTransfers` means an eligible transfer has no fact yet; typed-unavailable reasons are materialized facts and must not be presented as current valuations. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Prepared bounded historical-pricing coverage summary content: application/json: schema: $ref: "#/components/schemas/TokenTransferUsdCoverageSnapshot" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: No prepared coverage snapshot exists for this chain yet. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/privacy-pool/events: get: operationId: listPrivacyPoolEvents x-starkscan-stability: beta summary: Paginated privacy-pool public events description: v1 supports server-side filtering by `event` only. Contract/transaction/block filters shown in the UI are client-side over loaded windows. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: event in: query description: | Optional privacy-pool event-name filter. Use the indexed snake_case name, for example `deposit`, `proof_validity_blocks_set`, or `protocol_event`. schema: type: string maxLength: 32 pattern: ^[a-z0-9_]+$ - name: cursor in: query description: Optional cursor in `block:tx:log` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Privacy-pool event page headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolEventPage" "400": $ref: "#/components/responses/PrivacyPoolBadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/commitments: get: operationId: listPrivacyPoolCommitments x-starkscan-stability: beta summary: Paginated privacy-pool commitment facts description: Cursor-backed commitment evidence from durable privacy-pool serving tables. This endpoint exposes public commitment facts only; it does not infer ownership, linkage, balances, anonymity set size, or note state. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: pool in: query description: Optional 0x-prefixed pool contract address for a single-pool cursor scan. schema: type: string maxLength: 66 pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: Optional cursor in `block:tx:log` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Privacy-pool commitment fact page headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolCommitmentFactPage" "400": $ref: "#/components/responses/PrivacyPoolBadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/nullifiers: get: operationId: listPrivacyPoolNullifiers x-starkscan-stability: beta summary: Paginated privacy-pool nullifier facts description: Cursor-backed nullifier evidence from durable privacy-pool serving tables. This endpoint exposes public nullifier facts only; it does not infer which commitment was spent, owner linkage, balances, or anonymity set size. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: pool in: query description: Optional 0x-prefixed pool contract address for a single-pool cursor scan. schema: type: string maxLength: 66 pattern: ^0[xX][0-9a-fA-F]{1,64}$ - name: cursor in: query description: Optional cursor in `block:tx:log` numeric format. schema: type: string pattern: ^[0-9]+:[0-9]+:[0-9]+$ - name: limit in: query description: Page size (clamped to 1..100). schema: type: integer format: int32 minimum: 1 maximum: 100 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Privacy-pool nullifier fact page headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolNullifierFactPage" "400": $ref: "#/components/responses/PrivacyPoolBadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/status: get: operationId: getPrivacyPoolStatus x-starkscan-stability: beta summary: Privacy-pool public status counters description: Counter-focused public status snapshot for v1. Includes decoded counters plus raw-vs-decoded event cursor freshness so clients can detect materialization lag without querying RPC. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Privacy-pool status headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolStatusView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/analytics: get: operationId: getPrivacyPoolAnalytics x-starkscan-stability: beta summary: Privacy-pool analytics snapshot description: Low-latency analytics derived from indexed privacy-pool event rows and token metadata. This route intentionally avoids per-request RPC and external price calls; unavailable metrics explain which additional data sources or attribution rules are still required. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Privacy-pool analytics headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolAnalyticsView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/tvl: get: operationId: getPrivacyPoolTvl x-starkscan-stability: beta summary: Finalized Privacy Pool public-flow snapshot description: "Partner-oriented, versioned snapshot of public deposits minus public withdrawals from Starkscan's depth-confirmed indexed finalized tier. `finalizedOnly` does not mean L1 settlement: clients may call the snapshot L1-accepted only when `coverage.asOfL1Accepted` is true. The route reads a bounded materialized snapshot plus indexed latest-cursor and L1-acceptance evidence; it never scans event history or calls RPC on request. Raw token amounts, token addresses, and decimals are the supported integration inputs. Legacy price, valueUsd, valuation, and totalUsd fields are compatibility-only and must not be used as a new integration's pricing or accounting source. External integrations should call the authenticated https://api.starkscan.co/v1/{chain}/privacy-pool/tvl endpoint, or /api/v1/{chain}/privacy-pool/tvl on an app-origin deployment. Responses include weak ETag and Last-Modified validators. If-None-Match takes precedence over If-Modified-Since and a matching conditional read returns 304 with no body. Authenticated external responses remain private; validators reduce transfer and serialization work but do not authorize a shared cache to reuse keyed responses." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: If-None-Match in: header required: false description: Weak or strong entity tag, comma-separated tag list, or `*`. Takes precedence over If-Modified-Since. schema: type: string - name: If-Modified-Since in: header required: false description: HTTP date for a best-effort cache-generation-time check. ETag is the authoritative validator. schema: type: string format: http-date - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Finalized Privacy Pool protected-value snapshot headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" ETag: description: Weak SHA-256 validator over the exact uncompressed JSON response bytes. schema: type: string pattern: ^W/"sha256-[0-9a-f]{64}"$ Last-Modified: description: HTTP date for the in-process cache generation represented by this response. schema: type: string format: http-date Cache-Control: description: Public on the trusted same-origin lane and rewritten to private after successful external API-key authentication. schema: type: string Server-Timing: description: Includes the TVL cache outcome (`pp_tvl_cache_hit` or `pp_tvl_cache_miss`) and request-path timing metrics. schema: type: string X-Request-Id: description: Correlation identifier on authenticated private responses. Shared-cacheable trusted responses omit request-specific identifiers. schema: type: string content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolTvlView" "304": description: A supplied validator matches the current in-process cached representation. The response has no body and authentication and rate limiting still apply. headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" ETag: description: Validator for the current JSON representation. schema: type: string pattern: ^W/"sha256-[0-9a-f]{64}"$ Last-Modified: description: HTTP date for the current in-process cache generation. schema: type: string format: http-date Cache-Control: description: Cache policy for the authenticated request lane. schema: type: string Server-Timing: description: Includes the TVL cache outcome and request-path timing metrics for the conditional read. schema: type: string X-Request-Id: description: Correlation identifier on authenticated private responses. Shared-cacheable trusted responses omit request-specific identifiers. schema: type: string "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/PrivacyPoolServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/tvl/series: get: operationId: listPrivacyPoolTvlHourlyPoints x-starkscan-stability: beta summary: Finalized Privacy Pool hourly protected-value history description: "Oldest-first hourly cumulative public deposits minus public withdrawals from Starkscan's prepared finalized ledger. Raw address-keyed token amounts are authoritative. Historical USD fields are intentionally null: clients must apply their own token price at each point timestamp. The request path reads only bounded hourly serving rows and indexed token metadata; it never scans events or calls RPC, Voyager, or a price provider. Responses include weak ETag and Last-Modified validators. If-None-Match takes precedence over If-Modified-Since and a matching conditional read returns 304 with no body." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: from in: query required: true description: Inclusive RFC3339 timestamp aligned to a UTC hour. schema: type: string format: date-time example: '2026-08-10T00:00:00Z' - name: to in: query required: true description: Inclusive RFC3339 timestamp aligned to a UTC hour. schema: type: string format: date-time example: '2026-08-10T23:00:00Z' - name: granularity in: query required: true schema: type: string const: hour example: hour - name: cursor in: query required: false description: Opaque `nextCursor` value returned by the preceding page. schema: type: string maxLength: 512 - name: limit in: query required: false description: Hour points per page; defaults to 24. schema: type: integer minimum: 1 maximum: 24 default: 24 - name: If-None-Match in: header required: false description: Weak or strong entity tag, comma-separated tag list, or `*`. Takes precedence over If-Modified-Since. schema: type: string - name: If-Modified-Since in: header required: false description: HTTP date compared with the newest materialization timestamp in the page. ETag is authoritative. schema: type: string format: http-date - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Bounded finalized Privacy Pool hourly history page headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" ETag: description: Weak SHA-256 validator over the exact uncompressed JSON response bytes. schema: type: string pattern: ^W/"sha256-[0-9a-f]{64}"$ Last-Modified: description: Newest materialization timestamp in this page, or the Unix epoch for an empty page. schema: type: string format: http-date Cache-Control: description: Public on the trusted same-origin lane and rewritten to private after successful external API-key authentication. schema: type: string Server-Timing: description: Includes request-path timing metrics for the hourly TVL read. schema: type: string X-Request-Id: description: Correlation identifier on authenticated private responses. Shared-cacheable trusted responses omit request-specific identifiers. schema: type: string content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolTvlHourlyPageView" "304": description: A supplied validator matches the current hourly page representation. The response has no body and authentication and rate limiting still apply. headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" ETag: description: Validator for the current JSON representation. schema: type: string pattern: ^W/"sha256-[0-9a-f]{64}"$ Last-Modified: description: Newest materialization timestamp in the current page, or the Unix epoch for an empty page. schema: type: string format: http-date Cache-Control: description: Cache policy for the authenticated request lane. schema: type: string Server-Timing: description: Includes request-path timing metrics for the conditional hourly TVL read. schema: type: string X-Request-Id: description: Correlation identifier on authenticated private responses. Shared-cacheable trusted responses omit request-specific identifiers. schema: type: string "400": $ref: "#/components/responses/PrivacyPoolBadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/PrivacyPoolServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/metric-buckets: get: operationId: listPrivacyPoolMetricBuckets x-starkscan-stability: beta summary: Privacy-pool public metric buckets description: Precomputed daily buckets for tiny public-metric histograms. This route reads a bounded serving table only; it does not scan raw events, call RPC, infer ownership, link notes, or estimate anonymity k. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: limit in: query description: Number of daily buckets to return, newest-first in storage and chronological in response. schema: type: integer format: int32 minimum: 1 maximum: 90 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Privacy-pool public metric bucket page headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolMetricBucketPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/privacy-pool/metrics/series: get: operationId: getPrivacyPoolMetricSeries x-starkscan-stability: beta summary: Privacy-pool prepared metric series description: Precomputed public metric series for charting viewing-key growth and token shielded supply. This route reads prepared buckets only; it does not scan raw events on request, call RPC, infer private ownership, link notes, or estimate anonymity k. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: range in: query required: false description: Time range to return from prepared buckets. schema: type: string enum: - 24h - 7d - 30d - all default: 7d - name: granularity in: query required: false description: Prepared bucket granularity. `range=all&granularity=hour` returns the latest 720 prepared hourly buckets to keep this chart route bounded. schema: type: string enum: - hour - day - week default: day - name: token in: query required: false description: 0x-prefixed token contract address/felt for the shielded-supply series. Omit this parameter to use Starkscan's tracked strkBTC token address. schema: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ maxLength: 66 example: "0x1234" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Privacy-pool prepared metric series headers: X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/PrivacyPoolMetricSeriesPage" "400": $ref: "#/components/responses/PrivacyPoolBadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Privacy Pool /v1/{chain}/metrics/network: get: summary: Prepared Starknet network metrics description: Bounded finalized Starknet network metrics for dashboarding. This route serves metric values from prepared buckets only; it does not aggregate raw blocks, logs, or transactions on the request path, call an upstream RPC provider, or represent ERC-4337 user operations. Returned coverage and lag metadata uses one indexed finalized-tip lookup so staged backfills cannot appear as complete history. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: window in: query required: false description: | Requested prepared metrics window. Starkscan exposes product periods only: `30d`, `90d`, `ytd`, and `all`. The backend reads bounded hourly prepared buckets and returns calendar display buckets: daily for `30d`/`90d`, January-1-anchored weekly for `ytd`, and monthly for `all`. `all` is explicitly bounded to the latest 9,000 prepared hours, not full raw chain history. The response coverage timestamps remain exact prepared-source bounds, so a partial calendar bucket never appears complete. schema: type: string enum: - 30d - 90d - ytd - all default: 30d - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Prepared finalized Starknet network metric series with explicit materializer coverage status. content: application/json: schema: $ref: "#/components/schemas/NetworkMetricSeriesPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/metrics/wallets: get: summary: Prepared wallet-provider metrics description: Finalized account metrics grouped by known wallet implementation families. The route reads a prepared snapshot only. Priced fungible value is a lower bound over positive finalized balances with non-stale USD quotes; NFTs, DeFi and LP positions, lending collateral, and unpriced assets are excluded. OpenZeppelin-based accounts are an implementation family, not a wallet brand or user identity. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Prepared finalized wallet-provider metrics with explicit classification and freshness coverage. content: application/json: schema: $ref: "#/components/schemas/WalletProviderMetricPage" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/metrics/wallets/series: get: summary: Prepared wallet activity and deployment series description: "Exact finalized wallet counts per UTC calendar period, broken down by wallet family. Active wallets are distinct accounts that sent a successful INVOKE or DECLARE transaction or were the target of a successful SNIP-9 outside execution, including paymaster-forwarded execution; reverted transactions do not count. A week, month, or year is a distinct count over that period, never a sum or peak of shorter periods. New wallets are account deployments whose deploy class is a registered wallet class, or deployments confirmed as accounts by a successful DEPLOY_ACCOUNT transaction or by canonical account evidence (`is_account`), counted only inside certified class state-diff coverage. Other factory deployments of unregistered classes are not counted. A registry change or a repaired deployment inside counted history rebuilds the deployment series from its canonical facts. Active-wallet family attribution is fixed when a period is counted: completed periods keep it after a registry change, and all-time attribution moves out of `unclassified` through a bounded reclassification sweep once a wallet's class becomes resolvable, and follows a repaired deployment fact to its corrected family. A registry with more than 32 families returns 503 `wallet_family_bound_exceeded` instead of partial per-family counts. The route reads prepared rows only. A metric is null for a period whose start is outside its materializer coverage, and cumulative totals stay null until certified deployment history reaches genesis." security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: window in: query required: false description: | Requested period window: the latest 30 or 90 UTC days, the current UTC year, or all prepared history. The first period is aligned to the requested granularity. schema: type: string enum: - 30d - 90d - ytd - all default: 30d - name: granularity in: query required: false description: | Period width. Defaults to `day` for `30d` and `90d`, `week` (ISO weeks starting Monday) for `ytd`, and `month` for `all`; `year` returns UTC calendar years. `day` is rejected for `all`; `week` over `all` returns at most the newest 400 weeks. schema: type: string enum: - day - week - month - year - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Prepared finalized wallet series with per-track coverage. content: application/json: schema: $ref: "#/components/schemas/WalletMetricSeriesPage" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: beta x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Reference /v1/{chain}/prove: post: summary: Submit one STRK20 proof request description: Invite-only, mainnet-only asynchronous relay for an already formed STRK20 transaction. A mandatory Idempotency-Key absorbs safe client retries before upstream dispatch. Poll the returned jobId; a terminal unknown_delivery status is non-retryable because the prover may have received the request even though no complete response reached Starkscan. The route is absent when the relay is disabled. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: Idempotency-Key in: header required: true description: Stable unique key for this exact proof request. schema: type: string minLength: 16 maxLength: 128 example: starkscan-example-proof-request-0001 - $ref: "#/components/parameters/RequestIdHeader" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ProveRequest" examples: boundedRequest: summary: Bounded source-owned request fixture value: block_id: latest transaction: type: INVOKE transaction_hash: "0x054bfd961fb8b156c77ffa0f7882b8fcc1836753c2d3d88435b640d6300c8bd9" responses: "200": description: An idempotent replay returned the original job. content: application/json: schema: $ref: "#/components/schemas/ProveJobView" "202": description: A new proof job was accepted. content: application/json: schema: $ref: "#/components/schemas/ProveJobView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Relay disabled or unsupported chain. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "409": $ref: "#/components/responses/Conflict" "413": description: Request body exceeds the one-megabyte bound. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: operator-issued x-starkscan-key-tier: prove tags: - Reference /v1/{chain}/prove/{job_id}: get: summary: Poll one STRK20 proof job description: Returns a workspace-owned proof job. Stop polling when terminal is true. Never automatically resubmit a job whose status is unknown_delivery. The route is absent when the relay is disabled. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: job_id in: path required: true schema: type: string pattern: ^prv_[a-z0-9]{24,40}$ example: prv_0123456789abcdefghijklmn - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Current job state and terminal result or error when available. content: application/json: schema: $ref: "#/components/schemas/ProveJobView" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "404": description: Relay disabled, unsupported chain, or job not found for this workspace. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: operator-issued x-starkscan-key-tier: prove tags: - Reference /v1/me/api-keys: get: summary: List self-serve API keys for the authenticated workspace description: Returns metadata for the current workspace's self-serve Starkscan API keys. Secrets are never returned by this route. Hosted browser sessions may authenticate this safe read with Better Auth cookies or an explicit bearer session token. security: - SelfServeSession: [] - SelfServeSessionCookie: [] - SelfServeSessionCookieSecure: [] responses: "200": description: Self-serve API key list content: application/json: schema: $ref: "#/components/schemas/SelfServeApiKeyListResponse" examples: boundedResponse: summary: Empty bounded API-key list value: items: [] truncated: false "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: session parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Account post: summary: Issue or rotate the default self-serve API key for the authenticated workspace description: "Issues a live API key with read, batch, write, and verify scopes for the current workspace. Write scope is an entitlement only: execution remains gated by forwarding availability, structural payload validation, a dedicated upstream, plan limits and credits, and the global kill switch. If an active default key already exists, the old key is revoked and replaced in the same operation. This mutating route requires `Authorization: Bearer ` and rejects cookie-only calls." security: - SelfServeSession: [] responses: "200": description: Issued self-serve API key content: application/json: schema: $ref: "#/components/schemas/SelfServeIssueApiKeyResult" examples: boundedResponse: summary: Example-only API-key issuance response value: action: created plaintextKey: example-only-not-a-real-api-key apiKey: publicId: example_key_01 label: Default API key environment: live scopes: - read status: active secretHint: example maskedKey: starkscan_****_example rateLimitPolicy: policyKey: self-serve-read policyDisplayName: Self-serve read lightPerMinute: 120 heavyPerMinute: 20 burst: 20 maxActiveKeys: 2 createdAt: '2026-08-10T00:00:00Z' lastUsedAt: null expiresAt: null revokedAt: null revokedPublicIds: [] "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "403": $ref: "#/components/responses/ForbiddenSelfServeMutation" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: session parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Account /v1/me/api-keys/{public_id}: delete: summary: Revoke one self-serve API key for the authenticated workspace description: "Revokes the selected self-serve API key and returns its final metadata snapshot. This mutating route requires `Authorization: Bearer ` and rejects cookie-only calls." security: - SelfServeSession: [] parameters: - name: public_id in: path required: true schema: type: string example: example_key_01 - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Revoked self-serve API key content: application/json: schema: $ref: "#/components/schemas/SelfServeApiKeyDeleteResponse" "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "403": $ref: "#/components/responses/ForbiddenSelfServeMutation" "404": description: Self-serve API key not found headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: session tags: - Account /v1/me/redeem-code: post: summary: Redeem a single-use workspace-plan access code description: "Atomically consumes one labeled, unexpired and unrevoked access code and applies its plan to the authenticated workspace. Codes are single-use; missing, expired, revoked and already-used values share the same error. This mutating route requires `Authorization: Bearer ` and rejects cookie-only calls." security: - SelfServeSession: [] requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SelfServePartnerAccessCodeRequest" examples: documentationOnlyCode: summary: Documentation-only single-use access-code shape value: code: example-only-access-code responses: "200": description: Access code consumed and workspace plan updated content: application/json: schema: $ref: "#/components/schemas/SelfServePartnerAccessCodeResponse" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "403": $ref: "#/components/responses/ForbiddenSelfServeMutation" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: session parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Account /v1/me/usage: get: summary: Load recent self-serve API usage for the authenticated workspace description: Returns a recent usage window, per-key aggregates, recent requests, and recent failures for the current self-serve workspace. Hosted browser sessions may authenticate this safe read with Better Auth cookies or an explicit bearer session token. security: - SelfServeSession: [] - SelfServeSessionCookie: [] - SelfServeSessionCookieSecure: [] responses: "200": description: Self-serve usage snapshot content: application/json: schema: $ref: "#/components/schemas/SelfServeUsageSnapshot" examples: boundedResponse: summary: Empty bounded usage window value: windowStart: '2026-08-10T00:00:00Z' windowEnd: '2026-08-10T01:00:00Z' totalRequests: 0 totalFailures: 0 perKey: [] perKeyTruncated: false recentRequests: [] recentRequestsTruncated: false recentFailures: [] recentFailuresTruncated: false "401": $ref: "#/components/responses/UnauthorizedSelfServeSession" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: self-serve x-starkscan-key-tier: session parameters: - $ref: "#/components/parameters/RequestIdHeader" tags: - Account /v1/{chain}/search: get: summary: Universal search description: Identifier-only search remains the default. Legacy search preserves separate blocks, transactions, and addresses arrays and exact winner ordering. Opt-in mode=typed also returns bounded, chain-bound typed results for indexed identifiers, exact class hashes, canonical message hashes and related transactions, indexed token names/symbol prefixes (minimum three characters), and reviewed class-family aliases whose classes exist in the indexed catalog. For an exact address-shaped typed query that has no indexed typed match (or explicitly requests addresses), Starkscan performs one bounded existence proof through the configured chain authority and promotes the canonical padded address when the contract is live. This fallback does not scan activity or class ABIs. Confirmed nonexistence remains an empty result; missing chain authority, provider failure, or an existence-proof timeout returns the documented retryable 503 search_unavailable response. Other typed matches never trigger the fallback. It never fetches unbounded RPC or scans class ABIs. A label is discovery provenance, not verification. Multiple exact entity types are genuine collisions and clients must offer a choice rather than guess. security: - StarkscanApiKey: [] parameters: - $ref: "#/components/parameters/ChainParam" - name: q in: query required: true description: | Required exact or prefix identifier query. Missing or empty values return 400. Exact hash/address-style queries resolve first match in this order: transaction hash -> address -> block hash (single category returned). Prefix address matching reads address-activity tables only. In typed mode, an exact address-shaped miss receives one bounded live-contract existence proof and is returned as a canonical padded address when it exists; partial prefixes and non-address queries remain indexed-only. schema: type: string example: "0x054bfd961fb8b156c77ffa0f7882b8fcc1836753c2d3d88435b640d6300c8bd9" - name: mode in: query schema: type: string enum: - legacy - typed default: legacy - name: entity_types in: query description: Optional comma-separated unique typed families. Requires mode=typed; unknown or duplicate values return 400. schema: type: string maxLength: 64 example: class,message - $ref: "#/components/parameters/RequestIdHeader" responses: "200": description: Search results content: application/json: schema: $ref: "#/components/schemas/SearchView" "400": $ref: "#/components/responses/BadRequest" "401": $ref: "#/components/responses/UnauthorizedText" "403": $ref: "#/components/responses/ForbiddenText" "410": $ref: "#/components/responses/HistoryExpired" "429": $ref: "#/components/responses/RateLimited" "503": $ref: "#/components/responses/ServiceUnavailable" x-starkscan-audience: public-core x-starkscan-certification: beta x-starkscan-stability: stable x-starkscan-surface-tier: official-public-api x-starkscan-key-tier: read tags: - Search components: headers: PrivacyPoolBetaStability: description: Machine-readable lifecycle marker for the beta Privacy Pool public route. required: true schema: type: string const: beta RequestId: description: Canonical request correlation header for support and tracing. schema: type: string WwwAuthenticate: description: Authentication or scope hint when the request is rejected. schema: type: string RetryAfter: description: Seconds to wait before retrying this route class. schema: type: integer format: int64 StarkscanRouteClass: description: Route budget class for class-specific backoff. schema: type: string enum: - light - heavy - batch RateLimitLimit: description: Maximum request budget for the current route-class window. schema: type: integer format: int64 RateLimitRemaining: description: Remaining request budget for the current route-class window. schema: type: integer format: int64 RateLimitPolicy: description: Opaque rate-limit policy identifier for the current route class. schema: type: string securitySchemes: StarkscanApiKey: type: apiKey in: header name: X-Starkscan-Api-Key description: External Starkscan API key header. Required access tier and scope are defined per operation. SelfServeSession: type: http scheme: bearer bearerFormat: Better Auth session token description: Session token for authenticated self-serve workspace routes. Hosted browser safe reads can also use Better Auth session cookies, but mutating /v1/me/* routes require an explicit bearer token. SelfServeSessionCookie: type: apiKey in: cookie name: better-auth.session_token description: Better Auth session cookie accepted for hosted same-origin safe reads on /v1/me/*. SelfServeSessionCookieSecure: type: apiKey in: cookie name: __Secure-better-auth.session_token description: Secure Better Auth session cookie accepted for hosted same-origin safe reads on /v1/me/*. parameters: ChainParam: name: chain in: path required: true schema: type: string example: SN_MAIN VerificationJobId: name: job_id in: path required: true schema: type: string pattern: ^vrf_[a-z0-9]{24,40}$ example: vrf_0123456789abcdefghijklmn RequestIdHeader: name: X-Request-Id in: header required: false description: Optional caller-supplied correlation ID echoed back in the response. schema: type: string responses: BadRequest: description: Invalid request shape, path parameter, query parameter, or body. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" NotFound: description: The requested route or resource was not found. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" TokenHolderPolicyReviewRequired: description: | The token has no current explicit address-keyed holder policy. This is terminal eligibility state (`code=unqualified_token_policy`), so it has no `Retry-After` and retrying cannot make the token eligible. It differs from `503`, which applies only when an eligible token's prepared generation or projection is temporarily unavailable. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" examples: policyReviewRequired: value: code: unqualified_token_policy message: Token holder enumeration requires an explicit address-keyed policy review docSlug: api/errors requestId: null ForbiddenSelfServeMutation: description: Cookie-authenticated mutations are not allowed on self-serve routes. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" UnauthorizedText: description: Missing or invalid Starkscan credential. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" ForbiddenText: description: Valid Starkscan credential lacks the required scope. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" UnauthorizedSelfServeSession: description: Missing, invalid, or expired self-serve session. headers: X-Request-Id: $ref: "#/components/headers/RequestId" WWW-Authenticate: $ref: "#/components/headers/WwwAuthenticate" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" RateLimited: description: Rate limit hit for the current route class. headers: X-Request-Id: $ref: "#/components/headers/RequestId" Retry-After: $ref: "#/components/headers/RetryAfter" X-Starkscan-Route-Class: $ref: "#/components/headers/StarkscanRouteClass" x-ratelimit-limit: $ref: "#/components/headers/RateLimitLimit" x-ratelimit-remaining: $ref: "#/components/headers/RateLimitRemaining" x-ratelimit-policy: $ref: "#/components/headers/RateLimitPolicy" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" VerificationUploadRateLimited: description: The current route class is rate limited, the workspace already has an active upload, or both bounded upload slots are occupied. Capacity exhaustion returns error code `verification_upload_capacity_exhausted`; retry the same upload after the Retry-After delay without creating a new verification job. headers: X-Request-Id: $ref: "#/components/headers/RequestId" Retry-After: $ref: "#/components/headers/RetryAfter" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" VerificationUploadServiceUnavailable: description: Verification intake is temporarily unavailable. An upload body that provides no nonempty data chunk for 15 seconds fails closed with this response. Retry the same job and exact archive after the Retry-After delay. If a later retry returns 409 because that job no longer accepts uploads, create a new verification job instead of replaying it again. headers: X-Request-Id: $ref: "#/components/headers/RequestId" Retry-After: $ref: "#/components/headers/RetryAfter" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" HistoryExpired: description: | The request explicitly targets Sepolia indexed history below the published rolling-history floor. Current state and preserved lifecycle facts remain available; advance to `oldestAvailableBlock` or begin a new cursor traversal. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/HistoryExpiredErrorResponse" StakingDirectoryCapacityExceeded: description: Bounded directory capacity exceeded (code staking_directory_capacity_exceeded); operator review is required, no partial ranking is returned. headers: X-Request-Id: $ref: "#/components/headers/RequestId" Retry-After: description: Minimum retry delay in seconds; this does not imply the operator has expanded the capacity. schema: type: integer enum: - 60 content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" ServiceUnavailable: description: The route is temporarily unavailable. headers: X-Request-Id: $ref: "#/components/headers/RequestId" Retry-After: $ref: "#/components/headers/RetryAfter" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" PrivacyPoolServiceUnavailable: description: The Privacy Pool route is temporarily unavailable. headers: X-Request-Id: $ref: "#/components/headers/RequestId" X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" Retry-After: $ref: "#/components/headers/RetryAfter" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" IndexingFreshnessDegraded: description: Indexing is stale or required freshness evidence is unavailable or inconsistent. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/IndexingFreshnessHealthView" ContractVerificationDegraded: description: Verification is disabled or its controller, queue, staged receipt, retention, or bounded active-state evidence is outside the operational boundary. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/ContractVerificationHealthView" L1FinalityQuorumDegraded: description: Required L1 quorum evidence is missing, stale, failed, degraded, diverged, or inconsistent. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/L1FinalityQuorumHealthView" L1FinalityFreshnessDegraded: description: Settlement evidence is missing, stale, or inconsistent, or the complete materialization pipeline is missing or unhealthy. Watermark age above pipelineThresholdAgeSeconds is stale and returns HTTP 503; a healthy pipeline delayed versus the settlement target remains HTTP 200. headers: X-Request-Id: description: Canonical request correlation header for support and tracing. schema: type: string content: application/json: schema: $ref: "#/components/schemas/L1FinalityFreshnessHealthView" PrivacyPoolBadRequest: description: Invalid Privacy Pool path, query parameter, or cursor. headers: X-Request-Id: $ref: "#/components/headers/RequestId" X-Starkscan-Route-Stability: $ref: "#/components/headers/PrivacyPoolBetaStability" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" Conflict: description: The request conflicts with the current resource state. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: $ref: "#/components/schemas/ErrorResponse" schemas: VerificationPackageV1: type: object additionalProperties: false required: - selectedClassHash - uploadDigest - uploadByteLength - toolchainPolicyId - packageName - buildProfile - targetName - targetKind - artifactId - modulePath - sourceVisibility - retentionPolicyId properties: selectedClassHash: type: string pattern: ^0x(?:[1-7][0-9a-f]{0,62}|[89a-f][0-9a-f]{0,61}|80{12}(?:0[0-9a-f]{49}|10[0-9a-f]{48}|110{48}))$ uploadDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ uploadByteLength: type: integer minimum: 1 maximum: 67108864 description: Mathematically integral JSON decimal and exponent spellings are normalized to the canonical unsigned base-10 integer before validation and idempotency processing. toolchainPolicyId: type: string enum: - starkscan-exact-v1 - starkscan-exact-v2 - starkscan-exact-v3 - starkscan-exact-v4 - starkscan-exact-v5 - starkscan-exact-v6 - starkscan-exact-v7 - starkscan-exact-v8 - starkscan-exact-v9 - starkscan-exact-v10 - starkscan-exact-v11 - starkscan-exact-v12 - starkscan-exact-v13 - starkscan-exact-v14 - starkscan-exact-v15 - starkscan-exact-v16 - starkscan-exact-v17 - starkscan-exact-v18 - starkscan-exact-v19 - starkscan-exact-v20 - starkscan-exact-v21 - starkscan-exact-v22 - starkscan-exact-v23 - starkscan-exact-v24 - starkscan-exact-v25 packageName: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$ buildProfile: type: string enum: - release targetName: type: string minLength: 1 maxLength: 256 pattern: ^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$ targetKind: type: string enum: - starknet-contract artifactId: type: string minLength: 1 maxLength: 256 pattern: ^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$ modulePath: type: string minLength: 1 maxLength: 256 pattern: ^[A-Za-z0-9][A-Za-z0-9_.:/-]{0,255}$ sourceVisibility: type: string enum: - private - public description: Public selects public-30d-v1 intake retention; Package V1 does not publish source or record redistribution rights. retentionPolicyId: type: string enum: - private-24h-v1 - private-7d-v1 - public-30d-v1 description: Source-retention policy. Source publication is a separate explicit contract and is not implemented by Package V1. allOf: - if: properties: sourceVisibility: const: public required: - sourceVisibility then: properties: retentionPolicyId: const: public-30d-v1 else: properties: retentionPolicyId: enum: - private-24h-v1 - private-7d-v1 VerificationJob: type: object additionalProperties: false required: - jobRef - chainId - selectedClassHash - uploadDigest - uploadByteLength - toolchainPolicyId - sourceVisibility - retentionPolicyId - state - reasonCode - retryable - createdAt - uploadExpiresAt - occurredAt - receiptId - receiptBundleDigest properties: jobRef: type: string pattern: ^vrf_[a-z0-9]{24,40}$ chainId: type: string enum: - SN_MAIN selectedClassHash: type: string uploadDigest: type: string uploadByteLength: type: integer toolchainPolicyId: type: string enum: - starkscan-exact-v1 - starkscan-exact-v2 - starkscan-exact-v3 - starkscan-exact-v4 - starkscan-exact-v5 - starkscan-exact-v6 - starkscan-exact-v7 - starkscan-exact-v8 - starkscan-exact-v9 - starkscan-exact-v10 - starkscan-exact-v11 - starkscan-exact-v12 - starkscan-exact-v13 - starkscan-exact-v14 - starkscan-exact-v15 - starkscan-exact-v16 - starkscan-exact-v17 - starkscan-exact-v18 - starkscan-exact-v19 - starkscan-exact-v20 - starkscan-exact-v21 - starkscan-exact-v22 - starkscan-exact-v23 - starkscan-exact-v24 - starkscan-exact-v25 sourceVisibility: type: string enum: - private - public description: Public selects public-30d-v1 intake retention; it does not make source bytes public. retentionPolicyId: type: string description: Resolved source-retention policy; Package V1 does not grant source-publication rights. state: type: string enum: - awaiting_upload - validating - queued - building - comparing - succeeded - mismatch - failed - cancelled - expired reasonCode: type: - string - "null" retryable: type: boolean createdAt: type: string format: date-time uploadExpiresAt: type: string format: date-time occurredAt: type: string format: date-time receiptId: type: - integer - "null" receiptBundleDigest: type: - string - "null" PortableVerificationReceipt: type: object additionalProperties: false required: - schemaVersion - algorithm - keyId - evidence - signature properties: schemaVersion: type: string enum: - starkscan-portable-verification-receipt-v1 algorithm: type: string enum: - Ed25519 keyId: type: string pattern: ^[A-Za-z0-9._:-]{1,128}$ evidence: type: object additionalProperties: false required: - jobId - chainId - classHash - receiptId - verification - sourceArchiveDigest - toolchainPolicyId - candidateDigest - declaration - proofScope - notProofOf - issuedAt properties: jobId: type: string pattern: ^vrf_[a-z0-9]{24,40}$ chainId: type: string enum: - SN_MAIN - SN_SEPOLIA classHash: type: string pattern: ^0x(?:[1-7][0-9a-f]{0,62}|[89a-f][0-9a-f]{0,61}|80{12}(?:0[0-9a-f]{49}|10[0-9a-f]{48}|110{48}))$ receiptId: type: integer minimum: 1 description: Mathematically integral JSON decimal and exponent spellings are normalized to the canonical unsigned base-10 integer before receipt validation and signature verification. verification: type: string enum: - verified_exact sourceArchiveDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ toolchainPolicyId: type: string enum: - starkscan-exact-v1 - starkscan-exact-v2 - starkscan-exact-v3 - starkscan-exact-v4 - starkscan-exact-v5 - starkscan-exact-v6 - starkscan-exact-v7 - starkscan-exact-v8 - starkscan-exact-v9 - starkscan-exact-v10 - starkscan-exact-v11 - starkscan-exact-v12 - starkscan-exact-v13 - starkscan-exact-v14 - starkscan-exact-v15 - starkscan-exact-v16 - starkscan-exact-v17 - starkscan-exact-v18 - starkscan-exact-v19 - starkscan-exact-v20 - starkscan-exact-v21 - starkscan-exact-v22 - starkscan-exact-v23 - starkscan-exact-v24 - starkscan-exact-v25 candidateDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ declaration: type: object additionalProperties: false required: - blockNumber - blockHash - transactionHash - compiledClassHash properties: blockNumber: type: integer minimum: 0 description: Mathematically integral JSON decimal and exponent spellings are normalized to the canonical unsigned base-10 integer before receipt validation and signature verification. blockHash: type: string pattern: ^0x(?:[1-7][0-9a-f]{0,62}|[89a-f][0-9a-f]{0,61}|80{12}(?:0[0-9a-f]{49}|10[0-9a-f]{48}|110{48}))$ transactionHash: type: string pattern: ^0x(?:[1-7][0-9a-f]{0,62}|[89a-f][0-9a-f]{0,61}|80{12}(?:0[0-9a-f]{49}|10[0-9a-f]{48}|110{48}))$ compiledClassHash: type: string pattern: ^0x(?:[1-7][0-9a-f]{0,62}|[89a-f][0-9a-f]{0,61}|80{12}(?:0[0-9a-f]{49}|10[0-9a-f]{48}|110{48}))$ proofScope: type: string enum: - exact_source_rebuild_equals_finalized_declared_class notProofOf: type: array minItems: 5 maxItems: 5 uniqueItems: true items: type: string enum: - security - audit - official_attribution - deployment_configuration - current_address_class issuedAt: type: string format: date-time signature: type: string pattern: ^[A-Za-z0-9_-]{86}$ HostedPortableVerificationReceipt: description: Hosted public-verification receipt. Package tooling may validate additional chains locally, but the hosted service currently admits only SN_MAIN jobs. allOf: - $ref: "#/components/schemas/PortableVerificationReceipt" - type: object properties: evidence: type: object properties: chainId: type: string const: SN_MAIN EventKeyFeltFilter: type: array maxItems: 128 items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ SequentialEventKeyCompatibilityFilter: type: array maxItems: 15 items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ StakingRatio: type: object additionalProperties: false required: - numeratorRaw - denominatorRaw properties: numeratorRaw: type: string pattern: ^[0-9]+$ denominatorRaw: type: string pattern: ^[1-9][0-9]*$ StakingCoverage: type: object additionalProperties: false required: - status - reasonCode - finalizedOnly - materializedThroughBlock - materializedThroughHash - sourceLatestFinalizedBlock - lagBlocks - activityHistoryTruncated - gapIntervals - outstandingMaterializationIntervals - metricDefinitionVersion - lastSuccessfulRunAtIso properties: status: type: string enum: - prepared - catching_up - unavailable reasonCode: type: string finalizedOnly: type: boolean const: true materializedThroughBlock: type: - integer - "null" format: int64 minimum: 0 materializedThroughHash: type: - string - "null" sourceLatestFinalizedBlock: type: - integer - "null" format: int64 minimum: 0 description: Finalized source head recorded when this prepared snapshot was published, not the current chain head. lagBlocks: type: - integer - "null" format: int64 minimum: 0 description: Gap to sourceLatestFinalizedBlock at publication. Compare lastSuccessfulRunAtIso with current time before treating this as current lag. activityHistoryTruncated: type: boolean description: True when the prepared activity feed retains only its newest bounded window; full finalized history remains in the immutable source ledger. gapIntervals: type: array items: $ref: "#/components/schemas/StakingCoverageGap" outstandingMaterializationIntervals: type: array items: $ref: "#/components/schemas/StakingCoverageGap" metricDefinitionVersion: type: - string - "null" lastSuccessfulRunAtIso: type: - string - "null" format: date-time StakingCoverageGap: type: object additionalProperties: false required: - reasonCode - fromBlock - throughBlock - terminal properties: reasonCode: type: string minLength: 1 fromBlock: type: - integer - "null" format: int64 minimum: 0 throughBlock: type: - integer - "null" format: int64 minimum: 0 terminal: type: boolean StakingTokenAmount: type: object additionalProperties: false required: - tokenAddress - symbol - decimals - selfStakeRaw - delegatedStakeRaw - totalStakeRaw - pendingExitRaw - networkShare - metricValueReason properties: tokenAddress: type: string symbol: type: - string - "null" decimals: type: - integer - "null" minimum: 0 maximum: 255 selfStakeRaw: type: - string - "null" pattern: ^[0-9]+$ delegatedStakeRaw: type: - string - "null" pattern: ^[0-9]+$ totalStakeRaw: type: - string - "null" pattern: ^[0-9]+$ pendingExitRaw: type: - string - "null" pattern: ^[0-9]+$ networkShare: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" metricValueReason: type: - string - "null" StakingPool: type: object additionalProperties: false required: - tokenAddress - address - generationRaw - status - commission - top1Share - top5Share - hhi - metricValueReason properties: tokenAddress: type: string address: type: string generationRaw: type: string pattern: ^[0-9]+$ status: type: string enum: - active - retired commission: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" description: Exact fee for this pool generation only; null does not imply zero or a validator-wide fee. top1Share: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" top5Share: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" hhi: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" metricValueReason: type: - string - "null" StakingNetworkToken: type: object additionalProperties: false required: - tokenAddress - symbol - decimals - totalStakeRaw - nakamoto33Count - metricValueReason properties: tokenAddress: type: string symbol: type: - string - "null" decimals: type: - integer - "null" minimum: 0 maximum: 255 totalStakeRaw: type: - string - "null" pattern: ^[0-9]+$ nakamoto33Count: type: - integer - "null" format: int64 minimum: 1 metricValueReason: type: - string - "null" StakingAddressHistory: type: object additionalProperties: false required: - role - address - effectiveFromBlock - effectiveFromBlockHash - effectiveFromTxIndex - effectiveFromTxHash - effectiveFromLogIndex - effectiveFromFactIndex - emitterAddress - contractClassHash - decoderVersion - decoderFingerprint - finality - callPath - callPathReasonCode - effectiveToBlock properties: role: type: string enum: - reward - operational address: type: string effectiveFromBlock: type: integer format: int64 minimum: 0 effectiveFromBlockHash: type: string effectiveFromTxIndex: type: integer format: int32 minimum: 0 effectiveFromTxHash: type: string effectiveFromLogIndex: type: integer format: int32 minimum: 0 effectiveFromFactIndex: type: integer format: int32 minimum: 0 emitterAddress: type: string contractClassHash: type: string decoderVersion: type: string minLength: 1 decoderFingerprint: type: string pattern: ^sha256:[0-9a-f]{64}$ finality: type: string const: finalized callPath: {} callPathReasonCode: {} effectiveToBlock: type: - integer - "null" format: int64 minimum: 0 allOf: - $ref: "#/components/schemas/StakingCallPathAvailability" StakingCallPathAvailability: oneOf: - type: object required: - callPath - callPathReasonCode properties: callPath: type: array items: type: integer minimum: 0 callPathReasonCode: type: "null" - type: object required: - callPath - callPathReasonCode properties: callPath: type: "null" callPathReasonCode: type: string const: call_path_unavailable StakingDelegator: type: object additionalProperties: false required: - validatorGenerationId - validatorAddress - tokenAddress - poolAddress - address - delegatedRaw - pendingExitRaw - status - share properties: validatorGenerationId: type: string pattern: ^sha256:[0-9a-f]{64}$ validatorAddress: type: string tokenAddress: type: string poolAddress: type: string address: type: string delegatedRaw: type: string pattern: ^[0-9]+$ pendingExitRaw: type: - string - "null" pattern: ^[0-9]+$ status: type: string enum: - active - exiting share: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" StakingActivity: type: object additionalProperties: false required: - validatorGenerationId - validatorAddress - blockNumber - transactionIndex - logIndex - factIndex - transactionHash - timestampIso - emitterAddress - contractClassHash - decoderVersion - finality - callPath - callPathReasonCode - kind - participantAddress - tokenAddress - amountRaw properties: validatorGenerationId: type: string pattern: ^sha256:[0-9a-f]{64}$ validatorAddress: type: string blockNumber: type: integer format: int64 minimum: 0 transactionIndex: type: integer format: int32 minimum: 0 logIndex: type: integer format: int32 minimum: 0 factIndex: type: integer minimum: 0 maximum: 32767 transactionHash: type: string timestampIso: type: string format: date-time emitterAddress: type: string contractClassHash: type: string decoderVersion: type: string minLength: 1 finality: type: string const: finalized callPath: {} callPathReasonCode: {} kind: type: string enum: - validator_registered - validator_deleted - staker_exit_intent - pool_registered - pool_retired - stake_own_balance_changed - stake_delegated_balance_changed - pool_member_registered - pool_member_balance_changed - exit_intent - exit_action - pool_member_switched participantAddress: type: - string - "null" tokenAddress: type: - string - "null" amountRaw: type: - string - "null" pattern: ^[0-9]+$ allOf: - $ref: "#/components/schemas/StakingCallPathAvailability" StakingReward: type: object additionalProperties: false required: - tokenAddress - accruedSnapshotRaw - claimedWithinCoverageRaw - coverageFromBlock - coverageThroughBlock - accountingStatus - accountingReasonCode - realizedYield - yieldStatus - yieldReasonCode properties: tokenAddress: type: string accruedSnapshotRaw: type: - string - "null" pattern: ^[0-9]+$ claimedWithinCoverageRaw: type: - string - "null" pattern: ^[0-9]+$ coverageFromBlock: type: integer format: int64 minimum: 0 coverageThroughBlock: type: integer format: int64 minimum: 0 accountingStatus: type: string enum: - exact - unavailable accountingReasonCode: type: - string - "null" realizedYield: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" yieldStatus: type: string enum: - exact - unavailable yieldReasonCode: type: - string - "null" enum: - stake_time_coverage_incomplete - reward_token_scope_unavailable - position_history_gap - null StakingValidator: type: object additionalProperties: false required: - validatorGenerationId - address - name - protocolSlug - website - status - rewardAddress - operationalAddress - commission - delegatorCount - liveness7d - liveness7dReasonCode - liveness7dFirstEpoch - liveness7dLastEpoch - liveness30d - liveness30dReasonCode - liveness30dFirstEpoch - liveness30dLastEpoch - liveness90d - liveness90dReasonCode - liveness90dFirstEpoch - liveness90dLastEpoch - attestationDelay7d - attestationDelay30d - attestationDelay90d - currentEpoch - livenessCoverageFromEpoch - livenessRevision - lastAttestationEpochRaw - missedStreak - longestMissedStreak90d - metricValueReason - stake - pools - rewards properties: validatorGenerationId: type: string pattern: ^sha256:[0-9a-f]{64}$ address: type: string name: type: - string - "null" protocolSlug: type: - string - "null" website: type: - string - "null" status: type: - string - "null" enum: - active - inactive - exiting - null rewardAddress: type: - string - "null" operationalAddress: type: - string - "null" commission: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" delegatorCount: type: - integer - "null" format: int64 minimum: 0 liveness7d: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" liveness7dReasonCode: type: - string - "null" liveness7dFirstEpoch: type: - integer - "null" format: int64 minimum: 0 liveness7dLastEpoch: type: - integer - "null" format: int64 minimum: 0 liveness30d: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" liveness30dReasonCode: type: - string - "null" liveness30dFirstEpoch: type: - integer - "null" format: int64 minimum: 0 liveness30dLastEpoch: type: - integer - "null" format: int64 minimum: 0 liveness90d: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" liveness90dReasonCode: type: - string - "null" liveness90dFirstEpoch: type: - integer - "null" format: int64 minimum: 0 liveness90dLastEpoch: type: - integer - "null" format: int64 minimum: 0 attestationDelay7d: oneOf: - $ref: "#/components/schemas/StakingAttestationDelay" - type: "null" attestationDelay30d: oneOf: - $ref: "#/components/schemas/StakingAttestationDelay" - type: "null" attestationDelay90d: oneOf: - $ref: "#/components/schemas/StakingAttestationDelay" - type: "null" currentEpoch: oneOf: - $ref: "#/components/schemas/StakingCurrentEpoch" - type: "null" livenessCoverageFromEpoch: type: - integer - "null" format: int64 minimum: 0 livenessRevision: type: - integer - "null" format: int64 minimum: 1 lastAttestationEpochRaw: type: - string - "null" pattern: ^[0-9]+$ description: Exact latest successful attestation epoch for the configured attestation class through the finalized prepared boundary. It may be present when liveness ratios are null because the eligible-epoch denominator is unavailable. missedStreak: type: - integer - "null" format: int64 minimum: 0 longestMissedStreak90d: type: - integer - "null" format: int64 minimum: 0 metricValueReason: type: - string - "null" stake: type: array maxItems: 6400 items: $ref: "#/components/schemas/StakingTokenAmount" pools: type: array maxItems: 6400 items: $ref: "#/components/schemas/StakingPool" rewards: type: array maxItems: 6400 items: $ref: "#/components/schemas/StakingReward" StakingAttestationDelay: type: object additionalProperties: false required: - sampleCount - p50Blocks - p95Blocks properties: sampleCount: type: integer format: int64 minimum: 1 p50Blocks: type: integer format: int32 minimum: 0 description: Discrete nearest-rank p50 of inclusion block minus legal window-open block. p95Blocks: type: integer format: int32 minimum: 0 description: Discrete nearest-rank p95 of inclusion block minus legal window-open block. StakingCurrentEpoch: type: object additionalProperties: false required: - epoch - state - reasonCode - windowOpenBlock - windowCloseBlock - finalized properties: epoch: type: integer format: int64 minimum: 0 state: type: string enum: - not_yet_open - pending - attested - not_eligible - unavailable reasonCode: type: - string - "null" windowOpenBlock: type: - integer - "null" format: int64 minimum: 0 windowCloseBlock: type: - integer - "null" format: int64 minimum: 0 finalized: type: boolean const: false StakingSummaryPage: type: object additionalProperties: false required: - chainId - currentEpochRaw - validatorCount - delegatorCount - networkLiveness - networkLivenessReasonCode - networkEffectiveness - networkEffectivenessReasonCode - normalizedPowerUnit - normalizationRevision - metricValueReason - tokens - tokensTruncated - coverage - source properties: chainId: type: string currentEpochRaw: type: - string - "null" currentEpochReasonCode: type: - string - "null" description: Why the authoritative current epoch is unavailable; never infer one from an attestation. validatorCount: type: - integer - "null" format: int64 minimum: 0 delegatorCount: type: - integer - "null" format: int64 minimum: 0 networkLiveness: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" networkLivenessReasonCode: type: - string - "null" networkEffectiveness: oneOf: - $ref: "#/components/schemas/StakingRatio" - type: "null" networkEffectivenessReasonCode: type: - string - "null" normalizedPowerUnit: type: - string - "null" normalizationRevision: type: - string - "null" metricValueReason: type: - string - "null" tokens: type: array maxItems: 64 items: $ref: "#/components/schemas/StakingNetworkToken" tokensTruncated: type: boolean coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_prepared_staking_snapshot StakingMetricSeriesPage: type: object additionalProperties: false required: - chainId - range - bucketGranularity - flowDefinitionVersion - items - historyCoverage - valuationCoverage - coverage - source properties: chainId: type: string range: type: string enum: - 30d - 90d - ytd - all bucketGranularity: type: string enum: - hour - day - week flowDefinitionVersion: type: string const: net_stock_change_v1 items: type: array maxItems: 20000 items: $ref: "#/components/schemas/StakingMetricSeriesItem" historyCoverage: $ref: "#/components/schemas/StakingMetricSeriesHistoryCoverage" valuationCoverage: type: array description: Per-returned-token direct historical USD coverage. An unpriced point is null, not zero. items: $ref: "#/components/schemas/StakingMetricSeriesValuationCoverage" coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_prepared_staking_snapshot_series StakingMetricSeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - tokenAddress - symbol - decimals - stakedRaw - stakedInRaw - stakedOutRaw - validatorCount - delegatorCount - latestBlockNumber - latestBlockHash - sourceKind - valuationUsd - valuationSourceId - valuationProviderAssetId - valuationAtIso properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - hour - day - week tokenAddress: type: string symbol: type: - string - "null" decimals: type: - integer - "null" minimum: 0 maximum: 255 stakedRaw: type: string pattern: ^[0-9]+$ stakedInRaw: type: string pattern: ^[0-9]+$ description: Positive component of the end-of-bucket net stock change; not gross deposits. stakedOutRaw: type: string pattern: ^[0-9]+$ description: Negative component of the end-of-bucket net stock change; not gross withdrawals. validatorCount: type: - integer - "null" format: int64 minimum: 0 delegatorCount: type: - integer - "null" format: int64 minimum: 0 latestBlockNumber: type: integer format: int64 minimum: 0 latestBlockHash: type: string sourceKind: type: string enum: - sealed_prepared_snapshot - replayed_position_activity valuationUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Exact direct historical USD value using a quote no later than bucket end for completed buckets or request time for an in-progress bucket; null when unavailable. valuationSourceId: type: - string - "null" description: Provider-neutral source identifier for the enabled exact direct historical quote used when valuationUsd is present. valuationProviderAssetId: type: - string - "null" description: Provider asset identifier from the enabled exact direct historical mapping used for valuationUsd. valuationAtIso: type: - string - "null" format: date-time StakingMetricSeriesValuationCoverage: type: object additionalProperties: false required: - tokenAddress - valuedPointCount - unpricedPointCount - firstValuedAtIso - lastValuedAtIso - unpricedIntervals properties: tokenAddress: type: string valuedPointCount: type: integer minimum: 0 unpricedPointCount: type: integer minimum: 0 firstValuedAtIso: type: - string - "null" format: date-time lastValuedAtIso: type: - string - "null" format: date-time unpricedIntervals: type: array items: type: object additionalProperties: false required: - fromIso - throughIso - reasonCode properties: fromIso: type: string format: date-time throughIso: type: string format: date-time reasonCode: type: string enum: - direct_historical_price_unavailable StakingMetricSeriesHistoryCoverage: type: object additionalProperties: false required: - requestedFromIso - preparedFromIso - preparedThroughIso - complete - reasonCode - timeGapIntervals properties: requestedFromIso: type: - string - "null" format: date-time preparedFromIso: type: - string - "null" format: date-time preparedThroughIso: type: - string - "null" format: date-time complete: type: boolean reasonCode: type: string timeGapIntervals: type: array items: type: object additionalProperties: false required: - tokenAddress - reasonCode - fromIso - throughIso properties: tokenAddress: type: string reasonCode: type: string fromIso: type: string format: date-time throughIso: type: string format: date-time StakingValidatorPage: type: object additionalProperties: false required: - chainId - items - nextCursor - coverage - source properties: chainId: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/StakingValidator" nextCursor: type: - string - "null" coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_prepared_staking_snapshot StakingValidatorDetail: type: object additionalProperties: false required: - chainId - validator - addressHistory - addressHistoryTruncated - coverage - source properties: chainId: type: string validator: oneOf: - $ref: "#/components/schemas/StakingValidator" - type: "null" addressHistory: type: array maxItems: 256 items: $ref: "#/components/schemas/StakingAddressHistory" addressHistoryTruncated: type: boolean coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_prepared_staking_snapshot StakingLivenessEpoch: type: object additionalProperties: false required: - epoch - eligibility - status - effectiveStakeRaw - targetBlock - windowOpenBlock - windowCloseBlock - inclusionBlock - inclusionBlockHash - attestationTransactionHash - attestationDelayBlocks - stakingClassHash - attestationClassHash - sourceTipBlock - sourceTipHash - derivationRevision - finalized properties: epoch: type: integer format: int64 minimum: 0 eligibility: type: string const: eligible status: type: string enum: - attested - missed effectiveStakeRaw: type: string pattern: ^[1-9][0-9]*$ targetBlock: type: integer format: int64 minimum: 0 windowOpenBlock: type: integer format: int64 minimum: 0 windowCloseBlock: type: integer format: int64 minimum: 0 inclusionBlock: type: - integer - "null" format: int64 minimum: 0 inclusionBlockHash: type: - string - "null" attestationTransactionHash: type: - string - "null" attestationDelayBlocks: type: - integer - "null" format: int32 minimum: 0 stakingClassHash: type: string attestationClassHash: type: string sourceTipBlock: type: integer format: int64 minimum: 0 sourceTipHash: type: string derivationRevision: type: string pattern: ^sha256:[0-9a-f]{64}$ finalized: type: boolean const: true StakingExactLivenessCoverage: type: object additionalProperties: false required: - status - reasonCode properties: status: type: string enum: - backfilling - ready - degraded - unavailable reasonCode: type: - string - "null" StakingLivenessHistoryPage: type: object additionalProperties: false required: - chainId - validatorAddress - validatorGenerationId - livenessRevision - items - nextCursor - exactCoverage - coverage - source properties: chainId: type: string validatorAddress: type: string validatorGenerationId: type: - string - "null" pattern: ^sha256:[0-9a-f]{64}$ livenessRevision: type: - integer - "null" format: int64 minimum: 1 items: type: array maxItems: 100 items: $ref: "#/components/schemas/StakingLivenessEpoch" nextCursor: type: - string - "null" exactCoverage: $ref: "#/components/schemas/StakingExactLivenessCoverage" coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_exact_staking_liveness StakingDelegatorPage: type: object additionalProperties: false required: - chainId - items - nextCursor - coverage - source properties: chainId: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/StakingDelegator" nextCursor: type: - string - "null" coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_prepared_staking_snapshot StakingActivityPage: type: object additionalProperties: false required: - chainId - items - nextCursor - coverage - source properties: chainId: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/StakingActivity" nextCursor: type: - string - "null" coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_prepared_staking_snapshot StakingAddressView: type: object additionalProperties: false required: - chainId - address - positions - positionsTruncated - history - nextHistoryCursor - coverage - source properties: chainId: type: string address: type: string positions: type: array maxItems: 256 items: $ref: "#/components/schemas/StakingDelegator" positionsTruncated: type: boolean history: type: array maxItems: 100 items: $ref: "#/components/schemas/StakingActivity" nextHistoryCursor: type: - string - "null" coverage: $ref: "#/components/schemas/StakingCoverage" source: type: string const: finalized_prepared_staking_snapshot BlockReference: oneOf: - type: string enum: - latest - pending - type: string pattern: ^[0-9]+$ maxLength: 19 description: Decimal block number. Must be non-negative and fit in signed 64-bit range. - type: string pattern: ^0[xX][0-9a-fA-F]{1,128}$ maxLength: 130 description: 0x-prefixed Starknet block hash/felt. description: State reference. Block hashes are validated against the Starknet field range; decimal block numbers must be non-negative signed 64-bit values. ErrorResponse: type: object description: | Machine-readable error envelope. JSON error responses also emit `X-Request-Id` as the canonical correlation header when the request has one; `requestId` mirrors it when available inside the handler. additionalProperties: false required: - code - message - docSlug - requestId properties: code: type: string enum: - invalid_request - invalid_cursor - unauthorized - forbidden - not_found - conflict - rate_limited - service_unavailable - search_unavailable - staking_directory_capacity_exceeded - event_positional_scan_timeout - event_positional_index_timeout - event_key_index_coverage_unavailable - full_range_selector_not_supported - event_cursor_scope_changed - event_cursor_snapshot_changed - unqualified_token_policy - internal_error - api_error message: type: string docSlug: type: string description: Stable docs slug agents can use for next-step guidance. requestId: type: - string - "null" description: Mirrors `X-Request-Id` when available inside the handler; the response header is canonical. maxServableToBlock: type: integer format: int64 minimum: 0 description: Highest `to_block` proved servable for the exact failed selector/key request. Present only for coverage-unavailable errors with a safe non-empty prefix. HistoryExpiredErrorResponse: type: object description: Explicit Sepolia response for a request before the certified fixed indexed-history boundary. It is distinct from an unknown resource (`404`) and from indexer lag. additionalProperties: false required: - code - message - docSlug - requestId - historyPolicy - historyCompleteness - earliestAvailableBlock - earliestAvailableAt properties: code: type: string enum: - history_expired message: type: string docSlug: type: string description: Stable docs slug agents can use for next-step guidance. requestId: type: - string - "null" description: Mirrors `X-Request-Id` when available inside the handler; the response header is canonical. historyPolicy: type: string enum: - fixed_start historyCompleteness: type: string enum: - complete_from_earliest_available retentionDays: type: integer format: int32 minimum: 1 description: Legacy rolling-window duration. Omitted for the fixed-start Sepolia policy. earliestAvailableBlock: type: integer format: int64 minimum: 0 earliestAvailableAt: type: string format: date-time JsonRpcRequest: type: object description: Starknet JSON-RPC 2.0 request object accepted by the gateway. required: - jsonrpc - method additionalProperties: true properties: jsonrpc: type: string enum: - "2.0" method: type: string params: oneOf: - type: array items: {} - type: object additionalProperties: true - type: "null" id: oneOf: - type: string - type: integer - type: "null" JsonRpcBatchRequest: type: array description: JSON-RPC batch request accepted by the gateway pilot. minItems: 1 maxItems: 50 items: $ref: "#/components/schemas/JsonRpcRequest" JsonRpcError: type: object additionalProperties: true required: - code - message properties: code: type: integer message: type: string data: description: "Optional JSON-RPC error data: either gateway-owned data, which always carries `code` and `service`, or exactly the data the Starknet spec defines for a spec error from a read or simulation method. A spec error whose spec defines no data carries none. Upstream provider fields are never forwarded." oneOf: - $ref: "#/components/schemas/JsonRpcGatewayErrorData" - $ref: "#/components/schemas/StarknetNoTraceAvailableErrorData" - $ref: "#/components/schemas/StarknetContractErrorData" - $ref: "#/components/schemas/StarknetTransactionExecutionErrorData" - $ref: "#/components/schemas/StarknetCompilationErrorData" JsonRpcGatewayErrorData: type: object description: Gateway-owned JSON-RPC error data. Additional fields are error-code-specific. additionalProperties: true required: - code - service properties: code: type: string description: Stable Starkscan machine-readable error code. requestId: type: string description: Correlation identifier for this gateway response when request handling reached the gateway error mapper. service: type: string enum: - starkscan_rpc_gateway method: type: string description: Requested JSON-RPC method when a request method was available. StarknetNoTraceAvailableErrorData: type: object description: Spec data for code 10, `NO_TRACE_AVAILABLE`. additionalProperties: false required: - status properties: status: type: string enum: - RECEIVED - REJECTED StarknetContractErrorData: type: object description: Spec data for code 40, `CONTRACT_ERROR`. additionalProperties: false required: - revert_error properties: revert_error: $ref: "#/components/schemas/StarknetContractExecutionError" StarknetTransactionExecutionErrorData: type: object description: Spec data for code 41, `TRANSACTION_EXECUTION_ERROR`. additionalProperties: false required: - transaction_index - execution_error properties: transaction_index: type: integer minimum: 0 execution_error: $ref: "#/components/schemas/StarknetContractExecutionError" StarknetCompilationErrorData: type: object description: Spec data for code 100, `COMPILATION_ERROR`. A compilation error longer than 16 KiB ends with `[truncated by Starkscan]`. additionalProperties: false required: - compilation_error properties: compilation_error: type: string StarknetContractExecutionError: description: "Spec `CONTRACT_EXECUTION_ERROR`: the raised error string, or one call frame wrapping the next. A raised error longer than 16 KiB ends with `[truncated by Starkscan]`; a call chain deeper than 64 frames ends with the string `[call chain truncated by Starkscan]` in place of its next frame." oneOf: - type: string - type: object additionalProperties: false required: - contract_address - class_hash - selector - error properties: contract_address: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ class_hash: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ selector: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ error: $ref: "#/components/schemas/StarknetContractExecutionError" JsonRpcResponse: type: object description: Starknet JSON-RPC 2.0 result or error envelope. required: - jsonrpc - id oneOf: - required: - result not: required: - error - required: - error not: required: - result additionalProperties: true properties: jsonrpc: type: string enum: - "2.0" id: oneOf: - type: string - type: integer - type: "null" result: {} error: $ref: "#/components/schemas/JsonRpcError" JsonRpcBatchResponse: type: array description: JSON-RPC batch response from the gateway, bounded to 16 MiB serialized. maxItems: 50 items: $ref: "#/components/schemas/JsonRpcResponse" AgentMemoryContract: type: object additionalProperties: true required: - kind - schemaVersion - generatedFor - auth - firstCalls - routeFamilies - workspaceMemory - operatingRules - issueReportContract properties: kind: type: string enum: - starkscan.agent_memory schemaVersion: type: string example: '2026-05-02' generatedFor: type: string enum: - agents auth: type: object additionalProperties: true required: - header - externalBasePath - defaultChain properties: header: type: string example: X-Starkscan-Api-Key externalBasePath: type: string example: /v1 defaultChain: type: string example: SN_MAIN firstCalls: type: array items: $ref: "#/components/schemas/AgentFirstCall" routeFamilies: type: array items: $ref: "#/components/schemas/AgentMemoryRouteFamily" workspaceMemory: $ref: "#/components/schemas/AgentWorkspaceMemoryContract" operatingRules: type: array items: type: string issueReportContract: $ref: "#/components/schemas/AgentIssueReportContract" AgentFirstCall: type: object additionalProperties: true required: - method - path - purpose properties: method: type: string example: GET path: type: string example: /v1/meta/capabilities purpose: type: string AgentRouteOperation: type: object additionalProperties: false required: - method - path - openapiPath - openapiMethod - openapiOperationRef - rateLimitClass - summary description: | One caller-eligible operation from the runtime correctness manifest. Use openapiOperationRef against MetaCapabilitiesView.documentation.openapiUrl as a URI fragment, percent-decode the fragment once, then use the resulting JSON Pointer to retrieve parameters, request bodies, response schemas, and examples. properties: method: type: string example: GET path: type: string example: /api/v1/{chain}/status openapiPath: type: string example: /v1/{chain}/status openapiMethod: type: string enum: - get - post - put - patch - delete - head - options example: get openapiOperationRef: type: string example: "#/paths/~1v1~1%7Bchain%7D~1status/get" rateLimitClass: type: string enum: - light - heavy - batch description: Value returned in `X-Starkscan-Route-Class` for this operation. Use it with the rate-limit response headers for class-specific backoff. summary: type: string AgentRouteFamily: type: object additionalProperties: true required: - name - tier - routes - operations - useWhen properties: name: type: string tier: type: string enum: - read - batch - verify routes: type: array minItems: 1 items: type: string operations: type: array minItems: 1 items: $ref: "#/components/schemas/AgentRouteOperation" useWhen: type: string AgentMemoryRouteFamily: type: object description: | Public route-family summary from the unauthenticated agent-memory document. Detailed operations are intentionally omitted until a caller proves its API-key scope through the capabilities endpoint. additionalProperties: true required: - name - tier - routes - useWhen properties: name: type: string tier: type: string enum: - read - batch routes: type: array minItems: 1 items: type: string useWhen: type: string CapabilitiesDocumentation: type: object additionalProperties: false required: - openapiUrl - openapiPath - openapiFormat - operationReferenceFormat - operationLookup properties: openapiUrl: type: string format: uri const: https://starkscan.co/starkscan-openapi.yaml description: Canonical public URL for the OpenAPI artifact. This is absolute because api.starkscan.co is API-only and does not serve documentation artifacts. openapiPath: type: string const: /starkscan-openapi.yaml openapiFormat: type: string const: OpenAPI 3.1 operationReferenceFormat: type: string const: URI-encoded JSON Pointer fragment operationLookup: type: string minLength: 1 MetaCapabilitiesView: type: object additionalProperties: true required: - kind - schemaVersion - defaultChain - authHeader - externalBasePath - firstCalls - documentation - rateLimit - routeFamilies - sessionControl - apiKeyLifecycle - caller - eventSearch - tokenHolders - rpcProvider - walletInteraction - operatingRules - issueReportContract description: | Authenticated capability view for agents and developers. properties: kind: type: string enum: - starkscan.meta.capabilities schemaVersion: type: string defaultChain: type: string authHeader: type: string example: X-Starkscan-Api-Key externalBasePath: type: string enum: - /v1 - /api/v1 firstCalls: type: array items: $ref: "#/components/schemas/AgentFirstCall" documentation: $ref: "#/components/schemas/CapabilitiesDocumentation" rateLimit: $ref: "#/components/schemas/CapabilitiesRateLimit" routeFamilies: type: array items: $ref: "#/components/schemas/AgentRouteFamily" sessionControl: $ref: "#/components/schemas/SessionControlCapability" apiKeyLifecycle: $ref: "#/components/schemas/ApiKeyLifecycleCapability" caller: $ref: "#/components/schemas/CallerCapabilities" eventSearch: $ref: "#/components/schemas/PositionalEventSearchCapability" tokenHolders: $ref: "#/components/schemas/TokenHolderCapability" rpcProvider: $ref: "#/components/schemas/RpcProviderCapability" walletInteraction: $ref: "#/components/schemas/WalletInteractionCapability" operatingRules: type: array items: type: string issueReportContract: $ref: "#/components/schemas/AgentIssueReportContract" TokenHolderCapability: description: | Address-keyed token-holder policy and serving contract. Availability of this block means the policy registry parsed for the advertised chain; it never certifies a holder population or grants eligibility to a token absent from both policyRegistry.items and policyRegistry.additionalQualifiedItems. oneOf: - $ref: "#/components/schemas/TokenHolderCapabilityAvailable" - $ref: "#/components/schemas/TokenHolderCapabilityUnavailable" examples: - status: available chainId: SN_MAIN identity: canonical_chain_and_token_address routeTemplate: /v1/{chain}/token/{token}/holders screeningRouteTemplate: /v1/{chain}/token/{token}/holders/screening publicPageLimit: 100 ordering: - balanceRaw_desc - canonical_address_asc cursor: opaque_generation_bound screeningTopNDoesNotTruncatePopulation: true snapshotFreshness: immutableFields: - updatedAt - lagBlocks updatedAt: generation_publication_time lagBlocks: indexed_finalized_head_minus_snapshot_block exactnessRequires: - complete_canonical_transfer_coverage - qualified_token_adapter - generation_bound_exact_block_certification unqualifiedTokenPolicy: httpStatus: 422 reasonCode: unqualified_token_policy retryable: false meaning: token holder routes require an explicit address-keyed policy review requestPathExternalCalls: false policyRegistry: schemaVersion: 1 registryId: starkscan-token-holder-policy-v1 chainId: SN_MAIN identity: canonical_chain_and_token_address defaultPolicy: qualification: unqualified_unknown_erc20 behaviorClass: unsupported adapter: unsupported certificationPolicy: policy_review_required items: - symbol: STRK tokenAddress: "0x4718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 10 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: Starknet Token netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: ETH tokenAddress: "0x49d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7" qualification: qualified_native_fee_token behaviorClass: native_fee_token adapter: starknet_eth_transfer_ledger_v1 priority: 11 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: Ether netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: USDC tokenAddress: "0x33068f6539f8e6e6b131e6b2b814e6c34a5224bc66947c47dab9dfee93b35fb" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 12 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: USD Coin (native) netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: WBTC tokenAddress: "0x3fe2b97c1fd336e750087d68b9b867997fd64a2661ff3ca5a7c771641e8e7ac" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 13 screeningTopN: 200 freshnessSloSeconds: 3600 completeGenerationSloSeconds: 86400 certificationPolicy: coverage_and_exact_block_samples_required name: Wrapped BTC netWorthEligible: true holderScreeningEnabled: true priorityTier: A adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: EKUBO tokenAddress: "0x75afe6402ad5a5c20dd25e10ec3b3986acaa647b77e4ae24b0cbc9a54a27a87" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 20 screeningTopN: 100 freshnessSloSeconds: 7200 completeGenerationSloSeconds: 172800 certificationPolicy: coverage_and_exact_block_samples_required name: Ekubo Protocol netWorthEligible: true holderScreeningEnabled: true priorityTier: B adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: USDT tokenAddress: "0x68f5c6a61780768455de69077e07e89787839bf8166decfbf92b645209c0fb8" qualification: qualified_standard_erc20 behaviorClass: standard_erc20 adapter: canonical_transfer_ledger_v1 priority: 21 screeningTopN: 100 freshnessSloSeconds: 7200 completeGenerationSloSeconds: 172800 certificationPolicy: coverage_and_exact_block_samples_required name: Tether USD netWorthEligible: true holderScreeningEnabled: true priorityTier: B adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: strkBTC tokenAddress: "0x787150e306e6eae6e3f79dea881770e8bbff2c1b8eb490f969669ee945b3135" qualification: qualified_wrapper behaviorClass: wrapper adapter: wrapper_share_transfer_ledger_v1 priority: 30 screeningTopN: 50 freshnessSloSeconds: 14400 completeGenerationSloSeconds: 259200 certificationPolicy: coverage_and_exact_block_samples_required name: strkBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: C adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: SolvBTC tokenAddress: "0x593e034dda23eea82d2ba9a30960ed42cf4a01502cc2351dc9b9881f9931a68" qualification: qualified_wrapper behaviorClass: wrapper adapter: wrapper_share_transfer_ledger_v1 priority: 40 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Solv BTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: tBTC tokenAddress: "0x4daa17763b286d1e59b97c283c0b8c949994c361e426a28f743c67bdfe9a32f" qualification: qualified_wrapper behaviorClass: wrapper adapter: wrapper_share_transfer_ledger_v1 priority: 41 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: tBTC v2 netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xstrkBTC tokenAddress: "0x47751b3532fabca89b0f2e35ca1cb45e5a7b11d5e3d3663dfa1f4406b45fd88" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 42 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xstrkBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xWBTC tokenAddress: "0x6a567e68c805323525fe1649adb80b03cddf92c23d2629a6779f54192dffc13" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 43 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xWBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xtBTC tokenAddress: "0x43a35c1425a0125ef8c171f1a75c6f31ef8648edcc8324b55ce1917db3f9b91" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 44 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xtBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. - symbol: xsBTC tokenAddress: "0x580f3dc564a7b82f21d40d404b3842d490ae7205e6ac07b1b7af2b4a5183dc9" qualification: qualified_receipt_share behaviorClass: receipt_share adapter: wrapper_share_transfer_ledger_v1 priority: 45 screeningTopN: 10 freshnessSloSeconds: 21600 completeGenerationSloSeconds: 345600 certificationPolicy: coverage_and_exact_block_samples_required name: Endur xsBTC netWorthEligible: true holderScreeningEnabled: true priorityTier: D adapterQualificationRevision: holder-adapter-policy-v1 sourceProvenance: issue: 4042 rationale: Approved address-keyed wallet and holder launch cohort. registryDigest: sha256:ffa8e206b991a6d1e3156606da77c6127cabca3c4b0fe230c622a0fcdcfc0b18 - status: unavailable chainId: SN_MAIN reasonCode: invalid_policy_registry requestPathExternalCalls: false TokenHolderCapabilityAvailable: type: object additionalProperties: true required: - status - chainId - identity - routeTemplate - screeningRouteTemplate - publicPageLimit - ordering - cursor - screeningTopNDoesNotTruncatePopulation - snapshotFreshness - exactnessRequires - unqualifiedTokenPolicy - requestPathExternalCalls - policyRegistry properties: status: type: string const: available chainId: type: string minLength: 1 identity: type: string const: canonical_chain_and_token_address routeTemplate: type: string const: /v1/{chain}/token/{token}/holders screeningRouteTemplate: type: string const: /v1/{chain}/token/{token}/holders/screening publicPageLimit: type: integer const: 100 ordering: type: array minItems: 2 maxItems: 2 prefixItems: - const: balanceRaw_desc - const: canonical_address_asc cursor: type: string const: opaque_generation_bound screeningTopNDoesNotTruncatePopulation: type: boolean const: true snapshotFreshness: $ref: "#/components/schemas/TokenHolderSnapshotFreshnessCapability" exactnessRequires: type: array minItems: 3 uniqueItems: true items: type: string minLength: 1 unqualifiedTokenPolicy: $ref: "#/components/schemas/TokenHolderUnqualifiedPolicy" requestPathExternalCalls: type: boolean const: false policyRegistry: $ref: "#/components/schemas/TokenHolderPolicyRegistry" TokenHolderCapabilityUnavailable: type: object additionalProperties: true required: - status - chainId - reasonCode - requestPathExternalCalls properties: status: type: string const: unavailable chainId: type: string minLength: 1 reasonCode: type: string enum: - policy_registry_chain_mismatch - invalid_policy_registry requestPathExternalCalls: type: boolean const: false TokenHolderSnapshotFreshnessCapability: type: object additionalProperties: false required: - immutableFields - updatedAt - lagBlocks properties: immutableFields: type: array minItems: 2 uniqueItems: true items: type: string enum: - updatedAt - lagBlocks updatedAt: type: string const: generation_publication_time lagBlocks: type: string const: indexed_finalized_head_minus_snapshot_block TokenHolderUnqualifiedPolicy: type: object additionalProperties: false required: - httpStatus - reasonCode - retryable - meaning properties: httpStatus: type: integer const: 422 reasonCode: type: string const: unqualified_token_policy retryable: type: boolean const: false meaning: type: string minLength: 1 TokenHolderPolicyRegistry: type: object additionalProperties: true description: | One address-keyed qualification registry. items contains the approved 13-token priority cohort. Optional additionalQualifiedItems contains independently reviewed all-token policies, not additional cohort members. Discovery never grants a default adapter or complete-population authority. required: - schemaVersion - registryId - chainId - identity - defaultPolicy - items - registryDigest properties: schemaVersion: type: integer minimum: 1 registryId: type: string const: starkscan-token-holder-policy-v1 chainId: type: string minLength: 1 identity: type: string const: canonical_chain_and_token_address defaultPolicy: $ref: "#/components/schemas/TokenHolderDefaultDisposition" items: type: array minItems: 1 items: $ref: "#/components/schemas/TokenHolderPolicy" additionalQualifiedItems: type: array description: | Additional explicit qualified policies outside the priority cohort. Addresses, display symbols and priorities must be unique across both arrays. The same adapter, SLO and certification rules apply. items: $ref: "#/components/schemas/TokenHolderPolicy" registryDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ TokenHolderDefaultDisposition: type: object additionalProperties: true description: | A denial disposition for tokens absent from both policyRegistry.items and policyRegistry.additionalQualifiedItems. It does not supply a default Top-N, scheduler priority, freshness SLO, or adapter authority. required: - qualification - behaviorClass - adapter - certificationPolicy properties: qualification: type: string const: unqualified_unknown_erc20 behaviorClass: type: string const: unsupported adapter: type: string const: unsupported certificationPolicy: type: string const: policy_review_required CanonicalNonzeroStarknetAddress: type: string description: Canonical compact lowercase nonzero address strictly below the Starknet field prime 2^251 + 17 * 2^192 + 1. pattern: ^0x(?:[1-9a-f][0-9a-f]{0,61}|[1-7][0-9a-f]{62}|80000000000000[0-9a-f]{49}|800000000000010[0-9a-f]{48}|8000000000000110{48})$ TokenHolderPolicy: type: object additionalProperties: false required: - symbol - name - tokenAddress - netWorthEligible - holderScreeningEnabled - priorityTier - adapterQualificationRevision - sourceProvenance - qualification - behaviorClass - adapter - priority - screeningTopN - freshnessSloSeconds - completeGenerationSloSeconds - certificationPolicy properties: symbol: type: string minLength: 1 name: type: string minLength: 1 maxLength: 128 description: Display metadata only; never the token identity. netWorthEligible: type: boolean description: Wallet selection policy, not a balance or usable-price guarantee. holderScreeningEnabled: type: boolean const: true description: Explicit reviewed holder policy; absent tokens retain the default denial disposition. priorityTier: type: string enum: - A - B - C - D - standard description: A/B/C/D select Top-200/100/50/10 and priorities 10-19/20-29/30-39/40-49; standard priorities start at 100. SLOs remain explicit policy values, not measured availability. adapterQualificationRevision: type: string const: holder-adapter-policy-v1 description: Policy interpretation revision, not a population certificate. Native and rebasing authority remains separately required. sourceProvenance: type: object additionalProperties: false required: - issue - rationale properties: issue: type: integer minimum: 1 description: Repository issue recording the canonical address selection decision. rationale: type: string minLength: 1 maxLength: 512 tokenAddress: $ref: "#/components/schemas/CanonicalNonzeroStarknetAddress" qualification: type: string pattern: ^qualified_ behaviorClass: type: string enum: - standard_erc20 - native_fee_token - wrapper - receipt_share - rebasing adapter: type: string enum: - canonical_transfer_ledger_v1 - starknet_eth_transfer_ledger_v1 - wrapper_share_transfer_ledger_v1 - rebasing_supply_ledger_v1 priority: type: integer minimum: 0 screeningTopN: type: integer minimum: 1 maximum: 200 freshnessSloSeconds: type: integer minimum: 1 completeGenerationSloSeconds: type: integer minimum: 1 certificationPolicy: type: string minLength: 1 PositionalEventSearchCapability: type: object additionalProperties: false required: - chain - positions - bounded - fullRange description: | Caller-specific positional event-search contract. The bounded path is available to ordinary read callers. External full-range search additionally requires a DB-backed Wallet workspace; the authenticated loopback internal operator lane is also entitled. Both paths require certified contiguous index coverage for every requested selector at one common non-zero anchor position. The server chooses the populated position with the fewest requested values, breaking ties by lower position number. Additional populated later positions are applied to those anchor candidates and do not need separate coverage; entitlement alone never makes incomplete index data serveable. properties: chain: type: string positions: type: object additionalProperties: false required: - minimum - maximum properties: minimum: type: integer enum: - 0 maximum: type: integer enum: - 15 bounded: type: object additionalProperties: false required: - enabled - maximumBlocksInclusive properties: enabled: type: boolean enum: - true maximumBlocksInclusive: type: integer enum: - 10000 fullRange: type: object additionalProperties: false required: - entitled - requiredWorkspacePlan - coverageContract - unsupportedResponse - unavailableResponse - coverageAvailability - selectorCoverage properties: entitled: type: boolean requiredWorkspacePlan: type: string enum: - wallet description: Required for external callers; an authenticated loopback internal caller is an explicit alternative entitlement. coverageContract: type: string enum: - certified_per_selector_position unsupportedResponse: type: string enum: - 422_full_range_selector_not_supported unavailableResponse: type: string enum: - 503_event_key_index_coverage_unavailable coverageAvailability: type: string enum: - available - partial - unavailable description: | `available` means selectorCoverage is the complete bounded lookup result and every returned row is currently ready through its observed source high-water. `partial` means the lookup succeeded but selectorCoverage is a bounded prefix or at least one returned row is stale/building/failed. Clients must use row-level servableFromBlock, maxServableToBlock, and freshnessStatus before planning a wide request, and must not infer that an omitted selector lacks coverage when this value is `partial`. `unavailable` means the lookup failed or timed out. selectorCoverage: type: array description: | Current selector-position coverage facts for this chain. Clients may send the live chain head as `to_block`; for an entitled positional full-range request above the current serving ceiling, the server clamps the complete response to the exact scope's `maxServableToBlock` and discloses both the caller's bound and the completed bound in `rangeCoverage`. Every selected topic0 must still be ready at the same anchor position, and `from_block` must be no lower than the intersected `servableFromBlock`. Before matching, clients must canonicalize each requested topic0 to compact lowercase `0x` form by lowercasing hex digits and removing leading zeroes. Padded or uppercase request spellings are accepted as filters but never appear in `selector`. The server chooses the populated anchor position with the fewest requested values, breaking ties by lower position number. Additional populated later positions are applied to the anchor candidates and do not need separate coverage. A full-range request joins adjacent tier intervals in one repeatable-read snapshot: `finalized` is the retained historical prefix and `head` is the current moving source tail. `head.fromBlock` can increase when promoted rows leave the head table; that does not mean history is absent when the preceding finalized interval is adjacent. `throughBlock` is a legacy compatibility bound that never exceeds `maxServableToBlock`; rows that start after the composite serving ceiling are omitted from this legacy collection. `tierCertifiedThroughBlock` preserves the actual tier certificate diagnostic; `servableFromBlock` and `maxServableToBlock` are the composite complete-request bounds new clients should use. The server may bridge a small moving-head certification lag with one bounded raw head-tail scan and never returns an incomplete interval as complete. The composite interval remains a gap-free union. openEnded and liveMaintenance describe a maintained projection, not an unbounded serving promise. Published raw extensions reserve at most 5,000 blocks before and 5,000 blocks after each certificate so arbitrary selector intersections remain inside the shared 10,000-block request budget. Compare sourceHighWaterBlock, sourceContiguousLowWaterBlock, sourceContiguousHighWaterBlock, lagBlocks, and freshnessStatus before planning a wide request. `stale` means the certificate trails the physical source but can still be served inside the advertised composite bounds through a proved bounded raw segment; only ranges outside those bounds receive the typed unavailable response. `unavailable` means lifecycle coverage is not ready or that tier has no indexed block watermark. items: $ref: "#/components/schemas/EventKeySelectorCoverage" maxItems: 512 EventKeySelectorCoverage: type: object additionalProperties: false required: - selector - position - sourceTier - fromBlock - throughBlock - tierCertifiedThroughBlock - openEnded - liveMaintenance - status - verifiedAt - sourceLowWaterBlock - sourceHighWaterBlock - sourceContiguousLowWaterBlock - sourceContiguousHighWaterBlock - lagBlocks - freshnessStatus - servableFromBlock - maxServableToBlock properties: selector: type: string pattern: ^0x[0-9a-f]{1,64}$ description: Canonical compact topic0 selector covered by this record. position: type: integer minimum: 1 maximum: 15 sourceTier: type: string enum: - finalized - head description: "`finalized` is the retained historical prefix. `head` is the moving current source tail and is joined to finalized coverage by the server on one repeatable-read snapshot." fromBlock: type: integer minimum: 0 description: Lowest block in this tier's contiguous certified interval. A finalized fromBlock is its retained-history floor. A head fromBlock is the current moving tail floor and can increase after finalization; it does not by itself signal a history gap. throughBlock: type: integer minimum: 0 description: Legacy compatibility upper bound for this row. When a composite serving ceiling exists, this value is clamped so it never exceeds maxServableToBlock. Rows that start after that ceiling are omitted because no non-reversed legacy interval exists for them. New clients should use maxServableToBlock for requests and tierCertifiedThroughBlock for the actual tier certificate. tierCertifiedThroughBlock: type: integer minimum: 0 description: Highest block in this tier's contiguous source/index interval verified by the most recent bounded parity certification. This is a diagnostic tier-local certificate watermark and may exceed the composite maxServableToBlock; it must not be used as a request ceiling. openEnded: type: boolean liveMaintenance: type: boolean status: type: string enum: - building - ready - failed verifiedAt: type: - string - "null" format: date-time sourceLowWaterBlock: type: - integer - "null" minimum: 0 description: Lowest physical block currently present in this source tier while capabilities were built. sourceHighWaterBlock: type: - integer - "null" minimum: 0 description: Latest indexed block observed for this source tier while capabilities were built. It is informational and may advance before coverage is certified. sourceContiguousLowWaterBlock: type: - integer - "null" minimum: 0 description: Lowest block in the gap-free source interval proved for this selector scope. Finalized rows clamp the certificate to retained physical history; head rows start after the last gap in the bounded raw-prefix window. It can exceed sourceLowWaterBlock and floors any raw-prefix extension. sourceContiguousHighWaterBlock: type: - integer - "null" minimum: 0 description: Highest block in the gap-free source interval proved for this selector scope. Finalized rows use the bounded source/index parity certificate, clamped to retained physical history; head rows additionally stop before the first gap in the bounded live-tail window. It can trail sourceHighWaterBlock and caps any raw-tail extension. lagBlocks: type: - integer - "null" minimum: 0 description: Non-negative difference between sourceHighWaterBlock and tierCertifiedThroughBlock. For head this measures the current moving-tail lag, not retained-history coverage. Null only when the source tier has no indexed high-water observation. freshnessStatus: type: string enum: - current - stale - unavailable description: "`current` means this tier's certified interval reaches its observed source high-water; `stale` means it does not; `unavailable` means lifecycle coverage is not ready or this tier has no indexed block watermark. Never infer current coverage from openEnded or liveMaintenance alone." servableFromBlock: type: - integer - "null" minimum: 0 description: Lowest block of the conservative composite finalized-plus-head interval for this selector-position scope. Null when no complete interval is currently advertised. historicalArchiveThroughBlock: type: integer minimum: 0 description: Present only for a Ready Sepolia global selector-position scope when a separately verified genesis-to-Explorer-boundary archive and the adjacent retained positional certificate jointly make servableFromBlock zero. maxServableToBlock: type: - integer - "null" minimum: 0 description: Highest block an immediate complete request may use for this selector-position scope. This is computed from the finalized prefix, physical head bounds, and the bounded live-tail budget; clients should use it instead of a tier throughBlock. allOf: - if: properties: sourceTier: const: finalized required: - sourceTier then: oneOf: - properties: openEnded: const: false liveMaintenance: const: false - properties: openEnded: const: true liveMaintenance: const: true - if: properties: sourceTier: const: head status: enum: - building - ready required: - sourceTier - status then: properties: openEnded: const: true liveMaintenance: const: true - if: properties: status: const: failed required: - status then: properties: openEnded: const: false liveMaintenance: const: false - if: properties: status: const: ready required: - status then: properties: verifiedAt: type: string format: date-time CapabilitiesRateLimit: type: object additionalProperties: false required: - responseHeaders - classes - operationDisclosure - retryRule description: Public HTTP rate-limit/backoff contract. It intentionally names only response headers and classes, never a key, workspace, or internal limiter bucket. properties: responseHeaders: type: object additionalProperties: false required: - routeClass - limit - remaining - policy - retryAfter properties: routeClass: type: string enum: - X-Starkscan-Route-Class limit: type: string enum: - x-ratelimit-limit remaining: type: string enum: - x-ratelimit-remaining policy: type: string enum: - x-ratelimit-policy retryAfter: type: string enum: - Retry-After classes: type: array minItems: 3 maxItems: 3 uniqueItems: true items: type: string enum: - light - heavy - batch operationDisclosure: type: string minLength: 1 retryRule: type: string minLength: 1 SessionControlCapability: type: object additionalProperties: false description: | Separate dashboard workspace control-plane boundary. It is visible in API-key capabilities so clients do not mistake a typed 401 on `/v1/me/*` for an API-key failure, but API keys must never authorize these routes. required: - status - pathPrefix - apiKeyAccess - safeReadAuth - mutationAuth - documentationPath properties: status: type: string enum: - separate_dashboard_session_control_plane pathPrefix: type: string enum: - /v1/me apiKeyAccess: type: string enum: - not_supported safeReadAuth: type: array minItems: 2 maxItems: 2 uniqueItems: true items: type: string enum: - better_auth_session_cookie - bearer_session_token mutationAuth: type: string enum: - bearer_session_token documentationPath: type: string enum: - /docs/api/self-serve ApiKeyLifecycleCapability: type: object additionalProperties: false description: | API-key lifecycle contract. Inactive credentials deliberately receive a generic OAuth-compatible 401 response; lifecycle reason is never exposed. Rate-limit decisions stay distinct as 429 with Retry-After. required: - inactiveKeyResponse - inactiveKeyWwwAuthenticate - rateLimitResponse - ownerInspectionPath - internalObservability properties: inactiveKeyResponse: type: string enum: - generic_401_invalid_token inactiveKeyWwwAuthenticate: type: string enum: - Bearer realm="starkscan", error="invalid_token" description: Exact challenge returned for revoked or expired API keys; the generic response does not disclose which lifecycle state applied. rateLimitResponse: type: string enum: - 429_with_retry_after ownerInspectionPath: type: string enum: - /v1/me/api-keys internalObservability: type: string enum: - sanitized_lifecycle_reason_metrics RpcProviderCapability: type: object additionalProperties: true required: - status - endpoint - endpointTemplate - authHeader - minimumSpecVersion - publicSpecVersion - specVersionContract - specVersionMethod - supportedBlockTags - conditionalBlockTags - batch - storageProofBeta - writeBeta - traceBeta - quotaClasses - unsupportedUntilCertified properties: status: type: string enum: - enrolled_http_beta - authenticated_http_beta endpoint: type: string example: /api/v1/SN_MAIN/rpc endpointTemplate: type: string example: /api/v1/{chain}/rpc authHeader: type: string example: X-Starkscan-Api-Key minimumSpecVersion: type: string example: 0.10.2 publicSpecVersion: type: string example: 0.10.2 specVersionContract: type: string enum: - gateway_declared_compatibility specVersionMethod: type: string enum: - starknet_specVersion supportedBlockTags: type: array items: type: string enum: - latest - pre_confirmed - l1_accepted conditionalBlockTags: type: object additionalProperties: false required: - l1_accepted properties: l1_accepted: type: object additionalProperties: false required: - advertised - evidence properties: advertised: type: boolean evidence: type: string enum: - indexed_canonical_l1_accepted_watermark batch: type: object additionalProperties: false required: - supported - maxItems - maxResponseBytes - accounting properties: supported: type: boolean maxItems: type: integer minimum: 1 maximum: 50 maxResponseBytes: type: integer minimum: 1 maximum: 16777216 accounting: type: string enum: - Each JSON-RPC child request is classified and rate-limited independently. storageProofBeta: $ref: "#/components/schemas/StorageProofCapability" writeBeta: type: object additionalProperties: false required: - enabled - status - openToAllApiKeys - methods - payloadPolicy - quotaClass properties: enabled: type: boolean status: type: string enum: - enrolled_write_scoped_keys_only - disabled_until_operator_enabled - all_api_keys_signed_payloads_only openToAllApiKeys: type: boolean methods: type: array items: type: string enum: - starknet_addInvokeTransaction - starknet_addDeclareTransaction - starknet_addDeployAccountTransaction payloadPolicy: type: string quotaClass: type: string enum: - rpc_write traceBeta: type: object additionalProperties: false required: - status - scope - methods - quotaClass - maxResponseBytes - stateDiffPolicy - incompleteResponsePolicy - policy properties: status: type: string enum: - operator_scoped scope: type: string enum: - trace methods: type: array minItems: 2 maxItems: 2 uniqueItems: true items: type: string enum: - starknet_traceTransaction - starknet_traceBlockTransactions quotaClass: type: string enum: - rpc_trace maxResponseBytes: type: integer minimum: 1 maximum: 16777216 stateDiffPolicy: type: string enum: - omitted_use_starknet_getStateUpdate incompleteResponsePolicy: type: string enum: - fail_closed_trace_response_incomplete policy: type: string quotaClasses: type: object additionalProperties: false required: - rpc_read_light - rpc_read_state - rpc_read_history - rpc_simulation - rpc_write - rpc_trace properties: rpc_read_light: type: array items: type: string enum: - rpc.discover - starknet_chainId - starknet_specVersion - starknet_blockNumber - starknet_blockHashAndNumber - starknet_syncing rpc_read_state: type: array items: type: string enum: - starknet_call - starknet_getStorageAt - starknet_getStorageProof - starknet_getClass - starknet_getClassHashAt - starknet_getClassAt - starknet_getCompiledCasm - starknet_getNonce rpc_read_history: type: array items: type: string enum: - starknet_getBlockWithTxHashes - starknet_getBlockWithTxs - starknet_getBlockWithReceipts - starknet_getBlockTransactionCount - starknet_getTransactionByBlockIdAndIndex - starknet_getTransactionByHash - starknet_getTransactionReceipt - starknet_getTransactionStatus - starknet_getMessagesStatus - starknet_getStateUpdate - starknet_getEvents rpc_simulation: type: array items: type: string enum: - starknet_simulateTransactions - starknet_estimateFee - starknet_estimateMessageFee rpc_write: type: array items: type: string enum: - starknet_addInvokeTransaction - starknet_addDeclareTransaction - starknet_addDeployAccountTransaction rpc_trace: type: array items: type: string enum: - starknet_traceTransaction - starknet_traceBlockTransactions unsupportedUntilCertified: type: array items: type: string enum: - websocket_subscriptions - broad_trace_methods - archive_history_full_provider - no_key_public_rpc StorageProofCapability: type: object additionalProperties: false required: - enabled - status - availability - method - quotaClass - acceptedBlockIds - rejectedBlockTags - limits - historicalHorizon - stateDiffCommitment - responseValidation properties: enabled: type: boolean enum: - true status: type: string enum: - bounded_upstream_passthrough availability: type: string enum: - upstream_dependent method: type: string enum: - starknet_getStorageProof quotaClass: type: string enum: - rpc_read_state acceptedBlockIds: type: array minItems: 3 maxItems: 3 uniqueItems: true items: type: string enum: - latest - block_number - block_hash rejectedBlockTags: type: array minItems: 2 maxItems: 2 uniqueItems: true items: type: string enum: - pending - pre_confirmed limits: type: object additionalProperties: false required: - maxClassHashes - maxContractAddresses - maxContractStoragePairs - maxStorageKeysPerContract - maxTotalTargets - totalTargetCounting - maxResponseBytes properties: maxClassHashes: type: integer enum: - 8 maxContractAddresses: type: integer enum: - 8 maxContractStoragePairs: type: integer enum: - 8 maxStorageKeysPerContract: type: integer enum: - 16 maxTotalTargets: type: integer enum: - 32 totalTargetCounting: type: string enum: - class_hashes_plus_contract_addresses_plus_individual_storage_keys maxResponseBytes: type: integer enum: - 1048576 historicalHorizon: type: object additionalProperties: false required: - advertised - status - guaranteedBlocksBehindHead - certificationTargetBlocksBehindHead - policy properties: advertised: type: boolean enum: - false status: type: string enum: - not_certified guaranteedBlocksBehindHead: type: "null" certificationTargetBlocksBehindHead: type: integer enum: - 50000 policy: type: string minLength: 1 stateDiffCommitment: type: object additionalProperties: false required: - advertised - guaranteed - status - passthroughPolicy - policy properties: advertised: type: boolean enum: - false guaranteed: type: boolean enum: - false status: type: string enum: - not_in_starknet_openrpc_0_10_2 passthroughPolicy: type: string enum: - preserved_if_returned_by_upstream_not_synthesized_or_certified policy: type: string minLength: 1 responseValidation: type: string enum: - opaque_upstream_result_size_bounded CallerCapabilities: type: object additionalProperties: false required: - authenticated - authType - keyClass - scopes - scopeDisclosure - routeFamilyDisclosure - workspacePlan - rateLimit properties: authenticated: type: boolean authType: type: string keyClass: type: - string - "null" scopes: type: array uniqueItems: true items: type: string enum: - read - batch - write - verify - prove - trace scopeDisclosure: type: string enum: - exact_for_api_key - not_available_for_auth_type - not_bound_to_request - operator_internal routeFamilyDisclosure: type: string enum: - exact_for_api_key - verified_read_lower_bound - global_operator_view - global_unbound - fail_closed workspacePlan: description: Durable workspace plan for a DB-backed API key. Null when no workspace entitlement is safely bound to this request. oneOf: - type: "null" - type: string enum: - free - developer - growth - business - enterprise - wallet rateLimit: oneOf: - type: "null" - type: object additionalProperties: false required: - loadClass - limitPerMinute - remaining - retryAfterSeconds - bucketScope properties: loadClass: type: string enum: - light - heavy limitPerMinute: type: integer minimum: 0 remaining: type: integer minimum: 0 retryAfterSeconds: type: integer minimum: 0 bucketScope: type: string enum: - key - workspace WalletInteractionCapability: type: object additionalProperties: false required: - enabled - status - supportedChains - contractAllowlist - transactionPolicy - limits - simulation properties: enabled: type: boolean status: type: string enum: - disabled_until_operator_enabled - sepolia_basic_submission_pilot supportedChains: type: array items: type: string enum: - SN_SEPOLIA contractAllowlist: type: array maxItems: 32 items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ transactionPolicy: type: object additionalProperties: false required: - maxCalls - entryPointNameRequired - rawCalldataEnabled - mainnet properties: maxCalls: type: integer minimum: 0 maximum: 1 entryPointNameRequired: type: boolean enum: - true rawCalldataEnabled: type: boolean enum: - false mainnet: type: string enum: - disabled limits: type: object additionalProperties: false required: - maxCalls - maxCalldataFelts - maxArguments - maxStringBytes properties: maxCalls: type: integer enum: - 1 maxCalldataFelts: type: integer enum: - 256 maxArguments: type: integer enum: - 64 maxStringBytes: type: integer enum: - 4096 simulation: type: object additionalProperties: false required: - status - required properties: status: type: string enum: - not_certified - certified description: | `certified` is required before a Starkscan browser wallet flow may enable signing. `not_certified` keeps the flow fail-closed. required: type: boolean description: | Must be true with `status=certified` before a Starkscan browser wallet flow may enable signing. oneOf: - properties: status: const: not_certified required: const: false - properties: status: const: certified required: const: true MetaChainsView: type: object additionalProperties: true required: - kind - schemaVersion - defaultChain - chains properties: kind: type: string enum: - starkscan.meta.chains schemaVersion: type: string defaultChain: type: string chains: type: array items: type: object additionalProperties: true required: - chainId - statusPath - statusPathTemplate properties: chainId: type: string statusPath: type: string statusPathTemplate: type: string selectionRule: type: string MetaAgentContextView: type: object additionalProperties: true required: - kind - schemaVersion - agentMemory - workspaceMemory - preferredArtifactFormat properties: kind: type: string enum: - starkscan.meta.agent_context schemaVersion: type: string agentMemory: $ref: "#/components/schemas/AgentMemoryContract" workspaceMemory: $ref: "#/components/schemas/AgentWorkspaceMemoryContract" preferredArtifactFormat: type: string example: application/jsonl AgentWorkspaceMemoryContract: type: object additionalProperties: false required: - status - publicWriteApi - serverStoredArtifacts - writeSurface - localWorkspace - handoffContract properties: status: type: string enum: - no_public_write_api publicWriteApi: type: boolean enum: - false serverStoredArtifacts: type: string example: not available in this deployment writeSurface: type: string example: not exposed in this deployment localWorkspace: $ref: "#/components/schemas/AgentLocalWorkspaceContract" handoffContract: $ref: "#/components/schemas/AgentHandoffContract" rules: type: array items: type: string AgentLocalWorkspaceContract: type: object additionalProperties: false required: - status - defaultDirectory - artifactPattern - schemaPath - schemaUrl - guideUrl - validatorCommand - sampleCommand properties: status: type: string enum: - internal_local_only defaultDirectory: type: string example: .codex/handoffs/ artifactPattern: type: string example: .codex/handoffs/{taskId}.jsonl schemaPath: type: string example: docs/maintainers/schemas/agent-handoff-artifact.schema.json schemaUrl: type: string example: /agent-handoff-artifact.schema.json guideUrl: type: string example: /agent-workspace.md validatorCommand: type: string example: python3 scripts/ci/agent-handoff.py validate .codex/handoffs/{taskId}.jsonl sampleCommand: type: string example: python3 scripts/ci/agent-handoff.py sample --task-id --created-by AgentHandoffContract: type: object additionalProperties: false required: - sourceOfTruth - artifactKinds - requiredFields - evidenceRule - formats properties: sourceOfTruth: type: string example: typed JSON/JSONL artifacts, not chat history artifactKinds: type: array items: type: string requiredFields: type: array items: type: string evidenceRule: type: string formats: type: array items: type: string AgentIssueReportContract: type: object additionalProperties: false required: - requiredFields - rule properties: requiredFields: type: array items: type: string example: - route - queryParams - requestBody - responseStatus - responseSnippet - xRequestId rule: type: string HealthResponse: type: object additionalProperties: false required: - ok - databaseOk properties: ok: type: boolean databaseOk: type: boolean ReadyzResponse: type: object additionalProperties: false required: - ready - databaseOk properties: ready: type: boolean databaseOk: type: boolean LivezResponse: type: object additionalProperties: false required: - alive properties: alive: type: boolean SepoliaArchiveLookupRequest: type: object additionalProperties: false required: - kind - reference properties: kind: type: string enum: - transaction - contract - class - block reference: type: string minLength: 1 maxLength: 80 description: Transaction hash, contract address, class hash, block number, or block hash appropriate to kind. SepoliaArchiveLookupView: type: object additionalProperties: false required: - schemaVersion - chainId - kind - reference - state - earliestIndexedBlock - latestIndexedBlock - evidenceSource - message - verifiedAtIso properties: schemaVersion: type: integer const: 1 chainId: type: string kind: type: string enum: - transaction - contract - class - block reference: type: string state: type: string enum: - found_outside_index - found_inside_index - found_inside_index_gap - found_ahead_of_index - not_found_by_archive - archive_unavailable - unsupported blockNumber: type: integer format: int64 minimum: 0 blockHash: type: string classHash: type: string classHashAsOfBlock: type: integer format: int64 minimum: 0 classHashAsOfBlockHash: type: string earliestIndexedBlock: type: - integer - "null" format: int64 latestIndexedBlock: type: - integer - "null" format: int64 evidenceSource: type: string const: starkscan_archive_rpc message: type: string verifiedAtIso: type: string format: date-time ExplorerStatusView: type: object additionalProperties: false required: - chainId - headBlockNumber - headBlockHash - finalizedBlockNumber - latestL1AcceptedBlockNumber - l1AcceptedProof - l1Finality - latestIndexedBlockNumber - earliestIndexedBlockNumber - indexedBlockSpan - lagBlocks - l1SettlementLatencySeconds properties: chainId: type: string headBlockNumber: type: - integer - "null" format: int64 headBlockHash: type: - string - "null" finalizedBlockNumber: type: - integer - "null" format: int64 latestL1AcceptedBlockNumber: type: - integer - "null" format: int64 description: Latest Starknet block number covered by explicit L1 accepted proof, separate from finalized indexed storage. l1AcceptedProof: anyOf: - $ref: "#/components/schemas/L1AcceptedProofView" - type: "null" l1Finality: $ref: "#/components/schemas/L1FinalityView" latestIndexedBlockNumber: type: - integer - "null" format: int64 earliestIndexedBlockNumber: type: - integer - "null" format: int64 indexedBlockSpan: type: - integer - "null" format: int64 lagBlocks: type: - integer - "null" format: int64 l1SettlementLatencySeconds: type: - integer - "null" format: int64 historyPolicy: type: - string - "null" enum: - fixed_start - null description: Indexed-history availability policy. SN_SEPOLIA uses a fixed inclusive starting boundary that does not advance with time. historyCompleteness: type: - string - "null" enum: - complete_from_earliest_available - boundary_unavailable - null description: Honest completeness claim for the indexed-history window. boundary_unavailable means the fixed boundary could not be derived and clients must not infer it from another field. retentionDays: type: - integer - "null" format: int32 description: Rolling indexed-history duration configured for this chain. Present only when retention is active. earliestAvailableBlock: type: - integer - "null" format: int64 description: Inclusive lower block boundary currently available from the indexed API. For fixed_start this is the permanent indexed-history floor, not a rolling cutoff. earliestAvailableAt: type: - string - "null" format: date-time description: UTC timestamp represented by the inclusive indexed-history boundary. retentionStatus: type: - string - "null" description: Durable status of the most recent indexed-history retention attempt. retentionLastSuccessAt: type: - string - "null" format: date-time retentionBacklogRemaining: type: - boolean - "null" description: Whether additional rows older than the current boundary remain for a later bounded pass. IndexingFreshnessHealthView: type: object additionalProperties: false required: - chainId - classification - evidenceAvailable - headBlockNumber - latestIndexedBlockNumber - lagBlocks - thresholdLagBlocks - headSource - trustBoundary properties: chainId: type: string classification: type: string enum: - operational - degraded - evidence_unavailable - evidence_inconsistent evidenceAvailable: type: boolean headBlockNumber: type: - integer - "null" format: int64 latestIndexedBlockNumber: type: - integer - "null" format: int64 lagBlocks: type: - integer - "null" format: int64 thresholdLagBlocks: type: integer format: int64 const: 20 headSource: type: - string - "null" enum: - configured_starknet_rpc - null trustBoundary: type: string description: Explicitly limits this signal to Starkscan indexing freshness. ContractVerificationHealthView: type: object description: Raw verification-health evidence. Every non-operational response is HTTP 503. Classification precedence is disabled, evidence_unavailable (missing ledger snapshot or zero/future controller heartbeat), evidence_inconsistent (negative metrics), evidence_incomplete (either active-state or terminal-receipt-lag truncation), then degraded (remaining SLO failures). Negative metrics are preserved regardless of the selected fail-closed classification. Truncation always makes evidenceAvailable false, but earlier conditions take precedence over evidence_incomplete. Active-job counts and state-derived ages are null when the bounded active-state window is truncated. A truncated terminalReceiptLag is a lower bound, never a complete census. additionalProperties: false required: - chainId - classification - evidenceAvailable - enabled - controllerHeartbeatAgeSeconds - oldestQueueAgeSeconds - oldestStagedAgeSeconds - overdueRetentionObjects - terminalReceiptLag - terminalReceiptLagTruncated - activeJobs - activeJobsTruncated - activeJobsWindowLimit - heartbeatThresholdSeconds - queueThresholdSeconds - stagedThresholdSeconds - trustBoundary properties: chainId: type: string classification: type: string enum: - operational - degraded - disabled - evidence_unavailable - evidence_inconsistent - evidence_incomplete evidenceAvailable: type: boolean enabled: type: boolean controllerHeartbeatAgeSeconds: type: - integer - "null" format: int64 minimum: 0 oldestQueueAgeSeconds: type: - integer - "null" format: int64 oldestStagedAgeSeconds: type: - integer - "null" format: int64 overdueRetentionObjects: type: - integer - "null" format: int64 terminalReceiptLag: type: - integer - "null" format: int64 terminalReceiptLagTruncated: type: - boolean - "null" description: True only when the matching terminal receipt lag exceeds the bounded 100-row reporting window (a 101st sentinel row exists), making terminalReceiptLag a lower bound and evidenceAvailable false. Exactly 100 matching rows are complete and return false. HTTP 503 classification follows the schema precedence; null when no ledger snapshot is available. activeJobs: type: - integer - "null" format: int64 description: Exact active-job count only when activeJobsTruncated is false; null when the bounded active-state window is incomplete or unavailable. activeJobsTruncated: type: - boolean - "null" description: True when the active-state window exceeded activeJobsWindowLimit; null when no ledger snapshot is available. activeJobsWindowLimit: type: integer format: int64 const: 50 description: Maximum active rows inspected to derive public health counts and state-derived ages. heartbeatThresholdSeconds: type: integer format: int64 const: 90 queueThresholdSeconds: type: integer format: int64 const: 900 stagedThresholdSeconds: type: integer format: int64 const: 300 trustBoundary: type: string description: Limits the signal to Starkscan verification service operations. L1FinalityQuorumHealthView: type: object additionalProperties: false required: - chainId - classification - evidenceAvailable - status - endpointsConfigured - endpointsHealthy - observedAt - evidenceAgeSeconds - thresholdAgeSeconds - trustBoundary properties: chainId: type: string classification: type: string enum: - operational - degraded - failed - diverged - stale - evidence_unavailable - evidence_inconsistent evidenceAvailable: type: boolean status: type: string enum: - healthy - degraded - failed - diverged - stale - not_reported endpointsConfigured: type: - integer - "null" format: int64 endpointsHealthy: type: - integer - "null" format: int64 observedAt: type: - string - "null" format: date-time evidenceAgeSeconds: type: - integer - "null" format: int64 minimum: 0 thresholdAgeSeconds: type: integer format: int64 const: 300 trustBoundary: type: string description: Limits the signal to Starkscan's sanitized materialized L1 quorum evidence. L1FinalityFreshnessHealthView: type: object additionalProperties: false required: - chainId - classification - evidenceAvailable - watermarkBlockNumber - watermarkAgeSeconds - settlementLatencySeconds - settlementStatus - settlementTargetSeconds - settlementThresholdSeconds - pipelineStatus - pipelineThresholdAgeSeconds - continuousHealthMarker - thresholdAgeSeconds - trustBoundary properties: chainId: type: string classification: type: string enum: - operational - settlement_delayed - pipeline_unhealthy - evidence_unavailable - evidence_inconsistent - evidence_stale evidenceAvailable: type: boolean watermarkBlockNumber: type: - integer - "null" format: int64 watermarkAgeSeconds: type: - integer - "null" format: int64 description: Signed age computed by PostgreSQL from the newer of the accepted-proof materialization and a matching verified state-update checkpoint revalidation. A negative value is inconsistent evidence, and a value above pipelineThresholdAgeSeconds is stale evidence; either condition returns HTTP 503. Settlement latency is reported separately through settlementLatencySeconds. settlementLatencySeconds: type: - integer - "null" format: int64 description: L2 head timestamp minus the timestamp of the newest L2 block proven on L1. settlementStatus: type: - string - "null" enum: - within_target - delayed_vs_target - null description: Independent settlement-target classification. A delayed value can coexist with a healthy pipeline while SHARP trains close temporary frontier holes. settlementTargetSeconds: type: integer format: int64 const: 10800 description: Published three-hour settlement target. Crossing it changes settlementStatus but does not by itself make a healthy evidence pipeline fail. settlementThresholdSeconds: type: integer format: int64 const: 10800 deprecated: true description: Compatibility alias for settlementTargetSeconds. pipelineStatus: type: - string - "null" enum: - healthy - degraded - failed - diverged - stale - not_reported - null description: Strict aggregate state of all required L1 materialization guards; only healthy is operational. pipelineThresholdAgeSeconds: type: integer format: int64 const: 300 continuousHealthMarker: type: - string - "null" enum: - SN_MAIN:evidence_available:pipeline_healthy:threshold_300 - null description: Present only when SN_MAIN settlement evidence is available, the strict aggregate pipeline is healthy, and the five-minute pipeline threshold is active. This literal is intended for continuous-health monitors; it is null for incomplete or unhealthy served-chain responses. Requests for an unserved chain return the route's 404 ErrorResponse instead. thresholdAgeSeconds: type: integer format: int64 const: 10800 deprecated: true description: Older compatibility alias for settlementTargetSeconds. trustBoundary: type: string description: Limits the signal to Starkscan's materialized settled frontier and complete L1 guard pipeline. L1FinalityView: type: object additionalProperties: false required: - watermarkBlockNumber - watermarkAgeSeconds - currentSettlementLatencySeconds - quorum - lastDivergenceAt properties: watermarkBlockNumber: type: - integer - "null" format: int64 description: Starknet block number covered by the current proof-backed L1 accepted watermark. watermarkAgeSeconds: type: - integer - "null" format: int64 description: Signed seconds since the newer of the served L1 accepted-proof materialization and a matching verified state-update checkpoint revalidation, computed in PostgreSQL's clock domain. A negative value denotes inconsistent future-dated evidence. currentSettlementLatencySeconds: type: - integer - "null" format: int64 description: Signed L2-head-to-settled-frontier latency from current indexed block timestamps. A negative value is inconsistent evidence and the dedicated health route returns HTTP 503. quorum: $ref: "#/components/schemas/L1FinalityQuorumView" lastDivergenceAt: type: - string - "null" format: date-time description: Most recent persisted L1 RPC quorum divergence timestamp across required evidence components; null when no divergence has been observed. L1FinalityQuorumView: type: object additionalProperties: false x-starkscan-required-components: SN_SEPOLIA: - state_update - message_origin - message_consumption default: - state_update - message_origin - message_consumption required: - endpointsConfigured - endpointsHealthy - status - observedAt properties: endpointsConfigured: type: - integer - "null" format: int64 description: Opaque minimum configured-endpoint count across every required L1 evidence component; null until every component has reported. Configuration separately requires at least two distinct RPC origins. endpointsHealthy: type: - integer - "null" format: int64 description: Opaque minimum agreeing-endpoint count across every required L1 evidence component; null for missing, stale, failed, or diverged evidence. status: type: string enum: - healthy - degraded - failed - diverged - stale - not_reported description: Strict aggregate of state-update, message-origin, and message-consumption observations. Healthy requires every component required for the requested chain to have a fresh agreeing observation from every configured endpoint, with configuration independently requiring at least two distinct RPC origins. Retired product-specific readers are excluded. observedAt: type: - string - "null" format: date-time description: Oldest observation timestamp across every component required for the requested chain; null until every required component has reported. L1AcceptedProofView: type: object additionalProperties: false required: - source - starknetBlockNumber - starknetBlockHash - starknetGlobalRoot - l1BlockNumber - l1BlockHash - l1TxHash - updatedAt properties: source: type: string enum: - ethereum_starknet_core_log_state_update starknetBlockNumber: type: integer format: int64 starknetBlockHash: type: string starknetGlobalRoot: type: string l1BlockNumber: type: integer format: int64 l1BlockHash: type: - string - "null" l1TxHash: type: string updatedAt: type: string format: date-time OAuthProtectedResourceMetadata: type: object additionalProperties: false required: - authorization_servers - resource - bearer_methods_supported - scopes_supported properties: authorization_servers: type: array items: type: string resource: type: string bearer_methods_supported: type: array items: type: string scopes_supported: type: array items: type: string ChainBlockListItem: type: object additionalProperties: false required: - blockNumber - blockHash - parentHash - timestampIso - txCount - finalityStatus properties: blockNumber: type: integer format: int64 blockHash: type: string parentHash: type: string timestampIso: type: string txCount: type: integer format: int64 finalityStatus: type: string ChainBlockListPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array items: $ref: "#/components/schemas/ChainBlockListItem" nextCursor: type: - string - "null" BlockAtTimestampQueryView: type: object additionalProperties: false required: - timestampIso - timestampUnix - closest properties: timestampIso: type: string format: date-time timestampUnix: type: integer format: int64 closest: type: string enum: - before - after BlockAtTimestampBlockView: type: object additionalProperties: false required: - blockNumber - blockHash - timestampIso - timestampUnix - finalityStatus properties: blockNumber: type: integer format: int64 blockHash: type: string timestampIso: type: string format: date-time timestampUnix: type: integer format: int64 finalityStatus: type: string BlockAtTimestampView: type: object additionalProperties: false required: - chainId - query - block - previousBlock - nextBlock - source properties: chainId: type: string query: $ref: "#/components/schemas/BlockAtTimestampQueryView" block: $ref: "#/components/schemas/BlockAtTimestampBlockView" previousBlock: oneOf: - $ref: "#/components/schemas/BlockAtTimestampBlockView" - type: "null" description: Always present; inclusive indexed lower bound at or before the requested timestamp, or null when unavailable. nextBlock: oneOf: - $ref: "#/components/schemas/BlockAtTimestampBlockView" - type: "null" description: Always present; inclusive indexed upper bound at or after the requested timestamp, or null when unavailable. source: type: string enum: - indexed_blocks ChainTransactionListItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txHash - txIndex - txType - fromAddress - toAddress - executionStatus - finalityStatus properties: blockNumber: type: integer format: int64 timestampIso: type: string txHash: type: string txIndex: type: integer format: int32 txType: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: string ChainTransactionListPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array items: $ref: "#/components/schemas/ChainTransactionListItem" nextCursor: type: - string - "null" BlockTransactionView: type: object additionalProperties: false required: - txHash - txIndex - txCursor - fromAddress - toAddress - executionStatus - finalityStatus properties: txHash: type: string txIndex: type: integer format: int32 txCursor: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" BlockGasPriceView: type: object additionalProperties: false required: - priceInWei - priceInFri properties: priceInWei: type: - string - "null" priceInFri: type: - string - "null" BlockView: type: object additionalProperties: false required: - chainId - blockNumber - blockHash - parentHash - timestampIso - txCount - rawObjectKey - stateRoot - sequencerAddress - l1DataAvailabilityMode - starknetVersion - l1GasPrice - l2GasPrice - l1DataGasPrice - transactions properties: chainId: type: string blockNumber: type: integer format: int64 blockHash: type: string parentHash: type: string timestampIso: type: string txCount: type: integer format: int64 rawObjectKey: type: string stateRoot: type: - string - "null" description: Canonical Starknet block state root when indexed from the raw block payload. sequencerAddress: type: - string - "null" description: Sequencer address reported by the Starknet block header when available. l1DataAvailabilityMode: type: - string - "null" description: L1 data availability mode reported by the Starknet block header when available. starknetVersion: type: - string - "null" description: Starknet protocol version reported by the block header when available. l1GasPrice: anyOf: - $ref: "#/components/schemas/BlockGasPriceView" - type: "null" l2GasPrice: anyOf: - $ref: "#/components/schemas/BlockGasPriceView" - type: "null" l1DataGasPrice: anyOf: - $ref: "#/components/schemas/BlockGasPriceView" - type: "null" transactions: type: array maxItems: 200 items: $ref: "#/components/schemas/BlockTransactionView" BlockTransactionPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/BlockTransactionView" nextCursor: type: - string - "null" ExplorerLiveFeedSnapshot: type: object additionalProperties: false required: - schemaVersion - emittedAtIso - status - blocks properties: schemaVersion: type: integer format: int32 emittedAtIso: type: string status: $ref: "#/components/schemas/ExplorerStatusView" blocks: type: array maxItems: 50 items: $ref: "#/components/schemas/BlockView" TransactionReceiptView: type: object additionalProperties: false required: - executionStatus - finalityStatus - gasUsed - effectiveGasPrice - actualFeeAmount - actualFeeUnit - revertReason properties: executionStatus: type: - string - "null" finalityStatus: type: - string - "null" gasUsed: type: - string - "null" effectiveGasPrice: type: - string - "null" actualFeeAmount: type: - string - "null" pattern: ^0x[0-9a-fA-F]+$ description: Receipt-reported total fee amount as a Starknet felt hex string. actualFeeUnit: type: - string - "null" enum: - WEI - FRI - null description: Receipt-reported fee unit. revertReason: type: - string - "null" TransactionLogView: type: object additionalProperties: false required: - logIndex - address - keys - topic0 - topic1 - topic2 - topic3 - data - decodingStatus properties: logIndex: type: integer format: int32 address: type: string keys: type: array items: type: string description: Canonical on-chain event key array in indexed payload order. Legacy rows lacking `payload.keys` reconstruct only `topic0` through `topic3`, so their key array can be incomplete; raw keys/data are authoritative. topic0: type: - string - "null" topic1: type: - string - "null" topic2: type: - string - "null" topic3: type: - string - "null" data: type: array maxItems: 1024 items: type: string decodingStatus: type: string enum: - decoded - name_only - unknown description: Server-certified event decode state. `name_only` and `unknown` preserve the authoritative raw payload as available; legacy rows may expose a reconstructed, incomplete `keys[]` per the keys field description. eventName: type: - string - "null" description: Reviewed or ABI-derived event name when Starkscan can attribute the selector. eventNameSource: type: - string - "null" description: Provenance for eventName. eventNameUnavailableReason: type: - string - "null" enum: - event_time_class_epoch_unavailable - null decodedFields: type: array maxItems: 128 items: $ref: "#/components/schemas/EventDecodedField" description: Exact materialized ABI fields when available. Raw keys/data remain authoritative. decodedFieldsSource: type: - string - "null" decodedFieldsUnavailableReason: type: - string - "null" enum: - schema_unavailable - selector_only_attribution - payload_shape_mismatch - schema_shape_unsupported - null TransactionTransferView: type: object additionalProperties: false required: - logIndex - transferIndex - tokenAddress - fromAddress - toAddress - amount - tokenId - standard - tokenSymbol - tokenName - tokenDecimals - historicalUsd properties: logIndex: type: integer format: int32 transferIndex: type: integer format: int32 tokenAddress: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" amount: type: - string - "null" tokenId: type: - string - "null" standard: type: string tokenSymbol: description: | Address-keyed symbol from Starkscan's indexed on-chain token metadata. This identity is independent of price-provider coverage. type: - string - "null" tokenName: description: | Address-keyed name from Starkscan's indexed on-chain token metadata. Null means metadata hydration has not completed or the contract does not expose a valid standard value. type: - string - "null" tokenDecimals: description: | Indexed on-chain decimal scale used to render amount. Null means clients must preserve amount as base units rather than guessing. type: - integer - "null" format: int32 minimum: 0 maximum: 36 historicalUsd: description: | Transaction-time USD coverage when this route includes price materialization. Transaction-detail and token-transfer responses report a priced, typed-unpriced, or pending result. `outside_history_window` is terminal provider-policy coverage; `price_missing` is a repairable in-horizon gap. Lightweight preview/list responses that intentionally omit this enrichment may return null. Never treat a null or unpriced result as a live/current market price. oneOf: - $ref: "#/components/schemas/TokenTransferHistoricalUsd" - type: "null" TokenTransferHistoricalUsd: type: object description: | Historical-USD coverage for one transfer. This is exactly one of: a priced transaction-time valuation; a typed unpriced result; or a pending materialization result. Clients must branch on `coverageStatus` and `coverageReasonCode`; null price fields are never a request to substitute a current/spot price. additionalProperties: false required: - amountDecimal - priceUsd - valueUsd - priceHourIso - priceSourceTimestampIso - priceSource - provider - providerAssetId - quoteCurrency - coverageStatus - coverageReasonCode - valuationMethod - indexedAt properties: amountDecimal: type: - string - "null" priceUsd: description: Token unit price in USD for `priceHourIso`, not current spot price. type: - string - "null" valueUsd: description: Transfer USD value at `priceHourIso`, not current spot value. type: - string - "null" priceHourIso: type: - string - "null" format: date-time priceSourceTimestampIso: description: Timestamp of the provider observation used for this historical price. type: - string - "null" format: date-time priceSource: type: - string - "null" provider: type: - string - "null" providerAssetId: type: - string - "null" quoteCurrency: type: string coverageStatus: type: string enum: - priced - unpriced - pending coverageReasonCode: type: string enum: - priced - causal_hourly_price - derived_conversion_estimate - token_unmapped - metadata_missing - non_fungible - amount_missing - price_missing - provider_granularity_daily - outside_history_window - materialization_pending valuationMethod: description: | Valuation basis. `direct_market_quote` is a provider-observed token quote. `snip22_conversion_estimate` combines an exact-block reviewed vault conversion with a causal underlying quote and is not an independently observed executable market price. Null when no valuation was published. type: - string - "null" enum: - direct_market_quote - snip22_conversion_estimate - null indexedAt: type: - string - "null" format: date-time oneOf: - title: Priced transaction-time valuation properties: coverageStatus: const: priced coverageReasonCode: enum: - priced - causal_hourly_price valuationMethod: const: direct_market_quote - title: Exact-block conversion estimate properties: coverageStatus: const: priced coverageReasonCode: const: derived_conversion_estimate valuationMethod: const: snip22_conversion_estimate - title: Typed unpriced result properties: coverageStatus: const: unpriced valuationMethod: const: null coverageReasonCode: enum: - token_unmapped - metadata_missing - non_fungible - amount_missing - price_missing - provider_granularity_daily - outside_history_window - title: Eligible transfer awaiting materialization properties: coverageStatus: const: pending coverageReasonCode: const: materialization_pending valuationMethod: const: null TokenTransferUsdCoverageSnapshot: type: object description: | One offline-prepared snapshot over the provider's bounded trailing history window. This is coverage telemetry, not a price feed. A transaction-time USD value is authoritative only when its individual transfer fact has `coverageStatus=priced`. Eligible and covered block/timestamp bounds are each either fully null or fully present; covered bounds always stay inside the eligible window. additionalProperties: false required: - chainId - provider - quoteCurrency - maxHistoryDays - sourcePolicy - eligibleFromBlock - eligibleToBlock - eligibleFromTimestamp - eligibleToTimestamp - coveredFromBlock - coveredThroughBlock - coveredFromTimestamp - coveredThroughTimestamp - pricedTransfers - typedUnavailableTransfers - pendingMaterializationTransfers - typedUnavailableByReason - latestSuccessfulRunAt - measuredAt - nextMaterializerDirection - compactQuoteAssetsExpected - compactQuoteAssetsComplete - compactQuoteAssetsIncomplete - compactQuoteCoveredFromTimestamp - compactQuoteCoveredThroughTimestamp - exact - scope - status properties: chainId: type: string provider: type: string quoteCurrency: type: string maxHistoryDays: type: integer format: int32 minimum: 1 maximum: 365 sourcePolicy: type: string const: hourly_causal_no_forward_fill eligibleFromBlock: type: - integer - "null" format: int64 minimum: 0 eligibleToBlock: type: - integer - "null" format: int64 minimum: 0 eligibleFromTimestamp: type: - string - "null" format: date-time eligibleToTimestamp: type: - string - "null" format: date-time coveredFromBlock: type: - integer - "null" format: int64 minimum: 0 coveredThroughBlock: type: - integer - "null" format: int64 minimum: 0 coveredFromTimestamp: type: - string - "null" format: date-time coveredThroughTimestamp: type: - string - "null" format: date-time pricedTransfers: type: integer format: int64 minimum: 0 typedUnavailableTransfers: type: integer format: int64 minimum: 0 pendingMaterializationTransfers: type: integer format: int64 minimum: 0 typedUnavailableByReason: type: object additionalProperties: false properties: token_unmapped: type: integer format: int64 minimum: 0 metadata_missing: type: integer format: int64 minimum: 0 non_fungible: type: integer format: int64 minimum: 0 amount_missing: type: integer format: int64 minimum: 0 price_missing: type: integer format: int64 minimum: 0 provider_granularity_daily: type: integer format: int64 minimum: 0 description: | Materialized unpriced outcomes by reason. `provider_granularity_daily` is deliberately unpriced and must not be included in `pricedTransfers`. latestSuccessfulRunAt: type: - string - "null" format: date-time measuredAt: type: string format: date-time nextMaterializerDirection: type: - string - "null" enum: - forward - backfill - null compactQuoteAssetsExpected: type: integer format: int64 minimum: 0 description: Reviewed direct-price assets enrolled for compact hourly history. compactQuoteAssetsComplete: type: integer format: int64 minimum: 0 description: Enrolled assets whose bounded 365-day hourly recovery cursor is complete. compactQuoteAssetsIncomplete: type: integer format: int64 minimum: 0 description: Enrolled assets still advancing through bounded hourly recovery. compactQuoteCoveredFromTimestamp: type: - string - "null" format: date-time description: Common factual hourly-quote floor when every enrolled asset has quote rows. compactQuoteCoveredThroughTimestamp: type: - string - "null" format: date-time description: Common factual hourly-quote ceiling when every enrolled asset has quote rows. exact: type: boolean const: true scope: type: string const: eligible_finalized_transfers_in_bounded_provider_history_window status: type: string enum: - current - catching_up - stale - degraded BridgeIntentKind: type: string enum: - deposit - withdraw - bridge_unknown BridgeIntentConfidence: type: string description: | Confidence for emitted bridge intents. Low-confidence candidates are intentionally omitted from `bridgeIntent`. enum: - high - medium BridgeIntentView: type: object additionalProperties: false required: - kind - protocol - confidence - reasons properties: kind: $ref: "#/components/schemas/BridgeIntentKind" protocol: type: - string - "null" confidence: $ref: "#/components/schemas/BridgeIntentConfidence" reasons: type: array maxItems: 32 items: type: string TransactionPreviewLogView: type: object additionalProperties: false required: - logIndex - address - topic0 properties: logIndex: type: integer format: int32 address: type: string topic0: type: - string - "null" TransactionPreviewContractCallView: type: object additionalProperties: false required: - contractAddress - callIndex - entryPointSelector - methodName properties: contractAddress: type: string callIndex: type: integer format: int32 entryPointSelector: type: - string - "null" methodName: type: - string - "null" TransactionPreviewView: type: object additionalProperties: false required: - chainId - blockNumber - timestampIso - txIndex - txHash - txCursor - fromAddress - toAddress - executionStatus - finalityStatus - txType - transferCount - tokenTransfersTruncated - tokenTransfers - exchangeCalls - exchangeCallsTruncated properties: timestampIso: type: - string - "null" chainId: type: string blockNumber: type: integer format: int64 txIndex: type: integer format: int32 txHash: type: string txCursor: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" txType: type: - string - "null" signedCallTargets: type: array maxItems: 64 description: Optional additive projection of unique targets from an exactly decoded, bounded signed INVOKE call array. This records signed intent and does not claim that every call executed. items: type: string transferCount: type: integer format: int64 tokenTransfersTruncated: type: boolean tokenTransfers: type: array maxItems: 4096 items: $ref: "#/components/schemas/TransactionTransferView" exchangeCalls: type: array maxItems: 16 description: Trace-backed calls selected by exact reviewed swap entrypoint selectors. Empty unless requested. items: $ref: "#/components/schemas/TransactionPreviewContractCallView" exchangeCallsTruncated: type: boolean hasBurnToZero: type: boolean hasMintFromZero: type: boolean bridgeSignalContracts: type: array maxItems: 256 items: type: string bridgeIntent: oneOf: - $ref: "#/components/schemas/BridgeIntentView" - type: "null" logCount: type: integer format: int64 logsTruncated: type: boolean logs: type: array maxItems: 4096 items: $ref: "#/components/schemas/TransactionPreviewLogView" TransactionPreviewBatchView: type: object additionalProperties: false required: - items properties: items: type: array maxItems: 128 items: $ref: "#/components/schemas/TransactionPreviewView" TransactionPreviewBatchRequest: type: object additionalProperties: false required: - hashes properties: hashes: type: array minItems: 1 maxItems: 128 items: type: string includeLogs: type: - boolean - "null" description: | Include bounded preview logs for each transaction. Defaults to `false` when omitted. includeLogCounts: type: - boolean - "null" description: | Include exact log counts even when logs are not requested. When omitted, defaults to the same value as `includeLogs`. includeBridgeSignals: type: - boolean - "null" default: true description: | Include bridge transfer signal detection (`hasMintFromZero`, `hasBurnToZero`, `bridgeSignalContracts`, `bridgeIntent`). Defaults to `true` when omitted. includeExchangeCalls: type: - boolean - "null" default: false description: | Include up to 16 trace-backed calls per transaction whose selector is an exact reviewed swap entrypoint. Defaults to `false` when omitted. logLimitPerTx: type: - integer - "null" format: int32 default: 64 minimum: 1 maximum: 256 description: | Maximum number of logs returned per transaction when `includeLogs` is enabled. Defaults to `64` when omitted. TransactionAccountCallView: type: object additionalProperties: false required: - to - selector - calldataLen properties: to: type: string description: Contract address targeted by this account call. selector: type: string description: Entry-point selector invoked by this account call. calldataLen: type: integer format: int32 minimum: 0 description: Number of calldata felts supplied to this account call. TransactionDetailView: type: object additionalProperties: false required: - chainId - blockNumber - txIndex - txHash - txCursor - fromAddress - toAddress - executionStatus - finalityStatus - txType - rawObjectKey - calldata - accountCallCount - accountCalls - declaredL2GasCap - receipt - logsTruncated - eventDecodingDegraded - logs - tokenTransfers - messages - messagesCoverage - bridgeIntent properties: chainId: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 txHash: type: string txCursor: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" txType: type: - string - "null" rawObjectKey: type: string receipt: oneOf: - $ref: "#/components/schemas/TransactionReceiptView" - type: "null" logsTruncated: type: boolean eventDecodingDegraded: type: boolean description: True only when the optional server attribution lookup failed operationally. Individual unknown events do not set this flag. logs: type: array maxItems: 512 items: $ref: "#/components/schemas/TransactionLogView" calldata: type: array maxItems: 1024 items: type: string accountCallCount: type: - integer - "null" format: int32 minimum: 0 description: Number of calls decoded from a well-formed INVOKE account call array; null when the payload is not applicable or cannot be decoded safely. accountCalls: type: array maxItems: 1024 items: $ref: "#/components/schemas/TransactionAccountCallView" description: Ordered calls decoded from the transaction's account call array. declaredL2GasCap: type: - integer - "null" format: int64 minimum: 0 description: Sender-declared `resource_bounds.l2_gas.max_amount`; null when the transaction does not declare an L2 gas bound. tokenTransfers: type: array maxItems: 4096 items: $ref: "#/components/schemas/TransactionTransferView" messages: type: array maxItems: 32 items: $ref: "#/components/schemas/MessageItem" messagesCoverage: $ref: "#/components/schemas/MessageCoverageView" bridgeIntent: oneOf: - $ref: "#/components/schemas/BridgeIntentView" - type: "null" AddressContractExistenceView: type: object additionalProperties: false required: - status - reasonCode - evidenceSource - observedBlockNumber - observedBlockHash - expiresAtIso properties: status: type: string enum: - not_deployed reasonCode: type: string enum: - contract_not_found evidenceSource: type: string enum: - finalized_class_hash_at observedBlockNumber: type: integer format: int64 minimum: 0 observedBlockHash: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ expiresAtIso: type: string format: date-time description: Time-bounded fixed-finalized-block evidence that the address had no deployed contract at the observed block. Operational RPC failures never produce this object. AddressDeploymentProvenanceView: type: object additionalProperties: false required: - status - reasonCode - evidenceSource - deployedAtBlock - deployedAtBlockHash - transactionHash - deploymentKind - originAddress - factoryAddress properties: status: type: string enum: - known - not_applicable - unavailable description: Whether transaction-trace attribution is exact, intentionally inapplicable, or not yet certified. reasonCode: type: string enum: - trace_certified - deploy_account_has_no_external_deployer - legacy_deploy_has_no_external_deployer - transaction_trace_not_certified evidenceSource: type: string enum: - state_update_and_transaction_trace - starknet_state_diff_boundary deployedAtBlock: type: integer format: int64 minimum: 0 deployedAtBlockHash: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ transactionHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ deploymentKind: type: - string - "null" enum: - deploy_account - invoke_factory - legacy_deploy - null originAddress: type: - string - "null" description: Transaction sender for a trace-certified factory or UDC deployment. Null when no external deployer exists or attribution is unavailable. pattern: ^0x[0-9a-fA-F]{1,64}$ factoryAddress: type: - string - "null" description: Constructor caller for a trace-certified factory or UDC deployment. pattern: ^0x[0-9a-fA-F]{1,64}$ oneOf: - properties: status: type: string const: known reasonCode: type: string const: trace_certified evidenceSource: type: string const: state_update_and_transaction_trace transactionHash: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ deploymentKind: type: string const: invoke_factory originAddress: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ factoryAddress: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ - properties: status: type: string const: not_applicable evidenceSource: type: string const: state_update_and_transaction_trace transactionHash: type: string pattern: ^0x[0-9a-fA-F]{1,64}$ originAddress: type: "null" factoryAddress: type: "null" oneOf: - properties: reasonCode: type: string const: deploy_account_has_no_external_deployer deploymentKind: type: string const: deploy_account - properties: reasonCode: type: string const: legacy_deploy_has_no_external_deployer deploymentKind: type: string const: legacy_deploy - properties: status: type: string const: unavailable reasonCode: type: string const: transaction_trace_not_certified evidenceSource: type: string const: starknet_state_diff_boundary transactionHash: type: "null" deploymentKind: type: "null" originAddress: type: "null" factoryAddress: type: "null" description: Canonical creation-block evidence plus fail-closed transaction-trace attribution. DEPLOY_ACCOUNT and legacy DEPLOY intentionally do not fabricate a self-deployer. AddressSummaryView: type: object additionalProperties: false required: - address - totalActivityCount - latestActivityBlock properties: address: type: string totalActivityCount: type: - integer - "null" format: int64 minimum: 0 description: Exhaustive count, a documented positive lower bound, or null when activity is unknown/partial and no safe numeric lower bound exists. Zero is valid only with activityCountExact=true. latestActivityBlock: type: - integer - "null" format: int64 description: Highest proved indexed activity block for this aggregate summary. It is null when totalActivityCount is null; use address/intelligence for independently typed latest-activity evidence with an unmaterialized total. activityCountExact: type: - boolean - "null" classHash: type: - string - "null" description: Starknet contract class hash (0x-prefixed felt hex), null when unavailable. pattern: ^0x[0-9a-fA-F]{1,64}$ isAccount: type: - boolean - "null" description: True if the class behaves as an account contract, null when unknown. createdOnIso: type: - string - "null" deployedAtTxHash: type: - string - "null" deployedByAddress: type: - string - "null" deploymentProvenance: $ref: "#/components/schemas/AddressDeploymentProvenanceView" description: Present for a deployed address with a canonical creation boundary; omitted when no deployment evidence exists. A present value with status unavailable means the creation boundary is known but transaction-trace attribution is not certified. contractExistence: oneOf: - $ref: "#/components/schemas/AddressContractExistenceView" - type: "null" description: Present only while contract-not-found evidence is fresh and no positive class fact wins. ContractMetadataView: type: object additionalProperties: false required: - chainId - address - classHash - currentClassHash - deploymentClassHash - classHashSource - classHashAsOfBlock - classHashAsOfBlockHash - classHashFinality - deployedAtBlock - deployedAtTx - createdOnIso - deployedByAddress - isAccount - isToken - tokenKind - alias - metadataCompleteness - source properties: chainId: type: string address: type: string classHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Compatibility class hash backed by classHashSource. Uses currentClassHash when a trusted indexed runtime observation exists, otherwise deploymentClassHash; null is possible only when another indexed identity fact, such as token metadata, keeps the response addressable. currentClassHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Newest trusted indexed runtime class observation. Read with classHashAsOfBlock and classHashAsOfBlockHash; it is not a claim about blocks after that boundary. Null does not imply that the address is undeployed. deploymentClassHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Original indexed deployment class hash only when authoritative deployment evidence proves it. Null when unavailable; never inferred from current class or first activity. classHashSource: type: - string - "null" description: Provenance source for classHash. classHashAsOfBlock: type: - integer - "null" format: int64 minimum: 0 maximum: 9007199254740991 description: Exact evidence block for classHash when the source has a canonical block. classHashAsOfBlockHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Canonical block hash paired with classHashAsOfBlock. classHashFinality: type: - string - "null" enum: - finalized - null description: Finality of the classHash evidence; null means the exact-block observation does not assert finalized status. deployedAtBlock: type: - integer - "null" format: int64 description: Deployment block from canonical indexed state-update facts when available. deployedAtTx: type: - string - "null" description: Deployment transaction hash when an indexed deployment transaction is known. createdOnIso: type: - string - "null" format: date-time deployedByAddress: type: - string - "null" deploymentProvenance: $ref: "#/components/schemas/AddressDeploymentProvenanceView" description: Present for a deployed address with a canonical creation boundary; omitted when no deployment evidence exists. A present value with status unavailable means the creation boundary is known but transaction-trace attribution is not certified. isAccount: type: - boolean - "null" isToken: type: - boolean - "null" enum: - true - null description: True when token metadata exists; null means not identified in the indexed token metadata table. tokenKind: type: - string - "null" enum: - erc20 - erc721 - erc1155 - unknown - null alias: type: - string - "null" description: Token name or symbol when indexed token metadata is available. metadataCompleteness: type: boolean description: True when both class hash and canonical deployment block are available. source: type: string enum: - indexed_read_model allOf: - oneOf: - required: - isToken - tokenKind - alias properties: isToken: type: "null" tokenKind: type: "null" alias: type: "null" - required: - isToken - tokenKind properties: isToken: type: boolean enum: - true tokenKind: type: string enum: - erc20 - erc721 - erc1155 - unknown AddressSummaryBatchRequest: type: object additionalProperties: false required: - addresses properties: addresses: type: array minItems: 1 maxItems: 128 items: type: string AddressSummaryBatchView: type: object description: | Ordered indexed address summaries. Bulk responses favor predictable latency over cold repair; nullable fields and `activityCountExact=false` mean Starkscan does not have complete indexed evidence for that field in this batch response. additionalProperties: false required: - items properties: items: type: array maxItems: 128 items: $ref: "#/components/schemas/AddressSummaryView" AddressIntelligenceItemBaseView: type: object additionalProperties: false required: - address - label - protocol - isDeployed - classHash - currentClassHash - deploymentClassHash - classHashSource - classHashAsOfBlock - classHashAsOfBlockHash - classHashFinality - classLabel - classLabelSource - isAccount - createdOnIso - deployedAtTxHash - deployedByAddress - hasReceivedFunds - latestActivityBlock - totalActivityCount - activityCountExact - activityCoverage - source - labelSource - typeLabel - typeLabelSource properties: address: type: string label: type: - string - "null" description: Human-readable protocol, project, or token label when indexed attribution is known. labelSource: type: - string - "null" enum: - indexed_protocol_registry - indexed_token_metadata - curated_known_token_metadata - null description: Machine-readable provenance for `label`; null when no label is resolved. typeLabel: type: - string - "null" description: Human-readable account/contract type label derived from indexed account-kind evidence. This is separate from `label` and must not be treated as a curated counterparty name. typeLabelSource: type: - string - "null" enum: - indexed_account_kind - null description: Machine-readable provenance for `typeLabel`; null when no type label is resolved. protocol: anyOf: - $ref: "#/components/schemas/AddressAttributionProtocolView" - type: "null" isDeployed: type: - boolean - "null" description: True only when authoritative indexed deployment/class evidence exists. On Sepolia, null means the genesis-to-boundary class ledger has not certified a negative answer; a local indexed miss is not false. classHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Compatibility class hash. Uses currentClassHash when a trusted indexed current observation exists, otherwise deploymentClassHash. currentClassHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Newest trusted indexed runtime class observation. Read with classHashAsOfBlock and classHashAsOfBlockHash; it is not a claim about blocks after that boundary. deploymentClassHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Original indexed deployment class only when authoritative deployment evidence proves it. Null when unavailable; never inferred from current class or first activity. classHashSource: type: - string - "null" description: Evidence source for classHash. classHashAsOfBlock: type: - integer - "null" format: int64 minimum: 0 maximum: 9007199254740991 description: Exact evidence block for classHash when available. classHashAsOfBlockHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ description: Canonical block hash paired with classHashAsOfBlock. classHashFinality: type: - string - "null" enum: - finalized - null description: Finality of classHash evidence; null means the exact-block observation has not asserted finalized status. classLabel: type: - string - "null" description: Human-readable class-family label when `classHash` matches a reviewed official class registry. This is separate from `label` and must not be treated as a curated address name tag. classLabelSource: type: - string - "null" enum: - official_class_registry - null description: Machine-readable provenance for `classLabel`; null when no class-family label is resolved. isAccount: type: - boolean - "null" createdOnIso: type: - string - "null" format: date-time description: Indexed canonical deployment timestamp when authoritative deployment evidence exists. deployedAtTxHash: type: - string - "null" description: Indexed deployment transaction hash when authoritative deployment evidence exists. deployedByAddress: type: - string - "null" description: Indexed deployer/factory address when authoritative deployment attribution exists. deploymentProvenance: $ref: "#/components/schemas/AddressDeploymentProvenanceView" description: Present for a deployed address with a canonical creation boundary; omitted when no deployment evidence exists. A present value with status unavailable means the creation boundary is known but transaction-trace attribution is not certified. hasReceivedFunds: type: - boolean - "null" description: True when indexed or certified historical standard fungible-transfer evidence shows the address as recipient. On Sepolia, null means the genesis-to-boundary transfer scan has not certified a negative answer. latestActivityBlock: type: - integer - "null" format: int64 totalActivityCount: type: - integer - "null" format: int64 minimum: 0 description: Exhaustive count, a positive lower bound when one is actually materialized, or null. Proved activity may have a latestActivityBlock with a null total. Zero is valid only when activityCountExact=true and activityCoverage.status=exhaustive. activityCountExact: type: - boolean - "null" description: | True only when the returned activity count is exhaustive for the certified source range. False or null means the count is non-exact: it may be a positive lower bound or null. A null count can accompany a proved latest block when no numeric total is materialized. Only true makes zero trustworthy. activityCoverage: $ref: "#/components/schemas/AddressActivityCoverageView" source: type: string enum: - indexed_partner_address_evidence AddressActivityCoverageView: type: object additionalProperties: false required: - status - reasonCode - evidenceSource - fromBlock - throughBlock - sourceWatermarkBlock - sourceWatermarkHash properties: status: type: string enum: - exhaustive - lower_bound - partial - stale - unavailable reasonCode: type: string enum: - sealed_success_only_range - success_only_total_not_materialized - no_indexed_activity_evidence - activity_beyond_indexed_watermark - activity_evidence_unavailable - projection_watermark_unavailable - watermark_unavailable - indexed_watermark_lag evidenceSource: type: string enum: - indexed_successful_transaction_and_activity_summary fromBlock: type: - integer - "null" format: int64 throughBlock: type: - integer - "null" format: int64 sourceWatermarkBlock: type: - integer - "null" format: int64 sourceWatermarkHash: type: - string - "null" pattern: ^0x[0-9a-fA-F]{1,64}$ AddressIntelligenceItemView: oneOf: - allOf: - $ref: "#/components/schemas/AddressIntelligenceItemBaseView" - type: object description: Deployed address with authoritative indexed class evidence. required: - isDeployed - classHash properties: isDeployed: const: true classHash: type: string - allOf: - $ref: "#/components/schemas/AddressIntelligenceItemBaseView" - type: object description: Address without authoritative indexed deployment evidence. required: - isDeployed - classHash - createdOnIso - deployedAtTxHash - deployedByAddress not: required: - deploymentProvenance properties: isDeployed: const: false classHash: type: "null" createdOnIso: type: "null" deployedAtTxHash: type: "null" deployedByAddress: type: "null" AddressAttributionProtocolView: type: object additionalProperties: false required: - name - kind properties: name: type: string description: Human-readable protocol, project, or token label. kind: type: - string - "null" description: Indexed protocol or token kind when known. AddressAttributionBaseView: type: object additionalProperties: false required: - chainId - requestedAddress - canonicalAddress - known - label - confidence - source - protocol properties: chainId: type: string requestedAddress: type: string description: Address supplied by the client after path validation. canonicalAddress: type: string description: Canonical indexed Starknet address used for lookup. known: type: boolean description: True when Starkscan has a readable label/protocol attribution. label: type: - string - "null" description: Human-readable label when known. confidence: type: string enum: - high - none description: Confidence bucket for the resolved label. source: type: string enum: - indexed_address_attribution - indexed_protocol_registry - indexed_token_metadata - curated_known_token_metadata protocol: oneOf: - $ref: "#/components/schemas/AddressAttributionProtocolView" - type: "null" AddressAttributionView: oneOf: - allOf: - $ref: "#/components/schemas/AddressAttributionBaseView" - type: object description: Known address with a Starkscan-readable label. required: - known - label - confidence - protocol properties: known: const: true label: type: string confidence: const: high protocol: $ref: "#/components/schemas/AddressAttributionProtocolView" - allOf: - $ref: "#/components/schemas/AddressAttributionBaseView" - type: object description: Unknown address with no readable Starkscan attribution. required: - known - label - confidence - source - protocol properties: known: const: false label: type: "null" confidence: const: none source: const: indexed_address_attribution protocol: type: "null" AddressIntelligenceBatchView: type: object additionalProperties: false required: - contractVersion - sourceContractVersion - items properties: contractVersion: type: string const: starkscan.address_activity_truth.v1 description: Version of the public activity truth and correlation contract. sourceContractVersion: type: string const: indexed_successful_transaction_and_activity_summary.v1 description: Version of the bounded indexed evidence sources used by this response. items: type: array maxItems: 128 items: $ref: "#/components/schemas/AddressIntelligenceItemView" ClassDirectoryItemView: type: object additionalProperties: false description: | Indexed class fact derived from its earliest canonical DECLARE or legacy DEPLOY origin with optional deployment, ABI/class, and verification enrichment. A legacy deployment origin is not a declaration. `classLabel` is a reviewed class family label, not exact source verification. required: - chainId - classHash - classLabel - classLabelSource - verificationTier - verificationSource - verificationProvider - verificationEvidenceDigest - verificationObservedAtIso - verificationClaimCount - originKind - originTransactionHash - originatedAtBlock - originatedAtIso - originSource - originFinalityStatus - originRefreshedAtIso - declarationTxHash - declaredAtBlock - declaredAtIso - compiledClassHash - classKind - classVersion - abiAvailable - abiSource - instanceCount - currentInstanceCount - accountInstanceCount - contractInstanceCount - unknownInstanceCount - verifiedInstanceCount - instanceCoverage - firstSeenBlockNumber - usageAsOfBlock - firstSeenAtIso - sampleContractAddress - source - usageRefreshedAtIso - refreshedAtIso properties: chainId: type: string classHash: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ classLabel: type: - string - "null" description: Human-readable class-family label when the class hash matches the reviewed official class registry. classLabelSource: type: - string - "null" enum: - official_class_registry - null description: Machine-readable provenance for `classLabel`; null when no class-family label is resolved. verificationTier: type: string enum: - verified_exact - verified_external - official_release - source_candidate - abi_declared - class_family - unverified description: | Class verification tier. Values are ordered by evidence strength for this materialized directory: `verified_exact` means Starkscan has an active successful immutable verification receipt whose produced canonical class hash matches this class under an accepted verifier policy; `verified_external` is reserved for trusted third-party verification; `official_release` is reserved for official project release metadata; `source_candidate` is reserved for unverified source-candidate evidence; `abi_declared` means indexed ABI/class metadata is available but source is not verified; `class_family` means the class hash belongs to a reviewed official class-family registry and is not exact source verification; `unverified` means no verification, ABI, or class-family evidence was materialized. x-enumDescriptions: verified_exact: An active successful immutable Starkscan verification receipt exactly matches this canonical class hash. verified_external: Reserved for trusted external verifier evidence. official_release: Reserved for official project release metadata. source_candidate: Reserved for unverified source-candidate evidence. abi_declared: Indexed ABI/class metadata exists, but source verification is not established. class_family: Reviewed official class-family registry match only; not exact source verification. unverified: No verification, ABI, or class-family evidence is materialized. verificationSource: type: - string - "null" description: Machine-readable source family for the verification claim. `receipt` identifies an active Starkscan exact receipt; `federated_external` identifies retained provider evidence. verificationProvider: type: - string - "null" description: Verification provider. `starkscan` identifies independently rebuilt exact receipt evidence; external values identify the observing provider and do not imply a Starkscan rebuild. verificationEvidenceDigest: type: - string - "null" description: Content digest for the active exact receipt candidate or immutable build evidence, or for the retained external claim, when available. verificationObservedAtIso: type: - string - "null" format: date-time description: Exact receipt completion time or external claim observation time, depending on `verificationSource`. verificationClaimCount: type: - integer - "null" format: int64 minimum: 0 description: Number of active exact receipts or retained external claims supporting this materialized tier. originKind: type: - string - "null" enum: - declare - legacy_deploy - null description: How the class first entered the indexed chain. Legacy deployment is explicitly not declaration proof. originTransactionHash: type: - string - "null" description: Transaction containing the canonical indexed class origin. originatedAtBlock: type: - integer - "null" format: int64 originatedAtIso: type: - string - "null" format: date-time originSource: type: - string - "null" enum: - indexed_finalized_declare_tx - indexed_head_declare_tx - indexed_finalized_legacy_deploy_tx - indexed_head_legacy_deploy_tx - null originFinalityStatus: type: - string - "null" enum: - finalized - head - null originRefreshedAtIso: type: - string - "null" format: date-time declarationTxHash: type: - string - "null" description: Declaration transaction hash when indexed; null for legacy deployment-only or observation-only rows. declaredAtBlock: type: - integer - "null" format: int64 declaredAtIso: type: - string - "null" format: date-time compiledClassHash: type: - string - "null" description: Compiled class hash when supplied by indexed declaration metadata. classKind: type: - string - "null" description: Indexed class kind when supplied by declaration metadata. classVersion: type: - string - "null" description: Cairo or class-version metadata when materialized. abiAvailable: type: boolean abiSource: type: - string - "null" instanceCount: type: integer format: int64 minimum: 0 currentInstanceCount: type: integer format: int64 minimum: 0 description: Computed count of indexed addresses with a current ABI/class observation for this class. This is not a current-class-hash guarantee. accountInstanceCount: type: integer format: int64 minimum: 0 description: Count of indexed instances with explicit account evidence. contractInstanceCount: type: integer format: int64 minimum: 0 description: Count of indexed instances with explicit non-account evidence. unknownInstanceCount: type: integer format: int64 minimum: 0 description: Count of indexed instances without authoritative account-or-contract kind evidence. instanceCount equals accountInstanceCount plus contractInstanceCount plus unknownInstanceCount. verifiedInstanceCount: type: integer format: int64 minimum: 0 instanceCoverage: $ref: "#/components/schemas/ClassInstanceCoverageView" firstSeenBlockNumber: type: - integer - "null" format: int64 description: Earliest block from one paired indexed class-association evidence row; never derived from an unrelated address creation timestamp. usageAsOfBlock: type: - integer - "null" format: int64 description: Highest indexed relationship-evidence block included in the materialized usage counts. firstSeenAtIso: type: - string - "null" format: date-time description: Timestamp from the same evidence row as firstSeenBlockNumber. sampleContractAddress: type: - string - "null" pattern: ^0[xX][0-9a-fA-F]{1,64}$ source: type: string enum: - indexed_class_observation - indexed_finalized_declare_tx - indexed_head_declare_tx - indexed_finalized_legacy_deploy_tx - indexed_head_legacy_deploy_tx description: Evidence backing this row. Origin sources do not imply source-code verification. usageRefreshedAtIso: type: - string - "null" format: date-time description: Last refresh of usage counts and instance enrichment, separate from origin provenance freshness. refreshedAtIso: type: string format: date-time ClassInstanceCoverageView: type: object additionalProperties: false description: | Scope and classification evidence for class instance counts. Class counts are indexed observations, not a chain-wide census; consumers must not infer omitted instances from a numeric count. required: - coverageStatus - reasonCode - observedFromBlock - observedThroughBlock - classificationCoverage - isLowerBound - isExhaustive properties: coverageStatus: type: string enum: - partial - unavailable description: "`partial` means the usage projection produced a bounded indexed-observation window; `unavailable` means no trustworthy usage watermark exists." reasonCode: type: string enum: - indexed_observation_window - usage_projection_unavailable observedFromBlock: type: - integer - "null" format: int64 minimum: 0 description: Inclusive earliest materialized class-association evidence block, not necessarily the class's first chain occurrence. observedThroughBlock: type: - integer - "null" format: int64 minimum: 0 description: Inclusive usage-projection watermark for the materialized observation window. classificationCoverage: type: string enum: - partial - known_for_observed_instances - unavailable description: "`known_for_observed_instances` applies only to materialized rows; it is not a claim of chain-wide account-or-contract classification." isLowerBound: type: boolean description: True only when an observation window exists and the numeric counts can safely be treated as lower bounds. isExhaustive: type: boolean enum: - false description: Always false for the indexed-observation directory; it is not a global class-instance census. oneOf: - title: Bounded indexed-observation window properties: coverageStatus: const: partial reasonCode: const: indexed_observation_window observedFromBlock: type: integer observedThroughBlock: type: integer classificationCoverage: enum: - partial - known_for_observed_instances isLowerBound: const: true - title: No trustworthy usage watermark properties: coverageStatus: const: unavailable reasonCode: const: usage_projection_unavailable observedFromBlock: type: "null" observedThroughBlock: type: "null" classificationCoverage: const: unavailable isLowerBound: const: false ClassDirectoryPageView: type: object additionalProperties: false required: - items - nextCursor - source - catalogTotal - usageCohortTotal - catalogAsOfBlock - originSetDigest - originRefreshedAtIso - usageAsOfBlock - latestRelationshipEvidenceBlock - usageRefreshedAtIso properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/ClassDirectoryItemView" nextCursor: type: - string - "null" pattern: ^c(?:1:[0-9]+:0[xX][0-9a-fA-F]{1,64}|2:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]{1,64})$ source: type: string enum: - indexed_class_observation - indexed_class_origin catalogTotal: type: - integer - "null" format: int64 minimum: 0 description: Total materialized canonical class origins for this chain, independent of the loaded page or filters. usageCohortTotal: type: - integer - "null" format: int64 minimum: 0 description: Number of classes with materialized usage relationships. The instances_desc page is bounded to this cohort; it is separate from catalogTotal. catalogAsOfBlock: type: - integer - "null" format: int64 minimum: 0 description: Highest contiguous indexed block reconciled into the canonical class-origin catalog, beginning at block 0. Null means contiguous historical certification has not yet been established. originSetDigest: type: - string - "null" pattern: ^sha256:[0-9a-f]{64}$ description: Deterministic digest of the sorted canonical class-hash set for reconciliation evidence. originRefreshedAtIso: type: - string - "null" format: date-time description: Last successful canonical class-origin materialization time. usageAsOfBlock: type: - integer - "null" format: int64 minimum: 0 description: Indexed transaction head recorded when the off-request-path usage projection completed. This is a freshness reference, not proof that every relationship changed at that block; use latestRelationshipEvidenceBlock for the newest carried relationship evidence. latestRelationshipEvidenceBlock: type: - integer - "null" format: int64 minimum: 0 description: Highest block carried by a materialized class-relationship evidence row; may trail usageAsOfBlock when no relationship changed recently. usageRefreshedAtIso: type: - string - "null" format: date-time description: Last successful class-usage projection refresh time. ClassInstanceView: type: object additionalProperties: false required: - address - isAccount - relationshipKind - evidenceBlockNumber - evidenceTransactionHash - evidenceAtIso - evidenceSource - deployedAtBlock - deployedAtTxHash - deployedByAddress - createdOnIso - observedAtBlock - observedAtIso - observationSource - source properties: address: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ isAccount: type: - boolean - "null" relationshipKind: type: string enum: - deployed_as_class - current_class - abi_observed_class - historical_class_epoch - observed_class description: Evidence-specific relationship between this address and class. evidenceBlockNumber: type: - integer - "null" format: int64 evidenceTransactionHash: type: - string - "null" evidenceAtIso: type: - string - "null" format: date-time evidenceSource: type: string deployedAtBlock: type: - integer - "null" format: int64 deployedAtTxHash: type: - string - "null" deployedByAddress: type: - string - "null" createdOnIso: type: - string - "null" format: date-time observedAtBlock: type: - integer - "null" format: int64 description: Observation block for non-deployment class evidence; never presented as deployment proof. observedAtIso: type: - string - "null" format: date-time observationSource: type: - string - "null" source: type: string ClassDetailView: type: object additionalProperties: false required: - class - instances - nextInstanceCursor properties: class: $ref: "#/components/schemas/ClassDirectoryItemView" instances: type: array maxItems: 100 items: $ref: "#/components/schemas/ClassInstanceView" nextInstanceCursor: type: - string - "null" pattern: ^(?:0[xX][0-9a-fA-F]{1,64}|c3:(?:-1|[0-9]+):0[xX][0-9a-fA-F]{1,64})$ WalletAssetDiscoveryMetadata: type: object required: - symbol - name - decimals - source - trusted - spamStatus properties: symbol: type: - string - "null" name: type: - string - "null" decimals: type: - integer - "null" source: type: string enum: - reviewed_registry - indexed_metadata - unavailable trusted: type: boolean spamStatus: type: string const: not_assessed description: Spam classification is not currently performed. `not_assessed` must not be interpreted as safe, trusted, or non-spam. WalletAssetDiscoveryEvidence: type: object required: - tier - source - lastObservedBlock - evidenceCountLowerBound properties: tier: type: string enum: - reviewed_registry - indexed_discovery source: type: string enum: - checked_in_registry - fungible_transfer_evidence lastObservedBlock: type: - integer - "null" format: int64 evidenceCountLowerBound: type: - integer - "null" format: int64 description: Monotonic lower bound on indexed transfer evidence for this owner-token pair. It is the greatest idempotently observed batch count, not a cumulative or exact event count, and never a balance. WalletAssetDiscoveryItem: type: object required: - tokenAddress - evidence - metadata properties: tokenAddress: type: string evidence: type: array items: $ref: "#/components/schemas/WalletAssetDiscoveryEvidence" metadata: $ref: "#/components/schemas/WalletAssetDiscoveryMetadata" WalletAssetDiscoveryCoverage: type: object required: - declaredScope - completeWithinScope - globallyComplete - reasonCodes - coveredThroughBlock - targetThroughBlock - tailObservedThroughBlock properties: declaredScope: type: string enum: - standard_fungible_transfer_evidence - caller_explicit completeWithinScope: type: boolean globallyComplete: type: boolean const: false reasonCodes: type: array items: type: string enum: - seed_incomplete - source_truncated - tail_stale - unsupported_nonstandard coveredThroughBlock: type: - integer - "null" format: int64 description: Last block included in the completed historical discovery seed. This is not the current transfer-tail watermark. targetThroughBlock: type: - integer - "null" format: int64 description: Target block for the historical discovery seed. Seed progress is complete only when coveredThroughBlock reaches this boundary. tailObservedThroughBlock: type: - integer - "null" format: int64 description: Last block observed by the bounded standard ERC-20 transfer tail. This does not cover nonstandard token patterns; globallyComplete remains false with unsupported_nonstandard. WalletAssetDiscoveryPage: type: object required: - schemaVersion - chainId - ownerAddress - scope - snapshotId - items - hasMore - nextCursor - coverage properties: schemaVersion: type: string const: starkscan.wallet_asset_discovery.v1 chainId: type: string ownerAddress: type: string scope: type: string enum: - discovered - discovered_plus_registry snapshotId: type: string items: type: array maxItems: 50 items: $ref: "#/components/schemas/WalletAssetDiscoveryItem" hasMore: type: boolean nextCursor: type: - string - "null" coverage: $ref: "#/components/schemas/WalletAssetDiscoveryCoverage" RetiredTokenHoldingsResponse: type: object required: - schemaVersion - code - message - chainId - ownerAddress - requestId - migrationGuide - successors properties: schemaVersion: type: string const: starkscan.retirement.v1 code: type: string const: token_holdings_retired message: type: string migrationGuide: type: string successors: type: array items: type: object required: - rel - method - path properties: rel: type: string enum: - asset_discovery - wallet_state method: type: string enum: - GET - POST path: type: string chainId: type: string ownerAddress: type: string requestId: type: string WalletStateIncludeRequest: type: object properties: nonce: type: boolean default: false classHash: type: boolean default: false additionalProperties: false WalletStateRequest: type: object required: - ownerAddress properties: ownerAddress: type: string mode: type: string enum: - require_complete - verified_partial default: require_complete scope: type: string enum: - explicit - discovered - discovered_plus_registry description: | `discovered` uses wallet-observed candidates only. `discovered_plus_registry` also evaluates the curated registry and can require pagination even when no wallet-observed asset exists. tokenAddresses: type: array maxItems: 25 uniqueItems: true items: type: string cursor: type: string limit: type: integer minimum: 1 maximum: 25 default: 25 blockPreference: type: string enum: - latest_accepted_l2 - l1_accepted - explicit default: latest_accepted_l2 blockHash: type: string blockNumber: type: integer format: int64 minimum: 0 include: $ref: "#/components/schemas/WalletStateIncludeRequest" additionalProperties: false WalletStateBlock: type: object required: - preference - blockNumber - blockHash - finalityStatus properties: preference: type: string blockNumber: type: integer format: int64 blockHash: type: string finalityStatus: type: string enum: - accepted_on_l2 - accepted_on_l1 - explicit WalletStatePrice: type: object required: - status - reasonCode - quoteCurrency - priceUsd - valueUsd - source - provider - confidence - valuationMethod - priceTimestamp - observedAt - maxAgeSeconds oneOf: - title: Fresh direct market quote properties: status: const: priced reasonCode: const: fresh_exact_cached_price valuationMethod: const: direct_market_quote confidence: const: exact - title: Fresh conversion estimate properties: status: const: priced reasonCode: const: fresh_conversion_estimate valuationMethod: const: snip22_conversion_estimate confidence: const: proxy - title: Wallet price unavailable properties: status: const: unavailable valuationMethod: const: null reasonCode: enum: - price_metadata_unavailable - token_metadata_missing - token_unmapped - price_not_exact - price_missing - price_stale - value_calculation_failed properties: status: type: string enum: - priced - unavailable description: "`priced` is valid with either a fresh exact direct quote or a fresh reviewed conversion estimate and a non-null unit price. `valueUsd` is non-null only when the wallet balance was verified and value calculation succeeded. `unavailable` preserves the non-zero holding but excludes it from wallet totals." reasonCode: type: string enum: - fresh_exact_cached_price - fresh_conversion_estimate - price_metadata_unavailable - token_metadata_missing - token_unmapped - price_not_exact - price_missing - price_stale - value_calculation_failed description: Stable machine-readable reason for the pricing decision. A missing, empty, or unknown value is a response-contract violation; retain the response x-request-id and report it. quoteCurrency: type: string const: usd priceUsd: type: - string - "null" valueUsd: type: - string - "null" source: type: - string - "null" provider: type: - string - "null" confidence: type: - string - "null" valuationMethod: type: - string - "null" enum: - direct_market_quote - snip22_conversion_estimate - null priceTimestamp: type: - string - "null" format: date-time description: Provider quote timestamp used for the freshness decision; distinct from observedAt, which is materialization time. observedAt: type: - string - "null" format: date-time description: Time Starkscan materialized the quote; not the provider quote timestamp. maxAgeSeconds: type: - integer - "null" WalletStateAsset: type: object required: - tokenAddress - balanceRaw - status - metadata - price properties: tokenAddress: type: string balanceRaw: type: - string - "null" description: Present only when balanceOf succeeded at block.blockHash. Never indexed or synthesized from an error. status: type: string enum: - ok - unsupported - timeout - error metadata: $ref: "#/components/schemas/WalletAssetDiscoveryMetadata" price: $ref: "#/components/schemas/WalletStatePrice" WalletStateVerification: type: object required: - selected - verified - visibleNonZero - verifiedZeroHidden - failed - timedOut - unsupported properties: selected: type: integer description: Token candidates selected for block-pinned balance verification. Account-state reads are not included. verified: type: integer description: Token balanceOf calls that succeeded at block.blockHash, including verified zeros. visibleNonZero: type: integer description: Verified non-zero token balances returned in items. verifiedZeroHidden: type: integer description: Verified zero token balances intentionally omitted from items. failed: type: integer description: Token balance verification failures only. Inspect accountState statuses separately. timedOut: type: integer description: Failed token verifications classified as timeouts. unsupported: type: integer description: Failed token verifications classified as unsupported balanceOf behavior. WalletStateAccountState: type: object required: - nonce - nonceStatus - classHash - classHashStatus properties: nonce: type: - string - "null" nonceStatus: type: string enum: - not_requested - verified - timeout - error classHash: type: - string - "null" classHashStatus: type: string enum: - not_requested - verified - timeout - error WalletStateValuation: type: object required: - scope - singlePageComplete - completeForWallet - totalUsd - pricedAssetCount - unpricedNonZeroAssetCount - excludedUnpricedAssets properties: scope: type: string const: page description: Valuation counters and totalUsd cover only items in this response page. singlePageComplete: type: boolean description: True only when this discovery walk began without a cursor and the first response is terminal. It says the page is the whole selected discovery walk; it never describes a continuation page or a caller-supplied explicit token subset. completeForWallet: type: boolean deprecated: true description: Deprecated compatibility alias for singlePageComplete. On raw scope=page responses this is not a wallet-wide valuation guarantee. Use hasMore=false or nextCursor=null to detect walk termination, or the SDK aggregate's scope=wallet result for wallet-wide valuation. totalUsd: type: - string - "null" description: Exact decimal subtotal for priced assets in this response page. Raw scope=page responses never make this a wallet-wide total. pricedAssetCount: type: integer unpricedNonZeroAssetCount: type: integer excludedUnpricedAssets: type: boolean description: True means unpriced non-zero assets remain visible but are excluded from totalUsd; they are never counted as zero. WalletStateResponse: type: object required: - schemaVersion - chainId - ownerAddress - requestId - block - scope - coverage - correctness - partial - walletSafe - items - verification - accountState - valuation - hasMore - nextCursor properties: schemaVersion: type: string const: starkscan.wallet_state.v1 chainId: type: string ownerAddress: type: string requestId: type: string block: $ref: "#/components/schemas/WalletStateBlock" scope: type: string enum: - explicit - discovered - discovered_plus_registry description: | `discovered` uses wallet-observed candidates only. `discovered_plus_registry` also evaluates the curated registry and can require pagination even when no wallet-observed asset exists. coverage: $ref: "#/components/schemas/WalletAssetDiscoveryCoverage" correctness: type: string enum: - verified_complete - verified_partial partial: type: boolean walletSafe: type: boolean description: True only when verification is complete, the page has no continuation, and discovery is complete within its declared scope. items: type: array maxItems: 25 items: $ref: "#/components/schemas/WalletStateAsset" verification: $ref: "#/components/schemas/WalletStateVerification" accountState: $ref: "#/components/schemas/WalletStateAccountState" valuation: $ref: "#/components/schemas/WalletStateValuation" hasMore: type: boolean nextCursor: type: - string - "null" WalletPaymasterViewRequest: type: object additionalProperties: false required: - addresses properties: addresses: type: array minItems: 1 maxItems: 32 items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ include: $ref: "#/components/schemas/WalletPaymasterViewInclude" freshness: $ref: "#/components/schemas/WalletPaymasterViewFreshness" WalletPaymasterViewInclude: type: object additionalProperties: false properties: identity: type: boolean default: true accountState: type: boolean default: true tokenHoldings: oneOf: - $ref: "#/components/schemas/WalletPaymasterLimitedSectionRequest" - type: "null" description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section. recentTransactions: oneOf: - $ref: "#/components/schemas/WalletPaymasterRecentTransactionsRequest" - type: "null" description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section. bridgeAndMessages: type: boolean default: false description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section. finality: type: boolean default: true provenanceDetails: type: boolean default: false description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section; row-level details are not exposed in the first slice. WalletPaymasterLimitedSectionRequest: type: object additionalProperties: false properties: enabled: type: - boolean - "null" limit: type: - integer - "null" format: int32 minimum: 1 maximum: 100 cursorsByAddress: type: object additionalProperties: type: - string - "null" includeSpam: type: boolean default: false WalletPaymasterRecentTransactionsRequest: type: object additionalProperties: false properties: enabled: type: - boolean - "null" limit: type: - integer - "null" format: int32 minimum: 1 maximum: 25 cursorsByAddress: type: object additionalProperties: type: - string - "null" includeReceipts: type: boolean default: false WalletPaymasterViewFreshness: type: object additionalProperties: false properties: maxIndexedLagMs: type: - integer - "null" format: int64 minimum: 0 description: Accepted for forward-compatible requests; current responses warn that millisecond freshness is unavailable. requireFresh: type: boolean default: false DefiLendingMarketViewRequest: type: object additionalProperties: false required: - markets properties: markets: type: array minItems: 1 maxItems: 8 items: $ref: "#/components/schemas/DefiLendingMarketSelectorRequest" include: $ref: "#/components/schemas/DefiLendingMarketViewInclude" freshness: $ref: "#/components/schemas/DefiLendingMarketViewFreshness" DefiLendingMarketSelectorRequest: type: object additionalProperties: false required: - marketId properties: marketId: type: string minLength: 1 maxLength: 128 description: Client-supplied stable market identifier, for example `vesu-main`. contracts: type: array maxItems: 32 items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ description: Lending market, pool, singleton, vToken, periphery, oracle, or liquidation-helper contracts to hydrate from indexed address summaries. tokenAddresses: type: array maxItems: 32 items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ description: Token addresses relevant to the selected market; echoed back for stable partner request correlation. DefiLendingMarketViewInclude: type: object additionalProperties: false properties: contractIdentity: type: boolean default: true stateSamples: oneOf: - $ref: "#/components/schemas/DefiLendingStateSamplesRequest" - type: "null" description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section. events: oneOf: - $ref: "#/components/schemas/DefiLendingEventsRequest" - type: "null" description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section. recentTransactions: oneOf: - $ref: "#/components/schemas/DefiLendingRecentTransactionsRequest" - type: "null" description: Reserved for forward-compatible requests. When omitted, null, or disabled it is ignored; when enabled in v1 the request fails closed with unsupported_section. simulationMetadata: type: boolean default: true description: Returns the Query Plane boundary that simulation and signed-write execution remain on JSON-RPC. provenanceDetails: type: boolean default: false description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section; row-level details are not exposed in the first slice. DefiLendingStateSamplesRequest: type: object additionalProperties: false properties: enabled: type: - boolean - "null" keys: type: array items: type: string maxItems: 16 maxSamplesPerContract: type: - integer - "null" format: int32 minimum: 1 maximum: 16 DefiLendingEventsRequest: type: object additionalProperties: false properties: enabled: type: - boolean - "null" eventSelectors: type: array items: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ fromBlock: type: - integer - "null" format: int64 minimum: 0 toBlock: type: - integer - "null" format: int64 minimum: 0 limit: type: - integer - "null" format: int32 minimum: 1 maximum: 500 cursorsByMarketId: type: object additionalProperties: type: - string - "null" DefiLendingRecentTransactionsRequest: type: object additionalProperties: false properties: enabled: type: - boolean - "null" limit: type: - integer - "null" format: int32 minimum: 1 maximum: 50 cursorsByMarketId: type: object additionalProperties: type: - string - "null" DefiLendingMarketViewFreshness: type: object additionalProperties: false properties: maxIndexedLagMs: type: - integer - "null" format: int64 minimum: 0 description: Accepted for forward-compatible requests; current responses warn that millisecond freshness is unavailable. requireFresh: type: boolean default: false SupportProofBundleRequest: type: object additionalProperties: false properties: txHash: type: - string - "null" pattern: ^0[xX][0-9a-fA-F]{1,64}$ description: Incident transaction hash. Exactly one of `txHash` or `messageHash` is required. messageHash: type: - string - "null" pattern: ^0[xX][0-9a-fA-F]{1,64}$ description: Incident protocol-message hash. Exactly one of `txHash` or `messageHash` is required. supportCorrelationId: type: - string - "null" maxLength: 128 description: Optional customer-support ticket, case, or incident id echoed back for operator correlation. include: $ref: "#/components/schemas/SupportProofBundleInclude" freshness: $ref: "#/components/schemas/SupportProofBundleFreshness" SupportProofBundleInclude: type: object additionalProperties: false properties: transaction: type: boolean default: true description: Return transaction detail when the incident selector is `txHash`; message-hash incidents return a warning instead of doing a reverse scan. protocolMessages: type: boolean default: true starkgate: type: boolean default: true finality: type: boolean default: true provenanceDetails: type: boolean default: false description: Reserved for forward-compatible requests. In v1, true fails closed with unsupported_section; row-level details are not exposed in the first slice. SupportProofBundleFreshness: type: object additionalProperties: false properties: maxIndexedLagMs: type: - integer - "null" format: int64 minimum: 0 description: Accepted for forward-compatible requests; current responses warn that millisecond freshness is unavailable. requireFresh: type: boolean default: false WalletPaymasterQueryEnvelope: type: object additionalProperties: false required: - schemaVersion - chain - requestId - snapshot - provenance - partial - warnings - data properties: schemaVersion: type: string enum: - starkscan.query.wallet_paymaster_view.v1 chain: type: string requestId: type: string snapshot: $ref: "#/components/schemas/QueryPlaneSnapshot" provenance: type: array items: $ref: "#/components/schemas/QueryPlaneProvenance" partial: type: boolean description: True when requested sections or source rows are unavailable and warnings explain the gap. warnings: type: array items: $ref: "#/components/schemas/QueryPlaneWarning" data: $ref: "#/components/schemas/WalletPaymasterViewData" DefiLendingMarketQueryEnvelope: type: object additionalProperties: false required: - schemaVersion - chain - requestId - snapshot - provenance - partial - warnings - data properties: schemaVersion: type: string enum: - starkscan.query.defi_lending_market_view.v1 chain: type: string requestId: type: string snapshot: $ref: "#/components/schemas/QueryPlaneSnapshot" provenance: type: array items: $ref: "#/components/schemas/QueryPlaneProvenance" partial: type: boolean description: True when requested sections or source rows are unavailable and warnings explain the gap. warnings: type: array items: $ref: "#/components/schemas/QueryPlaneWarning" data: $ref: "#/components/schemas/DefiLendingMarketViewData" SupportProofBundleEnvelope: type: object additionalProperties: false required: - schemaVersion - chain - requestId - snapshot - provenance - partial - warnings - data properties: schemaVersion: type: string enum: - starkscan.query.support_proof_bundle.v1 chain: type: string requestId: type: string snapshot: $ref: "#/components/schemas/QueryPlaneSnapshot" provenance: type: array items: $ref: "#/components/schemas/QueryPlaneProvenance" partial: type: boolean description: True when requested sections or source rows are unavailable and warnings explain the gap. warnings: type: array items: $ref: "#/components/schemas/QueryPlaneWarning" data: $ref: "#/components/schemas/SupportProofBundleData" QueryPlaneSnapshot: type: object additionalProperties: false required: - blockNumber - blockHash - l1AcceptedBlockNumber - l1AcceptedSource - finalityStatus - freshnessMs - watermarkSource properties: blockNumber: type: - integer - "null" format: int64 blockHash: type: - string - "null" l1AcceptedBlockNumber: type: - integer - "null" format: int64 l1AcceptedSource: type: - string - "null" finalityStatus: type: string enum: - l1_accepted - l2_accepted - unknown freshnessMs: type: - integer - "null" format: int64 watermarkSource: type: string enum: - indexed_read_model QueryPlaneProvenance: type: object additionalProperties: false required: - fact - source - blockNumber - coverage properties: fact: type: string source: type: string blockNumber: type: - integer - "null" format: int64 coverage: type: string QueryPlaneWarning: type: object additionalProperties: false required: - warningCode - message properties: warningCode: type: string section: type: string source: type: string sourceBlockNumber: type: integer format: int64 bundleBlockNumber: description: | Bundle snapshot block number associated with this warning. This is the indexed Query Plane snapshot block, not the live head unless the bundle snapshot itself falls back to the live head. type: integer format: int64 message: type: string WalletPaymasterViewData: type: object additionalProperties: false required: - addresses properties: addresses: type: array maxItems: 32 items: $ref: "#/components/schemas/WalletPaymasterAddressView" WalletPaymasterAddressView: type: object additionalProperties: false required: - address properties: address: type: string identity: $ref: "#/components/schemas/WalletPaymasterIdentityView" accountState: $ref: "#/components/schemas/WalletPaymasterAccountStateView" tokenHoldings: type: "null" description: Present as null only when requested; first slice returns an unsupported-section warning. recentTransactions: type: "null" description: Present as null only when requested; first slice returns an unsupported-section warning. bridgeAndMessages: type: "null" description: Present as null only when requested; first slice returns an unsupported-section warning. finality: $ref: "#/components/schemas/WalletPaymasterFinalityView" WalletPaymasterIdentityView: type: object additionalProperties: false required: - label - protocol - isAccount - source properties: label: type: - string - "null" protocol: oneOf: - type: object additionalProperties: true - type: "null" description: Indexed protocol attribution object when available. isAccount: type: - boolean - "null" source: type: string enum: - starkscan_address_summary_read_model WalletPaymasterAccountStateView: type: object additionalProperties: false required: - classHash - nonce - deployed - latestObservedBlock - activityCount - activityCountExact - createdOnIso - deployedAtTxHash - deployedByAddress properties: classHash: type: - string - "null" nonce: type: - string - "null" deployed: type: - boolean - "null" latestObservedBlock: type: - integer - "null" format: int64 activityCount: type: - integer - "null" format: int64 activityCountExact: type: - boolean - "null" createdOnIso: type: - string - "null" format: date-time deployedAtTxHash: type: - string - "null" deployedByAddress: type: - string - "null" WalletPaymasterFinalityView: type: object additionalProperties: false required: - latestL1AcceptedBlockNumber - source properties: latestL1AcceptedBlockNumber: type: - integer - "null" format: int64 source: type: - string - "null" DefiLendingMarketViewData: type: object additionalProperties: false required: - markets properties: markets: type: array maxItems: 8 items: $ref: "#/components/schemas/DefiLendingMarketView" DefiLendingMarketView: type: object additionalProperties: false required: - marketId - tokenAddresses properties: marketId: type: string tokenAddresses: type: array maxItems: 32 items: type: string contracts: type: array maxItems: 32 items: $ref: "#/components/schemas/DefiLendingContractIdentityView" simulationMetadata: $ref: "#/components/schemas/DefiLendingSimulationMetadataView" DefiLendingContractIdentityView: type: object additionalProperties: false required: - address - classHash - deployed - latestObservedBlock - activityCount - activityCountExact - source properties: address: type: string classHash: type: - string - "null" deployed: type: - boolean - "null" latestObservedBlock: type: - integer - "null" format: int64 activityCount: type: - integer - "null" format: int64 activityCountExact: type: - boolean - "null" source: type: string enum: - starkscan_address_summary_read_model DefiLendingSimulationMetadataView: type: object additionalProperties: false required: - supported - boundary - source properties: supported: type: boolean enum: - false boundary: type: string description: Query Plane v1 boundary. Simulation and signed-write execution remain on the JSON-RPC compatibility plane. source: type: string enum: - starkscan_query_plane_contract SupportProofBundleData: type: object additionalProperties: false required: - incident properties: incident: $ref: "#/components/schemas/SupportProofIncidentView" transaction: oneOf: - $ref: "#/components/schemas/TransactionDetailView" - type: "null" description: Present when requested and the incident selector is a transaction hash. protocolMessages: oneOf: - $ref: "#/components/schemas/MessagePage" - type: "null" description: Protocol-message lifecycle rows for the incident selector. starkgate: oneOf: - $ref: "#/components/schemas/StarkgateTransferResolutionView" - type: "null" description: StarkGate transfer resolution for the incident selector. finality: oneOf: - $ref: "#/components/schemas/SupportProofFinalityView" - type: "null" SupportProofIncidentView: type: object additionalProperties: false required: - txHash - messageHash - supportCorrelationId properties: txHash: type: - string - "null" messageHash: type: - string - "null" supportCorrelationId: type: - string - "null" SupportProofFinalityView: type: object additionalProperties: false required: - latestL1AcceptedBlockNumber - source - bundleFinalityStatus properties: latestL1AcceptedBlockNumber: type: - integer - "null" format: int64 source: type: - string - "null" bundleFinalityStatus: type: string enum: - l1_accepted - l2_accepted - unknown ContractVerificationView: type: object additionalProperties: false required: - chainId - contractAddress - classHash - sourceRef - language - compilerVersion - verificationStatus - verificationError - requestedAtIso - verifiedAtIso - updatedAtIso - metadata properties: chainId: type: string contractAddress: type: string classHash: type: - string - "null" sourceRef: type: - string - "null" language: type: - string - "null" compilerVersion: type: - string - "null" verificationStatus: description: Legacy migration state only; never establishes source verification. type: string enum: - pending - failed verificationError: type: - string - "null" requestedAtIso: type: string verifiedAtIso: type: - string - "null" updatedAtIso: type: string metadata: type: object ContractEntrypointItem: type: object additionalProperties: false required: - selector - name - stateMutability - inputs - outputs properties: selector: type: string name: type: - string - "null" stateMutability: type: - string - "null" inputs: type: array maxItems: 64 items: $ref: "#/components/schemas/ContractAbiParameterView" outputs: type: array maxItems: 64 items: $ref: "#/components/schemas/ContractAbiParameterView" ContractAbiParameterView: type: object additionalProperties: false required: - name - type properties: name: type: - string - "null" type: type: string ContractAbiTypeView: type: object additionalProperties: false required: - name - kind - members properties: name: type: string kind: type: string enum: - struct - enum members: type: array maxItems: 128 items: $ref: "#/components/schemas/ContractAbiParameterView" ContractEntrypointsView: type: object additionalProperties: false required: - chainId - contractAddress - classHash - requestedBlockTag - blockTag - blockNumber - finalityStatus - external - constructor - l1Handler - abiTypes - abiTypesTruncated properties: chainId: type: string contractAddress: type: string classHash: type: string description: Class hash resolved at blockTag. requestedBlockTag: type: string description: Caller-supplied latest, block number, or block hash reference. blockTag: type: string description: Canonical block hash used for the class hash, class ABI, and paired contract call. blockNumber: type: integer format: int64 minimum: 0 finalityStatus: type: string enum: - ACCEPTED_ON_L1 - ACCEPTED_ON_L2 external: type: array maxItems: 256 items: $ref: "#/components/schemas/ContractEntrypointItem" constructor: type: array maxItems: 16 items: $ref: "#/components/schemas/ContractEntrypointItem" l1Handler: type: array maxItems: 16 items: $ref: "#/components/schemas/ContractEntrypointItem" abiTypes: type: array maxItems: 512 items: $ref: "#/components/schemas/ContractAbiTypeView" abiTypesTruncated: type: boolean ContractClassEpochView: type: object additionalProperties: false required: - classHash - fromBlockNumber - fromTxIndex - toBlockNumber - toTxIndex - isCurrent - source - confidence - incompleteReason properties: classHash: type: string fromBlockNumber: type: integer format: int64 fromTxIndex: type: integer format: int32 toBlockNumber: type: - integer - "null" format: int64 toTxIndex: type: - integer - "null" format: int32 isCurrent: type: boolean description: Compatibility name for the newest open observed epoch; not proof of the class currently in force. source: type: string confidence: type: string incompleteReason: type: - string - "null" ContractClassHistoryView: type: object additionalProperties: false required: - address - limit - epochs - truncated - coverage properties: address: type: string limit: type: integer format: int64 minimum: 1 maximum: 100 epochs: type: array maxItems: 100 description: Newest-first observed epochs. This array can omit unobserved class changes. items: $ref: "#/components/schemas/ContractClassEpochView" truncated: type: boolean description: True only when more observed rows exist than this bounded page returns; false does not certify complete upgrade history. coverage: $ref: "#/components/schemas/ContractClassHistoryCoverageView" ContractClassHistoryCoverageView: type: object additionalProperties: false required: - status - source - reasonCode - message properties: status: type: string enum: - partial source: type: string enum: - event_time_abi_observations reasonCode: type: string enum: - observation_backed_not_exhaustive message: type: string description: Human-readable warning that unobserved class changes can be absent. EventDecodedField: type: object additionalProperties: false required: - label - type - source - kind - status - rawValues - originIndexes - displayValue - addressValue - numericValue - textValue - boolValue properties: label: type: string type: type: - string - "null" description: Cairo ABI type used for this decoded field when available. source: type: string enum: - key - data kind: type: string enum: - address - hash - bool - u256 - felt - text status: type: string enum: - decoded - partial - raw rawValues: type: array maxItems: 8 items: type: string originIndexes: type: array maxItems: 8 items: type: integer minimum: 0 displayValue: type: string addressValue: type: - string - "null" numericValue: type: - string - "null" textValue: type: - string - "null" boolValue: type: - boolean - "null" ContractEventItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txHash - txIndex - logIndex - address - topic0 - topic1 - topic2 - topic3 - keys - data - decodingStatus properties: blockNumber: type: integer format: int64 timestampIso: type: string format: date-time txHash: type: string txIndex: type: integer format: int32 logIndex: type: integer format: int32 address: type: string contractAlias: type: - string - "null" description: Reviewed indexed/token/protocol label for the emitting contract when available. It is presentation metadata and never affects raw event data or decoding provenance. classAlias: type: - string - "null" description: Reviewed class-family label for the emitting contract's indexed class when available. It is presentation metadata and never affects raw event data or decoding provenance. keys: type: array items: type: string description: Canonical on-chain event key array in indexed payload order. Legacy rows lacking `payload.keys` reconstruct only `topic0` through `topic3`, so their key array can be incomplete; raw keys/data are authoritative. topic0: type: - string - "null" topic1: type: - string - "null" topic2: type: - string - "null" topic3: type: - string - "null" data: type: array maxItems: 1024 items: type: string decodingStatus: type: string enum: - decoded - name_only - unknown description: Server-certified event decode state. `name_only` and `unknown` preserve the authoritative raw payload as available; legacy rows may expose a reconstructed, incomplete `keys[]` per the keys field description. eventName: type: - string - "null" description: Reviewed or ABI-derived event name when Starkscan can attribute topic0. eventNameSource: type: - string - "null" description: Attribution source for eventName. Current values include verified_abi, class_abi, selector_unique, and curated_selector; clients should treat unknown strings as forward-compatible provenance labels. eventNameUnavailableReason: type: - string - "null" enum: - event_time_class_epoch_unavailable - null description: Reason eventName is omitted even though Starkscan has contract-scoped epoch facts for this event. Raw topic/data fields remain authoritative. decodedFields: type: array maxItems: 128 items: $ref: "#/components/schemas/EventDecodedField" description: Decoded key/data fields only when an exact materialized ABI schema or a reviewed standard selector-and-arity schema consumes the full payload. Raw topic/data fields remain authoritative. decodedFieldsSource: type: - string - "null" description: Attribution source used for decodedFields when present. decodedFieldsUnavailableReason: type: - string - "null" enum: - schema_unavailable - selector_only_attribution - payload_shape_mismatch - schema_shape_unsupported - null description: Reason decodedFields is omitted for an attributed event. Selector-only attribution names the event but does not prove the field layout; raw topic/data fields remain authoritative. EventRangeCoverage: type: object additionalProperties: false required: - requestedFromBlock - requestedToBlock - completeFromBlock - completeThroughBlock - completeThroughBlockHash - snapshotId - finalizedHighWaterBlock - headHighWaterBlock properties: requestedFromBlock: type: integer format: int64 minimum: 0 requestedToBlock: type: integer format: int64 minimum: 0 description: Upper bound supplied by the caller before any Wallet full-range serving-ceiling clamp. completeFromBlock: type: integer format: int64 minimum: 0 completeThroughBlock: type: integer format: int64 minimum: 0 description: Highest block completely served in this response. For an entitled positional full-range request above the current selector-position maxServableToBlock, this is clamped to that published ceiling and may be lower than requestedToBlock. completeThroughBlockHash: type: string pattern: ^0x(?:0|[1-9a-f][0-9a-f]{0,61}|[1-7][0-9a-f]{62}|80000000000000[0-9a-f]{49}|800000000000010[0-9a-f]{48}|8000000000000110{48})$ description: Canonical hash at completeThroughBlock. Full-range nextCursor values are bound to this anchor and the normalized query scope; they return event_cursor_snapshot_changed if a head reorganization changes the anchor and event_cursor_scope_changed if the route or filters change. snapshotId: type: string description: PostgreSQL repeatable-read snapshot identity used for the coverage proof and event rows. finalizedHighWaterBlock: type: - integer - "null" format: int64 headHighWaterBlock: type: - integer - "null" format: int64 ContractEventPage: type: object additionalProperties: false required: - items - nextCursor - eventDecodingDegraded properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/ContractEventItem" nextCursor: type: - string - "null" description: Opaque continuation. Full-range values are bound to completeThroughBlockHash and the normalized route/filter scope; discard them after event_cursor_snapshot_changed or event_cursor_scope_changed. eventDecodingDegraded: type: boolean description: True only when the optional server attribution lookup failed operationally. Individual unknown events do not set this flag. rangeCoverage: $ref: "#/components/schemas/EventRangeCoverage" ContractAdvancedCoverageView: type: object additionalProperties: false required: - status - source - reasonCode - message properties: status: type: string enum: - exact - partial - unavailable source: type: string enum: - trace_facts - l2_bridge_signals - bridge_adapter_events - bridge_message_facts reasonCode: type: string description: | Reason the contract coverage view is not exact. Each value identifies the unavailable or incomplete coverage evidence for this contract. enum: - indexed_trace_facts - no_matching_trace_rows - trace_tables_unavailable - trace_extraction_truncated - trace_projection_stale - indexed_bridge_pairing_facts - l1_pairing_not_indexed - bridge_message_facts_unavailable - adapter_pairing_facts_unavailable - query_timeout message: type: string latestIndexedBlockNumber: type: - integer - "null" format: int64 chainHeadBlockNumber: type: - integer - "null" format: int64 lagBlocks: type: - integer - "null" format: int64 ContractAccountCallItem: type: object additionalProperties: false required: - id - blockNumber - timestampIso - txIndex - callIndex - tracePath - txHash - methodName - entryPointSelector - senderAddress - callerAddress - calleeAddress - executionStatus - finalityStatus - sourceTier - extractionTruncated properties: id: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 callIndex: type: integer format: int32 tracePath: type: - string - "null" txHash: type: string methodName: type: - string - "null" entryPointSelector: type: - string - "null" senderAddress: type: - string - "null" callerAddress: type: - string - "null" calleeAddress: type: string executionStatus: type: - string - "null" finalityStatus: type: - string - "null" sourceTier: type: string enum: - head - finalized extractionTruncated: type: boolean ContractAccountCallPage: type: object additionalProperties: false required: - chainId - contractAddress - items - nextCursor - coverage properties: chainId: type: string contractAddress: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/ContractAccountCallItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Numeric block:tx:log continuation returned by the contract account-call endpoint. coverage: $ref: "#/components/schemas/ContractAdvancedCoverageView" ContractBridgeTransactionItem: type: object additionalProperties: false required: - id - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - status - direction - messageHash - l1Hash - l2Hash - l1ContractAddress - l2ContractAddress - tokenAddress - tokenSymbol - tokenDecimals - amountRaw - fromAddress - toAddress - pairingConfidence - sourceTier properties: id: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 transferIndex: type: integer format: int32 txHash: type: string status: type: string direction: type: - string - "null" enum: - inbound - outbound - null messageHash: type: - string - "null" l1Hash: type: - string - "null" l2Hash: type: - string - "null" l1ContractAddress: type: - string - "null" l2ContractAddress: type: - string - "null" tokenAddress: type: - string - "null" tokenSymbol: type: - string - "null" tokenDecimals: type: - integer - "null" format: int32 amountRaw: type: - string - "null" fromAddress: type: - string - "null" toAddress: type: - string - "null" pairingConfidence: type: string enum: - message_pairing_fact - adapter_pairing_fact - unpaired_l2_only sourceTier: type: string enum: - head - finalized ContractBridgeTransactionPage: type: object additionalProperties: false required: - chainId - contractAddress - items - nextCursor - coverage properties: chainId: type: string contractAddress: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/ContractBridgeTransactionItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+(:[0-9]+)?$ coverage: $ref: "#/components/schemas/ContractAdvancedCoverageView" StarkgateTransferCoverageView: type: object additionalProperties: false required: - status - source - reasonCode - message properties: status: type: string source: type: string reasonCode: type: string message: type: string StarkgateTransferStageView: type: object additionalProperties: false required: - key - label - status - chain - txHash - blockNumber properties: key: type: string label: type: string status: type: string chain: type: string txHash: type: - string - "null" blockNumber: type: - integer - "null" format: int64 StarkgateTransferItem: type: object additionalProperties: false required: - id - messageHash - direction - status - statusLabel - nextAction - tokenAddress - tokenSymbol - tokenName - tokenDecimals - tokenMetadataSource - amountRaw - l1BridgeAddress - l2BridgeAddress - l1SenderAddress - l1RecipientAddress - l2SenderAddress - l2RecipientAddress - l1TxHash - l2TxHash - l1BlockNumber - l2BlockNumber - claimabilityScope - claimabilityAmbiguous - matchingL2MessageCount - l1ConsumedMessageCount - registryClaimableMessageCount - registrySnapshotBlockNumber - registrySnapshotBlockHash - registrySnapshotSource - registrySnapshotObservedAt - registrySnapshotFresh - readyToClaimOnL1 - completedOnL1 - l1AcceptedBlockNumber - proofSource - proofL1BlockNumber - proofL1TxHash - proofEthereumFinality - proofUpdatedAt - selector - nonce - payload - payloadTruncated - sourceTier - evidence - missingFacts - stages properties: id: type: string messageHash: type: string direction: type: string status: type: string statusLabel: type: string nextAction: type: string tokenAddress: type: - string - "null" tokenSymbol: type: - string - "null" tokenName: type: - string - "null" tokenDecimals: type: - integer - "null" format: int32 tokenMetadataSource: description: Pinned official registry revision or explicit native-ETH payload rule used for metadata; null means Starkscan has no reviewed metadata source. type: - string - "null" amountRaw: type: - string - "null" l1BridgeAddress: type: - string - "null" l2BridgeAddress: type: - string - "null" l1SenderAddress: type: - string - "null" l1RecipientAddress: type: - string - "null" l2SenderAddress: type: - string - "null" l2RecipientAddress: type: - string - "null" l1TxHash: type: - string - "null" l2TxHash: type: - string - "null" l1BlockNumber: type: - integer - "null" format: int64 l2BlockNumber: type: - integer - "null" format: int64 claimabilityScope: type: string enum: - message_hash_group - not_applicable description: Withdrawal claimability is scoped to every identical L2-to-L1 message represented by the same canonical message hash; StarknetCore does not expose per-emission registry slots. claimabilityAmbiguous: type: boolean description: True when finalized emissions, consumptions, or the finalized registry show multiplicity, violate R + C <= M, or fail R + C = M after finalized L1 proof covers the represented emission, so no individual emission can be attributed to a claim. matchingL2MessageCount: type: integer format: int64 minimum: 0 description: Count of distinct finalized Starknet L2-to-L1 emissions in this message-hash group, deduplicated by transaction hash and message index. Head-only observations do not contribute. l1ConsumedMessageCount: type: integer format: int64 minimum: 0 description: Count of indexed canonical StarknetCore ConsumedMessageToL1 logs in this message-hash group. registryClaimableMessageCount: type: - string - "null" pattern: ^[0-9]+$ description: StarknetCore l2ToL1Messages(messageHash) uint256 value at the exact finalized Ethereum snapshot, or null when no trustworthy snapshot is materialized. registrySnapshotBlockNumber: type: - integer - "null" format: int64 minimum: 0 registrySnapshotBlockHash: type: - string - "null" description: Canonical Ethereum block hash agreed by the configured RPC quorum for the registry snapshot. registrySnapshotSource: type: - string - "null" registrySnapshotObservedAt: type: - string - "null" format: date-time registrySnapshotFresh: description: True only when the complete finalized registry snapshot is no more than five minutes old. Ready and cleared statuses require this freshness. type: boolean readyToClaimOnL1: type: boolean description: True only when the represented emission is finalized and the group has M = 1, R = 1, and C = 0 at a complete finalized StarknetCore registry snapshot. Recheck the registry before submitting a claim because this is snapshot evidence, not a request-time RPC promise. completedOnL1: type: boolean description: True only when the represented emission is finalized, the group has M = 1, R = 0, and C = 1, and a finalized L1 state-update proof covers the represented withdrawal block. l1AcceptedBlockNumber: type: - integer - "null" format: int64 proofSource: type: - string - "null" description: Latest indexed proof source used for L1 readiness decisions. proofL1BlockNumber: type: - integer - "null" format: int64 description: Ethereum block number for the latest indexed StarknetCore state-update proof. proofL1TxHash: type: - string - "null" description: Ethereum transaction hash for the latest indexed StarknetCore state-update proof. proofEthereumFinality: type: - string - "null" description: Ethereum consensus finality level required by Starkscan before marking ready-to-claim state. proofUpdatedAt: type: - string - "null" format: date-time description: Timestamp when Starkscan last updated the indexed proof row. selector: type: - string - "null" nonce: type: - string - "null" payload: type: array maxItems: 256 items: type: string payloadTruncated: type: boolean sourceTier: type: string evidence: type: array maxItems: 32 items: type: string missingFacts: type: array maxItems: 32 items: type: string stages: type: array maxItems: 8 items: $ref: "#/components/schemas/StarkgateTransferStageView" StarkgateTransferQueryView: type: object additionalProperties: false required: - txHash - messageHash - address - token - bridge - status - cursor - direction - limit properties: txHash: type: - string - "null" messageHash: type: - string - "null" address: type: - string - "null" token: type: - string - "null" bridge: type: - string - "null" status: type: - string - "null" cursor: type: - string - "null" direction: type: - string - "null" limit: type: integer format: int64 StarkgateTransferResolutionView: type: object additionalProperties: false required: - chainId - query - items - coverage properties: chainId: type: string query: $ref: "#/components/schemas/StarkgateTransferQueryView" items: type: array maxItems: 25 items: $ref: "#/components/schemas/StarkgateTransferItem" coverage: $ref: "#/components/schemas/StarkgateTransferCoverageView" StarkgateTransferPageView: type: object additionalProperties: false required: - chainId - query - items - nextCursor - coverage properties: chainId: type: string query: $ref: "#/components/schemas/StarkgateTransferQueryView" items: type: array maxItems: 100 items: $ref: "#/components/schemas/StarkgateTransferItem" nextCursor: type: - string - "null" coverage: $ref: "#/components/schemas/StarkgateTransferCoverageView" MessageCoverageView: type: object additionalProperties: false required: - status - source - reasonCode - message properties: status: type: string enum: - exact - partial - unavailable source: type: string enum: - starknet_protocol_messages reasonCode: type: string enum: - indexed_protocol_message_facts - no_matching_message_rows - message_not_found - message_detail_page_exhausted - message_facts_unavailable - message_detail_truncated - transaction_messages_truncated - query_timeout message: type: string MessageTokenInterpretationView: type: object additionalProperties: false required: - symbol - name - decimals properties: symbol: type: string minLength: 1 maxLength: 32 name: type: string minLength: 1 maxLength: 128 decimals: type: integer minimum: 0 maximum: 36 MessageInterpretationView: type: object additionalProperties: false description: | Additive, fail-closed semantics from one reviewed exact protocol adapter. Raw message fields remain authoritative; unknown or near-match payloads use null. required: - protocol - kind - action - summary - source - matchRule - token - amountRaw - amount - sender - recipient - factHash - mocked properties: protocol: type: string kind: type: string enum: - token_transfer - cairo_fact action: type: string enum: - deposit - withdrawal - fact_delivery summary: type: string source: type: string enum: - reviewed_protocol_adapter matchRule: type: string minLength: 1 maxLength: 256 token: oneOf: - $ref: "#/components/schemas/MessageTokenInterpretationView" - type: "null" amountRaw: type: - string - "null" pattern: ^[0-9]+$ amount: type: - string - "null" sender: type: - string - "null" recipient: type: - string - "null" factHash: type: - string - "null" pattern: ^0x[0-9a-f]{64}$ mocked: type: - boolean - "null" MessageItem: type: object additionalProperties: false required: - id - blockNumber - timestampIso - txIndex - logIndex - messageHash - direction - fromAddress - toAddress - txHash - l1Hash - l2Hash - l1BlockNumber - l1Fee - l1ContractAddress - l2ContractAddress - bridgeContractAddress - status - l1SentCount - l2SentCount - l1ConsumedCount - pendingCount - nonce - selector - payload - payloadTruncated - sourceTier - interpretation properties: id: type: string blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 messageHash: type: string direction: type: string enum: - l1_to_l2 - l2_to_l1 - unknown fromAddress: type: - string - "null" toAddress: type: - string - "null" txHash: type: string l1Hash: type: - string - "null" l2Hash: type: - string - "null" l1BlockNumber: type: - integer - "null" format: int64 minimum: 0 description: | Latest indexed canonical Ethereum block associated with this message hash. For L1-to-L2 messages where l1SentCount > 1, this is the latest indexed L1 send block. Null when the relevant L1 origin or consumption fact has not been indexed. l1Fee: type: - string - "null" pattern: ^0[xX][0-9a-fA-F]{1,64}$ description: | Canonical StarknetCore LogMessageToL2 fee for L1-to-L2 origins, encoded as a hex quantity when indexed. When l1SentCount > 1, this is the fee from the latest indexed L1 send, the same send reflected by l1BlockNumber. Null for L2-to-L1 messages or when no L1 origin has been indexed. l1ContractAddress: type: - string - "null" l2ContractAddress: type: - string - "null" bridgeContractAddress: type: - string - "null" status: type: string l1SentCount: type: integer format: int64 minimum: 0 description: Count of indexed canonical StarknetCore L1 origin logs sharing this L1-to-L2 message hash. l2SentCount: type: integer format: int64 minimum: 0 description: Count of indexed canonical L2 emissions sharing this message hash. l1ConsumedCount: type: integer format: int64 minimum: 0 description: Count of indexed canonical StarknetCore L1 consumption logs sharing this message hash. pendingCount: type: integer format: int64 minimum: 0 description: "Non-negative pending lifecycle count for this message hash: L1 origins minus L2 consumptions for L1-to-L2, or L2 emissions minus canonical L1 consumptions for L2-to-L1." nonce: type: - string - "null" selector: type: - string - "null" payload: type: array maxItems: 1024 items: type: string payloadTruncated: type: boolean sourceTier: type: string enum: - head - finalized interpretation: oneOf: - $ref: "#/components/schemas/MessageInterpretationView" - type: "null" description: Null unless one exact reviewed protocol adapter matches. MessagePage: type: object additionalProperties: false required: - chainId - contractAddress - items - nextCursor - coverage properties: chainId: type: string contractAddress: type: - string - "null" items: type: array maxItems: 100 items: $ref: "#/components/schemas/MessageItem" nextCursor: type: - string - "null" pattern: ^m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)$ coverage: $ref: "#/components/schemas/MessageCoverageView" MessageDetailView: type: object additionalProperties: false required: - chainId - messageHash - items - nextCursor - coverage properties: chainId: type: string messageHash: type: string items: type: array maxItems: 100 items: $ref: "#/components/schemas/MessageItem" nextCursor: type: - string - "null" pattern: ^m1:[0-9]+:[0-9]+:[0-9]+:0[xX][0-9a-fA-F]+:0[xX][0-9a-fA-F]+:(l1_to_l2|l2_to_l1):(head|finalized)$ coverage: $ref: "#/components/schemas/MessageCoverageView" ContractReadResultView: type: object additionalProperties: false required: - chainId - contractAddress - selector - blockTag - result properties: chainId: type: string contractAddress: type: string selector: type: string blockTag: allOf: - $ref: "#/components/schemas/BlockReference" description: Echoed validated caller text used for execution (`latest`, `pending`, block number, or block hash). result: type: array maxItems: 1024 items: type: string ContractStorageResultView: type: object additionalProperties: false required: - chainId - contractAddress - key - blockTag - value properties: chainId: type: string contractAddress: type: string key: type: string description: Normalized storage-slot key. blockTag: allOf: - $ref: "#/components/schemas/BlockReference" description: Echoed validated caller text used for the read (`latest`, `pending`, block number, or block hash). value: type: string description: Felt stored at the slot, or `0x0` when the slot has never been written. ContractWritePayloadRequest: type: object additionalProperties: false required: - selector properties: selector: type: string calldata: type: array default: [] maxItems: 1024 items: type: string ContractWritePayloadView: type: object additionalProperties: false required: - chainId - contractAddress - selector - calldata - call properties: chainId: type: string contractAddress: type: string selector: type: string calldata: type: array maxItems: 1024 items: type: string call: type: object ContractTransactionTraceView: type: object additionalProperties: false required: - chainId - txHash - trace properties: chainId: type: string txHash: type: string trace: type: object AddressActivityItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - txCursor - kind - counterparty - tokenAddress - amount - tokenId properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: - integer - "null" format: int32 transferIndex: type: - integer - "null" format: int32 txHash: type: string txCursor: type: string kind: type: string counterparty: type: - string - "null" tokenAddress: type: - string - "null" amount: type: - string - "null" tokenId: type: - string - "null" AddressActivityPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/AddressActivityItem" nextCursor: type: - string - "null" AddressTransactionListItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - txHash - kinds - counterparty - txType - executionStatus - finalityStatus - fromAddress - toAddress - primaryMethod - callCount - methodsDiffer - transferCount - topTransferTokenAddress - topTransferAmount - topTransferStandard properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 txHash: type: string kinds: type: array maxItems: 16 items: type: string counterparty: type: - string - "null" txType: type: - string - "null" executionStatus: type: - string - "null" finalityStatus: type: - string - "null" fromAddress: type: - string - "null" toAddress: type: - string - "null" primaryMethod: type: - string - "null" callCount: type: - integer - "null" format: int32 methodsDiffer: type: - boolean - "null" transferCount: type: - integer - "null" format: int32 topTransferTokenAddress: type: - string - "null" topTransferAmount: type: - string - "null" topTransferStandard: type: - string - "null" AddressTransactionPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/AddressTransactionListItem" nextCursor: type: - string - "null" AddressTokenHoldingItemView: type: object additionalProperties: false oneOf: - title: Fresh direct market quote properties: priceStatus: const: priced priceReasonCode: const: fresh_exact_cached_price priceValuationMethod: const: direct_market_quote priceConfidence: const: exact - title: Fresh conversion estimate properties: priceStatus: const: priced priceReasonCode: const: fresh_conversion_estimate priceValuationMethod: const: snip22_conversion_estimate priceConfidence: const: proxy - title: Holding price unavailable properties: priceStatus: const: unavailable priceValuationMethod: const: null priceReasonCode: enum: - token_unmapped - price_not_exact - price_missing - price_stale - token_metadata_missing - value_calculation_failed - valuation_not_loaded required: - tokenAddress - normalizedTokenAddress - indexedBalanceRaw - symbol - name - decimals - usd - priceStatus - priceReasonCode - priceUsd - valueUsd - priceSource - priceProvider - priceConfidence - priceValuationMethod - priceTimestampIso - priceObservedAtIso properties: tokenAddress: type: string description: Token contract address as stored by the indexed balance source. normalizedTokenAddress: type: string description: Lowercase compact `0x` token address for stable agent comparisons. indexedBalanceRaw: type: string description: | Decimal (base-10) balance served for this row. The legacy field name is retained for compatibility. On paginated responses, `balanceSource` states whether the value is transfer-derived or was replaced by a pinned RPC `balanceOf` result. symbol: type: - string - "null" description: Token symbol from trusted token-metadata data (token metadata indexes) or from known safe defaults when available. name: type: - string - "null" description: Token name from trusted token-metadata data (token metadata indexes) or from known safe defaults when available. decimals: type: - integer - "null" format: int32 description: Token decimals from trusted token-metadata data (token metadata indexes) or from known safe defaults when available. usd: $ref: "#/components/schemas/AddressTokenHoldingUsdView" priceStatus: type: string enum: - priced - unavailable description: Whether this holding has a fresh direct quote or reviewed conversion estimate. priceReasonCode: type: string enum: - fresh_exact_cached_price - fresh_conversion_estimate - token_unmapped - price_not_exact - price_missing - price_stale - token_metadata_missing - value_calculation_failed - valuation_not_loaded description: Typed reason for `priceStatus`; unavailable never means a zero-dollar holding. priceUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Exact cached USD unit price string when `priceStatus=priced`. valueUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Exact decimal multiplication of indexedBalanceRaw and priceUsd when priced. priceSource: type: - string - "null" priceProvider: type: - string - "null" priceConfidence: type: - string - "null" enum: - exact - proxy - null priceValuationMethod: type: - string - "null" enum: - direct_market_quote - snip22_conversion_estimate - null priceTimestampIso: type: - string - "null" format: date-time priceObservedAtIso: type: - string - "null" format: date-time AddressTokenHoldingUsdView: type: object additionalProperties: false oneOf: - title: Fresh direct market quote properties: status: const: priced reasonCode: const: fresh_exact_cached_price valuationMethod: const: direct_market_quote confidence: const: exact - title: Fresh conversion estimate properties: status: const: priced reasonCode: const: fresh_conversion_estimate valuationMethod: const: snip22_conversion_estimate confidence: const: proxy - title: Holding USD unavailable properties: status: const: unavailable valuationMethod: const: null reasonCode: enum: - price_metadata_unavailable - token_metadata_missing - balance_invalid - token_unmapped - price_not_exact - price_missing - price_stale - valuation_calculation_failed required: - status - reasonCode - quoteCurrency - balanceDecimal - priceUsd - valueUsd - provider - source - confidence - valuationMethod - priceTimestamp - observedAt - maxAgeSeconds properties: status: type: string enum: - priced - unavailable description: "`priced` only when a fresh direct quote or reviewed exact-block conversion estimate can value this indexed balance." reasonCode: type: string enum: - fresh_exact_cached_price - fresh_conversion_estimate - price_metadata_unavailable - token_metadata_missing - balance_invalid - token_unmapped - price_not_exact - price_missing - price_stale - valuation_calculation_failed quoteCurrency: type: string const: usd balanceDecimal: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Exact decimal balance derived from `indexedBalanceRaw`; never a floating-point value. priceUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Prepared USD price string. Null unless `status=priced`. valueUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Exact decimal multiplication of the indexed balance and prepared price. Null unless `status=priced`. provider: type: - string - "null" source: type: - string - "null" confidence: type: - string - "null" valuationMethod: type: - string - "null" enum: - direct_market_quote - snip22_conversion_estimate - null priceTimestamp: type: - string - "null" format: date-time observedAt: type: - string - "null" format: date-time maxAgeSeconds: type: - integer - "null" format: int32 TokenHoldingsCompletenessReasonCode: type: string enum: - complete - indexLag - boundedComputation - responseCap - metadataPending - degradedFallback - unknown description: | `complete` means the full inventory and every returned balance are independently certified for portfolio parity checks. Other values are useful evidence but not exact portfolio ground truth. `lagBlocks` measures indexed-source lag only and must not be interpreted as per-token `balanceOf` freshness. AddressTokenHoldingsCompletenessView: type: object additionalProperties: false required: - exact - truncated - complete - reasonCode - reason - lagBlocks - capped - cap properties: exact: type: boolean description: Mirrors the top-level `exact` field. truncated: type: boolean description: Mirrors the top-level `truncated` field. complete: type: boolean description: | True only when the response is exact, not truncated, and `reasonCode=complete`. reasonCode: $ref: "#/components/schemas/TokenHoldingsCompletenessReasonCode" reason: type: string description: Human-readable explanation for the current completeness state. lagBlocks: type: - integer - "null" format: int64 description: | Indexed-source lag in blocks when known. Zero does not certify that any token balance equals on-chain `balanceOf`. Null means the route cannot attribute index lag for this response. capped: type: boolean description: True when a response cap affected the result. cap: type: - integer - "null" format: int32 description: Effective response cap when capped, otherwise null. AddressTokenHoldingsView: type: object additionalProperties: false required: - chainId - ownerAddress - items - exact - truncated - completeness properties: chainId: type: string ownerAddress: type: string items: description: | Legacy bounded indexed observations embedded in a larger explorer response. These rows are not wallet-safe balance authority. Use assets/discovery for candidates and query/wallet-state for balances verified at one immutable block hash. type: array maxItems: 256 items: $ref: "#/components/schemas/AddressTokenHoldingItemView" exact: description: | True only when the complete token inventory and every returned balance are independently certified at one chain snapshot. Transfer-derived materialization alone never satisfies this field. type: boolean truncated: description: True when this response is a bounded subset of the holdings snapshot. type: boolean completeness: $ref: "#/components/schemas/AddressTokenHoldingsCompletenessView" AddressTokenHoldingsPageView: type: object additionalProperties: false required: - chainId - ownerAddress - items - exact - truncated - completeness - balanceSource - balanceVerifiedAtBlock - nextCursor - snapshotId - snapshotExact - hasMore - pageLimit - sort allOf: - if: properties: balanceSource: const: pinnedRpcBalanceOf required: - balanceSource then: properties: balanceVerifiedAtBlock: type: string - if: properties: balanceSource: const: indexedTransferLedger required: - balanceSource then: properties: balanceVerifiedAtBlock: type: "null" - if: properties: exact: const: true required: - exact then: properties: balanceSource: const: pinnedRpcBalanceOf completeness: allOf: - $ref: "#/components/schemas/AddressTokenHoldingsCompletenessView" - properties: exact: const: true complete: const: true reasonCode: const: complete properties: chainId: type: string ownerAddress: type: string items: description: | One page of non-zero holdings, capped at 256 items. Curated known tokens rank before unknown tokens; each group then uses descending raw balance and ascending normalized token address. When `nextCursor` is non-null, follow it to retrieve the remaining rows. type: array maxItems: 256 items: $ref: "#/components/schemas/AddressTokenHoldingItemView" exact: description: | True only when this response alone contains a complete token inventory whose balances are independently certified at one chain snapshot. Transfer-derived materialization alone never satisfies this field. Multi-page responses remain false because no single page contains the complete portfolio. type: boolean truncated: description: True when this response is a bounded subset of the holdings snapshot. type: boolean completeness: $ref: "#/components/schemas/AddressTokenHoldingsCompletenessView" balanceSource: type: string enum: - indexedTransferLedger - pinnedRpcBalanceOf description: | Provenance for every `indexedBalanceRaw` value in this page. `pinnedRpcBalanceOf` is emitted only after every returned indexed candidate was verified successfully at one block and verified zeros were removed. balanceVerifiedAtBlock: type: - string - "null" description: | Pinned block hash when `balanceSource=pinnedRpcBalanceOf`; null for transfer-derived or legacy fallback pages. nextCursor: type: - string - "null" description: Opaque keyset cursor for the next page, or null on the terminal page. snapshotId: type: - string - "null" description: | Address holdings version pinned by this cursor sequence. Null only for a non-pageable compatibility response while the versioned read model is warming. snapshotExact: type: boolean description: | True when all pages identified by snapshotId describe one stable indexed holdings snapshot. This is cursor-consistency provenance only: it does not certify token discovery or `balanceOf` values and can be true while top-level `exact` is false. hasMore: type: boolean description: True exactly when nextCursor is non-null. pageLimit: type: integer format: int32 minimum: 1 maximum: 256 description: Effective item limit applied to this response page. sort: type: string enum: - knownFirstBalanceDescTokenAsc - legacyBalanceDescTokenAsc description: | Deterministic ordering applied to the response. Clients may page only knownFirstBalanceDescTokenAsc responses with a non-null nextCursor; legacyBalanceDescTokenAsc is a bounded, non-pageable warmup fallback with hasMore=false. StakingValidatorCoverageView: type: object additionalProperties: false required: - status - reasonCode - reason properties: status: type: string enum: - indexed - not_indexed - unavailable reasonCode: type: string reason: type: string StakingValidatorDetailsView: type: object additionalProperties: false required: - chainId - requestedAddress - validator - description - delegators - delegatorTotal - activity - coverage properties: chainId: type: string requestedAddress: type: string validator: type: - object - "null" description: Prepared validator detail fact. Null when coverage is not indexed or unavailable. description: type: - string - "null" delegators: type: array maxItems: 100 items: type: object delegatorTotal: type: integer format: int64 minimum: 0 activity: type: array maxItems: 100 items: type: object coverage: $ref: "#/components/schemas/StakingValidatorCoverageView" ContractSnapshotView: type: object additionalProperties: false required: - chainId - address - summary - activityPage - transactionsPage - tokenHoldings - summaryCompleteness - activityCompleteness - holdingsCompleteness properties: chainId: type: string address: type: string summary: $ref: "#/components/schemas/AddressSummaryView" activityPage: $ref: "#/components/schemas/AddressActivityPage" transactionsPage: $ref: "#/components/schemas/AddressTransactionPage" tokenHoldings: $ref: "#/components/schemas/AddressTokenHoldingsView" summaryCompleteness: type: boolean activityCompleteness: type: boolean holdingsCompleteness: type: boolean TokenSummaryView: type: object additionalProperties: false required: - chainId - tokenAddress - symbol - name - decimals - standard - metadataUpdatedAtIso - summaryVersion - summaryVersionUpdatedAtIso - summaryCacheStatus - summaryCacheUpdatedAtIso - transferCount - distinctFromCount - distinctToCount - latestTransferBlock - totalSupplyRaw - totalSupplySource - totalSupplyBlockNumber - totalSupplyUpdatedAtIso properties: chainId: type: string tokenAddress: type: string symbol: type: - string - "null" name: type: - string - "null" decimals: type: - integer - "null" format: int32 standard: type: string metadataUpdatedAtIso: type: - string - "null" format: date-time summaryVersion: type: integer format: int64 summaryVersionUpdatedAtIso: type: - string - "null" format: date-time summaryCacheStatus: type: string enum: - current - stale - metadata_only - computed summaryCacheUpdatedAtIso: type: - string - "null" format: date-time transferCount: type: - integer - "null" format: int64 description: Null when summaryCacheStatus is metadata_only because transfer aggregates are not yet known. distinctFromCount: type: - integer - "null" format: int64 description: Null when summaryCacheStatus is metadata_only because transfer aggregates are not yet known. distinctToCount: type: - integer - "null" format: int64 description: Null when summaryCacheStatus is metadata_only because transfer aggregates are not yet known. latestTransferBlock: type: - integer - "null" format: int64 description: Latest independently indexed transfer block when known; this can remain populated while aggregate counts are null in metadata_only responses. totalSupplyRaw: type: - string - "null" description: Decimal string from the row-backed token_supply_snapshot read model when available. totalSupplySource: type: - string - "null" description: Source label for the row-backed total supply snapshot. totalSupplyBlockNumber: type: - integer - "null" format: int64 description: Block number associated with the total supply snapshot when available. totalSupplyUpdatedAtIso: type: - string - "null" format: date-time description: Timestamp when the total supply snapshot row was last updated. allOf: - oneOf: - required: - totalSupplyRaw - totalSupplySource - totalSupplyBlockNumber - totalSupplyUpdatedAtIso properties: totalSupplyRaw: type: string totalSupplySource: type: string totalSupplyBlockNumber: type: integer format: int64 totalSupplyUpdatedAtIso: type: string format: date-time - required: - totalSupplyRaw - totalSupplySource - totalSupplyBlockNumber - totalSupplyUpdatedAtIso properties: totalSupplyRaw: type: "null" totalSupplySource: type: "null" totalSupplyBlockNumber: type: "null" totalSupplyUpdatedAtIso: type: "null" TokenBalanceOfView: type: object additionalProperties: false required: - chainId - tokenAddress - ownerAddress - blockTag - balanceRaw properties: chainId: type: string tokenAddress: type: string ownerAddress: type: string blockTag: allOf: - $ref: "#/components/schemas/BlockReference" description: Echoed validated caller text used for execution (`latest`, `pending`, block number, or block hash). balanceRaw: type: string description: Decimal (base-10) string representation of the U256 balanceOf result. TokenTotalSupplyView: type: object additionalProperties: false required: - chainId - tokenAddress - blockTag - totalSupplyRaw properties: chainId: type: string tokenAddress: type: string blockTag: allOf: - $ref: "#/components/schemas/BlockReference" description: Echoed validated caller text used for execution (`latest`, `pending`, block number, or block hash). totalSupplyRaw: type: string description: Decimal (base-10) string representation of the U256 totalSupply result. TokenHolderItem: type: object additionalProperties: false required: - rank - address - balanceRaw - lastUpdatedBlock - lastUpdatedTimestampIso properties: rank: type: integer format: int64 description: One-based rank by descending indexed balance, then address ascending. address: $ref: "#/components/schemas/CanonicalNonzeroStarknetAddress" balanceRaw: type: string pattern: ^[1-9][0-9]*$ description: Decimal (base-10) indexed balance string. lastUpdatedBlock: type: integer format: int64 lastUpdatedTimestampIso: type: - string - "null" format: date-time TokenHolderSnapshot: type: object description: | Identity, provenance, and observable freshness for one holder population. `generationId`, `asOfBlockHash`, `rowDigest`, `expiresAt`, `updatedAt`, and `lagBlocks` are optional for legacy compatibility, but all six are present together for immutable complete-population and Top-N screening generations. Pages in one cursor walk preserve the generation identity. Analytics comparisons use `generationId`, block/hash, and `rowDigest`; `expiresAt` is a response-specific continuation deadline. `updatedAt` records publication time and `lagBlocks` compares the pinned snapshot to the indexed finalized head observed for this response. Clients must not fabricate an omitted field. additionalProperties: false required: - asOfBlock - source - freshness properties: asOfBlock: type: - integer - "null" format: int64 minimum: 0 description: Finalized generation block number when generation-bound; nullable for a missing or legacy snapshot. asOfBlockHash: type: string pattern: ^0[xX][0-9a-fA-F]{1,64}$ description: Exact finalized block hash for an immutable generation. generationId: type: integer format: int64 minimum: 1 description: Server-assigned immutable holder generation identifier. rowDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ description: SHA-256 identity of the complete ordered holder row population. It is response evidence, not a cursor field clients should construct. expiresAt: type: string format: date-time description: Retention deadline through which continuation cursors for this immutable generation can be served. The service default is six hours, but this timestamp is authoritative. updatedAt: type: string format: date-time description: Time at which this immutable generation was published and became available for reads. lagBlocks: type: integer format: int64 minimum: 0 description: Difference between the indexed finalized head observed for this response and the generation snapshot block. source: type: string enum: - materialized_fungible_balances - sealed_finalized_holder_generation - sealed_finalized_holder_screening_projection freshness: type: string enum: - head_plus_finalized - analytics_snapshot - finalized_generation - finalized_screening_generation allOf: - if: properties: source: const: sealed_finalized_holder_generation required: - source then: required: - asOfBlockHash - generationId - rowDigest - expiresAt - updatedAt - lagBlocks properties: asOfBlock: type: integer format: int64 minimum: 0 freshness: const: finalized_generation - if: properties: source: const: sealed_finalized_holder_screening_projection required: - source then: required: - asOfBlockHash - generationId - rowDigest - expiresAt - updatedAt - lagBlocks properties: asOfBlock: type: integer format: int64 minimum: 0 freshness: const: finalized_screening_generation TokenHolderScreeningSnapshot: allOf: - $ref: "#/components/schemas/TokenHolderSnapshot" - type: object required: - asOfBlock - asOfBlockHash - generationId - rowDigest - expiresAt - updatedAt - lagBlocks - source - freshness properties: asOfBlock: type: integer format: int64 minimum: 0 source: const: sealed_finalized_holder_screening_projection freshness: const: finalized_screening_generation TokenHolderCompleteness: type: object description: | Generation coverage and exactness state. A redacted public response, including a priority redaction, has `populationComplete=false` and `exact=false` together with the redacted page tuple (`holderCount=0`, `holderBalanceTotalRaw=null`, empty `items`, and `nextCursor=null`); it is never an empty-population assertion and is `Cache-Control: no-store`. Historical source corrections can invalidate an unexpired generation's proof without changing its immutable rows, block/hash, or row digest. Recheck `populationComplete` and `exact` on every retained cursor page; previous certification cannot override invalidated source authority. additionalProperties: false oneOf: - properties: populationComplete: const: true populationReasonCode: const: complete_canonical_transfer_coverage - properties: populationComplete: const: false populationReasonCode: const: population_coverage_unproven required: - populationComplete - populationReasonCode - exact - truncated - reasonCode properties: populationComplete: type: boolean description: | Whether Starkscan has established that the generation represents the token's full holder population. This is independent of cursor pagination and sampled `balanceOf` checks. A full cursor walk with this field set to `false` is only a complete walk of the published subset, not a complete ownership population. populationReasonCode: type: string description: | Population-coverage evidence state. `complete_canonical_transfer_coverage` requires canonical transfer coverage and generation-bound reconstruction. A newly published reconstruction-backed complete generation additionally requires paired exact-block total-supply and zero-address observations that conserve the generation's positive-holder total. `population_coverage_unproven` means the returned rows are useful indexed evidence but must not be used to make a complete-holder or supply-concentration claim. enum: - complete_canonical_transfer_coverage - population_coverage_unproven exact: type: boolean description: | Correctness of the complete holder generation, not coverage of the current page. True only when certification binds the exact chain, token, generation, finalized block number/hash, row digest, count, total, coverage authority, and cursor-retention identity. A generation receipt also records the exported count before the RPC sample and the count re-read in the certification write transaction; both must equal the immutable generation count. A token-scoped legacy balance sample is not generation certification. truncated: type: boolean description: | True only when the holder evidence/result was capped before a complete snapshot could be represented. Normal pagination is represented by `nextCursor` and does not make this field true; immutable holder pages therefore remain `truncated=false` while more pages exist. reasonCode: type: string description: | Completeness and certification reason for the holder generation. It is always present and must be interpreted alongside `exact`; `materialized_snapshot`, for example, can accompany `exact=true`. `cursor_snapshot_drift` means the cursor no longer matches the served snapshot identity; restart the holder walk from the first page rather than retrying or combining pages from that cursor. `priority_cohort_freshness_slo_exceeded` means the address-keyed priority generation is older than its server-evaluated freshness SLO (or has a future publication time), so the public zero count and empty rows are a redaction rather than an empty population and the response is `Cache-Control: no-store`. Other terminal certification states can use the same redacted tuple; always use the attached certification state and reason code rather than treating zero as an empty population. enum: - materialized_snapshot - uncertified_materialized_snapshot - certification_not_run - certification_table_missing - revoked - stale - unavailable - audit_failed - cursor_snapshot_drift - priority_cohort_freshness_slo_exceeded TokenHolderCertification: description: | Certification state for the complete holder generation. `validatedAgainst=starknet_rpc_balanceOf` means bounded deterministic balances were sampled at the exact snapshot block. RPC does not enumerate holders and is not the population-completeness authority; exactness also requires complete canonical transfer coverage and generation-bound ledger reconstruction. A certified immutable receipt has two count witnesses: the exported manifest count before sampling and the count re-read during the certification write; each must match the immutable generation count. Before a new reconstruction-backed complete generation can publish, the private generation-bound audit import must also carry paired exact-block total-supply and zero-address observations that conserve the positive-holder total. A completed private high-cardinality audit makes a generation eligible for this bounded certification path; it is not itself public certification. oneOf: - type: object additionalProperties: false required: - status - validatedAgainst - checkedAt - reasonCode properties: status: type: string enum: - certified validatedAgainst: type: string enum: - starknet_rpc_balanceOf description: Bounded exact-block balance sample oracle, not a holder enumeration source. checkedAt: type: string format: date-time reasonCode: type: string enum: - materialized_snapshot - type: object additionalProperties: false required: - status - validatedAgainst - checkedAt - reasonCode properties: status: type: string enum: - uncertified validatedAgainst: type: - string - "null" enum: - starknet_rpc_balanceOf - null checkedAt: type: - string - "null" format: date-time reasonCode: type: string enum: - uncertified_materialized_snapshot - certification_not_run - certification_table_missing - type: object additionalProperties: false required: - status - validatedAgainst - checkedAt - reasonCode properties: status: type: string enum: - revoked validatedAgainst: type: - string - "null" enum: - starknet_rpc_balanceOf - null checkedAt: type: - string - "null" format: date-time reasonCode: type: string enum: - revoked - type: object additionalProperties: false required: - status - validatedAgainst - checkedAt - reasonCode properties: status: type: string enum: - stale validatedAgainst: type: - string - "null" enum: - starknet_rpc_balanceOf - null checkedAt: type: - string - "null" format: date-time reasonCode: type: string enum: - stale - type: object additionalProperties: false required: - status - validatedAgainst - checkedAt - reasonCode properties: status: type: string enum: - unavailable validatedAgainst: type: - string - "null" enum: - starknet_rpc_balanceOf - null checkedAt: type: - string - "null" format: date-time reasonCode: type: string enum: - unavailable - type: object additionalProperties: false required: - status - validatedAgainst - checkedAt - reasonCode properties: status: type: string enum: - audit_failed validatedAgainst: type: - string - "null" enum: - starknet_rpc_balanceOf - null checkedAt: type: - string - "null" format: date-time reasonCode: type: string enum: - audit_failed TokenHolderLimits: type: object additionalProperties: false required: - maxPageSize - tier properties: maxPageSize: type: integer format: int64 maximum: 100 tier: type: string enum: - partner TokenHolderScreeningCoverage: type: object additionalProperties: false required: - kind - requestedTopN - returnedCount - populationComplete - exact - reasonCode properties: kind: type: string const: top_k_screening requestedTopN: type: integer format: int32 minimum: 1 maximum: 200 description: Server-resolved Top-N from the address-keyed screening policy; clients do not supply this value. returnedCount: type: integer format: int32 minimum: 0 maximum: 200 description: Total rows materialized in this bounded projection across all pages, not the current page length or the token's holderCount. populationComplete: type: boolean const: false exact: type: boolean const: false reasonCode: type: string const: screening_projection_not_population_proof TokenHolderScreeningPage: type: object additionalProperties: false required: - chainId - tokenAddress - snapshot - screening - items - nextCursor - limits properties: chainId: type: string tokenAddress: type: string snapshot: $ref: "#/components/schemas/TokenHolderScreeningSnapshot" screening: $ref: "#/components/schemas/TokenHolderScreeningCoverage" items: type: array maxItems: 100 items: $ref: "#/components/schemas/TokenHolderItem" nextCursor: type: - string - "null" description: Opaque continuation for this projection. Null proves only projection exhaustion. limits: $ref: "#/components/schemas/TokenHolderLimits" TokenHolderPage: type: object description: | One balance-ranked page from a token holder population. A complete immutable walk follows `nextCursor` to null while preserving the full snapshot identity, contiguous ranks, and stable count/total. Exactness is certification metadata and is independent of page coverage. An intentional public redaction, including a priority redaction, uses `holderCount=0`, `holderBalanceTotalRaw=null`, `items=[]`, `nextCursor=null`, `populationComplete=false`, and `exact=false`; it is `no-store` and is not an empty-population assertion. allOf: - if: required: - holderCount properties: holderCount: const: 0 then: properties: holderBalanceTotalRaw: enum: - "0" - null items: maxItems: 0 nextCursor: const: null - if: required: - holderCount - completeness properties: holderCount: const: 0 completeness: required: - populationComplete properties: populationComplete: const: true then: properties: holderBalanceTotalRaw: const: "0" additionalProperties: false required: - chainId - tokenAddress - snapshot - holderCount - holderBalanceTotalRaw - items - nextCursor - completeness - certification - limits properties: chainId: type: string tokenAddress: type: string snapshot: $ref: "#/components/schemas/TokenHolderSnapshot" holderCount: type: integer format: int64 minimum: 0 description: | Exact number of positive-balance rows in the immutable generation. When a non-serving certification state redacts public rows, zero is a redaction value and not proof that the token has no holders. A redacted response has `holderBalanceTotalRaw=null`; use that signal and the accompanying `certification.status`/`reasonCode` before treating zero as an empty population. The reviewed address-keyed priority cohort also redacts a generation that is incomplete, lacks generation-bound certification, or exceeds its freshness SLO. holderBalanceTotalRaw: type: - string - "null" description: Snapshot-aligned sum of every positive holder balance used as the analytics denominator. A zero-count response cannot claim a positive total; a complete empty population has the canonical string zero. Null when rows are redacted or legacy population authority is unavailable, never an empty-population certificate. items: type: array maxItems: 100 description: Page rows ordered by balanceRaw descending and canonical holder address ascending, with one-based contiguous generation ranks. items: $ref: "#/components/schemas/TokenHolderItem" nextCursor: type: - string - "null" description: | Opaque immutable-generation v3 cursor for the next holder page. Non-null means more rows are available. Pass it back unchanged before `snapshot.expiresAt`; never decode, construct, or reuse it for another chain or token. completeness: $ref: "#/components/schemas/TokenHolderCompleteness" certification: $ref: "#/components/schemas/TokenHolderCertification" limits: $ref: "#/components/schemas/TokenHolderLimits" TokenControlFact: type: object additionalProperties: false required: - status - actor properties: status: type: string enum: - fixed - mintable - minter_detected - pausable - freezable - blocklist_detected - not_detected - admin_detected - renounced - proxy_admin_detected - immutable_class - unknown actor: type: - string - "null" description: Indexed actor address when the status has a proven controlling actor. TokenSupplyControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - fixed - mintable - minter_detected - unknown TokenTransferControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - pausable - freezable - blocklist_detected - not_detected - unknown TokenMetadataAdminControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - admin_detected - renounced - unknown TokenUpgradeControlFact: allOf: - $ref: "#/components/schemas/TokenControlFact" - type: object properties: status: type: string enum: - proxy_admin_detected - immutable_class - unknown TokenControlEvidenceItem: type: object additionalProperties: true required: - kind properties: kind: type: string description: Evidence record kind, for example cached selector read, ABI scan, or operator proof. source: type: - string - "null" contractAddress: type: - string - "null" selector: type: - string - "null" txHash: type: - string - "null" blockNumber: type: - integer - "null" format: int64 minimum: 0 block: type: - integer - "null" format: int64 minimum: 0 actor: type: - string - "null" status: type: - string - "null" note: type: - string - "null" TokenControlsSnapshot: type: object additionalProperties: false required: - supplyControl - transferControl - metadataAdmin - upgradeControl - evidence - asOfBlock - source - indexedAtIso properties: supplyControl: $ref: "#/components/schemas/TokenSupplyControlFact" transferControl: $ref: "#/components/schemas/TokenTransferControlFact" metadataAdmin: $ref: "#/components/schemas/TokenMetadataAdminControlFact" upgradeControl: $ref: "#/components/schemas/TokenUpgradeControlFact" evidence: type: array description: Compact provenance records collected outside the request path. items: $ref: "#/components/schemas/TokenControlEvidenceItem" asOfBlock: type: integer format: int64 minimum: 0 source: type: string indexedAtIso: type: string format: date-time TokenControlsView: type: object additionalProperties: false required: - chainId - tokenAddress - indexed - reasonCode - snapshot properties: chainId: type: string tokenAddress: type: string indexed: type: boolean reasonCode: type: string enum: - materialized_controls_snapshot - controls_snapshot_missing snapshot: oneOf: - $ref: "#/components/schemas/TokenControlsSnapshot" - type: "null" TokenMarketPoolItem: type: object additionalProperties: false required: - marketId - marketKind - poolKey - displayName - protocolSlug - protocolName - poolType - dex - poolAddress - pairedTokenAddress - pairedTokenSymbol - feeBps - priceUsd - tvlUsd - volume24hUsd - volume24hPrevUsd - volume24hChangeBps - volumeWindowStartUnix - volumeWindowEndUnix - trades24h - traders24h - lastTradeBlock - snapshotBlock - source - updatedAtIso properties: marketId: type: string description: Stable market identity. For singleton protocols this can identify a market inside the same pool contract. marketKind: type: string enum: - pool_contract - singleton_pool - orderbook poolKey: type: - string - "null" description: Protocol-native pool or market key when distinct from the contract address. displayName: type: - string - "null" description: Human label for the market when materialized offline. protocolSlug: type: - string - "null" protocolName: type: string poolType: type: - string - "null" enum: - cl - cpmm - stable - orderbook - unknown - null dex: type: string description: Legacy DEX label retained for compatibility; prefer protocolName/protocolSlug for new clients. poolAddress: type: string pairedTokenAddress: type: - string - "null" pairedTokenSymbol: type: - string - "null" feeBps: type: - integer - "null" format: int32 minimum: 0 priceUsd: type: - string - "null" description: Decimal USD price string from the materialized snapshot. tvlUsd: type: - string - "null" description: Decimal USD TVL string from the materialized snapshot. pattern: ^[0-9]+(\.[0-9]+)?$ volume24hUsd: type: - string - "null" description: Decimal USD 24h volume string from the materialized snapshot. pattern: ^[0-9]+(\.[0-9]+)?$ volume24hPrevUsd: type: - string - "null" description: Decimal USD previous-window 24h volume used for delta display. volume24hChangeBps: type: - integer - "null" format: int32 description: Signed basis-point change from previous 24h volume to current 24h volume. volumeWindowStartUnix: type: - integer - "null" format: int64 minimum: 0 description: Unix timestamp for the inclusive start of the indexed 24h metric window. volumeWindowEndUnix: type: - integer - "null" format: int64 minimum: 0 description: Unix timestamp for the exclusive end of the indexed 24h metric window. trades24h: type: - integer - "null" format: int64 minimum: 0 traders24h: type: - integer - "null" format: int64 minimum: 0 lastTradeBlock: type: - integer - "null" format: int64 minimum: 0 snapshotBlock: type: - integer - "null" format: int64 minimum: 0 source: type: string updatedAtIso: type: string format: date-time TokenMarketPoolCoverage: type: object additionalProperties: false required: - exact - reasonCode properties: exact: type: boolean reasonCode: type: string enum: - materialized_pool_snapshot - pool_snapshot_missing - pool_rollup_missing TokenMarketPoolLimits: type: object additionalProperties: false required: - maxPageSize - tier properties: maxPageSize: type: integer format: int64 maximum: 100 tier: type: string enum: - partner TokenMarketPoolPage: type: object additionalProperties: false required: - chainId - tokenAddress - totalPairs - totalTvlUsd - totalVolume24hUsd - snapshotBlock - updatedAtIso - volumeWindowStartUnix - volumeWindowEndUnix - items - coverage - limits properties: chainId: type: string tokenAddress: type: string totalPairs: type: - integer - "null" format: int64 minimum: 0 totalTvlUsd: type: - string - "null" description: Indexed total TVL from the materialized token market pool rollup for this token, or null when that rollup value is not materialized. totalVolume24hUsd: type: - string - "null" description: Indexed total 24h volume from the materialized token market pool rollup for this token, or null when that rollup window is not materialized. snapshotBlock: type: - integer - "null" format: int64 minimum: 0 description: Highest pool snapshot block included in the token-level rollup. updatedAtIso: type: - string - "null" format: date-time description: Latest indexed pool snapshot timestamp included in the token-level rollup. volumeWindowStartUnix: type: - integer - "null" format: int64 minimum: 0 description: Earliest imported 24h metric window start across pool rows in the rollup. volumeWindowEndUnix: type: - integer - "null" format: int64 minimum: 0 description: Latest imported 24h metric window end across pool rows in the rollup. items: type: array maxItems: 100 items: $ref: "#/components/schemas/TokenMarketPoolItem" coverage: $ref: "#/components/schemas/TokenMarketPoolCoverage" limits: $ref: "#/components/schemas/TokenMarketPoolLimits" TokenHolderTierDistributionItem: type: object additionalProperties: false required: - tier - minShareBps - holderCount - shareBps properties: tier: type: string minShareBps: type: integer format: int64 holderCount: type: integer format: int64 shareBps: type: integer format: int64 TokenHolderThresholdCountItem: type: object additionalProperties: false required: - label - thresholdBps - holderCount properties: label: type: string thresholdBps: type: integer format: int64 holderCount: type: integer format: int64 TokenHolderAnalyticsMetrics: type: object additionalProperties: false required: - holderBalanceTotalRaw - top5BalanceRaw - top10BalanceRaw - top100BalanceRaw - top5ShareBps - top10ShareBps - top100ShareBps - whaleCount - whaleShareBps - giniScorePpm - nakamoto50Count - holdersAbove1Percent - tierDistribution - thresholdCounts properties: holderBalanceTotalRaw: type: string top5BalanceRaw: type: string top10BalanceRaw: type: string top100BalanceRaw: type: string top5ShareBps: type: integer format: int64 top10ShareBps: type: integer format: int64 top100ShareBps: type: integer format: int64 whaleCount: type: integer format: int64 whaleShareBps: type: integer format: int64 giniScorePpm: type: integer format: int64 nakamoto50Count: type: - integer - "null" format: int64 holdersAbove1Percent: type: integer format: int64 tierDistribution: type: array maxItems: 4 description: Fixed four-bucket holder concentration distribution. items: $ref: "#/components/schemas/TokenHolderTierDistributionItem" thresholdCounts: type: array maxItems: 3 description: Fixed three-threshold holder counts for >=1%, >=0.1%, and >=0.01%. items: $ref: "#/components/schemas/TokenHolderThresholdCountItem" TokenHolderAnalyticsSnapshot: type: object description: | Offline concentration analytics for the full holder population. A fresh generation-bound response repeats the immutable holder snapshot identity, including `rowDigest`; compare all identity fields before combining these metrics with holder pages. Metrics are never computed from one loaded page or by request-time RPC. additionalProperties: false required: - chainId - tokenAddress - snapshot - holderCount - computedAt - metrics - completeness properties: chainId: type: string tokenAddress: type: string snapshot: $ref: "#/components/schemas/TokenHolderSnapshot" holderCount: type: integer format: int64 minimum: 0 description: | Holder population used for every metric in this snapshot. Zero when no prepared analytics snapshot exists (`computedAt=null` and `metrics=null`); clients must check `metrics` before treating this value as an authoritative empty population. computedAt: type: - string - "null" format: date-time description: Offline analytics computation time. Null means no prepared analytics snapshot exists. metrics: oneOf: - $ref: "#/components/schemas/TokenHolderAnalyticsMetrics" - type: "null" description: Complete-generation metrics, or null when the prepared analytics snapshot is missing or incomplete. completeness: $ref: "#/components/schemas/TokenHolderCompleteness" SelfServeApiRateLimitPolicySummary: type: object additionalProperties: false required: - policyKey - policyDisplayName - lightPerMinute - heavyPerMinute - burst - maxActiveKeys properties: policyKey: type: string policyDisplayName: type: string lightPerMinute: type: integer format: int64 heavyPerMinute: type: integer format: int64 burst: type: integer format: int64 maxActiveKeys: type: integer format: int64 SelfServeApiKeySummary: type: object additionalProperties: false required: - publicId - label - environment - scopes - status - secretHint - maskedKey - rateLimitPolicy - createdAt - lastUsedAt - expiresAt - revokedAt properties: publicId: type: string label: type: string environment: type: string enum: - test - live scopes: type: array maxItems: 5 uniqueItems: true items: type: string enum: - read - batch - write - verify - prove - trace status: type: string enum: - active - revoked secretHint: type: string maskedKey: type: string rateLimitPolicy: $ref: "#/components/schemas/SelfServeApiRateLimitPolicySummary" createdAt: type: string format: date-time lastUsedAt: type: - string - "null" format: date-time expiresAt: type: - string - "null" format: date-time revokedAt: type: - string - "null" format: date-time SelfServeIssueApiKeyResult: type: object additionalProperties: false required: - action - plaintextKey - apiKey - revokedPublicIds properties: action: type: string enum: - created - rotated plaintextKey: type: string apiKey: $ref: "#/components/schemas/SelfServeApiKeySummary" revokedPublicIds: type: array maxItems: 1 items: type: string SelfServePartnerAccessCodeRequest: type: object additionalProperties: false required: - code properties: code: type: string minLength: 12 maxLength: 128 pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{11,127}$ writeOnly: true description: Single-use partner access code. Trim surrounding whitespace before sending; these constraints apply to the exact request value. Case is not significant because the server uppercases before matching. SelfServePartnerAccessCodeResponse: type: object additionalProperties: false required: - plan properties: plan: type: string enum: - free - developer - growth - business - enterprise - wallet SelfServeRateLimitState: type: object additionalProperties: false required: - loadClass - limitPerMinute - remaining - policy - retryAfterSeconds - observedAt properties: loadClass: type: string limitPerMinute: type: integer format: int64 remaining: type: integer format: int64 policy: type: string retryAfterSeconds: type: - integer - "null" format: int64 observedAt: type: string format: date-time SelfServeUsageEvent: type: object additionalProperties: false required: - requestId - apiKeyPublicId - apiKeyLabel - apiKeyEnvironment - apiKeyScopes - method - routePath - loadClass - statusCode - latencyMs - rateLimitState - observedAt properties: requestId: type: string apiKeyPublicId: type: string apiKeyLabel: type: string apiKeyEnvironment: type: string enum: - test - live apiKeyScopes: type: array maxItems: 5 uniqueItems: true items: type: string enum: - read - batch - write - verify - prove - trace method: type: string routePath: type: string loadClass: type: string statusCode: type: integer format: int64 latencyMs: oneOf: - type: integer format: int64 minimum: 0 - type: "null" rateLimitState: oneOf: - $ref: "#/components/schemas/SelfServeRateLimitState" - type: "null" observedAt: type: string format: date-time SelfServePerKeyUsage: type: object additionalProperties: false required: - apiKey - totalRequests - successCount - failureCount - lastRequestAt - lastFailureAt - latestRateLimitState properties: apiKey: $ref: "#/components/schemas/SelfServeApiKeySummary" totalRequests: type: integer format: int64 successCount: type: integer format: int64 failureCount: type: integer format: int64 lastRequestAt: type: - string - "null" format: date-time lastFailureAt: type: - string - "null" format: date-time latestRateLimitState: oneOf: - $ref: "#/components/schemas/SelfServeRateLimitState" - type: "null" SelfServeUsageSnapshot: type: object additionalProperties: false required: - windowStart - windowEnd - totalRequests - totalFailures - perKey - perKeyTruncated - recentRequests - recentRequestsTruncated - recentFailures - recentFailuresTruncated properties: windowStart: type: string format: date-time windowEnd: type: string format: date-time totalRequests: type: integer format: int64 totalFailures: type: integer format: int64 perKey: type: array maxItems: 100 description: Per-key aggregates for the bounded recent usage window. items: $ref: "#/components/schemas/SelfServePerKeyUsage" perKeyTruncated: type: boolean description: True when older keys fell outside the bounded per-key window. recentRequests: type: array maxItems: 100 description: Most recent request events in the bounded usage window. items: $ref: "#/components/schemas/SelfServeUsageEvent" recentRequestsTruncated: type: boolean description: True when more recent request events exist outside the returned slice. recentFailures: type: array maxItems: 25 description: Most recent failure events in the bounded usage window. items: $ref: "#/components/schemas/SelfServeUsageEvent" recentFailuresTruncated: type: boolean description: True when more failure events exist outside the returned slice. SelfServeApiKeyListResponse: type: object additionalProperties: false required: - items - truncated properties: items: type: array maxItems: 100 description: Newest-first self-serve API key metadata slice for the authenticated workspace. items: $ref: "#/components/schemas/SelfServeApiKeySummary" truncated: type: boolean description: True when older historical keys exist outside the returned slice. SelfServeApiKeyDeleteResponse: type: object additionalProperties: false required: - apiKey properties: apiKey: $ref: "#/components/schemas/SelfServeApiKeySummary" TokenTransferActionContext: type: object additionalProperties: false required: - actionKind - actionLabel - methodLabel - protocolSlug - protocolName - reasonCode - confidence - isInternalRouting - source - indexedAt properties: actionKind: type: string enum: - transfer - mint - burn - swap_leg - bridge_leg - lp_add - lp_remove - fee - internal_routing - unknown actionLabel: type: string methodLabel: type: - string - "null" protocolSlug: type: - string - "null" protocolName: type: - string - "null" reasonCode: type: string confidence: type: string enum: - exact - partial - heuristic - unknown isInternalRouting: type: boolean source: type: string indexedAt: type: - string - "null" format: date-time TokenTransferItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - fromAddress - toAddress - amount - rawValue - tokenId - standard - tokenSymbol - tokenName - tokenDecimals - actionContext - historicalUsd - sourceTier properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 transferIndex: type: integer format: int32 txHash: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" amount: type: - string - "null" rawValue: type: - string - "null" tokenId: type: - string - "null" standard: type: string tokenSymbol: type: - string - "null" description: Indexed or reviewed token symbol for display; null when unavailable. tokenName: type: - string - "null" description: Indexed or reviewed token display name; null when unavailable. tokenDecimals: type: - integer - "null" format: int32 minimum: -2147483648 maximum: 2147483647 description: Indexed or reviewed token decimals for amount formatting; null when unavailable. actionContext: oneOf: - $ref: "#/components/schemas/TokenTransferActionContext" - type: "null" historicalUsd: description: | Transaction-time USD coverage when this route includes price materialization. Transaction-detail and token-transfer responses report a priced, typed-unpriced, or pending result. `outside_history_window` is terminal provider-policy coverage; `price_missing` is a repairable in-horizon gap. Lightweight preview/list responses that intentionally omit this enrichment may return null. Never treat a null or unpriced result as a live/current market price. oneOf: - $ref: "#/components/schemas/TokenTransferHistoricalUsd" - type: "null" sourceTier: type: string enum: - head - finalized TokenTransferPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/TokenTransferItem" nextCursor: type: - string - "null" GlobalTransferItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - transferIndex - txHash - tokenAddress - fromAddress - toAddress - amount - rawValue - tokenId - standard - tokenSymbol - tokenName - tokenDecimals - sourceTier - actionContext - historicalUsd properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 transferIndex: type: integer format: int32 txHash: type: string tokenAddress: type: string fromAddress: type: - string - "null" toAddress: type: - string - "null" amount: type: - string - "null" rawValue: type: - string - "null" tokenId: type: - string - "null" standard: type: string tokenSymbol: type: - string - "null" description: Indexed or reviewed token symbol for display; null when unavailable. tokenName: type: - string - "null" description: Indexed or reviewed token display name; null when unavailable. tokenDecimals: type: - integer - "null" format: int32 minimum: -2147483648 maximum: 2147483647 description: Indexed or reviewed token decimals for amount formatting; null when unavailable. sourceTier: type: string enum: - head - finalized actionContext: oneOf: - $ref: "#/components/schemas/TokenTransferActionContext" - type: "null" historicalUsd: description: | Transaction-time USD coverage for this transfer. A null result is an explicit omission or unavailable fact, never a current-price substitute. oneOf: - $ref: "#/components/schemas/TokenTransferHistoricalUsd" - type: "null" GlobalTransferPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/GlobalTransferItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+:[0-9]+$ GlobalEventItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - txHash - address - topic0 - topic1 - topic2 - topic3 - keys - data - decodingStatus - sourceTier properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string address: type: string contractAlias: type: - string - "null" description: Reviewed indexed/token/protocol label for the emitting contract when available. It is presentation metadata and never affects raw event data or decoding provenance. classAlias: type: - string - "null" description: Reviewed class-family label for the emitting contract's indexed class when available. It is presentation metadata and never affects raw event data or decoding provenance. keys: type: array items: type: string description: Canonical on-chain event key array in indexed payload order. Legacy rows lacking `payload.keys` reconstruct only `topic0` through `topic3`, so their key array can be incomplete; raw keys/data are authoritative. topic0: type: - string - "null" topic1: type: - string - "null" topic2: type: - string - "null" topic3: type: - string - "null" data: type: array maxItems: 1024 items: type: string decodingStatus: type: string enum: - decoded - name_only - unknown description: Server-certified event decode state. `name_only` and `unknown` preserve the authoritative raw payload as available; legacy rows may expose a reconstructed, incomplete `keys[]` per the keys field description. eventName: type: - string - "null" description: Reviewed or ABI-derived event name when Starkscan can attribute topic0. eventNameSource: type: - string - "null" description: Attribution source for eventName. Current values include verified_abi, class_abi, selector_unique, and curated_selector; clients should treat unknown strings as forward-compatible provenance labels. eventNameUnavailableReason: type: - string - "null" enum: - event_time_class_epoch_unavailable - null description: Reason eventName is omitted even though Starkscan has contract-scoped epoch facts for this event. Raw topic/data fields remain authoritative. decodedFields: type: array maxItems: 128 items: $ref: "#/components/schemas/EventDecodedField" description: Decoded key/data fields only when an exact materialized ABI schema or a reviewed standard selector-and-arity schema consumes the full payload. Raw topic/data fields remain authoritative. decodedFieldsSource: type: - string - "null" description: Attribution source used for decodedFields when present. decodedFieldsUnavailableReason: type: - string - "null" enum: - schema_unavailable - selector_only_attribution - payload_shape_mismatch - schema_shape_unsupported - null description: Reason decodedFields is omitted for an attributed event. Selector-only attribution names the event but does not prove the field layout; raw topic/data fields remain authoritative. eventTimeClassHash: type: - string - "null" description: Exact execution class selected from the emitting contract's applicable on-chain class epoch at this event. Omitted when event-time class evidence is absent or ambiguous; the current contract class is never substituted. sourceTier: type: string enum: - head - finalized GlobalEventPage: type: object additionalProperties: false required: - items - nextCursor - eventDecodingDegraded properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/GlobalEventItem" nextCursor: type: - string - "null" description: Opaque continuation. Full-range values are bound to completeThroughBlockHash and the normalized route/filter scope; discard them after event_cursor_snapshot_changed or event_cursor_scope_changed. eventDecodingDegraded: type: boolean description: True only when the optional server attribution lookup failed operationally. Individual unknown events do not set this flag. rangeCoverage: $ref: "#/components/schemas/EventRangeCoverage" StrkbtcShieldEventItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - contractAddress - topic0 - direction - commitmentOrNullifier - publicAmount properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string contractAddress: type: string topic0: type: string direction: type: string enum: - shield - unshield commitmentOrNullifier: type: string publicAmount: type: - string - "null" StrkbtcShieldEventPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/StrkbtcShieldEventItem" nextCursor: type: - string - "null" StrkbtcCommitmentItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - commitmentHash properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string commitmentHash: type: string StrkbtcCommitmentPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/StrkbtcCommitmentItem" nextCursor: type: - string - "null" StrkbtcNullifierItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - nullifierHash properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string nullifierHash: type: string StrkbtcNullifierPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/StrkbtcNullifierItem" nextCursor: type: - string - "null" StrkbtcPoolStatusView: type: object additionalProperties: false required: - chainId - commitmentCount - nullifierCount - netOpenCount - version - updatedAtIso properties: chainId: type: string commitmentCount: type: integer format: int64 nullifierCount: type: integer format: int64 netOpenCount: type: integer format: int64 version: type: integer format: int64 updatedAtIso: type: string PrivacyPoolPublicVisibility: type: string enum: - public - partial - hidden_by_design PrivacyPoolTokenView: type: object additionalProperties: false required: - address - symbol - name - decimals properties: address: type: string symbol: type: - string - "null" name: type: - string - "null" decimals: type: - integer - "null" format: int32 description: Token decimals from authoritative indexed metadata, with an address-keyed two-provider-audited Privacy Pool manifest fallback on SN_MAIN only when indexed metadata is missing or incomplete. Null when neither source provides decimals; no request-time RPC lookup is performed. PrivacyPoolPublicFieldsView: type: object additionalProperties: false required: - visibility - actorAddress - toAddress - token - amountRaw - noteId - nullifier - auditorPublicKey properties: visibility: $ref: "#/components/schemas/PrivacyPoolPublicVisibility" actorAddress: description: Public on-chain actor address when the decoded event exposes one, such as a depositor. Null when absent, partial, or hidden by the event shape. type: - string - "null" toAddress: description: Public on-chain recipient address when the decoded event exposes one, such as a withdrawal recipient. Null when absent, partial, or hidden by the event shape. type: - string - "null" token: oneOf: - $ref: "#/components/schemas/PrivacyPoolTokenView" - type: "null" amountRaw: type: - string - "null" noteId: type: - string - "null" nullifier: type: - string - "null" auditorPublicKey: type: - string - "null" PrivacyPoolFeeEvidenceView: type: object additionalProperties: false required: - tokenAddress - amountRaw - collectorAddress - transferLogIndex - transferIndex - feeCollectorConfigBlockNumber - feeCollectorConfigTxIndex - feeCollectorConfigLogIndex - feeAmountConfigBlockNumber - feeAmountConfigTxIndex - feeAmountConfigLogIndex properties: tokenAddress: type: string amountRaw: type: string collectorAddress: type: string transferLogIndex: type: integer format: int32 transferIndex: type: integer format: int32 feeCollectorConfigBlockNumber: type: integer format: int64 feeCollectorConfigTxIndex: type: integer format: int32 feeCollectorConfigLogIndex: type: integer format: int32 feeAmountConfigBlockNumber: type: integer format: int64 feeAmountConfigTxIndex: type: integer format: int32 feeAmountConfigLogIndex: type: integer format: int32 PrivacyPoolEventItem: type: object additionalProperties: false required: - blockNumber - timestampIso - txIndex - logIndex - txHash - contractAddress - topic0 - eventName - key1 - key2 - data0 - data1 - data2 - keys - data - publicFields - privacyFees properties: blockNumber: type: integer format: int64 timestampIso: type: - string - "null" format: date-time description: UTC block timestamp when the indexed block is available. txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string contractAddress: type: string topic0: type: string eventName: type: string description: Indexed snake_case privacy-pool event name. maxLength: 32 pattern: ^[a-z0-9_]+$ examples: - deposit - withdrawal - proof_validity_blocks_set - protocol_event key1: type: - string - "null" key2: type: - string - "null" data0: type: - string - "null" data1: type: - string - "null" data2: type: - string - "null" keys: type: array description: Raw Starknet event keys as stored by the indexer. Payload-backed rows expose the full receipt keys array with the selector at index 0. Legacy rows without payload arrays expose only the indexed selector/key subset and must not be treated as receipt-complete evidence until verified against the transaction receipt. minItems: 1 maxItems: 1024 items: type: string data: type: array description: Raw Starknet event data as stored by the indexer. Payload-backed rows expose the full receipt data array. Legacy rows without payload arrays expose only the indexed data subset and must not be treated as receipt-complete evidence until verified against the transaction receipt. maxItems: 1024 items: type: string publicFields: $ref: "#/components/schemas/PrivacyPoolPublicFieldsView" privacyFees: type: array description: Public fee-transfer evidence for the same transaction, deduped per Activity row; empty when no configured privacy-pool fee transfer is present. maxItems: 64 items: $ref: "#/components/schemas/PrivacyPoolFeeEvidenceView" PrivacyPoolEventPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolEventItem" nextCursor: type: - string - "null" PrivacyPoolCommitmentFactItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - poolContractAddress - eventName - commitmentHash - tokenAddress - amountRaw properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string poolContractAddress: type: string eventName: type: string commitmentHash: type: string tokenAddress: type: - string - "null" amountRaw: type: - string - "null" PrivacyPoolCommitmentFactPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolCommitmentFactItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ PrivacyPoolNullifierFactItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - poolContractAddress - eventName - nullifierHash properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string poolContractAddress: type: string eventName: type: string nullifierHash: type: string PrivacyPoolNullifierFactPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolNullifierFactItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ PrivacyPoolRootFactItem: type: object additionalProperties: false required: - blockNumber - txIndex - logIndex - txHash - poolContractAddress - eventName - rootHash - treeSize properties: blockNumber: type: integer format: int64 txIndex: type: integer format: int32 logIndex: type: integer format: int32 txHash: type: string poolContractAddress: type: string eventName: type: string rootHash: type: string treeSize: type: - string - "null" PrivacyPoolRootFactPage: type: object additionalProperties: false required: - items - nextCursor properties: items: type: array maxItems: 100 items: $ref: "#/components/schemas/PrivacyPoolRootFactItem" nextCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ PrivacyPoolStatusView: type: object additionalProperties: false required: - chainId - totalEvents - depositCount - withdrawalCount - openNoteCreatedCount - openNoteDepositedCount - encNoteCreatedCount - noteUsedCount - auditorPublicKeySetCount - viewingKeySetCount - registeredUserCount - noteState - eventBreakdown - latestEventBlock - latestEventTxIndex - latestEventLogIndex - latestEventCursor - latestDecodedEventBlock - latestDecodedEventTxIndex - latestDecodedEventLogIndex - latestDecodedEventCursor - latestRawEventBlock - latestRawEventTxIndex - latestRawEventLogIndex - latestRawEventCursor - eventLagBlocks - rawEventFilterTruncated - materializationFresh properties: chainId: type: string totalEvents: type: integer format: int64 depositCount: type: integer format: int64 withdrawalCount: type: integer format: int64 openNoteCreatedCount: type: integer format: int64 openNoteDepositedCount: type: integer format: int64 encNoteCreatedCount: type: integer format: int64 noteUsedCount: type: integer format: int64 auditorPublicKeySetCount: type: integer format: int64 viewingKeySetCount: type: integer format: int64 description: Number of indexed public ViewingKeySet event rows. registeredUserCount: type: integer format: int64 description: Distinct public user addresses that registered a viewing key. noteState: $ref: "#/components/schemas/PrivacyPoolNoteStateView" eventBreakdown: type: array description: Complete partition of indexed privacy-pool events by event name. items: $ref: "#/components/schemas/PrivacyPoolCountView" latestEventBlock: type: - integer - "null" format: int64 description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event block. latestEventTxIndex: type: - integer - "null" format: int32 description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event transaction index. latestEventLogIndex: type: - integer - "null" format: int32 description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event log index. latestEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Backwards-compatible alias for the latest decoded/materialized privacy-pool event cursor as block:tx:log. latestDecodedEventBlock: type: - integer - "null" format: int64 description: Latest privacy-pool event block that has passed decoding and materialization. latestDecodedEventTxIndex: type: - integer - "null" format: int32 description: Transaction index component of the latest decoded/materialized privacy-pool event cursor. latestDecodedEventLogIndex: type: - integer - "null" format: int32 description: Log index component of the latest decoded/materialized privacy-pool event cursor. latestDecodedEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Exact latest decoded/materialized privacy-pool event cursor as block:tx:log. latestRawEventBlock: type: - integer - "null" format: int64 description: Latest raw privacy-pool contract event block observed by the source-event filter, when available. latestRawEventTxIndex: type: - integer - "null" format: int32 description: Transaction index component of the latest raw privacy-pool source-event cursor, when available. latestRawEventLogIndex: type: - integer - "null" format: int32 description: Log index component of the latest raw privacy-pool source-event cursor, when available. latestRawEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Exact latest raw privacy-pool source-event cursor as block:tx:log, when available. eventLagBlocks: type: - integer - "null" format: int64 description: Raw-event block minus decoded/materialized event block when the raw source-event filter is available. rawEventFilterTruncated: type: boolean description: True when a raw source-event filter is configured but exceeds the bounded serving-path candidate limit, so raw freshness cannot be certified. This is distinct from no raw filter being configured. materializationFresh: type: - boolean - "null" description: True when decoded privacy-pool materialization is caught up with raw event evidence; null when no raw source-event filter is configured or raw freshness is unavailable. Check rawEventFilterTruncated to distinguish the bounded-filter case. PrivacyPoolNoteStateView: type: object additionalProperties: false required: - commitmentCount - nullifierCount - openNoteCreatedCount - openNoteDepositedCount - encNoteCreatedCount - noteUsedCount - spentNoteProxyCount - unspentNoteProxyCount - source - caveat properties: commitmentCount: type: integer format: int64 minimum: 0 description: Count of public commitment facts indexed for the pool. nullifierCount: type: integer format: int64 minimum: 0 description: Count of public nullifier facts indexed for the pool. openNoteCreatedCount: type: integer format: int64 minimum: 0 openNoteDepositedCount: type: integer format: int64 minimum: 0 encNoteCreatedCount: type: integer format: int64 minimum: 0 noteUsedCount: type: integer format: int64 minimum: 0 spentNoteProxyCount: type: integer format: int64 minimum: 0 description: Public spent-note proxy equal to the nullifier count; notes are not linked. unspentNoteProxyCount: type: integer format: int64 minimum: 0 description: Public unspent-note proxy computed as commitments minus nullifiers, floored at zero. source: type: string enum: - public_decoded_event_rows caveat: type: string const: Public note/nullifier proxy only; not exact anonymity k; exact anonymity requires root-time state and denomination semantics. description: Explicit caveat that this is not exact anonymity k. PrivacyPoolTvlAsOfView: type: object additionalProperties: false required: - blockNumber - blockHash - blockTimestamp - materializedAt properties: blockNumber: type: - integer - "null" format: int64 blockHash: type: - string - "null" blockTimestamp: type: - string - "null" format: date-time materializedAt: type: - string - "null" format: date-time PrivacyPoolTvlCoverageView: type: object additionalProperties: false required: - status - reasonCode - finalizedOnly - finalityBasis - latestL1AcceptedBlockNumber - asOfL1Accepted - fromBlockNumber - throughBlockNumber - latestEventBlockNumber - latestEventCursor - poolContractCount - tokenCount - missingAmountEventCount - decodedMaterializationFresh - decodedEventLagBlocks properties: status: type: string enum: - complete - partial - unavailable reasonCode: type: string enum: - finalized_public_flow_ledger - incomplete_finalized_flow_ledger - no_finalized_flow_snapshot - decoded_materialization_lag - materialization_freshness_unavailable - raw_event_filter_truncated finalizedOnly: type: boolean const: true description: True because the ledger reads Starkscan's depth-confirmed indexed finalized tier. This does not by itself assert Starknet L1 acceptance. finalityBasis: type: string const: starkscan_indexed_finalized_tier description: Exact meaning of `finalizedOnly`; this is an indexed confirmation tier, not an L1-settlement claim. latestL1AcceptedBlockNumber: type: - integer - "null" format: int64 minimum: 0 description: Latest indexed Starknet block proven accepted on L1, or null when that evidence is unavailable. asOfL1Accepted: type: - boolean - "null" description: True only when `asOf.blockNumber` is at or below `latestL1AcceptedBlockNumber`; null when either comparison input is unavailable. fromBlockNumber: type: - integer - "null" format: int64 throughBlockNumber: type: - integer - "null" format: int64 latestEventBlockNumber: type: - integer - "null" format: int64 latestEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ description: Canonical block:tx:log position of the latest public deposit or withdrawal included in the ledger. This is the precise same-block reconciliation watermark. poolContractCount: type: integer format: int64 minimum: 0 tokenCount: type: integer format: int64 minimum: 0 maximum: 256 description: Number of served assets. Known zero-balance tokens are omitted; amount-incomplete tokens remain included with degraded status. missingAmountEventCount: type: integer format: int64 minimum: 0 decodedMaterializationFresh: type: - boolean - "null" description: True when finalized decoded deposit/withdrawal facts are caught up to matching raw finalized logs; null when the raw comparison filter is not configured or was truncated and therefore cannot certify completeness. decodedEventLagBlocks: type: - integer - "null" format: int64 minimum: 0 description: Raw finalized deposit/withdrawal block minus the latest decoded finalized flow block. Cursor-level lag can still exist when this value is zero. PrivacyPoolTvlPriceView: type: object deprecated: true description: Legacy compatibility valuation. Not a supported Privacy Pool pricing or accounting input; consumers must price raw address-keyed token amounts independently. additionalProperties: false allOf: - oneOf: - title: Fresh direct market valuation required: - status - reasonCode - priceUsd - confidence - valuationMethod properties: status: const: priced reasonCode: const: fresh_exact_cached_price priceUsd: type: string pattern: ^[0-9]+(?:\.[0-9]+)?$ confidence: const: exact valuationMethod: const: direct_market_quote - title: Fresh conversion estimate required: - status - reasonCode - priceUsd - confidence - valuationMethod properties: status: const: priced reasonCode: const: fresh_conversion_estimate priceUsd: type: string pattern: ^[0-9]+(?:\.[0-9]+)?$ confidence: const: proxy valuationMethod: const: snip22_conversion_estimate - title: Price unavailable required: - status - reasonCode - priceUsd - valuationMethod properties: status: const: unavailable valuationMethod: const: null reasonCode: enum: - amount_decode_incomplete - negative_protected_amount - token_metadata_missing - token_unmapped - price_not_exact - price_missing - price_stale priceUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ required: - status - reasonCode - priceUsd - source - provider - confidence - valuationMethod - priceTimestamp - observedAt - maxAgeSeconds properties: status: type: string enum: - priced - unavailable reasonCode: type: string enum: - fresh_exact_cached_price - fresh_conversion_estimate - amount_decode_incomplete - negative_protected_amount - token_metadata_missing - token_unmapped - price_not_exact - price_missing - price_stale priceUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ source: type: - string - "null" provider: type: - string - "null" confidence: type: - string - "null" valuationMethod: type: - string - "null" enum: - direct_market_quote - snip22_conversion_estimate - null priceTimestamp: type: - string - "null" format: date-time observedAt: type: - string - "null" format: date-time maxAgeSeconds: type: - integer - "null" format: int32 minimum: 1 PrivacyPoolTvlAssetView: type: object additionalProperties: false allOf: - oneOf: - title: Freshly priced asset required: - status - price - valueUsd properties: status: const: complete price: allOf: - $ref: "#/components/schemas/PrivacyPoolTvlPriceView" - properties: status: const: priced valueUsd: type: string pattern: ^[0-9]+(?:\.[0-9]+)?$ - title: Unpriced asset required: - price - valueUsd properties: price: allOf: - $ref: "#/components/schemas/PrivacyPoolTvlPriceView" - properties: status: const: unavailable valueUsd: type: "null" - oneOf: - title: Complete finalized-flow accounting required: - status - reasonCode properties: status: const: complete reasonCode: const: finalized_public_flow_ledger - title: Degraded finalized-flow accounting required: - status - reasonCode properties: status: const: degraded reasonCode: enum: - amount_decode_incomplete - negative_protected_amount required: - token - status - reasonCode - poolContractCount - depositEventCount - withdrawalEventCount - depositAmountRaw - withdrawalAmountRaw - protectedAmountRaw - protectedAmount - missingAmountEventCount - price - valueUsd properties: token: $ref: "#/components/schemas/PrivacyPoolTokenView" status: type: string enum: - complete - degraded reasonCode: type: string enum: - finalized_public_flow_ledger - amount_decode_incomplete - negative_protected_amount poolContractCount: type: integer format: int64 minimum: 0 depositEventCount: type: integer format: int64 minimum: 0 withdrawalEventCount: type: integer format: int64 minimum: 0 depositAmountRaw: type: string pattern: ^[0-9]+$ withdrawalAmountRaw: type: string pattern: ^[0-9]+$ protectedAmountRaw: type: string pattern: ^-?[0-9]+$ protectedAmount: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Exact normalized protected amount derived from protectedAmountRaw using indexed decimals, or audited SN_MAIN manifest decimals when indexed metadata is missing or incomplete. Null when decimals are unavailable or the raw amount cannot be safely normalized, including incomplete amount decoding or a negative protected amount. missingAmountEventCount: type: integer format: int64 minimum: 0 price: deprecated: true description: Legacy compatibility valuation. Do not use as a pricing or accounting input. $ref: "#/components/schemas/PrivacyPoolTvlPriceView" valueUsd: deprecated: true description: Legacy compatibility display value. Do not use as a pricing or accounting input. type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ PrivacyPoolTvlValuationView: type: object deprecated: true description: Legacy compatibility aggregate valuation. Consumers must price raw address-keyed token amounts independently. additionalProperties: false allOf: - oneOf: - title: Complete valuation required: - status - reasonCode - totalUsd properties: status: const: complete reasonCode: enum: - all_assets_fresh_exact_cached_price - all_assets_fresh_with_conversion_estimates totalUsd: type: string pattern: ^[0-9]+(?:\.[0-9]+)?$ - title: Unavailable valuation required: - status - reasonCode - totalUsd properties: status: const: unavailable reasonCode: enum: - one_or_more_assets_unpriced - no_finalized_flow_snapshot - coverage_incomplete totalUsd: type: "null" required: - status - reasonCode - quoteCurrency - totalUsd properties: status: type: string enum: - complete - unavailable reasonCode: type: string enum: - all_assets_fresh_exact_cached_price - all_assets_fresh_with_conversion_estimates - one_or_more_assets_unpriced - no_finalized_flow_snapshot - coverage_incomplete quoteCurrency: type: string const: USD totalUsd: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ PrivacyPoolTvlView: type: object additionalProperties: false required: - schemaVersion - chainId - scope - accountingMethod - status - asOf - coverage - valuation - assets - caveat properties: schemaVersion: type: string const: "1" chainId: type: string scope: type: string const: strk20_privacy_pool accountingMethod: type: string const: finalized_public_flow_ledger_v1 status: type: string enum: - complete - degraded - unavailable asOf: $ref: "#/components/schemas/PrivacyPoolTvlAsOfView" coverage: $ref: "#/components/schemas/PrivacyPoolTvlCoverageView" valuation: deprecated: true description: Legacy compatibility valuation. Not part of the supported Privacy Pool accounting contract. $ref: "#/components/schemas/PrivacyPoolTvlValuationView" assets: type: array maxItems: 256 description: Canonical-address-sorted nonzero public-flow amounts plus amount-incomplete degraded entries. Known zero-flow tokens are omitted. Consumers must use coverage and status fields and must not infer a custody balance from an empty array. items: $ref: "#/components/schemas/PrivacyPoolTvlAssetView" caveat: type: string PrivacyPoolTvlHourlyAsOfView: type: object additionalProperties: false required: - blockNumber - blockHash - blockTimestamp - latestEventCursor - materializedAt properties: blockNumber: type: integer format: int64 minimum: 0 blockHash: type: string blockTimestamp: type: string format: date-time latestEventCursor: type: - string - "null" pattern: ^[0-9]+:[0-9]+:[0-9]+$ materializedAt: type: string format: date-time PrivacyPoolTvlHourlyAssetView: type: object additionalProperties: false allOf: - oneOf: - properties: status: const: complete reasonCode: const: finalized_public_flow_ledger - properties: status: const: degraded reasonCode: enum: - amount_decode_incomplete - negative_protected_amount required: - token - status - reasonCode - poolContractCount - depositEventCount - withdrawalEventCount - depositAmountRaw - withdrawalAmountRaw - protectedAmountRaw - protectedAmount - missingAmountEventCount - valueUsd properties: token: $ref: "#/components/schemas/PrivacyPoolTokenView" status: type: string enum: - complete - degraded reasonCode: type: string enum: - finalized_public_flow_ledger - amount_decode_incomplete - negative_protected_amount poolContractCount: type: integer format: int64 minimum: 0 depositEventCount: type: integer format: int64 minimum: 0 withdrawalEventCount: type: integer format: int64 minimum: 0 depositAmountRaw: type: string pattern: ^[0-9]+$ withdrawalAmountRaw: type: string pattern: ^[0-9]+$ protectedAmountRaw: type: string pattern: ^-?[0-9]+$ protectedAmount: type: - string - "null" pattern: ^[0-9]+(?:\.[0-9]+)?$ missingAmountEventCount: type: integer format: int64 minimum: 0 valueUsd: type: "null" description: Historical USD pricing is consumer-owned for this contract. PrivacyPoolTvlHourlyPointView: type: object additionalProperties: false allOf: - oneOf: - properties: status: const: complete reasonCode: const: finalized_public_flow_ledger - properties: status: const: degraded reasonCode: const: incomplete_finalized_flow_ledger required: - timestamp - status - reasonCode - accountingMethod - asOf - poolContractCount - tokenCount - missingAmountEventCount - valuation - assets properties: timestamp: type: string format: date-time description: Start of this inclusive UTC-hour bucket. status: type: string enum: - complete - degraded reasonCode: type: string enum: - finalized_public_flow_ledger - incomplete_finalized_flow_ledger accountingMethod: type: string const: finalized_public_flow_ledger_v1 asOf: $ref: "#/components/schemas/PrivacyPoolTvlHourlyAsOfView" poolContractCount: type: integer format: int64 minimum: 0 tokenCount: type: integer format: int64 minimum: 0 maximum: 256 missingAmountEventCount: type: integer format: int64 minimum: 0 valuation: type: object additionalProperties: false required: - status - reasonCode - quoteCurrency - totalUsd properties: status: type: string const: unavailable reasonCode: type: string const: consumer_price_at_timestamp_required quoteCurrency: type: string const: USD totalUsd: type: "null" assets: type: array maxItems: 256 description: Nonzero protected-value assets plus amount-incomplete assets. Known zero-balance tokens are omitted until reactivated. items: $ref: "#/components/schemas/PrivacyPoolTvlHourlyAssetView" PrivacyPoolTvlHourlyPageView: type: object additionalProperties: false required: - schemaVersion - chainId - scope - granularity - order - from - to - limit - coverage - freshness - items - nextCursor - caveat properties: schemaVersion: type: string const: "1" chainId: type: string scope: type: string const: strk20_privacy_pool granularity: type: string const: hour order: type: string const: ascending from: type: string format: date-time to: type: string format: date-time limit: type: integer minimum: 1 maximum: 24 coverage: $ref: "#/components/schemas/PrivacyPoolTvlHourlyCoverageView" freshness: $ref: "#/components/schemas/PrivacyPoolTvlHourlyFreshnessView" items: type: array maxItems: 24 items: $ref: "#/components/schemas/PrivacyPoolTvlHourlyPointView" nextCursor: type: - string - "null" maxLength: 512 caveat: type: string PrivacyPoolTvlHourlyCoverageView: type: object additionalProperties: false required: - status - reasonCode - pageFrom - pageTo - expectedPointCount - availablePointCount - missingPointCount properties: status: type: string enum: - complete - degraded reasonCode: type: string enum: - prepared_hourly_coverage_complete - prepared_hourly_point_missing pageFrom: type: string format: date-time pageTo: type: string format: date-time expectedPointCount: type: integer minimum: 1 maximum: 24 availablePointCount: type: integer minimum: 0 maximum: 24 missingPointCount: type: integer minimum: 0 maximum: 24 oneOf: - properties: status: const: complete reasonCode: const: prepared_hourly_coverage_complete missingPointCount: const: 0 - properties: status: const: degraded reasonCode: const: prepared_hourly_point_missing PrivacyPoolTvlHourlyFreshnessView: type: object additionalProperties: false required: - status - reasonCode - finalizedThrough - materializedThrough - lagHours properties: status: type: string enum: - fresh - stale - unavailable reasonCode: type: string enum: - prepared_hourly_tail_current - prepared_hourly_tail_behind_finalized - prepared_hourly_tail_missing - finalized_hour_unavailable finalizedThrough: type: - string - "null" format: date-time materializedThrough: type: - string - "null" format: date-time lagHours: type: - integer - "null" minimum: 0 oneOf: - properties: status: const: fresh reasonCode: const: prepared_hourly_tail_current finalizedThrough: type: string format: date-time materializedThrough: type: string format: date-time lagHours: const: 0 - properties: status: const: stale reasonCode: const: prepared_hourly_tail_behind_finalized finalizedThrough: type: string format: date-time materializedThrough: type: string format: date-time lagHours: type: integer minimum: 1 - properties: status: const: unavailable reasonCode: const: prepared_hourly_tail_missing finalizedThrough: type: string format: date-time materializedThrough: type: "null" lagHours: type: "null" - properties: status: const: unavailable reasonCode: const: finalized_hour_unavailable finalizedThrough: type: "null" lagHours: type: "null" PrivacyPoolCountView: type: object additionalProperties: false required: - name - count properties: name: type: string maxLength: 32 pattern: ^[a-z0-9_]+$ description: | Breakdown bucket name. Event breakdowns use indexed privacy-pool snake_case event names; visibility breakdowns use `public`, `partial`, or `hidden_by_design`. examples: - deposit - protocol_event - hidden_by_design count: type: integer format: int64 PrivacyPoolTokenFlowView: type: object additionalProperties: false required: - token - eventCount - depositEventCount - withdrawalEventCount - observableDepositAmountRaw - observableWithdrawalAmountRaw - observableNetAmountRaw - missingAmountEventCount properties: token: $ref: "#/components/schemas/PrivacyPoolTokenView" eventCount: type: integer format: int64 depositEventCount: type: integer format: int64 withdrawalEventCount: type: integer format: int64 observableDepositAmountRaw: type: string observableWithdrawalAmountRaw: type: string observableNetAmountRaw: type: string missingAmountEventCount: type: integer format: int64 PrivacyPoolUnavailableMetricView: type: object additionalProperties: false required: - metric - reasonCode - reason properties: metric: type: string enum: - tvlUsd - privateSwapVolume - exactAnonymitySet - privateActivity reasonCode: type: string enum: - requires_balance_and_price_snapshots - volume_pricing_not_certified - commitment_state_materializer_required - historical_materialization_not_reconciled - source_coverage_stale - private_activity_metrics_not_migrated reason: type: string oneOf: - properties: metric: const: tvlUsd reasonCode: const: requires_balance_and_price_snapshots - properties: metric: const: privateSwapVolume reasonCode: const: volume_pricing_not_certified - properties: metric: const: exactAnonymitySet reasonCode: const: commitment_state_materializer_required - properties: metric: const: privateActivity reasonCode: enum: - historical_materialization_not_reconciled - source_coverage_stale - private_activity_metrics_not_migrated PrivacyPoolMetricBucketItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - newViewingKeyWallets - cumulativeViewingKeyWallets - visibleDeposits - visibleWithdrawals - noteUsedEvents - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - day newViewingKeyWallets: type: integer format: int64 minimum: 0 cumulativeViewingKeyWallets: type: integer format: int64 minimum: 0 visibleDeposits: type: integer format: int64 minimum: 0 visibleWithdrawals: type: integer format: int64 minimum: 0 noteUsedEvents: type: integer format: int64 minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolMetricBucketPage: type: object additionalProperties: false required: - chainId - bucketGranularity - items properties: chainId: type: string bucketGranularity: type: string enum: - day items: type: array maxItems: 90 items: $ref: "#/components/schemas/PrivacyPoolMetricBucketItem" PrivacyPoolWalletMetricSeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - newViewingKeyWallets - cumulativeViewingKeyWallets - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - hour - day - week newViewingKeyWallets: type: integer format: int64 minimum: 0 cumulativeViewingKeyWallets: type: integer format: int64 minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolShieldedSupplySeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - tokenAddress - depositedRaw - withdrawnRaw - shieldedSupplyRaw - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - hour - day - week tokenAddress: type: string depositedRaw: type: string pattern: ^[0-9]+$ maxLength: 80 withdrawnRaw: type: string pattern: ^[0-9]+$ maxLength: 80 shieldedSupplyRaw: type: string pattern: ^[0-9]+$ maxLength: 80 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolFeeMetricSeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - tokenAddress - feeAmountRaw - cumulativeFeeAmountRaw - feeTransferCount - latestBlockNumber properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - hour - day - week tokenAddress: type: string feeAmountRaw: type: string pattern: ^[0-9]+$ maxLength: 80 cumulativeFeeAmountRaw: type: string pattern: ^[0-9]+$ maxLength: 80 feeTransferCount: type: integer format: int64 minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 PrivacyPoolMetricSeriesPage: type: object additionalProperties: false required: - chainId - range - bucketGranularity - token - walletSeries - shieldedSupplySeries - privacyFeeSeries properties: chainId: type: string range: type: string enum: - 24h - 7d - 30d - all bucketGranularity: type: string enum: - hour - day - week token: $ref: "#/components/schemas/PrivacyPoolTokenView" walletSeries: type: array maxItems: 720 items: $ref: "#/components/schemas/PrivacyPoolWalletMetricSeriesItem" shieldedSupplySeries: type: array maxItems: 720 items: $ref: "#/components/schemas/PrivacyPoolShieldedSupplySeriesItem" privacyFeeSeries: type: array maxItems: 720 items: $ref: "#/components/schemas/PrivacyPoolFeeMetricSeriesItem" ProveRequest: type: object additionalProperties: false required: - block_id - transaction properties: block_id: description: Starknet block identifier forwarded to the prover unchanged. transaction: description: STRK20 transaction payload forwarded to the prover unchanged. ProveJobView: type: object additionalProperties: false required: - jobId - status - terminal - attemptCount - createdAt properties: jobId: type: string pattern: ^prv_[a-z0-9]{24,40}$ status: type: string enum: - queued - dispatched - succeeded - failed - unavailable - unknown_delivery terminal: type: boolean description: Stop polling when true. attemptCount: type: integer format: int32 minimum: 0 createdAt: type: string format: date-time completedAt: type: string format: date-time queuePosition: type: integer format: int64 minimum: 1 pollAfterSeconds: type: integer format: int64 minimum: 0 result: description: Prover result, passed through verbatim and available briefly after successful completion. Carries proof, proof_facts and l2_to_l1_messages, and for screened deposits also additional_data with the screening attestation. Persist the whole object on the first successful poll; a deposit is unusable on chain without additional_data. resultUnavailableReason: type: string enum: - delivered_or_expired error: type: object additionalProperties: true description: Caller-safe terminal error. unknown_delivery errors are non-retryable. NetworkMetricSeriesItem: type: object additionalProperties: false required: - bucketStartIso - bucketGranularity - blockCount - transactionCount - invokeTransactionCount - eventCount - l1ToL2MessageCount - l2ToL1MessageCount - activeSenderCount - averageTransactionsPerBlock - maxTransactionsPerSecond - latestBlockNumber - blockIntervalSampleCount - blockIntervalSecondsSum - averageBlockIntervalSeconds - maxBlockIntervalSeconds - actualFeeWeiTotalRaw - actualFeeFriTotalRaw - actualFeeKnownUnitCount - actualFeeUnclassifiedCount - finalizedClassDeclarationCount - deployedAccountCount - deployedContractCount - unclassifiedDeploymentCount properties: bucketStartIso: type: string format: date-time bucketGranularity: type: string enum: - day - week - month description: Calendar display resolution for this requested window. blockCount: type: integer format: int64 minimum: 0 transactionCount: type: integer format: int64 minimum: 0 invokeTransactionCount: type: integer format: int64 minimum: 0 description: Finalized Starknet INVOKE transactions. This is not an ERC-4337 user-operation count. eventCount: type: integer format: int64 minimum: 0 l1ToL2MessageCount: type: integer format: int64 minimum: 0 l2ToL1MessageCount: type: integer format: int64 minimum: 0 activeSenderCount: type: integer format: int64 minimum: 0 averageTransactionsPerBlock: type: number minimum: 0 maxTransactionsPerSecond: type: - number - "null" minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 blockIntervalSampleCount: type: - integer - "null" format: int64 minimum: 0 description: Positive consecutive finalized-block intervals in this bucket. Null means resource enrichment has not reached the bucket. blockIntervalSecondsSum: type: - number - "null" minimum: 0 description: Approximate floating-point sum of positive finalized-block intervals in seconds for weighted aggregation. This display metric is not an exact decimal contract. averageBlockIntervalSeconds: type: - number - "null" minimum: 0 maxBlockIntervalSeconds: type: - number - "null" minimum: 0 actualFeeWeiTotalRaw: type: - string - "null" pattern: ^[0-9]+$ description: Exact canonical receipt actual-fee total in WEI. Kept separate from FRI. Zero means a complete enriched bucket had no WEI fees; null means enrichment or expected finalized-receipt coverage is incomplete. actualFeeFriTotalRaw: type: - string - "null" pattern: ^[0-9]+$ description: Exact canonical receipt actual-fee total in FRI. Kept separate from WEI. Zero means a complete enriched bucket had no FRI fees; null means enrichment or expected finalized-receipt coverage is incomplete. actualFeeKnownUnitCount: type: - integer - "null" format: int64 minimum: 0 actualFeeUnclassifiedCount: type: - integer - "null" format: int64 minimum: 0 description: Receipts with missing, malformed, or unsupported canonical fee data, plus expected finalized receipt rows not indexed yet. finalizedClassDeclarationCount: type: - integer - "null" format: int64 minimum: 0 description: Classes declared by finalized DECLARE transactions in this bucket. Null means adoption enrichment has not reached the bucket. deployedAccountCount: type: - integer - "null" format: int64 minimum: 0 description: Canonical deployments classified as accounts in this bucket. deployedContractCount: type: - integer - "null" format: int64 minimum: 0 description: Canonical deployments classified as non-account contracts in this bucket. unclassifiedDeploymentCount: type: - integer - "null" format: int64 minimum: 0 description: Canonical deployments whose account-versus-contract classification is not yet known. NetworkMetricSeriesPage: type: object additionalProperties: false required: - chainId - window - bucketGranularity - items - preparedCoverageStartIso - preparedCoverageEndIso - latestBlockNumber - updatedAtIso - source - metricDefinitionVersion - coverageStatus - coverageReasonCode - materializedThroughBlockNumber - sourceLatestFinalizedBlockNumber - replicationLagBlocks - resourceCoverageStatus - resourceCoverageReasonCode - resourceMaterializedThroughBlockNumber - resourceReplicationLagBlocks - adoptionCoverageStatus - adoptionCoverageReasonCode - adoptionMaterializedThroughBlockNumber - adoptionReplicationLagBlocks properties: chainId: type: string window: type: string enum: - 30d - 90d - ytd - all bucketGranularity: type: string enum: - day - week - month description: Calendar display resolution for this requested window. items: type: array maxItems: 9000 items: $ref: "#/components/schemas/NetworkMetricSeriesItem" preparedCoverageStartIso: type: - string - "null" format: date-time preparedCoverageEndIso: type: - string - "null" format: date-time latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 updatedAtIso: type: - string - "null" format: date-time source: type: string enum: - finalized_materialized_buckets description: Serving source. This route reads prepared finalized buckets, not raw chain facts. metricDefinitionVersion: type: string enum: - network_metrics_v3 description: Version of the checked-in metric definition. coverageStatus: type: string enum: - prepared - partial - unavailable description: Whether the prepared materialization covers the latest finalized source block. coverageReasonCode: type: string enum: - finalized_materialized_buckets - materializer_lagging - materializer_state_unavailable - materialized_ahead_of_source_tip - no_prepared_buckets - source_tip_unavailable description: Machine-readable explanation of the coverage status. A prepared response requires the global materializer watermark to match the observed finalized source tip. materializedThroughBlockNumber: type: - integer - "null" format: int64 minimum: 0 description: Latest finalized block incorporated by the prepared materializer when known. sourceLatestFinalizedBlockNumber: type: - integer - "null" format: int64 minimum: 0 description: Latest finalized source block observed by the read store when known. replicationLagBlocks: type: - integer - "null" format: int64 minimum: 0 description: Difference between the source finalized tip and materialized watermark. Zero means current. resourceCoverageStatus: type: string enum: - prepared - partial - unavailable description: Independent coverage state for finalized block timing and canonical receipt fees. resourceCoverageReasonCode: type: string enum: - finalized_resource_buckets - no_prepared_resource_buckets - resource_metrics_not_materialized - resource_metrics_partial_window - resource_receipts_incomplete - resource_materializer_lagging - resource_materializer_state_unavailable - resource_materialized_ahead_of_source_tip - source_tip_unavailable resourceMaterializedThroughBlockNumber: type: - integer - "null" format: int64 minimum: 0 resourceReplicationLagBlocks: type: - integer - "null" format: int64 minimum: 0 adoptionCoverageStatus: type: string enum: - prepared - partial - unavailable description: Independent coverage state for finalized declarations and canonical deployments. adoptionCoverageReasonCode: type: string enum: - finalized_adoption_buckets - no_prepared_adoption_buckets - adoption_metrics_not_materialized - adoption_metrics_partial_window - adoption_materializer_lagging - adoption_materializer_state_unavailable - adoption_materialized_ahead_of_source_tip - source_tip_unavailable adoptionMaterializedThroughBlockNumber: type: - integer - "null" format: int64 minimum: 0 adoptionReplicationLagBlocks: type: - integer - "null" format: int64 minimum: 0 WalletProviderMetricItem: type: object additionalProperties: false required: - providerFamily - providerLabel - knownDeployedAccountCount - activeAccount30dCount - pricedFungibleValueUsd - pricedAccountCount - unpricedBalanceAccountCount - accountsOver10Usd - accountsOver100Usd - accountsOver1000Usd - classificationSource properties: providerFamily: type: string description: Stable machine-readable wallet-provider origin family. providerLabel: type: string description: Human-readable wallet-provider label. knownDeployedAccountCount: type: integer format: int64 minimum: 0 description: Distinct recognized wallet-provider deployment origins. Canonical deployment facts or finalized immutable deployment-class evidence is sufficient even when the derived address-activity summary has not been populated yet. activeAccount30dCount: type: integer format: int64 minimum: 0 description: Classified accounts that sent a successful finalized transaction in the trailing 30 days. pricedFungibleValueUsd: type: string pattern: ^[0-9]+(?:\.[0-9]+)?$ description: Lower-bound USD value as a decimal string to avoid JavaScript precision loss. pricedAccountCount: type: integer format: int64 minimum: 0 unpricedBalanceAccountCount: type: integer format: int64 minimum: 0 accountsOver10Usd: type: integer format: int64 minimum: 0 description: Accounts whose priced finalized fungible balance is strictly greater than 10 USD. accountsOver100Usd: type: integer format: int64 minimum: 0 description: Accounts whose priced finalized fungible balance is strictly greater than 100 USD. accountsOver1000Usd: type: integer format: int64 minimum: 0 description: Accounts whose priced finalized fungible balance is strictly greater than 1,000 USD. classificationSource: type: string enum: - deployment_origin_with_current_class_fallback WalletImplementationMetricItem: type: object additionalProperties: false required: - implementationFamily - implementationLabel - knownAccountCount - classificationSource properties: implementationFamily: type: string description: Stable machine-readable current account-code lineage. implementationLabel: type: string description: Human-readable current account-code lineage label. knownAccountCount: type: integer format: int64 minimum: 0 classificationSource: type: string enum: - finalized_current_class WalletMetricFamily: type: object additionalProperties: false required: - family - label properties: family: type: string pattern: ^[a-z][a-z0-9_]{0,63}$ description: Stable wallet-family key from the wallet class registry, or `unclassified`. label: type: string WalletMetricFamilyCount: type: object additionalProperties: false required: - family - activeWalletCount - newWalletCount - cumulativeWalletCount properties: family: type: string activeWalletCount: type: - integer - "null" format: int64 minimum: 0 description: Distinct active wallets. Null when activity coverage does not reach the period start. newWalletCount: type: - integer - "null" format: int64 minimum: 0 description: New wallets. Null when certified deployment coverage does not reach the period start. cumulativeWalletCount: type: - integer - "null" format: int64 minimum: 0 description: Wallets deployed since genesis through the end of the period. For a series period or the open year-to-date and all-time summaries whose deployments are not complete, the total runs through the deployment watermark instead. The latest complete day and week summaries report null until that period's deployments are complete, and a summary reports null when deployments are prepared more than 64 periods past it. Null until deployment coverage reaches genesis. WalletMetricPeriod: type: object additionalProperties: false required: - periodStartIso - granularity - activityComplete - deploymentsComplete - activeWalletCount - newWalletCount - cumulativeWalletCount - families properties: periodStartIso: type: string format: date-time granularity: type: string enum: - day - week - month - year - all activityComplete: type: boolean description: True when every finalized block of the period is counted for activity. The period at the indexed tip stays false. deploymentsComplete: type: boolean description: True when every finalized block of the period is counted for certified deployments. activeWalletCount: type: - integer - "null" format: int64 minimum: 0 description: Distinct active wallets across families. Families partition wallets, so this equals the family sum. newWalletCount: type: - integer - "null" format: int64 minimum: 0 cumulativeWalletCount: type: - integer - "null" format: int64 minimum: 0 families: type: array maxItems: 32 items: $ref: "#/components/schemas/WalletMetricFamilyCount" WalletMetricTrackCoverage: type: object additionalProperties: false required: - earliestBlockNumber - latestBlockNumber - fromGenesis - lagBlocks - updatedAtIso properties: earliestBlockNumber: type: - integer - "null" format: int64 minimum: 0 latestBlockNumber: type: - integer - "null" format: int64 minimum: 0 fromGenesis: type: boolean description: True once the contiguous materializer watermark starts at genesis block 0. lagBlocks: type: - integer - "null" format: int64 minimum: 0 updatedAtIso: type: - string - "null" format: date-time WalletMetricSummary: type: object additionalProperties: false required: - latestCompleteDay - latestCompleteWeek - yearToDate - allTime properties: latestCompleteDay: description: Most recent UTC day whose activity is complete. Its cumulative values are null until the day's deployments are also complete. oneOf: - $ref: "#/components/schemas/WalletMetricPeriod" - type: "null" latestCompleteWeek: description: Most recent ISO week whose activity is complete. Its cumulative values are null until the week's deployments are also complete. oneOf: - $ref: "#/components/schemas/WalletMetricPeriod" - type: "null" yearToDate: description: Current UTC year through the indexed tip; open, so never complete. Null when the current year has no prepared coverage. oneOf: - $ref: "#/components/schemas/WalletMetricPeriod" - type: "null" allTime: oneOf: - $ref: "#/components/schemas/WalletMetricPeriod" - type: "null" WalletMetricSeriesPage: type: object additionalProperties: false required: - chainId - window - bucketGranularity - windowStartIso - truncated - metricDefinitionVersion - source - families - items - summary - activityCoverage - deploymentCoverage - sourceLatestFinalizedBlockNumber - coverageStatus - coverageReason - caveat properties: chainId: type: string window: type: string enum: - 30d - 90d - ytd - all bucketGranularity: type: string enum: - day - week - month - year windowStartIso: type: - string - "null" format: date-time description: UTC start of the oldest requested period; null for all history. truncated: type: boolean description: True when an `all` window held more than 400 periods and only the newest 400 were returned. metricDefinitionVersion: type: string enum: - wallet_metric_series_v1 source: type: string enum: - finalized_materialized_wallet_series families: type: array maxItems: 32 description: Wallet families in stable key order; `unclassified` is always last. items: $ref: "#/components/schemas/WalletMetricFamily" items: type: array maxItems: 400 description: Periods oldest to newest whose start is covered by at least one track. An `all` window beyond 400 periods returns the newest 400 and sets `truncated`. items: $ref: "#/components/schemas/WalletMetricPeriod" summary: $ref: "#/components/schemas/WalletMetricSummary" activityCoverage: $ref: "#/components/schemas/WalletMetricTrackCoverage" deploymentCoverage: $ref: "#/components/schemas/WalletMetricTrackCoverage" sourceLatestFinalizedBlockNumber: type: - integer - "null" format: int64 minimum: 0 coverageStatus: type: string enum: - prepared - partial - unavailable coverageReason: type: string enum: - finalized_materialized_wallet_series - history_backfilling - materializer_lagging - materializer_blocked - deployment_source_lagging - deployment_source_unavailable - no_prepared_periods caveat: type: string WalletProviderMetricPage: type: object additionalProperties: false required: - chainId - items - implementationItems - sourceKnownAccountCount - trackedProviderAccountCount - trackedProviderAccountSharePercent - pricedTokenCount - unpricedTokenCount - classificationSource - sourceLatestFinalizedBlockNumber - materializedThroughBlockNumber - replicationLagBlocks - coverageStatus - coverageReasonCode - metricDefinitionVersion - source - caveat - updatedAtIso properties: chainId: type: string items: type: array maxItems: 16 items: $ref: "#/components/schemas/WalletProviderMetricItem" implementationItems: type: array maxItems: 16 description: Current account-code lineage, separate from immutable wallet-provider origin. items: $ref: "#/components/schemas/WalletImplementationMetricItem" sourceKnownAccountCount: type: integer format: int64 minimum: 0 description: Distinct account contracts known through finalized account summaries, account-marked deployment facts, or a recognized wallet-provider deployment origin backed by canonical deployment facts or finalized immutable deployment-class evidence. trackedProviderAccountCount: type: integer format: int64 minimum: 0 trackedProviderAccountSharePercent: type: number minimum: 0 maximum: 100 description: Share of indexed account contracts attributed to a tracked original wallet provider. This is not a claim that every account is classified. pricedTokenCount: type: integer format: int64 minimum: 0 unpricedTokenCount: type: integer format: int64 minimum: 0 classificationSource: type: string sourceLatestFinalizedBlockNumber: type: - integer - "null" format: int64 minimum: 0 materializedThroughBlockNumber: type: - integer - "null" format: int64 minimum: 0 replicationLagBlocks: type: - integer - "null" format: int64 minimum: 0 coverageStatus: type: string enum: - prepared - partial - unavailable coverageReasonCode: type: string enum: - finalized_materialized_snapshot - materializer_stale - materializer_state_unavailable - materialized_ahead_of_source_tip - no_prepared_snapshot - source_contract_mismatch - source_tip_unavailable metricDefinitionVersion: type: string enum: - wallet_provider_metrics_v1 - wallet_provider_metrics_v2 - wallet_provider_metrics_v3 - wallet_provider_metrics_v4 source: type: string enum: - finalized_materialized_snapshot caveat: type: string updatedAtIso: type: - string - "null" format: date-time PrivacyPoolDashboardView: type: object additionalProperties: false required: - status - analytics - events properties: status: $ref: "#/components/schemas/PrivacyPoolStatusView" analytics: $ref: "#/components/schemas/PrivacyPoolAnalyticsView" events: $ref: "#/components/schemas/PrivacyPoolEventPage" PrivacyPoolPrivateActivityMetricView: type: object additionalProperties: false required: - activityKind - protocolSlug - protocolName - helperAddress - helperLabel - confidence - attributionRuleVersion - txCount - noteUsedEventCount - openNoteCreatedEventCount - openNoteDepositedEventCount - encNoteCreatedEventCount - helperWithdrawalEventCount - latestBlockNumber - latestTxHash properties: activityKind: type: string enum: - private_swap protocolSlug: type: string protocolName: type: string helperAddress: type: string helperLabel: type: string confidence: type: string enum: - certified - candidate - unavailable attributionRuleVersion: type: string description: Versioned public attribution rule. AVNU helper-attributed Privacy Pool activity uses private_swap_v2 (finalized event quartet, AVNU Router calldata marker, and changed token set); it is not AVNU's total swap count or volume. txCount: type: integer format: int64 noteUsedEventCount: type: integer format: int64 openNoteCreatedEventCount: type: integer format: int64 openNoteDepositedEventCount: type: integer format: int64 encNoteCreatedEventCount: type: - integer - "null" format: int64 description: Certified public EncNoteCreated count, or null when the serving snapshot does not carry that evidence. Null must not be interpreted as zero. helperWithdrawalEventCount: type: integer format: int64 latestBlockNumber: type: - integer - "null" format: int64 latestTxHash: type: - string - "null" PrivacyPoolPrivateActivitySourceProvenanceView: type: object additionalProperties: false required: - generation - definitionFingerprint - sourceCommitSeq - sourceRangeDigest - terminalBlockNumber - terminalBlockHash properties: generation: type: integer format: int64 minimum: 1 definitionFingerprint: type: string pattern: ^sha256:[0-9a-f]{64}$ sourceCommitSeq: type: integer format: int64 minimum: 1 sourceRangeDigest: type: string pattern: ^sha256:[0-9a-f]{64}$ terminalBlockNumber: type: integer format: int64 minimum: 0 terminalBlockHash: type: string pattern: ^0x(0|[1-9a-f][0-9a-f]*)$ maxLength: 66 PrivacyPoolPrivateActivityView: type: object additionalProperties: false required: - source - coverageStatus - coverageReasonCode - sourceProvenance - caveat - totalPrivateActionTxCount - totalHelperWithdrawalEventCount - totalNoteUsedEventCount - totalOpenNoteDepositedEventCount - metricsLimit - metricsTruncated - metrics properties: source: type: string coverageStatus: type: string description: Only `complete` permits clients to treat the returned counters as lifetime totals. `stale` and `unavailable` fail closed and return no lifetime counter. enum: - complete - stale - unavailable coverageReasonCode: type: - string - "null" description: Stable reason lifetime coverage is not complete. `source_coverage_stale` means a sealed source exists but finalized source facts extend beyond it. `historical_materialization_not_reconciled` means older finalized routes have not been reconciled into the serving aggregate. `private_activity_metrics_not_migrated` means the serving migration is not available. enum: - historical_materialization_not_reconciled - source_coverage_stale - private_activity_metrics_not_migrated - null sourceProvenance: oneOf: - $ref: "#/components/schemas/PrivacyPoolPrivateActivitySourceProvenanceView" - type: "null" caveat: type: string totalPrivateActionTxCount: type: - integer - "null" format: int64 totalHelperWithdrawalEventCount: type: - integer - "null" format: int64 totalNoteUsedEventCount: type: - integer - "null" format: int64 totalOpenNoteDepositedEventCount: type: - integer - "null" format: int64 metricsLimit: type: integer format: int64 metricsTruncated: type: boolean metrics: type: array items: $ref: "#/components/schemas/PrivacyPoolPrivateActivityMetricView" oneOf: - properties: coverageStatus: const: complete coverageReasonCode: const: null sourceProvenance: $ref: "#/components/schemas/PrivacyPoolPrivateActivitySourceProvenanceView" totalPrivateActionTxCount: type: integer format: int64 totalHelperWithdrawalEventCount: type: integer format: int64 totalNoteUsedEventCount: type: integer format: int64 totalOpenNoteDepositedEventCount: type: integer format: int64 metrics: type: array items: allOf: - $ref: "#/components/schemas/PrivacyPoolPrivateActivityMetricView" - type: object properties: confidence: const: certified required: - confidence required: - coverageStatus - coverageReasonCode - sourceProvenance - properties: coverageStatus: const: stale coverageReasonCode: const: source_coverage_stale sourceProvenance: $ref: "#/components/schemas/PrivacyPoolPrivateActivitySourceProvenanceView" totalPrivateActionTxCount: const: null totalHelperWithdrawalEventCount: const: null totalNoteUsedEventCount: const: null totalOpenNoteDepositedEventCount: const: null metrics: maxItems: 0 metricsTruncated: const: false required: - coverageStatus - coverageReasonCode - sourceProvenance - properties: coverageStatus: const: unavailable coverageReasonCode: const: historical_materialization_not_reconciled sourceProvenance: const: null totalPrivateActionTxCount: const: null totalHelperWithdrawalEventCount: const: null totalNoteUsedEventCount: const: null totalOpenNoteDepositedEventCount: const: null metrics: maxItems: 0 metricsTruncated: const: false required: - coverageStatus - coverageReasonCode - sourceProvenance - properties: coverageStatus: const: unavailable coverageReasonCode: const: private_activity_metrics_not_migrated sourceProvenance: const: null totalPrivateActionTxCount: const: null totalHelperWithdrawalEventCount: const: null totalNoteUsedEventCount: const: null totalOpenNoteDepositedEventCount: const: null metrics: maxItems: 0 metricsTruncated: const: false required: - coverageStatus - coverageReasonCode - sourceProvenance PrivacyPoolAnalyticsView: type: object additionalProperties: false required: - chainId - totalEvents - uniqueTransactionCount - contractCount - latestEventBlock - eventBreakdown - visibilityBreakdown - tokenFlows - tokenFlowsLimit - tokenFlowsTruncated - tokenFlowSourceEventLimit - tokenFlowSourceEventsTruncated - missingAmountEventCount - strkbtcObserved - unknownTokenCount - privateActivity - unavailableMetrics properties: chainId: type: string totalEvents: type: integer format: int64 uniqueTransactionCount: type: integer format: int64 contractCount: type: integer format: int64 latestEventBlock: type: - integer - "null" format: int64 eventBreakdown: type: array items: $ref: "#/components/schemas/PrivacyPoolCountView" visibilityBreakdown: type: array items: $ref: "#/components/schemas/PrivacyPoolCountView" tokenFlows: type: array items: $ref: "#/components/schemas/PrivacyPoolTokenFlowView" tokenFlowsLimit: type: integer format: int64 tokenFlowsTruncated: type: boolean tokenFlowSourceEventLimit: type: integer format: int64 description: | Source event window used to derive tokenFlows. A value of 0 means the route is using all-history indexed public token-flow facts instead of deriving metrics from a bounded recent event sample. tokenFlowSourceEventsTruncated: type: boolean description: | True when tokenFlows were derived from a clipped source event window. False for all-history fact-backed token-flow metrics. missingAmountEventCount: type: integer format: int64 strkbtcObserved: type: boolean unknownTokenCount: type: integer format: int64 privateActivity: $ref: "#/components/schemas/PrivacyPoolPrivateActivityView" unavailableMetrics: type: array items: $ref: "#/components/schemas/PrivacyPoolUnavailableMetricView" SearchBlockItem: type: object additionalProperties: false required: - blockNumber - blockHash properties: blockNumber: type: integer format: int64 blockHash: type: string SearchTransactionItem: type: object additionalProperties: false required: - txHash - blockNumber - txIndex properties: txHash: type: string blockNumber: type: integer format: int64 txIndex: type: integer format: int32 SearchView: type: object additionalProperties: false required: - blocks - transactions - addresses properties: blocks: type: array maxItems: 5 items: $ref: "#/components/schemas/SearchBlockItem" transactions: type: array maxItems: 10 items: $ref: "#/components/schemas/SearchTransactionItem" addresses: type: array maxItems: 10 items: type: string results: description: Present only for opt-in typed mode; an empty array is authoritative. At most six results per family and 24 overall. Absence identifies a legacy server, not a typed miss. type: array maxItems: 24 items: $ref: "#/components/schemas/TypedSearchResult" resultsMayBeTruncated: description: Typed suggestions are not a complete directory. True conservatively marks bounded prefix catalogs, saturated family/overall bounds, or possibly omitted message occurrences; no total count is inferred. type: boolean TypedSearchResult: type: object additionalProperties: false required: - type - id - chain - matchKind properties: type: type: string enum: - tx - block - address - class - message - token id: type: string maxLength: 66 description: Canonical identifier. Block results use the decimal height; message hashes are lowercase padded bytes32. Other hashes/addresses are Starknet field elements. chain: type: string matchKind: type: string enum: - exact - indexed-prefix - registry-alias displayName: type: string maxLength: 256 labelSource: type: string maxLength: 256 symbol: type: string maxLength: 256 blockNumber: type: integer minimum: 0 txHash: type: string maxLength: 66 direction: type: string enum: - l1_to_l2 - l2_to_l1 description: Omitted for a message with contexts in multiple directions. Never inferred from its hash. contextsTruncated: type: boolean description: Required for message results. True means the bounded occurrence view may omit more contexts; never a global occurrence count. contexts: type: array minItems: 1 maxItems: 6 description: Required for message results. Indexed source occurrences, not inferred bridge pairs; duplicate source tiers are collapsed only for the same direction/transaction/index identity. items: type: object additionalProperties: false required: - direction - txHash - messageIndex - blockNumber properties: direction: type: string enum: - l1_to_l2 - l2_to_l1 txHash: type: string maxLength: 66 messageIndex: type: integer minimum: 0 maximum: 2147483647 blockNumber: type: integer minimum: 0 allOf: - if: properties: type: const: message then: required: - contexts - contextsTruncated else: not: anyOf: - required: - contexts - required: - contextsTruncated - required: - direction x-starkscan-audience: public-core tags: - name: Account description: Session-authenticated self-serve API-key lifecycle and usage routes for workspace operators. - name: Addresses - name: Blocks - name: Contracts - name: Verification description: Workspace-authenticated asynchronous exact-source verification jobs and portable signed receipts. - name: Privacy Pool description: Beta indexed public activity, note evidence, prepared metrics, and finalized public-flow amounts. These routes never infer private ownership or note linkage. - name: Reference description: Low-level explorer read surfaces that stay public but sit outside the default block/transaction/address entrypoints. - name: Search - name: Status - name: Tokens - name: Transactions - name: Utilities description: Supported helper routes that remain external, but are not the default public API starting point and can require broader utility-access keys.