Polkadot Account API

openapi: 3.2.0
info:
  contact:
    email: bruce.sun@itering.io
    name: API Support
    url: http://www.swagger.io/support
  description: This is a subscan API server.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: http://swagger.io/terms/
  title: Subscan Account API
  version: '1.0'
servers:
- url: https://https://www.subscan.io/
tags:
- name: Account
paths:
  /api/scan/account/assets_changed:
    post:
      description: Returns paginated change history for account asset balances. This endpoint currently supports assets and foreign-assets style tokens.
      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.AssetChangedHistoryJson'
                          type: array
                      type: object
                  type: object
      summary: List account asset-change history
      tags:
      - Account
      x-synonyms:
      - account
      - assets
      - changed
      - history
      - scan
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.assetsChangedParams'
        description: params
        required: true
  /api/scan/account/balance_history:
    post:
      description: Returns historical balance snapshots for an account and token. Polkadot, Kusama, and Westend support block-level history, while other supported networks return daily snapshots.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        history:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.SnapshotBalanceHistoryJson'
                          type: array
                        status:
                          $ref: '#/components/schemas/subscan_internal_model.AccountBalanceHistoryStatus'
                      type: object
                  type: object
      summary: Get account balance history
      tags:
      - Account
      x-synonyms:
      - account
      - balance
      - history
      - scan
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountBalanceParams'
        description: params
        required: true
  /api/scan/account/tokens:
    post:
      description: Returns token holdings for one account, including the native token, built-in assets, and supported EVM tokens such as ERC-20 and ERC-721.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      $ref: '#/components/schemas/subscan_internal_service_scan.AccountTokenJson'
                  type: object
      summary: List token balances for an account
      tags:
      - Account
      x-synonyms:
      - account
      - token
      - scan
      - tokens
      - wallet
      - address
      - user
      - asset
      - coin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountTokenParams'
        description: params
        required: true
  /api/scan/accounts/merkle:
    post:
      description: Returns the account merkle list with optional tag and balance filters. This endpoint is available only on Polkadot and Asset Hub Polkadot.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      items:
                        $ref: '#/components/schemas/subscan_internal_model.AccountMerkleJson'
                      type: array
                  type: object
      summary: List account merkle records
      tags:
      - Account
      x-synonyms:
      - account
      - merkle
      - scan
      - accounts
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountsMerkleParams'
        description: params
        required: true
  /api/scan/accounts/statistics:
    post:
      description: Returns aggregated account statistics, including either asset-distribution counts or account-role counts depending on the requested type.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      items:
                        $ref: '#/components/schemas/subscan_internal_model.AccountRoleCountJson'
                      type: array
                  type: object
      summary: Get account statistics
      tags:
      - Account
      x-synonyms:
      - account
      - statistics
      - scan
      - accounts
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountsStatisticsParams'
        description: params
        required: true
  /api/scan/search/identity:
    post:
      description: Performs a fuzzy search on account identity display names and returns matching identities with any related sub-accounts.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        identity:
                          items:
                            $ref: '#/components/schemas/subscan_internal_service_scan.IdentifierWithSubAccount'
                          type: array
                      type: object
                  type: object
      summary: Search accounts by identity display name
      tags:
      - Account
      x-synonyms:
      - search
      - identity
      - account
      - scan
      - lookup
      - find
      - query
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.searchByIdentityParams'
        description: params
        required: true
  /api/scan/token/holders:
    post:
      description: Returns a paginated holder list for the selected token or unique ID, with optional balance filters and ordering.
      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.AccountSampleJson'
                          type: array
                      type: object
                  type: object
      summary: List token holders
      tags:
      - Account
      x-synonyms:
      - token
      - holders
      - account
      - scan
      - asset
      - coin
      - owners
      - token holders
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.tokenHoldersParams'
        description: params
        required: true
  /api/v2/scan/account/tokens:
    post:
      description: Returns paginated token holdings for one account address, including the native token, built-in assets, and EVM tokens such as ERC-20 and ERC-721 when available on the current network. Use token_type to narrow the token source or class, order_field and order to sort by token, balance, price, or supply, and page/row for pagination (max row 100). This is the primary endpoint for wallet token balances, account asset holdings, and token portfolio lookups.
      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.TokenJsonV2Json'
                          type: array
                        module:
                          items:
                            type: string
                          type: array
                      type: object
                  type: object
      summary: List token balances for an account (v2)
      tags:
      - Account
      x-synonyms:
      - account
      - token
      - tokens
      - wallet
      - address
      - asset
      - coin
      - balance
      - balances
      - token balance
      - token balances
      - holdings
      - portfolio
      - wallet assets
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountTokenV2Params'
        description: Account address plus optional token type, sorting, and pagination controls.
        required: true
  /api/v2/scan/accounts:
    post:
      description: Returns a paginated account list with optional balance filters, role filters, explicit address selection, and ordering.
      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.AccountSampleJson'
                          type: array
                      type: object
                  type: object
      summary: List accounts
      tags:
      - Account
      x-synonyms:
      - accounts
      - account
      - scan
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountsParams'
        description: params
        required: true
  /api/v2/scan/accounts/net_assets:
    post:
      description: '**PRO API**: Requires a [Pro plan](http://pro.subscan.io/) Returns a paginated account-level net-asset leaderboard. Native-only networks read directly from chain_accounts; other networks use pre-aggregated priced fungible-token snapshots.'
      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.AccountNetAssetJson'
                          type: array
                      type: object
                  type: object
      summary: '[PRO] List accounts by net assets'
      tags:
      - Account
      x-synonyms:
      - accounts
      - net assets
      - wealth
      - leaderboard
      - wallet
      - token value
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountNetAssetsParams'
        description: params
        required: true
  /api/v2/scan/search:
    post:
      description: Resolves one account from a Substrate address, EVM address, or SS58 account index and returns normalized account details. If the account is not cached, the service may query on-chain balance data to create or refresh the account before responding. Use this endpoint for account lookup, wallet profile lookup, or resolving an address before calling balance- or token-related APIs.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/internal_server_http.J'
                - properties:
                    data:
                      properties:
                        account:
                          $ref: '#/components/schemas/subscan_internal_model.AccountJsonV1'
                      type: object
                  type: object
      summary: Get account information by address or account index
      tags:
      - Account
      x-synonyms:
      - account
      - address
      - wallet
      - lookup
      - find
      - query
      - resolve address
      - wallet profile
      - account profile
      - evm address
      - account index
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.accountInfoParams'
        description: Account lookup input. Accepts a Substrate address, EVM address, or account index.
        required: true
  /api/v2/scan/transfers:
    post:
      description: Returns paginated transfer records with account, token, amount, 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
                        total:
                          $ref: '#/components/schemas/subscan_internal_model.TransferHistoryTokensTotal'
                        transfers:
                          items:
                            $ref: '#/components/schemas/subscan_internal_model.TransferHistoryJson'
                          type: array
                      type: object
                  type: object
      summary: List transfers
      tags:
      - Account
      x-synonyms:
      - transfers
      - account
      - scan
      - wallet
      - address
      - user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/internal_server_http.transfersParams'
        description: params
        required: true
components:
  schemas:
    subscan_internal_model.TransferHistoryTokensTotal:
      additionalProperties:
        $ref: '#/components/schemas/subscan_internal_model.TransferHistoryTotal'
      type: object
    subscan_internal_model.LinearVestingSchedule:
      properties:
        balance:
          type: string
        cliff:
          type: integer
        vesting:
          type: integer
      type: object
    subscan_internal_model.TokenJson:
      properties:
        alias_name:
          type: string
        asset_id:
          type: string
        balance:
          type: string
        bonded:
          type: string
        contract:
          type: string
        conviction_lock:
          type: string
        currency_id:
          type: string
        decimals:
          type: integer
        democracy_lock:
          type: string
        election_lock:
          type: string
        exchange_ratio:
          type: string
        label:
          type: string
        lock:
          type: string
        lp_bonded_token_combination:
          items:
            $ref: '#/components/schemas/subscan_internal_model.LpTokenInfo'
          type: array
        lp_token_combination:
          items:
            $ref: '#/components/schemas/subscan_internal_model.LpTokenInfo'
          type: array
        media:
          items:
            $ref: '#/components/schemas/subscan_internal_model.MetadataMedia'
          type: array
        multi_location: {}
        price:
          type: string
        reserved:
          type: string
        symbol:
          type: string
        token_image:
          description: TokenId        *decimal.Decimal `json:"token_id,omitempty"`
          type: string
        unbonding:
          type: string
        unclaimed:
          type: string
        unique_id:
          type: string
        vesting:
          $ref: '#/components/schemas/subscan_internal_model.VestingJson'
      type: object
    subscan_internal_model.RoleRegistrarJson:
      properties:
        registrar_fee:
          type: string
        registrar_index:
          type: integer
      type: object
    internal_server_http.tokenHoldersParams:
      properties:
        included_zero_balance:
          type: boolean
        max_balance:
          type: string
        min_balance:
          type: string
        order:
          enum:
          - desc
          - asc
          type: string
        order_field:
          enum:
          - balance
          - locked
          type: string
        page:
          description: Page number, starting from 0
          example: 0
          minimum: 0
          type: integer
        row:
          description: Data size per page
          example: 10
          maximum: 100
          minimum: 1
          type: integer
        token:
          type: string
        unique_id:
          type: string
      type: object
    subscan_internal_model.AccountDerive:
      properties:
        balance:
          type: string
        bonded:
          type: string
        id:
          type: integer
        locked:
          type: string
        reserved:
          type: string
        token:
          type: string
        unbonding:
          type: string
        unique_id:
          type: string
      type: object
    internal_server_http.assetsChangedParams:
      properties:
        address:
          type: string
        asset_unique_id:
          type: string
        page:
          example: 0
          minimum: 0
          type: integer
        row:
          example: 10
          maximum: 100
          minimum: 1
          type: integer
      required:
      - address
      type: object
    subscan_internal_model.MerkleTag:
      properties:
        address_type:
          type: string
        tag_name:
          type: string
        tag_subtype:
          type: string
        tag_type:
          type: string
      type: object
    internal_server_http.accountsParams:
      properties:
        account:
          description: Get the account data associated with different roles of the account,Only proxy,proxies,multisig,multisigMember,convictionDelegate,convictionDelegated,democracyDelegate,democracyDelegated role is valid
          type: string
        address:
          description: Get the specified account data
          items:
            type: string
          maxItems: 100
          minItems: 1
          type: array
        filter:
          enum:
          - validator
          - nominator
          - councilMember
          - techcomm
          - registrar
          - system
          - module
          - evm
          - erc20
          - erc721
          - erc1155
          - contract
          - nominationPool
          - proxies
          - proxy
          - multisig
          - multisigMember
          - fellowship
          - onChainIdentity
          - convictionDelegate
          - convictionDelegated
          - democracyDelegate
          - democracyDelegated
          - multiTokensHolder
          - tanssiOperator
          - activeBlockAuthor
          - collator
          type: string
        max_balance:
          type: string
        min_balance:
          type: string
        order:
          enum:
          - desc
          - asc
          type: string
        order_field:
          enum:
          - balance
          - locked
          - ring_lock
          - nft_amount
          - evm_txn_count
          type: string
        page:
          description: Page number, starting from 0
          example: 0
          minimum: 0
          type: integer
        row:
          description: Data size per page
          example: 10
          maximum: 100
          minimum: 1
          type: integer
      type: object
    subscan_internal_model.TransferHistoryTotal:
      properties:
        received:
          type: string
        sent:
          type: string
        total:
          type: string
      type: object
    internal_server_http.J:
      properties:
        code:
          example: 0
          type: integer
        data: {}
        generated_at:
          example: 1699600641
          type: integer
        message:
          example: Success
          type: string
      type: object
    subscan_internal_model.TokenJsonV2Json:
      properties:
        alias_name:
          type: string
        asset_id:
          type: string
        balance:
          type: string
        bonded:
          type: string
        category:
          type: string
        contract:
          type: string
        conviction_lock:
          type: string
        currency_id:
          type: string
        decimals:
          type: integer
        democracy_lock:
          type: string
        election_lock:
          type: string
        exchange_ratio:
          type: string
        label:
          type: string
        lock:
          type: string
        lp_bonded_token_combination:
          items:
            $ref: '#/components/schemas/subscan_internal_model.LpTokenInfo'
          type: array
        lp_token_combination:
          items:
            $ref: '#/components/schemas/subscan_internal_model.LpTokenInfo'
          type: array
        media:
          items:
            $ref: '#/components/schemas/subscan_internal_model.MetadataMedia'
          type: array
        multi_location: {}
        price:
          type: string
        reserved:
          type: string
        supply:
          type: string
        symbol:
          type: string
        token_image:
          description: TokenId        *decimal.Decimal `json:"token_id,omitempty"`
          type: string
        unbonding:
          type: string
        unclaimed:
          type: string
        unique_id:
          type: string
        vesting:
          $ref: '#/components/schemas/subscan_internal_model.VestingJson'
      type: object
    internal_server_http.searchByIdentityParams:
      properties:
        identity:
          maxLength: 300
          minLength: 1
          type: string
      required:
      - identity
      type: object
    subscan_internal_model.AccountHold:
      properties:
        amount:
          type: string
        id: {}
      type: object
    subscan_internal_model.AccountParentJson:
      properties:
        address:
          type: string
        display:
          type: string
        identity:
          type: boolean
        sub_symbol:
          type: string
      type: object
    subscan_internal_model.AccountRoleCountJson:
      properties:
        count:
          type: integer
        role:
          type: string
      type: object
    subscan_internal_model.AccountDisplay:
      properties:
        account_index:
          type: string
        address:
          description: Current network account
          type: string
        display:
          type: string
        evm_address:
          type: string
        evm_contract:
          $ref: '#/components/schemas/subscan_internal_model.EvmAccountDisplay'
        identity:
          type: boolean
        judgements:
          items:
            $ref: '#/components/schemas/subscan_internal_model.RegistrationJudgementJson'
          type: array
        merkle:
          $ref: '#/components/schemas/subscan_internal_model.MerkleTag'
        parent:
          allOf:
          - $ref: '#/components/schemas/subscan_internal_model.AccountParentJson'
          description: Parent account
        people:
          $ref: '#/components/schemas/subscan_internal_model.SampleIdentity'
      type: object
    subscan_internal_model.SnapshotBalanceHistoryJson:
      properties:
        balance:
          type: string
        block:
          type: integer
        date:
          type: string
      type: object
    subscan_internal_model.DelegateJson:
      properties:
        account:
          $ref: '#/components/schemas/subscan_internal_model.AccountDisplay'
        amount:
          type: string
        conviction:
          type: string
        delegate_account:
          $ref: '#/components/schemas/subscan_internal_model.AccountDisplay'
        origins:
          type: integer
        votes:
          type: string
      type: object
    subscan_internal_model.ProxyAccountJson:
      properties:
        proxy_account:
          items:
            $ref: '#/components/schemas/subscan_internal_model.ProxyAccountInfoJson'
          type: array
        real_account:
          items:
            $ref: '#/components/schemas/subscan_internal_model.ProxyAccountInfoJson'
          type: array
      type: object
    subscan_internal_model.OrmlVestingSchedule:
      properties:
        per_period:
          type: string
        period:
          type: integer
        period_count:
          type: integer
        start:
          type: integer
      type: object
    subscan_internal_model.AccountJsonExtra:
      properties:
        amount:
          type: string
        conviction:
          type: string
        origins:
          type: integer
        proxy_type:
          type: string
      type: object
    subscan_internal_model.AccountNetAssetJson:
      properties:
        account_display:
          $ref: '#/components/schemas/subscan_internal_model.AccountDisplay'
        evm_account:
          type: string
        priced_token_count:
          type: integer
        total_value:
          type: string
        unpriced_token_count:
          type: integer
      type: object
    subscan_internal_model.RegistrationJudgementJson:
      properties:
        index:
          type: integer
        judgement:
          type: string
      type: object
    internal_server_http.transfersParams:
      properties:
        address:
          type: string
        after_id:
          items:
            type: integer
          type: array
        asset_symbol:
          type: string
        asset_unique_id:
          type: string
        block_range:
          type: string
        currency:
          enum:
          - token
          - usd
          type: string
        direction:
          enum:
          - all
          - sent
          - received
          type: string
        extrinsic_index:
          type: string
        filter_nft:
          description: filter nft transfer, support uniques module and enjin multi-token
          type: boolean
        include_total:
          type: boolean
        item_id:
          type: integer
        max_amount:
          type: string
        min_amount:
          type: string
        order:
          enum:
          - asc
          - desc
          type: string
        page:
          description: Page number, starting from 0
          example: 0
          minimum: 0
          type: integer
        receiver:
          type: string
        row:
          description: Data size per page
          example: 10
          maximum: 100
          minimum: 1
          type: integer
        sender:
          type: string
        success:
          type: boolean
        timeout:
          type: integer
        token_category:
          items:
            type: string
          type: array
      type: object
    subscan_internal_model.ItemDetail:
      properties:
        collection_symbol:
          type: string
        fallback_image:
          type: string
        image:
          type: string
        local_image:
          type: string
        media:
          items:
            $ref: '#/components/schemas/subscan_internal_model.MetadataMedia'
          type: array
        symbol:
          type: string
        thumbnail:
          type: string
      type: object
    subscan_internal_model.AccountJsonV1:
      properties:
        account_display:
          $ref: '#/components/schemas/subscan_internal_model.AccountDisplay'
        address:
          type: string
        assets_tag:
          items:
            type: string
          type: array
        balance:
          type: string
        balance_lock:
          type: string
        bonded:
          type: string
        conviction_lock:
          type: string
        count_extrinsic:
          type: integer
        customize_role:
          additionalProperties:
            type: boolean
          type: object
        delegate:
          $ref: '#/components/schemas/subscan_internal_model.DelegateAccountJson'
        democracy_lock:
          type: string
        derive_token:
          additionalProperties:
            $ref: '#/components/schemas/subscan_internal_model.AccountDerive'
          type: object
        discord:
          type: string
        display:
          type: string
        election_lock:
          type: string
        email:
          type: string
        evm_account:
          type: string
        evm_txn_count:
          type: integer
        extra:
          items:
            $ref: '#/components/schemas/subscan_internal_model.AccountJsonExtra'
          type: array
        fellowship_rank:
          type: integer
        github:
          type: string
        holds:
          items:
            $ref: '#/components/schemas/subscan_internal_model.AccountHold'
          type: array
        is_collator:
          type: boolean
        is_contract:
          type: boolean
        is_council_member:
          type: boolean
        is_erc20:
          type: boolean
        is_erc721:
          type: boolean
        is_erc1155:
          type: boolean
        is_evm_contract:
          type: boolean
        is_evm_system:
          type: boolean
        is_fellowship_member:
          type: boolean
        is_module_account:
          type: boolean
        is_pool_member:
          type: boolean
        is_registrar:
          type: boolean
        is_techcomm_member:
          type: boolean
        judgements:
          items:
            $ref: '#/components/schemas/subscan_internal_model.RegistrationJudgementJson'
          type: array
        legal:
          type: string
        lock:
          type: string
        matrix:
          type: string
        multisig:
          $ref: '#/components/schemas/subscan_internal_model.MultiAccountJson'
        nft_amount:
          description: UpgradeV2      bool `json:"-"`
          type: string
        nomination_pool_balance:
          items: {}
          type: array
        nonce:
          type: integer
        proxy:
          $ref: '#/components/schemas/subscan_internal_model.ProxyAccountJson'
        registrar_fee:
          type: string
        registrar_index:
          type: integer
        registrar_info:
          $ref: '#/comp

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