openapi: 3.1.0
info:
title: Polkadot REST Account Staking API
description: High-performance Rust REST API for Substrate/Polkadot blockchain data. Drop-in replacement for substrate-api-sidecar.
contact:
url: https://github.com/paritytech/polkadot-rest-api
license:
name: GPL-3.0-or-later
version: 0.1.3
servers:
- url: http://localhost:8080/v1
description: Localhost
tags:
- name: Staking
paths:
/api/scan/account/reward_slash:
post:
consumes:
- application/json
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.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.rewardSlashParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/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
/api/scan/daily/reward_payout:
post:
consumes:
- application/json
description: Returns reward payouts aggregated by date for global dashboard and chart-center views.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.dailyRewardPayoutParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/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
/api/scan/daily/reward_slash:
post:
consumes:
- application/json
description: 'Returns daily reward/slash aggregates with optional account, category, and date-range filters.
This API only supports networks with the staking frame pallet.'
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.dailyRewardSlashParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/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
/api/scan/staking/era_stat:
post:
consumes:
- application/json
description: Returns paginated validator era statistics for one account. This API only supports networks with the staking frame or parachain-staking pallet.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.eraStatParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/subscan_internal_model.ValidatorStatJson'
type: array
type: object
type: object
summary: List validator era statistics
tags:
- Staking
x-synonyms:
- era
- stat
- staking
- scan
/api/scan/staking/nominator:
post:
consumes:
- application/json
description: Returns staking details for one nominator account. This API only supports networks with the staking frame or parachain-staking pallet.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.nominatorParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
$ref: '#/definitions/subscan_internal_model.NominatorDetail'
type: object
summary: Get nominator details
tags:
- Staking
x-synonyms:
- nominator
- staking
- scan
- delegator
- staking participant
/api/scan/staking/nominators:
post:
consumes:
- application/json
description: Returns the nominators backing the specified validator account. This API only supports networks with the staking frame or parachain-staking pallet.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.nominatorsParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/subscan_internal_model.NominatorJson'
type: array
type: object
type: object
summary: List nominators for a validator
tags:
- Staking
x-synonyms:
- nominators
- staking
- scan
/api/scan/staking/total_reward:
post:
consumes:
- application/json
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.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.stakingRewardParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/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
/api/scan/staking/unbonding:
post:
consumes:
- application/json
description: Returns the current unbonding schedule for one staking account. This API only supports networks with the staking frame.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.unbondingParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
additionalProperties:
items:
$ref: '#/definitions/subscan_libs_substrate_derive.Unbonding'
type: array
type: object
type: object
summary: List unbonding records
tags:
- Staking
x-synonyms:
- unbonding
- staking
- scan
/api/scan/staking/validator:
post:
consumes:
- application/json
description: Returns staking details for one validator stash address. This API only supports networks with the staking frame or parachain-staking pallet.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.validatorParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
info:
$ref: '#/definitions/subscan_internal_model.ValidatorJson'
type: object
type: object
summary: Get validator details
tags:
- Staking
x-synonyms:
- validator
- staking
- scan
- staker
- node operator
/api/scan/staking/validator/bond_stat:
post:
consumes:
- application/json
description: Returns era-level bond statistics for one validator stash address. This API only supports networks with the staking frame or parachain-staking pallet.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.bondStatParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
list:
items:
$ref: '#/definitions/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
/api/scan/staking/validator/commission_history:
post:
consumes:
- application/json
description: Returns paginated commission-history records for one validator stash address. This API only supports networks with the staking frame pallet.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.commissionHistoryParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/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
/api/scan/staking/validators:
post:
consumes:
- application/json
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.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.validatorsParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/subscan_internal_model.ValidatorJson'
type: array
type: object
type: object
summary: List validators
tags:
- Staking
x-synonyms:
- validators
- staking
- scan
/api/scan/staking/voted:
post:
consumes:
- application/json
description: Returns validators voted by the specified account.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.votedParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
list:
items:
$ref: '#/definitions/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
/api/scan/staking/waiting:
post:
consumes:
- application/json
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.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.waitingValidatorsParams'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/subscan_internal_model.ValidatorWaiting'
type: array
type: object
type: object
summary: List waiting validators
tags:
- Staking
x-synonyms:
- waiting
- validators
- staking
- scan
/api/v2/scan/account/reward_slash:
post:
consumes:
- application/json
description: Returns paginated reward/slash records for an account with category, claim, and block-range filters.
parameters:
- description: params
in: body
name: params
required: true
schema:
$ref: '#/definitions/internal_server_http.rewardSlashV2Params'
produces:
- application/json
responses:
'200':
description: OK
schema:
allOf:
- $ref: '#/definitions/internal_server_http.J'
- properties:
data:
properties:
count:
type: integer
list:
items:
$ref: '#/definitions/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
/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'
/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'
/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'
/pallets/staking/validators:
get:
tags:
- Staking
summary: Get all validators (active/waiting) of a specific chain.
description: Returns a list of all validators addresses and their corresponding status which can be either active or waiting. For declared validators, it also includes their commission rate and nomination blocking status. It will also return a list of active validators that will not be part of the next era for staking. They will be under the key "validatorsToBeChilled". It's important to note, that addresses can be present in both the "validators" key, and "validatorsToBeChilled". Commission and blocked properties are not present for active validators that have been chilled.
operationId: getStakingValidators
parameters:
- name: at
in: query
description: Block at which to retrieve the list of validators.
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 validators. 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:
$ref: '#/components/schemas/StakingValidators'
'400':
description: invalid blockId supplied for at query param, or invalid parameter combination
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Nominations:
type: object
properties:
targets:
type: array
items:
type: string
description: The targets of the nomination.
submittedIn:
type: string
format: unsignedInteger
description: The era the nominations were submitted. (Except for initial nominations which are considered submitted at era 0.)
suppressed:
type: boolean
description: Whether the nominations have been suppressed.
Error:
type: object
properties:
code:
type: number
message:
type: string
stack:
type: string
level:
type: string
UnappliedSlash:
type: o
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/polkadot/refs/heads/main/openapi/polkadot-staking-api-openapi.yml