Polkadot Staking API

openapi: 3.2.0
info:
  title: Polkadot Staking API
  version: '1.0'
  description: 'Operations tagged Staking across 2 of this provider''s published API definitions: subscan-swagger.yaml, substrate-api-sidecar-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://https://www.subscan.io/
- 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: Staking
paths:
  /api/scan/account/reward_slash:
    post:
      description: Returns paginated staking reward and slash records for one account, with optional category and block-range filters. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.AccountEventJson'
                          type: array
                      type: object
                  type: object
      summary: List reward and slash records
      tags:
      - Staking
      x-synonyms:
      - reward
      - slash
      - staking
      - scan
      - account
      - penalty
      - slashing
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.rewardSlashParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/daily/reward_payout:
    post:
      description: Returns reward payouts aggregated by date for global dashboard and chart-center views.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.DailyRewardPayoutJson'
                          type: array
                      type: object
                  type: object
      summary: Get daily reward payout totals
      tags:
      - Staking
      x-synonyms:
      - daily
      - reward
      - payout
      - chart
      - aggregate
      - staking
      - scan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.dailyRewardPayoutParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/daily/reward_slash:
    post:
      description: 'Returns daily reward/slash aggregates with optional account, category, and date-range filters.

        This API only supports networks with the staking frame pallet.'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.DailyRewardSlashJson'
                          type: array
                      type: object
                  type: object
      summary: Get daily reward and slash aggregates
      tags:
      - Staking
      x-synonyms:
      - daily
      - reward
      - slash
      - data
      - staking
      - scan
      - penalty
      - slashing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.dailyRewardSlashParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/era_stat:
    post:
      description: Returns paginated validator era statistics for one account. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.ValidatorStatJson'
                          type: array
                      type: object
                  type: object
      summary: List validator era statistics
      tags:
      - Staking
      x-synonyms:
      - era
      - stat
      - staking
      - scan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.eraStatParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/nominator:
    post:
      description: Returns staking details for one nominator account. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      $ref: '#/components/schemas/subscan_internal_model.NominatorDetail'
                  type: object
      summary: Get nominator details
      tags:
      - Staking
      x-synonyms:
      - nominator
      - staking
      - scan
      - delegator
      - staking participant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.nominatorParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/nominators:
    post:
      description: Returns the nominators backing the specified validator account. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.NominatorJson'
                          type: array
                      type: object
                  type: object
      summary: List nominators for a validator
      tags:
      - Staking
      x-synonyms:
      - nominators
      - staking
      - scan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.nominatorsParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/total_reward:
    post:
      description: Returns the summed staking rewards for one account, with optional block-range or date-range filters. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        sum:
                          type: number
                      type: object
                  type: object
      summary: Get staking reward totals
      tags:
      - Staking
      x-synonyms:
      - staking
      - reward
      - sum
      - scan
      - total
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.stakingRewardParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/unbonding:
    post:
      description: Returns the current unbonding schedule for one staking account. This API only supports networks with the staking frame.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      additionalProperties:
                        items:
                          $ref: '#/components/schemas/subscan_libs_substrate_derive.Unbonding'
                        type: array
                      type: object
                  type: object
      summary: List unbonding records
      tags:
      - Staking
      x-synonyms:
      - unbonding
      - staking
      - scan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.unbondingParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/validator:
    post:
      description: Returns staking details for one validator stash address. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        info:
                          $ref: '#/components/schemas/subscan_internal_model.ValidatorJson'
                      type: object
                  type: object
      summary: Get validator details
      tags:
      - Staking
      x-synonyms:
      - validator
      - staking
      - scan
      - staker
      - node operator
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.validatorParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/validator/bond_stat:
    post:
      description: Returns era-level bond statistics for one validator stash address. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.EraBondStat'
                          type: array
                      type: object
                  type: object
      summary: Get validator bond statistics
      tags:
      - Staking
      x-synonyms:
      - validator
      - bond
      - stat
      - staking
      - scan
      - staker
      - node operator
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.bondStatParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/validator/commission_history:
    post:
      description: Returns paginated commission-history records for one validator stash address. This API only supports networks with the staking frame pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.StakingCommissionHistoryJson'
                          type: array
                      type: object
                  type: object
      summary: Get validator commission history
      tags:
      - Staking
      x-synonyms:
      - validator
      - commission
      - history
      - staking
      - scan
      - staker
      - node operator
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.commissionHistoryParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/validators:
    post:
      description: Returns a paginated validator list with optional blocked and commission-range filters. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.ValidatorJson'
                          type: array
                      type: object
                  type: object
      summary: List validators
      tags:
      - Staking
      x-synonyms:
      - validators
      - staking
      - scan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.validatorsParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/voted:
    post:
      description: Returns validators voted by the specified account.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.AccountNominateList'
                          type: array
                      type: object
                  type: object
      summary: List account-voted validators
      tags:
      - Staking
      x-synonyms:
      - account-voted
      - validators
      - staking
      - scan
      - voted
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.votedParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/scan/staking/waiting:
    post:
      description: Returns validators waiting in the staking queue, with optional commission-range sorting. This API only supports networks with the staking frame or parachain-staking pallet.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.ValidatorWaiting'
                          type: array
                      type: object
                  type: object
      summary: List waiting validators
      tags:
      - Staking
      x-synonyms:
      - waiting
      - validators
      - staking
      - scan
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.waitingValidatorsParams'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /api/v2/scan/account/reward_slash:
    post:
      description: Returns paginated reward/slash records for an account with category, claim, and block-range filters.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        count:
                          type: integer
                        list:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.StakingAccountEventJson'
                          type: array
                      type: object
                  type: object
      summary: List account reward and slash records
      tags:
      - Staking
      x-synonyms:
      - account
      - reward
      - slash
      - records
      - staking
      - scan
      - wallet
      - address
      - user
      - penalty
      - slashing
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.rewardSlashV2Params'
        description: params
        required: true
    servers:
    - url: https://https://www.subscan.io/
  /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. The _Stash_ account can be either a validator or nominator account.
      operationId: getStakingSummaryByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account. Must be a _Stash_ account.
        required: true
        schema:
          format: SS58
          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
      - name: useRcBlock
        in: query
        description: When set to 'true', uses the relay chain block specified in the 'at' parameter to determine corresponding Asset Hub block(s) for retrieving staking info. Only supported for Asset Hub endpoints. Requires 'at' parameter to specify the relay chain block. When used, returns an array of response objects (one for each Asset Hub block found) or empty array if none found.
        required: false
        schema:
          type: boolean
          description: When set to 'true', uses relay chain block mode with the 'at' parameter.
      - name: useRcBlockFormat
        in: query
        description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
        required: false
        schema:
          type: string
          enum:
          - array
          - object
          description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
      - name: includeClaimedRewards
        in: query
        description: When set to `false`, the `claimedRewards` field is not included in the response.
        required: false
        schema:
          type: string
          format: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/AccountStakingInfo'
                - type: array
                  items:
                    $ref: '#/components/schemas/AccountStakingInfo'
                description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
        '400':
          description: invalid blockId supplied for at query param, or invalid parameter combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    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
  /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).


        **Asset Hub Migration Support:**

        For Asset Hub chains that have migrated staking from the relay chain, this endpoint automatically handles era query routing:

        - **Pre-migration eras**: Queries historical data from the relay chain

        - **Post-migration eras**: Queries current data from Asset Hub

        - **Cross-migration queries**: Automatically splits the era range and combines results from both chains


        **Note:** 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:
          format: SS58
          type: string
      - name: at
        in: query
        description: Block at which to query staking payouts.
        required: false
        schema:
          type: string
          description: Block height (as a non-negative integer) or hash (as a hex string).
          format: unsignedInteger or $hex
      - name: useRcBlock
        in: query
        description: When set to 'true', uses the relay chain block specified in the 'at' parameter to determine corresponding Asset Hub block(s) for retrieving staking payouts. Only supported for Asset Hub endpoints. Requires 'at' parameter to specify the relay chain block. When used, returns an array of response objects (one for each Asset Hub block found) or empty array if none found.
        required: false
        schema:
          type: boolean
          description: When set to 'true', uses relay chain block mode with the 'at' parameter.
      - name: useRcBlockFormat
        in: query
        description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
        required: false
        schema:
          type: string
          enum:
          - array
          - object
          description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
      - 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:
                oneOf:
                - $ref: '#/components/schemas/AccountStakingPayouts'
                - type: array
                  items:
                    $ref: '#/components/schemas/AccountStakingPayouts'
                description: "**Standard Mode**: Returns a single object when using standard parameters (without useRcBlock). \n\n**Relay Chain Block Mode**: Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).\n\n**Asset Hub Migration**: For both modes, when querying eras that span the Asset Hub migration boundary, the endpoint automatically fetches and combines data from both relay chain (pre-migration eras) and Asset Hub (post-migration eras). The migration handling is transparent to the user - you get complete payout information regardless of which chain originally held the data.\n"
        '400':
          description: invalid blockId supplied for at query param, or invalid parameter combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    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
  /pallets/staking/progress:
    get:
      tags:
      - Staking
      summary: Get progress on the general Staking pallet system.
      description: Returns information on the progress of key components of the staking system and estimates of future points of interest. If you are querying from Asset Hub for staking progress, this endpoint requires multi chain connections between the relay chain, and asset hub itself. Set the asset hub rpc to SAS_SUBSTRATE_URL, and add the relay chain to the SAS_SUBSTRATE_MULTI_CHAIN_URL env var. Refer to the README for the structure of the env vars. The `useRcBlock` parameter allows querying Asset Hub state using relay chain block numbers, enabling post-migration infrastructure to continue using relay chain block identifiers while accessing Asset Hub data.
      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
      - name: useRcBlock
        in: query
        description: When set to 'true', uses the relay chain block specified in the 'at' parameter to determine corresponding Asset Hub block(s) for retrieving staking progress report. Only supported for Asset Hub endpoints. Requires 'at' parameter to specify the relay chain block. When used, returns an array of response objects (one for each Asset Hub block found) or empty array if none found.
        required: false
        schema:
          type: boolean
          description: When set to 'true', uses relay chain block mode with the 'at' parameter.
      - name: useRcBlockFormat
        in: query
        description: Controls the response format when using 'useRcBlock=true'. When set to 'object', wraps the response in an object containing relay chain block info ('rcBlock') and the parachain data array ('parachainDataPerBlock'). When set to 'array' or omitted, returns the standard array format. Only valid when 'useRcBlock=true' is specified.
        required: false
        schema:
          type: string
          enum:
          - array
          - object
          description: Response format - 'array' (default) returns standard array, 'object' wraps response with rcBlock info.
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/StakingProgress'
                - type: array
                  items:
                    $ref: '#/components/schemas/StakingProgress'
                description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
        '400':
          description: invalid blockId supplied for at query param, or invalid parameter combination
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    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
    -

# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/polkadot/refs/heads/main/openapi/polkadot-staking-api-openapi.yml