openapi: 3.1.0
info:
title: Polkadot REST Account accounts 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: accounts
description: Account balance, staking, and proxy information
paths:
/v1/accounts/compare:
get:
tags:
- accounts
summary: Compare account addresses
description: Compares multiple SS58 addresses to determine if they have the same underlying public key.
operationId: get_compare
parameters:
- name: addresses
in: query
description: Comma-separated list of SS58 addresses to compare (max 30)
required: true
schema:
type: string
responses:
'200':
description: Comparison result
content:
application/json:
schema:
$ref: '#/components/schemas/AccountCompareResponse'
'400':
description: Invalid parameters
/v1/accounts/{accountId}/asset-approvals:
get:
tags:
- accounts
summary: Account asset approvals
description: Returns asset approval information for a given account, asset, and delegate.
operationId: get_asset_approvals
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: assetId
in: query
description: The asset ID to query approval for
required: true
schema:
type: string
- name: delegate
in: query
description: The delegate address with spending approval
required: true
schema:
type: string
responses:
'200':
description: Asset approval information
content:
application/json:
schema:
$ref: '#/components/schemas/AssetApprovalResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/asset-balances:
get:
tags:
- accounts
summary: Account asset balances
description: Returns asset balances for a given account on Asset Hub chains.
operationId: get_asset_balances
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: assets
in: query
description: Comma-separated list of asset IDs to query
required: false
schema:
type: string
- name: showEmpty
in: query
description: 'When true, include assets with zero balance (default: false)'
required: false
schema:
type: boolean
responses:
'200':
description: Account asset balances
content:
application/json:
schema:
$ref: '#/components/schemas/AssetBalancesResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/balance-info:
get:
tags:
- accounts
summary: Account balance info
description: Returns balance information for a given account including free, reserved, and locked balances.
operationId: get_balance_info
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: token
in: query
description: Token symbol for chains with multiple tokens
required: false
schema:
type: string
- name: denominated
in: query
description: When true, denominate balances using chain decimals
required: false
schema:
type: boolean
responses:
'200':
description: Account balance information
content:
application/json:
schema:
$ref: '#/components/schemas/BalanceInfoResponse'
'400':
description: Invalid account or block parameter
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/convert:
get:
tags:
- accounts
summary: Convert account format
description: Converts an account address between different SS58 formats and key types.
operationId: get_convert
parameters:
- name: accountId
in: path
description: SS58-encoded account address or hex public key
required: true
schema:
type: string
- name: scheme
in: query
description: 'Cryptographic scheme: ed25519, sr25519, or ecdsa (default: sr25519)'
required: false
schema:
type: string
- name: prefix
in: query
description: 'SS58 prefix number (default: 42)'
required: false
schema:
type: integer
format: int32
minimum: 0
- name: publicKey
in: query
description: If true, treat input as a public key
required: false
schema:
type: boolean
responses:
'200':
description: Converted account information
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConvertResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/foreign-asset-balances:
get:
tags:
- accounts
summary: Account foreign asset balances
description: Returns foreign asset balances for a given account on Asset Hub chains. Foreign assets use XCM MultiLocation as their identifier.
operationId: get_foreign_asset_balances
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: foreignAssets
in: query
description: List of multilocation JSON strings to filter by
required: false
schema:
type: array
items:
type: string
- name: showEmpty
in: query
description: 'When true, include assets with zero balance (default: false)'
required: false
schema:
type: boolean
responses:
'200':
description: Foreign asset balances
content:
application/json:
schema:
type: object
'400':
description: Invalid account or parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/pool-asset-approvals:
get:
tags:
- accounts
summary: Account pool asset approvals
description: Returns pool asset approval information for a given account, asset, and delegate.
operationId: get_pool_asset_approvals
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: assetId
in: query
description: The pool asset ID to query approval for
required: true
schema:
type: string
- name: delegate
in: query
description: The delegate address with spending approval
required: true
schema:
type: string
responses:
'200':
description: Pool asset approval information
content:
application/json:
schema:
$ref: '#/components/schemas/PoolAssetApprovalResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/pool-asset-balances:
get:
tags:
- accounts
summary: Account pool asset balances
description: Returns pool asset balances for a given account.
operationId: get_pool_asset_balances
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: assets
in: query
description: Comma-separated list of pool asset IDs to query
required: false
schema:
type: string
- name: showEmpty
in: query
description: 'When true, include assets with zero balance (default: false)'
required: false
schema:
type: boolean
responses:
'200':
description: Pool asset balances
content:
application/json:
schema:
$ref: '#/components/schemas/PoolAssetBalancesResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/proxy-info:
get:
tags:
- accounts
summary: Account proxy info
description: Returns proxy information for a given account including delegated proxies and their types.
operationId: get_proxy_info
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
responses:
'200':
description: Proxy information
content:
application/json:
schema:
$ref: '#/components/schemas/ProxyInfoResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/staking-info:
get:
tags:
- accounts
summary: Account staking info
description: Returns staking information for a given stash account including bonded amount, controller, and nominations.
operationId: get_staking_info
parameters:
- name: accountId
in: path
description: SS58-encoded stash account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: includeClaimedRewards
in: query
description: When true, include claimed rewards in the response
required: false
schema:
type: boolean
responses:
'200':
description: Staking information
content:
application/json:
schema:
$ref: '#/components/schemas/StakingInfoResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/staking-payouts:
get:
tags:
- accounts
summary: Account staking payouts
description: Returns staking payout history for a given account including era rewards and claimed status.
operationId: get_staking_payouts
parameters:
- name: accountId
in: path
description: SS58-encoded stash account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: depth
in: query
description: 'Number of eras to query (default: 1)'
required: false
schema:
type: string
- name: era
in: query
description: 'The era to query at (default: active_era - 1)'
required: false
schema:
type: string
- name: unclaimedOnly
in: query
description: 'Only show unclaimed rewards (default: true)'
required: false
schema:
type: boolean
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
responses:
'200':
description: Staking payout information
content:
application/json:
schema:
$ref: '#/components/schemas/StakingPayoutsResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/v1/accounts/{accountId}/validate:
get:
tags:
- accounts
summary: Validate account address
description: Validates an SS58-encoded account address and returns details about its format.
operationId: get_validate
parameters:
- name: accountId
in: path
description: SS58-encoded account address to validate
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number (accepted for API consistency)
required: false
schema:
type: string
responses:
'200':
description: Validation result
content:
application/json:
schema:
$ref: '#/components/schemas/AccountValidateResponse'
/v1/accounts/{accountId}/vesting-info:
get:
tags:
- accounts
summary: Account vesting info
description: Returns vesting information for a given account including vesting schedules and locked amounts.
operationId: get_vesting_info
parameters:
- name: accountId
in: path
description: SS58-encoded account address
required: true
schema:
type: string
- name: at
in: query
description: Block hash or number to query at
required: false
schema:
type: string
- name: useRcBlock
in: query
description: Treat 'at' as relay chain block identifier
required: false
schema:
type: boolean
- name: includeClaimable
in: query
description: When true, calculate vested amounts
required: false
schema:
type: boolean
responses:
'200':
description: Vesting information
content:
application/json:
schema:
$ref: '#/components/schemas/VestingInfoResponse'
'400':
description: Invalid parameters
'500':
description: Internal server error
'503':
description: Service unavailable
/accounts/{accountId}/asset-balances:
get:
tags:
- accounts
summary: Get an array of asset-balances for an account.
description: Returns information about an account's asset-balances. This is specific to the assets pallet for parachains. If no `assets` query parameter is provided, all asset-balances for the given account will be returned.
operationId: getAssetBalances
parameters:
- name: accountId
in: path
description: SS58 address of the account.
required: true
schema:
type: string
format: SS58
- name: at
in: query
description: Block at which to query asset-balance info for the specified account.
required: false
schema:
type: string
description: Block height (as a positive 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). Only supported for Asset Hub endpoints. 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: assets
in: query
description: An array of AssetId's to be queried. If not supplied, defaults to providing all asset balances associated with the `accountId` will be returned. The array query param format follows Express 4.x API. ex:`?assets[]=1&assets[]=2&assets[]=3`.
required: false
schema:
type: array
items:
type: string
description: An array of assetId numbers represented as strings
format: Array of unsignedInteger's
responses:
'200':
description: successfull operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AccountAssetsBalances'
- type: array
items:
$ref: '#/components/schemas/AccountAssetsBalances'
description: Returns a single object when using 'at' parameter or no query params. 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 Address, invalid blockId supplied for at query param, or invalid parameter combination
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/accounts/{accountId}/asset-approvals:
get:
tags:
- accounts
summary: Get an asset approval for an account.
description: Returns information about an account's asset approval transaction. It is required to pass in a delegate and an assetId as query parameters.
operationId: getAssetApprovals
parameters:
- name: accountId
in: path
description: SS58 address of the account.
required: true
schema:
type: string
format: SS58
- name: at
in: query
description: Block at which to query asset approval 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
- 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). Only supported for Asset Hub endpoints. 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: assetId
in: query
description: The `assetId` associated with the asset-approval.
required: true
schema:
type: string
description: An assetId represented as an unsignedInteger.
format: unsignedInteger
- name: delegate
in: query
description: The delegate's `accountId` associated with an asset-approval.
required: true
schema:
type: string
format: SS58
responses:
'200':
description: successfull operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AccountAssetsApproval'
- type: array
items:
$ref: '#/components/schemas/AccountAssetsApproval'
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 Address, invalid blockId supplied for at query param, or invalid parameter combination
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/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: getAccountBalanceInfo
parameters:
- name: accountId
in: path
description: SS58 address of the account.
required: true
schema:
type: string
format: SS58
- 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
- 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 balance 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: token
in: query
description: 'Token to query the balance of. If not specified it will query the chains native token (e.g. DOT for Polkadot). Note: this is only relevant for chains that support multiple tokens through the ORML tokens pallet.'
required: false
schema:
type: string
description: Token symbol
- name: denominated
in: query
description: When set to `true` it will denominate any balance's given atomic value using the chains given decimal value.
required: false
schema:
type: boolean
default: false
responses:
'200':
description: successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/AccountBalanceInfo'
- type: array
items:
$ref: '#/components/schemas/AccountBalanceInfo'
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 Address, 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}/convert:
get:
tags:
- accounts
summary: Convert a given AccountId to an SS58 address.
description: Returns the SS58 prefix, the network address format, the SS58 address, and the AccountId that was given as input parameter, the scheme that was used and if it is a public key or not (boolean).
operationId: accountConvert
parameters:
- name: accountId
in: path
description: AccountId or Public Key (hex).
required: true
schema:
format: AccountId or Hex
type: string
- name: scheme
in: query
description: The cryptographic scheme to be used in order to convert the AccountId to an SS58 address. It can take one of three values [sr25519, ed25519, ecdsa]. The default scheme that is used is `sr25519` (if it is not set in the query parameter).
required: false
schema:
type: string
format: string
default: sr25519
- name: prefix
in: query
description: The address prefix which can be one of the values found in the SS58-registry.
required: false
schema:
type: string
format: number
default: 42
- name: publicKey
in: query
description: Defines if the given value in the path parameter is a Public Key (hex) or not (hence AccountId).
required: false
schema:
type: string
format: boolean
default: true
responses:
'200':
description: successfully converted the AccountId and retrieved the address info.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountConvert'
'400':
description: Invalid AccountId
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: AccountId not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/accounts/{accountId}/pool-asset-balances:
get:
tags:
- accounts
summary: Get an array of pool-asset-balances for an account.
description: Returns information about an account's pool-asset-balances. This is specific to the pool assets pallet for parachains. If no `assets` query parameter is provided, all pool-asset-balances for the given account will be returned.
operationId: getPoolAssetBalances
parameters:
- name: accountId
in: path
description: SS58 address of the account.
required: true
schema:
type: string
format: SS58
- name: at
in: query
description: Block at which to query pool-asset-balance info for the specified account.
required: false
schema:
type: string
description: Block height (as a positive 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 pool-asset-balance 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: assets
in: query
description: An arra
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/polkadot/refs/heads/main/openapi/polkadot-accounts-api-openapi.yml