{
  "version": 2,
  "updatedAt": "2026-06-04",
  "description": "Agent/client launch matrix for public Starkscan integration surfaces. Route-level certification remains owned by public-api-correctness-manifest.json; this file classifies the higher-level REST, RPC, SDK, CLI, and MCP surfaces. Version 2 adds provider-blocked; strict consumers should treat the states object as the authoritative enum list for this version.",
  "states": {
    "certified": "Production-safe for the stated scope, with current correctness evidence and stable client contract.",
    "beta": "Usable by named clients with documented limits or release-channel caveats.",
    "experimental": "Partner/internal preview only; schema, packaging, or auth may still change.",
    "provider-blocked": "The route or adapter exists for gated proof, but customer migration is blocked on provider-readiness evidence.",
    "unsupported": "Not a supported client contract."
  },
  "surfaces": [
    {
      "id": "rest-core-api",
      "publicName": "REST core API",
      "state": "certified",
      "releaseState": "ready-for-named-client-production",
      "audience": "external clients and agents that call HTTP directly",
      "entrypoint": "https://<host>/api/v1/...",
      "auth": "X-Starkscan-Api-Key",
      "scope": [
        "GET /v1/{chain}/status",
        "GET /v1/{chain}/block/{number_or_hash}",
        "GET /v1/{chain}/block-at-timestamp",
        "GET /v1/{chain}/tx/{tx_hash}",
        "GET /v1/{chain}/token/{token}/total-supply",
        "GET /v1/{chain}/token/{token}/balance-of/{address}"
      ],
      "evidence": [
        "rust-exp/docs/api/public-api-correctness-manifest.json",
        "rust-exp/deploy/hetzner/scripts/core-api-rpc-parity-gate.sh",
        "rust-exp/deploy/hetzner/scripts/block-at-timestamp-correctness-gate.sh",
        "rust-exp/deploy/hetzner/scripts/token-read-correctness-gate.sh",
        "rust-exp/docs/api/block-at-timestamp-certification.md",
        "rust-exp/scripts/agent-api-conformance-smoke.sh"
      ],
      "checks": [
        "public API correctness manifest validation",
        "core API RPC parity gate",
        "block-at-timestamp RPC correctness gate",
        "exact-block token read correctness gate",
        "authenticated agent API conformance smoke"
      ],
      "blockers": [],
      "notes": "Correctness is the hard gate. The certified accounting scope is timestamp-to-block plus exact token balance for one known token/account at a concrete block. Indexed lists, historical portfolio discovery, and protocol routes stay beta until their reconciliation gates are current."
    },
    {
      "id": "starkscan-rpc-provider",
      "publicName": "Starkscan RPC provider",
      "state": "provider-blocked",
      "releaseState": "provider-pilot-mainnet-upstream-blocked",
      "audience": "Partner/operator readiness testing for Starknet clients that need a JSON-RPC endpoint instead of REST routes",
      "entrypoint": "POST https://<host>/api/v1/{chain}/rpc",
      "auth": "X-Starkscan-Api-Key on the public /api/v1 path; /rpc/v0_10/{chain}/{token} is a compatibility nodeUrl path for clients that cannot attach headers and must use a dedicated RPC compatibility key; treat the full URL-token form as sensitive",
      "scope": [
        "JSON-RPC 2.0 route and auth shape for gated readiness testing",
        "header-auth requests on /api/v1/{chain}/rpc",
        "nodeUrl-compatible URL-token requests through /rpc/v0_10/{chain}/{token}",
        "single-request and batch-envelope parsing paths",
        "provider-readiness evidence only after a dedicated mainnet RPC_GATEWAY_* upstream/LB is configured",
        "customer migration remains blocked until live evidence proves starknet_specVersion >= 0.10.2, mainnet chain id, batch support, fixed-block reads, starknet_call, and simulate/fee method recognition"
      ],
      "evidence": [
        "rust-exp/scripts/starkscan-rpc-provider-smoke.sh",
        "rust-exp/scripts/tests/starkscan-rpc-provider-smoke.sh",
        "rust-exp/scripts/starkscan-rpc-provider-pilot-gate.py",
        "rust-exp/scripts/tests/starkscan-rpc-provider-pilot-gate.sh",
        "webapp/apps/docs/content/docs/api/agent-quickstart.mdx"
      ],
      "checks": [
        "RPC provider smoke validates public auth rejection on /api/v1",
        "RPC provider smoke validates authenticated chainId, URL-token nodeUrl, and batch reads",
        "RPC provider smoke validates planned write rejection and batch-size cap",
        "RPC provider pilot gate validates read-state and read-history method matrices",
        "RPC provider pilot gate validates simulation and fee JSON-RPC forwarding envelopes",
        "tester readiness smoke includes the RPC provider smoke",
        "provider-readiness deploy gate records pilot, Chipi workload, and live parity report summaries when RUN_RPC_PROVIDER_READINESS_GATE=true"
      ],
      "blockers": [
        "dedicated mainnet RPC_GATEWAY_* upstream/LB with starknet_specVersion >= 0.10.2 is not yet proven on preview-main",
        "provider-readiness deploy attestation has not been recorded for a mainnet candidate upstream",
        "method-level observability and SLO dashboard before promotion beyond the provider pilot",
        "multi-client conformance matrix across Juno and Pathfinder before full-provider claims",
        "writes, traces, and WebSockets are outside the current pilot"
      ],
      "notes": "This is separate from the certified REST launch set. The route exists and is auth-gated, but live preview currently uses the fallback upstream path and is not a customer migration target. Keep Alchemy, Infura, Juno, Pathfinder, or another existing Starknet RPC provider for storage, class, nonce, call, fee, simulation, and broad provider workflows until issue #1781 records a dedicated mainnet 0.10.2+ upstream preflight and provider-readiness attestation."
    },
    {
      "id": "typescript-sdk",
      "publicName": "TypeScript SDK",
      "state": "experimental",
      "releaseState": "alpha2-published-tags-clean-live-smoke-passed",
      "audience": "TypeScript applications and agent runtimes that want typed REST access",
      "entrypoint": "@starkscan/sdk@alpha",
      "auth": "SDK forwards the same hosted API-key contract as REST",
      "scope": [
        "typed wrappers over the public REST contract",
        "chain-bound Starkscan client helpers",
        "live tester smoke against preview"
      ],
      "evidence": [
        "webapp/packages/sdk/package.json",
        "webapp/packages/sdk/src/index.ts",
        "webapp/packages/sdk/src/starkscanClient.ts",
        "webapp/packages/sdk/scripts/tester-smoke.ts"
      ],
      "checks": [
        "bun run --cwd packages/sdk typecheck",
        "bun run --cwd packages/sdk test",
        "bun run --cwd packages/sdk build",
        "bun run --cwd packages/sdk smoke:tester",
        "clean npm install of @starkscan/sdk@0.1.0-alpha.2, Node ESM import, and live public status smoke with baseUrl=https://starkscan.co after alpha2 publish"
      ],
      "blockers": [
        "npm Trusted Publisher must be configured on the @starkscan/sdk package page before CI publish",
        "public provenance strategy decided before promoting beyond alpha while the canonical repository is private"
      ],
      "notes": "@starkscan/sdk@0.1.0-alpha.2 is currently published on the alpha dist-tag and imports under Node ESM from a clean npm install. npm latest points at the stable fail-closed placeholder 0.0.2, not the alpha prerelease. Trusted Publishing is the chosen CI publish path, with repository metadata pointing at the checked-in private repository URL string for npm publisher matching. Treat @alpha as experimental until the npm package-page trusted publisher is configured. npm provenance is not claimed while the canonical repository is private.",
      "packageTrust": {
        "package": "@starkscan/sdk",
        "channel": "alpha",
        "targetVersion": "0.1.0-alpha.2",
        "currentPublicVersion": "0.1.0-alpha.2",
        "npm": "https://www.npmjs.com/package/@starkscan/sdk",
        "source": "https://starkscan.co/docs/build/package-trust",
        "socket": "https://socket.dev/npm/package/@starkscan/sdk",
        "controls": [
          "public scoped package under the @starkscan npm org",
          "public package trust source lives at https://starkscan.co/docs/build/package-trust because the canonical repository is private",
          "repository metadata points at the checked-in private repository URL string for npm Trusted Publishing publisher matching",
          "package artifacts from the checked release workflow",
          "package entrypoint and type entrypoint preflight before publish",
          "post-publish dist-tag verifier confirms alpha resolves to 0.1.0-alpha.2 and latest resolves to the stable fail-closed placeholder 0.0.2",
          "post-publish public status smoke with baseUrl=https://starkscan.co",
          "authenticated /api smoke remains a per-client beta-key check",
          "manual passkey-backed alpha publish until npm Trusted Publisher is configured; CI publish must use OIDC with NPM_CONFIG_PROVENANCE=false",
          "Socket package monitoring candidate; do not treat it as a formal certification"
        ]
      }
    },
    {
      "id": "agent-cli",
      "publicName": "Agent CLI",
      "state": "experimental",
      "releaseState": "alpha2-published-live-smoke-request-id-prefix-passed",
      "audience": "shell users, local exports, and agent subprocess workflows",
      "entrypoint": "@starkscan/cli@alpha",
      "auth": "CLI sends X-Starkscan-Api-Key and uses STARKSCAN_* env names",
      "scope": [
        "npx/npm wrapper",
        "native artifact verification",
        "doctor and command forwarding"
      ],
      "evidence": [
        "webapp/packages/cli/package.json",
        "webapp/packages/cli/README.md",
        "webapp/packages/cli/scripts/tests/cli-wrapper.mjs",
        "rust-exp/scripts/release-cli-smoke.sh"
      ],
      "checks": [
        "npm run typecheck in webapp/packages/cli",
        "npm run test in webapp/packages/cli",
        "clean npm install of @starkscan/cli@0.1.0-alpha.2 after alpha2 publish",
        "npx -y @starkscan/cli@0.1.0-alpha.2 --base-url https://starkscan.co status after alpha2 publish",
        "npx -y @starkscan/cli@0.1.0-alpha.2 doctor with STARKSCAN_BASE_URL=https://starkscan.co/api and a beta key when running per-client authenticated smoke",
        "unauthenticated doctor smoke must emit starkscan-cli- request IDs and never the legacy request-id prefix"
      ],
      "blockers": [
        "npm Trusted Publisher must be configured on the @starkscan/cli package page before CI publish",
        "public provenance strategy decided before promoting beyond alpha while the canonical repository is private"
      ],
      "notes": "@starkscan/cli@0.1.0-alpha.2 is currently published on the alpha dist-tag, includes bundled native artifacts, and passed unauthenticated error-path request ID prefix smoke. npm latest points at the stable fail-closed placeholder 0.0.2, not the alpha prerelease. Trusted Publishing is the chosen CI publish path, with repository metadata pointing at the checked-in private repository URL string for npm publisher matching. Run authenticated doctor smoke with a beta key before adding a new unattended client.",
      "packageTrust": {
        "package": "@starkscan/cli",
        "channel": "alpha",
        "targetVersion": "0.1.0-alpha.2",
        "currentPublicVersion": "0.1.0-alpha.2",
        "npm": "https://www.npmjs.com/package/@starkscan/cli",
        "source": "https://starkscan.co/docs/build/package-trust",
        "socket": "https://socket.dev/npm/package/@starkscan/cli",
        "controls": [
          "public scoped package under the @starkscan npm org",
          "public package trust source lives at https://starkscan.co/docs/build/package-trust because the canonical repository is private",
          "repository metadata points at the checked-in private repository URL string for npm Trusted Publishing publisher matching",
          "native archives bundled for darwin-aarch64, darwin-x86_64, linux-aarch64, and linux-x86_64",
          "manifest and sha256 verification before executing the native binary",
          "safe tar entry checks and package-version release-tag binding before publish",
          "GitHub artifact attestations for release workflow outputs",
          "post-publish dist-tag verifier confirms alpha resolves to 0.1.0-alpha.2 and latest resolves to the stable fail-closed placeholder 0.0.2",
          "post-publish unauthenticated error-path smoke confirms request IDs use starkscan-cli- and never the legacy request-id prefix",
          "post-publish public status smoke with --base-url https://starkscan.co",
          "authenticated doctor smoke with STARKSCAN_BASE_URL=https://starkscan.co/api remains a per-client beta-key check",
          "manual passkey-backed alpha publish until npm Trusted Publisher is configured; CI publish must use OIDC with NPM_CONFIG_PROVENANCE=false",
          "Socket package monitoring candidate; do not treat it as a formal certification"
        ]
      }
    },
    {
      "id": "hosted-mcp-http",
      "publicName": "Hosted MCP HTTP",
      "state": "beta",
      "releaseState": "usable-with-api-key-auth-and-discovery",
      "audience": "MCP-capable agents that can call the hosted JSON-RPC endpoint",
      "entrypoint": "POST https://<host>/api/mcp",
      "auth": "X-Starkscan-Api-Key for the hosted /api/mcp path",
      "scope": [
        "single JSON-RPC request per POST",
        "tools/list and tools/call parity with the read surface",
        "stateless hosted transport",
        "OAuth protected-resource discovery metadata for MCP-capable clients"
      ],
      "evidence": [
        "rust-exp/docs/mcp-http-rollout.md",
        "rust-exp/docs/mcp-tool-parity.md",
        "rust-exp/src/transport/api/mcp_http_adapter.rs",
        "rust-exp/src/transport/mcp.rs",
        "rust-exp/deploy/hetzner/scripts/post-deploy-smoke.sh"
      ],
      "checks": [
        "GET /api/mcp returns 405 Allow: POST",
        "POST /api/mcp initialize returns MCP protocol 2025-11-25",
        "OAuth protected-resource discovery routes pass post-deploy smoke",
        "MCP tool parity tests in rust-exp"
      ],
      "blockers": [],
      "notes": "Direct hosted MCP is live with API-key auth on /api/mcp, and OAuth protected-resource discovery is validated by preview smoke. Root /mcp may be served as a compatibility alias on some deployments, but public clients should use the API-base path. Discovery metadata is not the same as launching a full OAuth token issuance flow. npm launcher promotion is tracked separately from the hosted HTTP transport."
    },
    {
      "id": "mcp-launcher",
      "publicName": "Official MCP launcher",
      "state": "experimental",
      "releaseState": "alpha2-published-tags-clean-live-smoke-passed",
      "audience": "Codex, Claude Code, Cursor, Cline, and other desktop MCP clients",
      "entrypoint": "npx -y @starkscan/mcp@alpha",
      "auth": "STARKSCAN_API_KEY environment variable passed by the host client",
      "scope": [
        "one-command MCP onboarding",
        "generated client config snippets",
        "packaged launcher smoke"
      ],
      "evidence": [
        "webapp/packages/mcp/package.json",
        "webapp/packages/mcp/README.md",
        "webapp/apps/docs/content/docs/ai/mcp-quickstart.mdx",
        "rust-exp/scripts/tester-mcp-remote-smoke.sh",
        "rust-exp/scripts/release-mcp-remote-smoke.sh"
      ],
      "checks": [
        "npm run typecheck in webapp/packages/mcp",
        "npm run test in webapp/packages/mcp",
        "packaged launcher smoke, not cargo-run fallback",
        "clean npm install of @starkscan/mcp@0.1.0-alpha.2 after alpha2 publish",
        "npx -y @starkscan/mcp@0.1.0-alpha.2 print-config and tools with STARKSCAN_BASE_URL=https://starkscan.co/api after alpha2 publish",
        "npx -y @starkscan/mcp@0.1.0-alpha.2 doctor with STARKSCAN_BASE_URL=https://starkscan.co/api and a beta key when running per-client authenticated smoke",
        "unauthenticated doctor smoke must emit starkscan-cli- request IDs and never the legacy request-id prefix",
        "client config examples for Codex and Claude Code"
      ],
      "blockers": [
        "npm Trusted Publisher must be configured on the @starkscan/mcp package page before CI publish",
        "public provenance strategy decided before promoting beyond alpha while the canonical repository is private"
      ],
      "notes": "@starkscan/mcp@0.1.0-alpha.2 is currently published on the alpha dist-tag through the matching CLI package, passes packaged launcher smoke, and inherits the fixed CLI unauthenticated error-path request ID prefix. Trusted Publishing is the chosen CI publish path, with repository metadata pointing at the private canonical repo for npm publisher matching. Keep this experimental until the npm package-page trusted publisher is configured. Run authenticated doctor smoke with a beta key before adding a new unattended client.",
      "packageTrust": {
        "package": "@starkscan/mcp",
        "channel": "alpha",
        "targetVersion": "0.1.0-alpha.2",
        "currentPublicVersion": "0.1.0-alpha.2",
        "npm": "https://www.npmjs.com/package/@starkscan/mcp",
        "source": "https://starkscan.co/docs/build/package-trust",
        "socket": "https://socket.dev/npm/package/@starkscan/mcp",
        "controls": [
          "public scoped package under the @starkscan npm org",
          "public package trust source lives at https://starkscan.co/docs/build/package-trust because the canonical repository is private",
          "repository metadata points at the checked-in private repository URL string for npm Trusted Publishing publisher matching",
          "exact dependency pin to the matching @starkscan/cli package version",
          "packaged launcher smoke before publish",
          "secret-redaction tests for API-key bearing env and URLs",
          "post-publish dist-tag verifier confirms alpha resolves to 0.1.0-alpha.2 and latest resolves to the stable fail-closed placeholder 0.0.2",
          "post-publish unauthenticated error-path smoke confirms request IDs use starkscan-cli- and never the legacy request-id prefix",
          "post-publish print-config/tools smoke with STARKSCAN_BASE_URL=https://starkscan.co/api",
          "authenticated doctor smoke with STARKSCAN_BASE_URL=https://starkscan.co/api remains a per-client beta-key check",
          "manual passkey-backed alpha publish until npm Trusted Publisher is configured; CI publish must use OIDC with NPM_CONFIG_PROVENANCE=false",
          "Socket package monitoring candidate; do not treat it as a formal certification"
        ]
      }
    }
  ]
}