Kusama JSON-RPC Subscription API

asyncapi: 3.0.0
info:
  title: Kusama JSON-RPC Subscription API
  version: '1.24.0-660acefe665'
  description: |
    The event/streaming surface of the Kusama relay chain, served over WebSocket at
    wss://kusama-rpc.polkadot.io.

    Kusama publishes no webhooks — there is no vendor to register a callback URL with. Push delivery is
    instead done by holding a WebSocket subscription open against a node. This document describes the 13
    subscription-producing methods observed live in the `rpc_methods` response on 2026-07-19, out of 130
    total methods.

    PROVENANCE: generated by the API Evangelist enrichment pipeline from a live probe of
    https://kusama-rpc.polkadot.io/ plus the Polkadot JSON-RPC interface specification. This is NOT a
    provider-published AsyncAPI document — Parity does not publish one. Method names, subscribe/unsubscribe
    pairings and availability are verbatim from the live endpoint; message payload shapes are described
    from the interface specification and observed responses.
  contact:
    name: Polkadot JSON-RPC interface specification
    url: https://paritytech.github.io/json-rpc-interface-spec/
  license:
    name: GPL-3.0
    url: https://github.com/paritytech/polkadot-sdk/blob/master/LICENSE
  externalDocs:
    description: Polkadot JSON-RPC interface specification
    url: https://paritytech.github.io/json-rpc-interface-spec/
defaultContentType: application/json
servers:
  kusama:
    host: kusama-rpc.polkadot.io
    protocol: wss
    description: Public Kusama relay-chain node. No authentication. Best-effort community infrastructure
      with no published SLA or rate limits.
channels:
  chainHeadFollow:
    address: chainHead_v1_follow
    title: Chain head follow (spec-versioned)
    description: |
      The modern, light-client-oriented replacement for the legacy chain_/state_ subscriptions. A single
      subscription reports new blocks, best-block changes, and finalization, and pins the reported blocks
      so their state stays queryable until explicitly unpinned. Preferred for new integrations.
      Pair with chainHead_v1_unfollow, chainHead_v1_unpin, chainHead_v1_body, chainHead_v1_header,
      chainHead_v1_storage and chainHead_v1_call.
    messages:
      followEvent:
        $ref: '#/components/messages/FollowEvent'
  newHeads:
    address: chain_subscribeNewHeads
    title: New block headers (best chain)
    description: Emits a header for every new block on the best chain. Unsubscribe with
      chain_unsubscribeNewHeads. Aliases chain_subscribeNewHead and subscribe_newHead are also served.
    messages:
      header:
        $ref: '#/components/messages/BlockHeader'
  finalizedHeads:
    address: chain_subscribeFinalizedHeads
    title: Finalized block headers
    description: |
      Emits a header only once a block is finalized by GRANDPA. This is the subscription that matters for
      anything financial — a block on the best chain can still be reorged away; a finalized block cannot.
      Unsubscribe with chain_unsubscribeFinalizedHeads. The British spelling
      chain_subscribeFinalisedHeads is also served as an alias.
    messages:
      header:
        $ref: '#/components/messages/BlockHeader'
  allHeads:
    address: chain_subscribeAllHeads
    title: All block headers including forks
    description: Emits headers for every block the node imports, including blocks not on the best chain.
      Use only when you need fork visibility. Unsubscribe with chain_unsubscribeAllHeads.
    messages:
      header:
        $ref: '#/components/messages/BlockHeader'
  storage:
    address: state_subscribeStorage
    title: Storage change notifications
    description: |
      Emits a change set whenever any of the supplied storage keys changes. This is the closest thing
      Kusama has to a domain-event webhook: subscribing to a pallet's storage keys is how you observe
      balance changes, staking era rollovers, referendum state, and so on.
      Takes an array of hex-encoded storage keys as its parameter. Unsubscribe with
      state_unsubscribeStorage.
    messages:
      storageChangeSet:
        $ref: '#/components/messages/StorageChangeSet'
  runtimeVersion:
    address: state_subscribeRuntimeVersion
    title: Runtime version changes
    description: |
      Emits whenever the runtime is upgraded. Operationally important: a bump in transactionVersion breaks
      extrinsic encoding, so any service that constructs transactions must re-fetch metadata on this event
      or it will start producing invalid payloads. chain_subscribeRuntimeVersion is served as an alias.
      Unsubscribe with state_unsubscribeRuntimeVersion.
    messages:
      runtimeVersion:
        $ref: '#/components/messages/RuntimeVersion'
  transactionWatch:
    address: transactionWatch_v1_submitAndWatch
    title: Transaction status stream (spec-versioned)
    description: Submit a signed extrinsic and receive its lifecycle events until it is finalized,
      invalidated, or dropped. Unsubscribe with transactionWatch_v1_unwatch.
    messages:
      transactionStatus:
        $ref: '#/components/messages/TransactionStatus'
  submitAndWatchExtrinsic:
    address: author_submitAndWatchExtrinsic
    title: Transaction status stream (legacy)
    description: Legacy equivalent of transactionWatch_v1_submitAndWatch. Unsubscribe with
      author_unwatchExtrinsic.
    messages:
      transactionStatus:
        $ref: '#/components/messages/TransactionStatus'
  grandpaJustifications:
    address: grandpa_subscribeJustifications
    title: GRANDPA finality justifications
    description: Emits GRANDPA justifications — the cryptographic proof that a block was finalized.
      Consumed by bridges and light clients. Unsubscribe with grandpa_unsubscribeJustifications.
    messages:
      justification:
        $ref: '#/components/messages/Justification'
  beefyJustifications:
    address: beefy_subscribeJustifications
    title: BEEFY finality justifications
    description: Emits BEEFY justifications, the bridge-friendly finality gadget layered on GRANDPA and
      designed to be verifiable by non-Substrate chains (notably Ethereum). Unsubscribe with
      beefy_unsubscribeJustifications.
    messages:
      justification:
        $ref: '#/components/messages/Justification'
operations:
  followChainHead:
    action: receive
    channel:
      $ref: '#/channels/chainHeadFollow'
    summary: Follow the chain head with pinned blocks (recommended for new integrations).
  receiveNewHeads:
    action: receive
    channel:
      $ref: '#/channels/newHeads'
    summary: Receive best-chain block headers as they are imported.
  receiveFinalizedHeads:
    action: receive
    channel:
      $ref: '#/channels/finalizedHeads'
    summary: Receive block headers only after GRANDPA finalization.
  receiveAllHeads:
    action: receive
    channel:
      $ref: '#/channels/allHeads'
    summary: Receive every imported header including forks.
  receiveStorageChanges:
    action: receive
    channel:
      $ref: '#/channels/storage'
    summary: Receive change sets for a supplied set of storage keys.
  receiveRuntimeVersion:
    action: receive
    channel:
      $ref: '#/channels/runtimeVersion'
    summary: Receive runtime upgrade notifications; re-fetch metadata on transactionVersion bumps.
  watchTransaction:
    action: receive
    channel:
      $ref: '#/channels/transactionWatch'
    summary: Receive lifecycle status for a submitted extrinsic.
  watchExtrinsicLegacy:
    action: receive
    channel:
      $ref: '#/channels/submitAndWatchExtrinsic'
    summary: Legacy extrinsic status stream.
  receiveGrandpaJustifications:
    action: receive
    channel:
      $ref: '#/channels/grandpaJustifications'
    summary: Receive GRANDPA finality proofs.
  receiveBeefyJustifications:
    action: receive
    channel:
      $ref: '#/channels/beefyJustifications'
    summary: Receive BEEFY finality proofs for bridging.
components:
  messages:
    FollowEvent:
      name: followEvent
      title: chainHead follow event
      summary: 'One of: initialized, newBlock, bestBlockChanged, finalized, operationBodyDone,
        operationCallDone, operationStorageItems, operationStorageDone, operationWaitingForContinue,
        operationInaccessible, operationError, or stop.'
      contentType: application/json
      payload:
        type: object
        properties:
          event:
            type: string
            description: The event discriminator.
          finalizedBlockHashes:
            type: array
            items:
              type: string
          blockHash:
            type: string
          parentBlockHash:
            type: string
    BlockHeader:
      name: blockHeader
      title: Block header
      contentType: application/json
      payload:
        type: object
        properties:
          parentHash:
            type: string
            description: 0x-prefixed hash of the parent block.
          number:
            type: string
            description: Block height, hex-encoded in the JSON-RPC representation.
          stateRoot:
            type: string
          extrinsicsRoot:
            type: string
          digest:
            type: object
            properties:
              logs:
                type: array
                items:
                  type: string
      examples:
      - name: liveHeader
        summary: Shape captured from the Kusama sidecar projection of the same header on 2026-07-19.
        payload:
          parentHash: '0x119b623486df6575de30b16c567710e5f221a3d5215103e30d28830c4b49532f'
          number: '34448611'
          stateRoot: '0x83fdf53da545b85a9c037bc181a98e89b245e461493275620309833f4955029a'
          extrinsicsRoot: '0x054f3e3cb8582354e56255bfd93d3500d581ebf974669910309795484b51d4e4'
    StorageChangeSet:
      name: storageChangeSet
      title: Storage change set
      contentType: application/json
      payload:
        type: object
        properties:
          block:
            type: string
            description: Hash of the block in which the change occurred.
          changes:
            type: array
            description: Array of [storageKey, newValue] pairs. newValue is null when the key was cleared.
            items:
              type: array
              items:
                type: string
    RuntimeVersion:
      name: runtimeVersion
      title: Runtime version
      contentType: application/json
      payload:
        type: object
        properties:
          specName:
            type: string
          implName:
            type: string
          specVersion:
            type: integer
          implVersion:
            type: integer
          transactionVersion:
            type: integer
            description: A bump here breaks extrinsic encoding — re-fetch metadata.
          authoringVersion:
            type: integer
      examples:
      - name: observed
        summary: Captured live from state_getRuntimeVersion on 2026-07-19.
        payload:
          specName: kusama
          implName: parity-kusama
          specVersion: 2003000
          implVersion: 0
          authoringVersion: 2
    TransactionStatus:
      name: transactionStatus
      title: Transaction lifecycle status
      summary: 'Progresses through: validated, broadcasted, bestChainBlockIncluded, finalized — or
        terminates with invalid, dropped, or error. Only `finalized` is safe to treat as settled.'
      contentType: application/json
      payload:
        type: object
        properties:
          event:
            type: string
          block:
            type: object
            properties:
              hash:
                type: string
              index:
                type: integer
          error:
            type: string
    Justification:
      name: justification
      title: Finality justification
      contentType: application/json
      payload:
        type: string
        description: SCALE-encoded, hex-prefixed justification blob.