{
  "version": 1,
  "updatedAt": "2026-06-01",
  "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.",
  "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.",
    "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}/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/token-read-correctness-gate.sh",
        "rust-exp/scripts/agent-api-conformance-smoke.sh"
      ],
      "checks": [
        "public API correctness manifest validation",
        "core API RPC parity gate",
        "exact-block token read correctness gate",
        "authenticated agent API conformance smoke"
      ],
      "blockers": [],
      "notes": "Correctness is the hard gate. Indexed lists and protocol routes stay beta until their reconciliation gates are current."
    },
    {
      "id": "starkscan-rpc-provider",
      "publicName": "Starkscan RPC provider",
      "state": "beta",
      "releaseState": "provider-beta-read-simulation-smoke-gated",
      "audience": "Starknet clients and agents 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 single requests",
        "JSON-RPC 2.0 batch requests capped at 25 items",
        "nodeUrl-compatible URL-token requests through /rpc/v0_10/{chain}/{token}",
        "read-light methods such as chainId, specVersion, blockNumber, blockHashAndNumber, and syncing",
        "state reads such as call, getStorageAt, getClass, getClassHashAt, getClassAt, and getNonce",
        "history reads such as blocks, transactions, receipts, status, state update, and bounded getEvents",
        "simulation and fee estimation methods"
      ],
      "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"
      ],
      "blockers": [
        "method-level observability and SLO dashboard before promotion beyond beta",
        "multi-client conformance matrix across Juno and Pathfinder before full-provider claims",
        "writes, traces, and WebSockets are not part of the first beta"
      ],
      "notes": "This is separate from the certified REST launch set. Treat it as beta for named clients that need starknet.js-style JSON-RPC reads, storage, class, nonce, receipts, events, simulation, fee, and batch support. Simulation and fee are currently envelope-gated with deliberately invalid fixtures; successful signed partner fixtures are required before stronger paymaster claims."
    },
    {
      "id": "typescript-sdk",
      "publicName": "TypeScript SDK",
      "state": "experimental",
      "releaseState": "alpha1-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.1 and live status smoke with STARKSCAN_BASE_URL=https://starkscan.co/api"
      ],
      "blockers": [
        "Trusted Publishing/public source metadata decision before CI publish",
        "public provenance strategy decided before promoting beyond alpha while the canonical repository is private"
      ],
      "notes": "@starkscan/sdk@0.1.0-alpha.1 is published on the alpha dist-tag, imports under Node ESM from a clean npm install, and passed live status smoke with STARKSCAN_BASE_URL=https://starkscan.co/api. npm latest points at the stable fail-closed placeholder 0.0.0, not the alpha prerelease. Treat @alpha as experimental until the publish-control decision is complete. npm provenance is not claimed while the canonical repository is private.",
      "packageTrust": {
        "package": "@starkscan/sdk",
        "channel": "alpha",
        "targetVersion": "0.1.0-alpha.1",
        "currentPublicVersion": "0.1.0-alpha.1",
        "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",
          "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.1 and latest resolves to the stable fail-closed placeholder 0.0.0",
          "post-publish live status smoke with STARKSCAN_BASE_URL=https://starkscan.co/api",
          "manual passkey-backed alpha publish until Trusted Publishing metadata requirements are resolved; npm provenance is not claimed while the canonical repository is private",
          "Socket package monitoring candidate; do not treat it as a formal certification"
        ]
      }
    },
    {
      "id": "agent-cli",
      "publicName": "Agent CLI",
      "state": "experimental",
      "releaseState": "alpha1-published-tags-clean-live-smoke-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.1",
        "npx -y @starkscan/cli@0.1.0-alpha.1 status and npx -y @starkscan/cli@0.1.0-alpha.1 doctor with STARKSCAN_BASE_URL=https://starkscan.co/api and a beta key"
      ],
      "blockers": [
        "Trusted Publishing/public source metadata decision before CI publish",
        "public provenance strategy decided before promoting beyond alpha while the canonical repository is private"
      ],
      "notes": "@starkscan/cli@0.1.0-alpha.1 is published on the alpha dist-tag, starts from a clean npm install, bundles native artifacts, and passed live status/doctor smoke with STARKSCAN_BASE_URL=https://starkscan.co/api. npm latest points at the stable fail-closed placeholder 0.0.0, not the alpha prerelease. Production agents should pin a smoked exact version instead of floating on @alpha.",
      "packageTrust": {
        "package": "@starkscan/cli",
        "channel": "alpha",
        "targetVersion": "0.1.0-alpha.1",
        "currentPublicVersion": "0.1.0-alpha.1",
        "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",
          "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.1 and latest resolves to the stable fail-closed placeholder 0.0.0",
          "post-publish live status and doctor smoke with STARKSCAN_BASE_URL=https://starkscan.co/api",
          "manual passkey-backed alpha publish until Trusted Publishing metadata requirements are resolved; npm provenance is not claimed while the canonical repository is private",
          "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": "alpha1-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.1",
        "npx -y @starkscan/mcp@0.1.0-alpha.1 doctor with STARKSCAN_BASE_URL=https://starkscan.co/api and a beta key",
        "client config examples for Codex and Claude Code"
      ],
      "blockers": [
        "Trusted Publishing/public source metadata decision before CI publish",
        "public provenance strategy decided before promoting beyond alpha while the canonical repository is private"
      ],
      "notes": "@starkscan/mcp@0.1.0-alpha.1 is published on the alpha dist-tag, starts from a clean npm install, delegates to the exact matching CLI dependency, and passed live doctor smoke with STARKSCAN_BASE_URL=https://starkscan.co/api. npm latest points at the stable fail-closed placeholder 0.0.0, not the alpha prerelease. Keep this experimental until the publish-control decision is complete.",
      "packageTrust": {
        "package": "@starkscan/mcp",
        "channel": "alpha",
        "targetVersion": "0.1.0-alpha.1",
        "currentPublicVersion": "0.1.0-alpha.1",
        "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",
          "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.1 and latest resolves to the stable fail-closed placeholder 0.0.0",
          "post-publish live doctor smoke with STARKSCAN_BASE_URL=https://starkscan.co/api",
          "manual passkey-backed alpha publish until Trusted Publishing metadata requirements are resolved; npm provenance is not claimed while the canonical repository is private",
          "Socket package monitoring candidate; do not treat it as a formal certification"
        ]
      }
    }
  ]
}