openapi-proposal.yaml

openapi: 3.0.0
info:
  title: Substrate API Sidecar [V1 Proposal]
  description: Substrate API Sidecar is a REST service that makes it easier to
    interact with blockchain nodes built using Substrate's FRAME framework.
  contact:
    url: https://github.com/paritytech/substrate-api-sidecar/issues/new
  license:
    name: Apache License Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
  version: 1.0.0-oas3
tags:
- name: accounts
- name: blocks
- name: node
  description: node connected to sidecar
- name: pallets
  description: pallets employed in the runtime
- name: runtime
- name: transaction
paths:
  /accounts/{accountId}/balance-info:
    get:
      tags:
      - accounts
      summary: Get balance information for an account.
      description: Returns information about an account's balance.
        Replaces `/balance/{address}` from versions < v1.0.0.
      operationId: getBalanceSummaryByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account.
        required: true
        schema:
          type: string
          pattern: '^[1-9A-HJ-NP-Za-km-z]{8,64}$'
      - name: at
        in: query
        description: Block at which to query balance info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block height (as a non-negative integer) or hash
            (as a hex string).
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalanceInfo'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/staking-info:
    get:
      tags:
      - staking
      summary: Get staking information for a _Stash_ account.
      description: Returns information about a _Stash_ account's staking activity.
        Replaces `/staking/{address}` from versions < v1.0.0.
      operationId: getStakingSummaryByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account. Must be a _Stash_ account.
        required: true
        schema:
          pattern: '^[1-9A-HJ-NP-Za-km-z]{8,64}$'
          type: string
      - name: at
        in: query
        description: Block at which to query the staking info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStakingInfo'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/staking-payouts:
    get:
      tags:
      - staking
      summary: Get payout information for a _Stash_ account.
      description: Returns payout information for the last specified eras. If
        specifying both the depth and era query params, this endpoint will
        return information for (era - depth) through era. (i.e. if depth=5 and
        era=20 information will be returned for eras 16 through 20). N.B. You
        cannot query eras less then `current_era - HISTORY_DEPTH`. N.B. The 
        `nominator*` fields correspond to the address being queried, even if it
        is a validator's _Stash_ address. This is because a validator is technically
        nominating itself.
      operationId: getStakingPayoutsByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account. Must be a _Stash_ account.
        required: true
        schema:
          pattern: '^[1-9A-HJ-NP-Za-km-z]{8,64}$'
          type: string
      - name: depth
        in: query
        description: The number of eras to query for payouts of. Must be less
          than or equal to `HISTORY_DEPTH`. In cases where `era - (depth -1)` is 
          less than 0, the first era queried will be 0.
        required: false
        schema:
          type: string
          format: unsignedInteger
          default: 1
      - name: era
        in: query
        description: The era to query at.
        required: false
        schema:
          type: string
          format: unsignedInteger
          default: '`active_era - 1`'
      - name: unclaimedOnly
        in: query
        description: Only return unclaimed rewards.
        required: false
        schema:
          type: string
          format: boolean
          default: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStakingPayouts'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/vesting-info:
    get:
      tags:
      - accounts
      summary: Get vesting information for an account.
      description: Returns the vesting schedule for an account.
        Replaces `/vesting/{address}` from versions < v1.0.0.
      operationId: getVestingSummaryByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account.
        required: true
        schema:
          pattern: '^[1-9A-HJ-NP-Za-km-z]{8,64}$'
          type: string
      - name: at
        in: query
        description: Block at which to query the vesting info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountVestingInfo'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blocks/{blockId}:
    get:
      tags:
      - blocks
      summary: Get a block by its height or hash.
      description: Returns a single block. BlockId can either be a block hash or a
        block height. Replaces `/block/{number}` from versions < v1.0.0.
      operationId: getBlockById
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          pattern: 'a-km-zA-HJ-NP-Z1-9{8,64}'
          type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        "400":
          description: invalid Block identifier supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blocks/head:
    get:
      tags:
      - blocks
      summary: Get the most recently finalized block.
      description: Returns the most recently finalized block
      operationId: getHeadBlock
      parameters:
      - name: finalized
        in: query
        description: Boolean representing whether or not to get the finalized head.
          If it is not set the value defaults to true. When set to false it will attempt
          to get the newest known block, which may not be finalized. Replaces `/block`
          from versions < v1.0.0.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
  /node/network:
    get:
      tags:
      - node
      summary: Get information about the Substrate node's activity in the peer-to-peer network.
      description: Returns network related information of the node.
      operationId: getNodeNetworking
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeNetwork'
  /node/transaction-pool:
    get:
      tags:
      - node
      summary: Get pending extrinsics from the Substrate node.
      description: Returns the extrinsics that the node knows of that have not
        been included in a block.
      operationId: getNodeTransactionPool
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPool'
  /node/version:
    get:
      tags:
      - node
      summary: Get information about the Substrates node's implementation and versioning.
      description: Returns versioning information of the node.
      operationId: getNodeVersion
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeVersion'
  /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 practice submission of a transaction.
      operationId: dryrunTransaction
      requestBody:
        $ref: '#/components/requestBodies/Transaction'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDryRun'
        "500":
          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. Replaces `/tx/fee-estimate` from versions < v1.0.0.
      operationId: feeEstimateTransaction
      requestBody:
        $ref: '#/components/requestBodies/Transaction'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFeeEstimate'
        "500":
          description: fee estimation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFeeEstimateFailure'
  /transaction/material:
    get:
      tags:
      - transaction
      summary: Get the baseline material to construct a transaction.
      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
      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'
  /pallets/staking/progress:
    get:
      tags:
      - staking
      summary: Get a progress report on the chain's staking system.
      description: Returns information on the progress of key components of the
        staking system and estimates of future points of interest. Replaces
        `/staking-info` from versions < v1.0.0.
      operationId: getStakingProgress
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve a staking progress report.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingProgress'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets:
    get:
      tags:
      - pallets
      summary: Get a list of pallets used in the runtime.
      description: Returns an array of metadata for pallets that are used in the
        runtime. Can use `only-names` query param to just return an array of
        pallet names.
      parameters:
      - name: only-names
        in: query
        description: Only return the names of pallets.
        required: false
        schema:
          type: boolean
      - name: at
        in: query
        description: Block at which to retrieve a list of the runtime's pallets.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsResponses'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/constants:
    get:
      tags:
      - pallets
      summary: Get a list of constants for a pallet.
      description: Returns a list of metadata for constants of the pallet specified
        by palletId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to query the constant of.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve the list of exposed pallet
          constants.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsConstantsResponse'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find pallet with with palletId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/constants/{constantId}:
    get:
      tags:
      - pallets
      summary: Get the value of a constant.
      description: Returns the value stored under the constantId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to query the constant of.
        required: true
        schema:
          type: string
      - name: constantId
        in: path
        description: Id of the constant to query for.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to query the constant at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsConstantValue'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find resource with with id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/dispatchables:
    get:
      tags:
      - pallets
      summary: Get a list of dispatchables for a pallet.
      description: Returns a list of the dispatchables of the specified palletId
         and the associated metadata of each.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to get the metadata of its dispatchables.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve a list of the pallet's
          dispatchables at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsDispatchablesResponse'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find pallet with with palletId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/dispatchables/{dispatchableId}:
    get:
      tags:
      - pallets
      summary: Get the metadata of a dispatchable.
      description: Returns the metadata of a dispatchable with dispatchableId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to get the dispatchable of.
        required: true
        schema:
          type: string
      - name: dispatchableId
        in: path
        description: Index of the dispatchable in the pallet's dispatchable array.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve the dispatchable at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsDispatchableResponse'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find resource with with id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/errors:
    get:
      tags:
      - pallets
      summary: Get a list of the errors for a pallet.
      description: Returns a list of metadata for errors of the specified palletId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to get the metadata of its errors.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve a list of the pallet's
          errors at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsErrorsResponse'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find pallet with palletId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/errors/{errorId}:
    get:
      tags:
      - pallets
      summary: Get the metadata of an error.
      description: Returns the metadata of an error with errorId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to the error of.
        required: true
        schema:
          type: string
      - name: errorId
        in: path
        description: Index of the error in the pallet's errors array.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve the error at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsErrorResponse'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find resource with id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/events:
    get:
      tags:
      - pallets
      summary: Get a list of events for a pallet.
      description: Returns a list of metadata for events of the specified palletId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to get the metadata of its events.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve a list of the pallet's events at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsEventsResponse'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find pallet with palletId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/events/{eventId}:
    get:
      tags:
      - pallets
      summary: Get the metadata of an event.
      description: Returns the metadata of an event with eventId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to the event of.
        required: true
        schema:
          type: string
      - name: eventId
        in: path
        description: Index of the event in the pallet's events array.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve the event at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsEventResponse'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find resource with id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/storage:
    get:
      tags:
      - pallets
      summary: Get a list of storage items for a pallet.
      description: Returns a list of storage item metadata for storage items of the
        specified palletId.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to query the storage of.
        required: true
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to retrieve a list of
          the pallet's storage items.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                description: Array of storageItemIds.
                items:
                  $ref: '#/components/schemas/PalletStorageItem'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find pallet with palletId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/storage/{storageItemId}:
    get:
      tags:
      - pallets
      summary: Get the value of a storage item.
      description: Returns the value stored under the storageItemId. If it is a
        map, query param key1 is required. If the storage item is double map
        query params key1 and key2 are required.
      parameters:
      - name: palletId
        in: path
        description: Name or index of the pallet to query the storage of.
        required: true
        schema:
          type: string
      - name: storageItemId
        in: path
        description: Id of the storage item to query for.
        required: true
        schema:
          type: string
      - name: key1
        in: query
        description: Key for a map, or first key for a double map. Required for querying
          a map.
        required: false
        schema:
          type: string
      - name: key2
        in: query
        description: Second key for a double map. Required for querying a double map.
        required: false
        schema:
          type: string
      - name: at
        in: query
        description: Block at which to query the storage item at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                description: Successful query response type is dependent on the storage
                  item value.
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find resource with with id
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /runtime/metadata:
    get:
      tags:
      - runtime
      summary: Get the runtime metadata in decoded, JSON form.
      description: Returns the runtime metadata as a JSON object.
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve the metadata at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                description: Response is dependent on the runtime metadata contents.
  /runtime/code:
    get:
      tags:
      - runtime
      summary: Get the runtime wasm blob.
      description: Returns the runtime Wasm blob in hex format.
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve the runtime wasm blob at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeCode'
  /runtime/spec:
    get:
      tags:
      - runtime
      summary: Get version information of the Substrate runtime.
      description: Returns version information related to the runtime.
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve runtime version information at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.