Kusama transaction API

openapi: 3.0.0
info:
  title: Substrate API Sidecar accounts transaction API
  description: '> ⚠️ **Deprecation Notice** — `substrate-api-sidecar` is deprecated in favor of

    > [`polkadot-rest-api`](https://github.com/paritytech/polkadot-rest-api), a ground-up Rust rewrite

    > built on [`subxt`](https://github.com/paritytech/subxt) with 1:1 API compatibility (endpoints

    > served under `/v1/`, e.g. `/v1/blocks/head`), stable memory under sustained load, significantly

    > lower latency and higher throughput, and native SCALE decoding via `parity-scale-codec`.

    >

    > **Migrate today:** Docker `paritytech/polkadot-rest-api:v0.1.0` ·

    > [crate](https://crates.io/crates/polkadot-rest-api) ·

    > [migration guide](https://github.com/paritytech/polkadot-rest-api/blob/main/docs/guides/MIGRATION.md) ·

    > [docs](https://paritytech.github.io/polkadot-rest-api/) ·

    > [issues](https://github.com/paritytech/polkadot-rest-api/issues)


    Substrate API Sidecar is a REST service that makes it easy to interact with blockchain nodes

    built using Substrate''s FRAME framework.

    '
  contact:
    url: https://github.com/paritytech/substrate-api-sidecar
  license:
    name: GPL-3.0-or-later
    url: https://github.com/paritytech/substrate-api-sidecar/blob/master/LICENSE
  version: 20.14.1
servers:
- url: https://polkadot-public-sidecar.parity-chains.parity.io/
  description: Polkadot Parity public sidecar
- url: https://kusama-public-sidecar.parity-chains.parity.io/
  description: Kusama Parity public sidecar
- url: https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/
  description: Polkadot Asset Hub Parity public sidecar
- url: https://kusama-asset-hub-public-sidecar.parity-chains.parity.io/
  description: Kusama Asset Hub Parity public sidecar
- url: http://localhost:8080
  description: Localhost
tags:
- name: transaction
paths:
  /transaction:
    post:
      tags:
      - transaction
      summary: Submit a transaction to the node's transaction pool.
      description: Accepts a valid signed extrinsic. Replaces `/tx` from versions < v1.0.0.
      operationId: submitTransaction
      requestBody:
        $ref: '#/components/requestBodies/Transaction'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionSuccess'
        '400':
          description: failed to parse or submit transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFailure'
  /transaction/dry-run:
    post:
      tags:
      - transaction
      summary: Dry run an extrinsic.
      description: Use the `dryRun` call to simulate the submission of a transaction without executing it so that you can check for potential errors and validate the expected outcome.
      operationId: dryrunTransaction
      requestBody:
        $ref: '#/components/requestBodies/TransactionDryRun'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDryRun'
        '400':
          description: failed to dry-run transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFailure'
  /transaction/fee-estimate:
    post:
      tags:
      - transaction
      summary: Receive a fee estimate for a transaction.
      description: 'Send a serialized transaction and receive back a naive fee estimate. Note: `partialFee` does not include any tips that you may add to increase a transaction''s priority. See the reference on `compute_fee`. Replaces `/tx/fee-estimate` from versions < v1.0.0. Substrate Reference: - `RuntimeDispatchInfo`: https://crates.parity.io/pallet_transaction_payment_rpc_runtime_api/struct.RuntimeDispatchInfo.html - `query_info`: https://crates.parity.io/pallet_transaction_payment/struct.Module.html#method.query_info - `compute_fee`: https://crates.parity.io/pallet_transaction_payment/struct.Module.html#method.compute_fee'
      operationId: feeEstimateTransaction
      requestBody:
        $ref: '#/components/requestBodies/Transaction'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFeeEstimate'
        '400':
          description: fee estimation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFeeEstimateFailure'
  /transaction/material:
    get:
      tags:
      - transaction
      summary: Get all the network information needed to construct a transaction offline.
      description: Returns the material that is universal to constructing any signed transaction offline. Replaces `/tx/artifacts` from versions < v1.0.0.
      operationId: getTransactionMaterial
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve the transaction construction material.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      - name: noMeta
        in: query
        description: DEPRECATED! This is no longer supported
        schema:
          type: boolean
          default: false
      - name: metadata
        in: query
        description: Specifies the format of the metadata to be returned. Accepted values are 'json', and 'scale'. 'json' being the decoded metadata, and 'scale' being the SCALE encoded metadata. When `metadata` is not inputted, the `metadata` field will be absent.
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionMaterial'
        '400':
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transaction/material/{metadataVersion}:
    get:
      tags:
      - transaction
      summary: Get all the network information needed to construct a transaction offline and the version of metadata specified in `metadataVersion`.
      description: Returns all the materials necessary for constructing any signed transactions offline.
      operationId: getTransactionMaterialwithVersionedMetadata
      parameters:
      - name: metadataVersion
        in: path
        description: The version of metadata. The input is expected in a `vX` format, where `X` represents the version number (e.g. `v14`, `v15`). By default, metadata is outputted in 'json' format, unless the `metadata` query parameter is provided, in which case it can be either in 'json' or 'scale' format.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve the transaction construction material.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      - name: metadata
        in: query
        description: Specifies the format of the metadata to be returned. Accepted values are 'json', and 'scale'. 'json' being the decoded metadata, and 'scale' being the SCALE encoded metadata.
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionMaterial'
        '400':
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /transaction/metadata-blob:
    post:
      tags:
      - transaction
      summary: Get the metadata blob for offline signers.
      description: 'Returns the minimal metadata ("metadata blob" or "proof") needed by offline signers to decode a transaction''s signing payload, along with the metadata hash for the CheckMetadataHash signed extension per RFC-0078.


        The metadata blob contains type definitions needed to decode the specific transaction, Merkle proofs verifying these types are part of the full metadata, and extra chain info (specVersion, specName, base58Prefix, decimals, tokenSymbol).


        Offline signers can use this to decode the transaction to display what the user is signing and verify the metadata subset matches the on-chain metadata via Merkle proofs.


        Reference: RFC-0078 https://polkadot-fellows.github.io/RFCs/approved/0078-merkleized-metadata.html'
      operationId: getTransactionMetadataBlob
      requestBody:
        $ref: '#/components/requestBodies/TransactionMetadataBlob'
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionMetadataBlob'
        '400':
          description: invalid request body or metadata V15 not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    TransactionValidityError:
      type: object
      description: The error result from an invalid transaction submitted via the `dry-run` endpoint.
      properties:
        errorType:
          type: string
          enum:
          - Unimplemented
          - VersionedConversionFailed
          description: The type of transaction error, either `Unimplemented` or `VersionedConversionFailed`.
    TransactionFeeEstimateFailure:
      type: object
      properties:
        code:
          type: number
        at:
          type: object
          properties:
            hash:
              type: string
        error:
          type: string
          description: Error description.
        transaction:
          type: string
          format: hex
        block:
          type: string
          description: Block hash of the block fee estimation was attempted at.
        cause:
          type: string
          description: Error message from the client.
        stack:
          type: string
    BlockIdentifiers:
      type: object
      properties:
        hash:
          type: string
          description: The block's hash.
          format: hex
        height:
          type: string
          description: The block's height.
          format: unsignedInteger
    TransactionDispatchError:
      type: object
      description: The reason why the dispatch call failed.
      properties:
        errorType:
          type: string
          enum:
          - Other
          - CannotLookup
          - BadOrigin
          - ModuleError
          - ConsumerRemaining
          - NoProviders
          - TooManyConsumers
          - TokenError
          - ArithmeticError
          - TransactionalError
          - Exhausted
          - Corruption
          - Unavailable
          - RootNotAllowed
          description: The type of transaction error.
    TransactionMetadataBlob:
      type: object
      properties:
        at:
          $ref: '#/components/schemas/BlockIdentifiers'
        metadataHash:
          type: string
          format: hex
          description: The 32-byte metadata hash (hex-encoded) that should be used with the CheckMetadataHash signed extension.
        metadataBlob:
          type: string
          format: hex
          description: The metadata blob (hex-encoded) containing the minimal metadata required for offline signers to decode the transaction. This is a SCALE-encoded Proof structure per RFC-0078.
        specVersion:
          type: number
          description: The chain's spec version.
        specName:
          type: string
          description: The chain's spec name.
        base58Prefix:
          type: number
          description: The chain's SS58 address prefix.
        decimals:
          type: number
          description: Number of decimals for the chain's native token.
        tokenSymbol:
          type: string
          description: Symbol for the chain's native token.
      description: Response containing the metadata blob for offline signers. The metadataBlob contains type definitions needed to decode the specific transaction, Merkle proofs verifying these types are part of the full metadata, and extra chain info.
    DryRunBody:
      type: object
      properties:
        at:
          type: string
          format: unsignedInteger
        tx:
          type: string
          format: hex
        senderAddress:
          type: string
          format: ss58
    WeightsV2:
      type: object
      properties:
        refTime:
          type: string
          description: The weight of computational time used based on some reference hardware.
        proofSize:
          type: string
          description: The weight of storage space used by proof of validity.
    TransactionMaterial:
      type: object
      properties:
        at:
          $ref: '#/components/schemas/BlockIdentifiers'
        genesisHash:
          type: string
          description: The hash of the chain's genesis block.
          format: blockHash
        chainName:
          type: string
          description: The chain's name.
        specName:
          type: string
          description: The chain's spec.
        specVersion:
          type: string
          description: The spec version. Always increased in a runtime upgrade.
        txVersion:
          type: string
          description: The transaction version. Common `txVersion` numbers indicate that the transaction encoding format and method indices are the same. Needed for decoding in an offline environment. Adding new transactions does not change `txVersion`.
        metadata:
          type: string
          description: The chain's metadata. It will only be present when the metadata query param is used.
      description: 'Note: `chainName`, `specName`, and `specVersion` are used to define a type registry with a set of signed extensions and types. For Polkadot and Kusama, `chainName` is not used in defining this registry, but in other Substrate-based chains that re-launch their network without changing the `specName`, the `chainName` would be needed to create the correct registry. Substrate Reference: - `RuntimeVersion`: https://crates.parity.io/sp_version/struct.RuntimeVersion.html - `SignedExtension`: https://crates.parity.io/sp_runtime/traits/trait.SignedExtension.html -  FRAME Support: https://crates.parity.io/frame_support/metadata/index.html'
    MetadataBlobBody:
      type: object
      properties:
        tx:
          type: string
          format: hex
          description: Full encoded extrinsic as a hex string.
        txAdditionalSigned:
          type: string
          format: hex
          description: Optional additional signed data for the extrinsic. Used together with `tx`.
        callData:
          type: string
          format: hex
          description: Call data as hex string. Use this alongside includedInExtrinsic and includedInSignedData instead of `tx`.
        includedInExtrinsic:
          type: string
          format: hex
          description: Signed extension data included in the extrinsic. Required when using callData.
        includedInSignedData:
          type: string
          format: hex
          description: Signed extension data included in the signature. Required when using callData.
        at:
          type: string
          description: Block hash or number to query at. Defaults to finalized head.
          format: unsignedInteger or $hex
      description: 'Request body for generating the metadata blob. You must provide either: (1) `tx` (full extrinsic) with optional `txAdditionalSigned`, or (2) `callData` with `includedInExtrinsic` and `includedInSignedData`.'
    TransactionFailedToSubmit:
      type: object
      properties:
        code:
          type: number
        error:
          type: string
          description: Failed to submit transaction.
        transaction:
          type: string
          format: hex
        cause:
          type: string
        stack:
          type: string
      description: Error message when the node rejects the submitted transaction.
    TransactionFailedToParse:
      type: object
      properties:
        code:
          type: number
        error:
          type: string
          description: '`Failed to parse a tx.`'
        transaction:
          type: string
          format: hex
        cause:
          type: string
        stack:
          type: string
      description: Error message when Sidecar fails to parse the transaction.
    Transaction:
      type: object
      properties:
        tx:
          type: string
          format: hex
    TransactionFeeEstimate:
      type: object
      properties:
        weight:
          $ref: '#/components/schemas/WeightsV2'
          description: Weights represented as WeightsV2 (two dimensional weights). When querying historical blocks that use WeightsV1, the weight will be returned as a weight key that points to a number represented as a string.
        class:
          type: string
          description: Extrinsic class.
          enum:
          - Normal
          - Operational
          - Mandatory
        partialFee:
          type: string
          description: Expected inclusion fee for the transaction. Note that the fee rate changes up to 30% in a 24 hour period and this will not be the exact fee.
          format: unsignedInteger
      description: 'Note: `partialFee` does not include any tips that you may add to increase a transaction''s priority. See [compute_fee](https://crates.parity.io/pallet_transaction_payment/struct.Module.html#method.compute_fee).'
    TransactionDryRun:
      type: object
      properties:
        resultType:
          type: string
          enum:
          - DispatchOutcome
          - DispatchError
          - TransactionValidityError
          description: The result will be either a `DispatchOutcome` if the transaction is valid, a `DispatchError` if the transaction failed, or a `TransactionValidityError` if the transaction is invalid.
        result:
          oneOf:
          - $ref: '#/components/schemas/TransactionDispatchOutcome'
          - $ref: '#/components/schemas/TransactionDispatchError'
          - $ref: '#/components/schemas/TransactionValidityError'
      description: "References:\n  - `PostDispatchInfo`: https://docs.rs/frame-support/38.0.0/frame_support/dispatch/struct.PostDispatchInfo.html\n  - `DispatchError`: https://docs.rs/sp-runtime/39.0.1/sp_runtime/enum.DispatchError.html\n  - `Error Type`: https://paritytech.github.io/polkadot-sdk/master/xcm_runtime_apis/dry_run/enum.Error.html"
    Error:
      type: object
      properties:
        code:
          type: number
        message:
          type: string
        stack:
          type: string
        level:
          type: string
    TransactionSuccess:
      type: object
      properties:
        hash:
          type: string
          description: The hash of the encoded transaction.
    TransactionDispatchOutcome:
      type: object
      description: The result of a valid transaction submitted via the `dry-run` endpoint.
      properties:
        actualWeight:
          type: string
          format: unsignedInteger
          description: The actual weight of the transaction.
        paysFee:
          type: string
          format: boolean
          description: Whether the transaction pays a fee.
    TransactionFailure:
      oneOf:
      - $ref: '#/components/schemas/TransactionFailedToSubmit'
      - $ref: '#/components/schemas/TransactionFailedToParse'
  requestBodies:
    TransactionDryRun:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DryRunBody'
      required: true
    Transaction:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Transaction'
      required: true
    TransactionMetadataBlob:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/MetadataBlobBody'
      required: true