openapi: 3.1.0
info:
  title: Polkadot REST Account Parachain 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: Parachain
paths:
  /api/scan/parachain/info:
    post:
      consumes:
      - application/json
      description: 'Returns detailed parachain information with optional parachain-status filters. Only available on relay chains: Polkadot, Kusama, Westend, and Paseo.'
      parameters:
      - description: params
        in: body
        name: params
        required: true
        schema:
          $ref: '#/definitions/internal_server_http.parachainInfoParams'
      produces:
      - application/json
      responses:
        '200':
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/internal_server_http.J'
            - properties:
                data:
                  properties:
                    chains:
                      items:
                        $ref: '#/definitions/subscan_internal_model.ParachainInfoJson'
                      type: array
                    count:
                      type: integer
                  type: object
              type: object
      summary: Get parachain details
      tags:
      - Parachain
      x-synonyms:
      - parachain
      - scan
      - para chain
      - relaychain shard
  /api/scan/parachain/list:
    post:
      consumes:
      - application/json
      description: 'Returns a paginated list of parachains and parathreads with status and basic metadata. Only available on relay chains: Polkadot, Kusama, Westend, and Paseo.'
      parameters:
      - description: params
        in: body
        name: params
        required: true
        schema:
          $ref: '#/definitions/internal_server_http.paraChainListParams'
      produces:
      - application/json
      responses:
        '200':
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/internal_server_http.J'
            - properties:
                data:
                  properties:
                    chains:
                      items:
                        $ref: '#/definitions/subscan_internal_model.ParaChainSample'
                      type: array
                    count:
                      type: integer
                  type: object
              type: object
      summary: List parachains and parathreads
      tags:
      - Parachain
      x-synonyms:
      - parachain
      - scan
      - para chain
      - relaychain shard
  /api/scan/parachain/meta:
    post:
      consumes:
      - application/json
      description: 'Returns aggregate metadata for all parachains on the current relay chain. Only available on relay chains: Polkadot, Kusama, Westend, and Paseo.'
      produces:
      - application/json
      responses:
        '200':
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/internal_server_http.J'
            - properties:
                data:
                  $ref: '#/definitions/subscan_internal_model.ParaChainMetaJson'
              type: object
      summary: Get parachain metadata
      tags:
      - Parachain
      x-synonyms:
      - parachain
      - meta
      - scan
      - para chain
      - relaychain shard
  /api/scan/parachain/registerinfo:
    post:
      consumes:
      - application/json
      description: Returns the current relay-chain name and parachain registration mapping when parachain registration data is available.
      produces:
      - application/json
      responses:
        '200':
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/internal_server_http.J'
            - properties:
                data:
                  properties:
                    paraID:
                      additionalProperties:
                        type: string
                      type: object
                    relay_chain:
                      type: string
                  type: object
              type: object
      summary: Get parachain registration info
      tags:
      - Parachain
      x-synonyms:
      - parachain
      - register
      - scan
      - registerinfo
      - para chain
      - relaychain shard
  /api/scan/parachain/statistics/list:
    post:
      consumes:
      - application/json
      description: Returns one cached aggregate row per parachain network for relay-level dashboards.
      parameters:
      - description: params
        in: body
        name: params
        required: true
        schema:
          $ref: '#/definitions/internal_server_http.parachainMetricListParams'
      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.ParachainMetricNetworkStat'
                      type: array
                  type: object
              type: object
      summary: List relay parachain statistics
      tags:
      - Parachain
      x-synonyms:
      - parachain
      - statistics
      - relaychain
      - list
      - network
      - para id
  /api/scan/parachain/statistics/overview:
    post:
      consumes:
      - application/json
      description: Returns cached aggregate extrinsic, transfer, TPS, and XCM counters for parachains under the current relay chain. Reads pre-aggregated rollups only and does not fan out to parachain APIs.
      parameters:
      - description: params
        in: body
        name: params
        required: true
        schema:
          $ref: '#/definitions/internal_server_http.parachainMetricParams'
      produces:
      - application/json
      responses:
        '200':
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/internal_server_http.J'
            - properties:
                data:
                  properties:
                    total:
                      $ref: '#/definitions/subscan_internal_model.ParachainMetricTotal'
                    updated_at:
                      type: string
                  type: object
              type: object
      summary: Get relay parachain statistics overview
      tags:
      - Parachain
      x-synonyms:
      - parachain
      - statistics
      - relaychain
      - tps
      - extrinsic
      - transfer
      - xcm
  /api/scan/parachain/statistics/timeseries:
    post:
      consumes:
      - application/json
      description: Returns cached hourly or daily parachain metric rollups for chart rendering.
      parameters:
      - description: params
        in: body
        name: params
        required: true
        schema:
          $ref: '#/definitions/internal_server_http.parachainMetricParams'
      produces:
      - application/json
      responses:
        '200':
          description: OK
          schema:
            allOf:
            - $ref: '#/definitions/internal_server_http.J'
            - properties:
                data:
                  properties:
                    series:
                      items:
                        $ref: '#/definitions/subscan_internal_model.ParachainMetricSeriesPoint'
                      type: array
                  type: object
              type: object
      summary: Get relay parachain statistics timeseries
      tags:
      - Parachain
      x-synonyms:
      - parachain
      - statistics
      - relaychain
      - timeseries
      - chart
      - tps
definitions:
  subscan_internal_model.ParachainMetricTotal:
    properties:
      avg_tps:
        type: string
      extrinsic_count:
        type: integer
      peak_tps:
        type: string
      transfer_count:
        type: integer
      updated_at:
        type: string
      xcm_receive_count:
        type: integer
      xcm_send_count:
        type: integer
    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.MerkleTag:
    properties:
      address_type:
        type: string
      tag_name:
        type: string
      tag_subtype:
        type: string
      tag_type:
        type: string
    type: object
  internal_server_http.parachainMetricParams:
    properties:
      end:
        example: '2026-05-20'
        type: string
      format:
        enum:
        - hour
        - day
        example: day
        type: string
      metrics:
        items:
          type: string
        type: array
      networks:
        items:
          type: string
        type: array
      para_ids:
        items:
          type: integer
        type: array
      relay_network:
        example: polkadot
        type: string
      start:
        example: '2026-05-01'
        type: string
    required:
    - end
    - start
    type: object
  subscan_internal_model.SampleIdentity:
    properties:
      display:
        type: string
      identity:
        type: boolean
      judgements:
        items:
          $ref: '#/definitions/subscan_internal_model.RegistrationJudgementJson'
        type: array
      parent:
        $ref: '#/definitions/subscan_internal_model.AccountParentJson'
    type: object
  subscan_internal_model.ParachainMetricSeriesPoint:
    properties:
      avg_tps:
        type: string
      bucket_format:
        type: string
      bucket_time:
        type: string
      extrinsic_count:
        type: integer
      network:
        type: string
      para_id:
        type: integer
      peak_tps:
        type: string
      relay_network:
        type: string
      transfer_count:
        type: integer
      updated_at:
        type: string
      xcm_receive_count:
        type: integer
      xcm_send_count:
        type: integer
    type: object
  subscan_internal_model.ParachainInfoJson:
    properties:
      auction_index:
        type: integer
      begin_period:
        description: 周期开始时间(begin-first-end)
        type: integer
      bid_id:
        type: string
      deposit:
        type: string
      first_period:
        type: integer
      fund_account:
        type: string
      fund_account_display:
        $ref: '#/definitions/subscan_internal_model.AccountDisplay'
      fund_id:
        type: string
      genesis_head:
        type: string
      last_period:
        type: integer
      manager:
        type: string
      manager_display:
        $ref: '#/definitions/subscan_internal_model.AccountDisplay'
      open_channel_count:
        type: integer
      para_id:
        type: integer
      reserved_extrinsic_index:
        type: string
      source:
        type: integer
      status:
        type: string
      validation_code_url:
        type: string
      validators:
        items:
          type: string
        type: array
      validators_display:
        items:
          $ref: '#/definitions/subscan_internal_model.AccountDisplay'
        type: array
      xcm_receive_message_count:
        type: integer
      xcm_receive_transfer_count:
        type: integer
      xcm_send_message_count:
        type: integer
      xcm_send_transfer_count:
        type: integer
    type: object
  internal_server_http.parachainMetricListParams:
    properties:
      end:
        example: '2026-05-20'
        type: string
      format:
        enum:
        - hour
        - day
        example: day
        type: string
      metrics:
        items:
          type: string
        type: array
      networks:
        items:
          type: string
        type: array
      order:
        enum:
        - asc
        - desc
        example: desc
        type: string
      order_field:
        example: extrinsic_count
        type: string
      page:
        example: 0
        minimum: 0
        type: integer
      para_ids:
        items:
          type: integer
        type: array
      relay_network:
        example: polkadot
        type: string
      row:
        example: 10
        maximum: 100
        minimum: 1
        type: integer
      start:
        example: '2026-05-01'
        type: string
    required:
    - end
    - start
    type: object
  subscan_internal_model.ParachainMetricNetworkStat:
    properties:
      avg_tps:
        type: string
      extrinsic_count:
        type: integer
      network:
        type: string
      para_id:
        type: integer
      peak_tps:
        type: string
      relay_network:
        type: string
      transfer_count:
        type: integer
      updated_at:
        type: string
      xcm_receive_count:
        type: integer
      xcm_send_count:
        type: integer
    type: object
  subscan_internal_model.ParaChainMetaJson:
    properties:
      auction_active:
        type: boolean
      auction_count:
        type: integer
      ending_period:
        type: integer
      lease_offset:
        type: integer
      lease_period:
        type: integer
      lease_periods_per_slot:
        type: integer
      online_count:
        type: integer
      retirement_period:
        type: integer
      total_slot_num:
        type: integer
      upcoming_count:
        type: integer
    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
  internal_server_http.paraChainListParams:
    properties:
      filter_anonymous:
        type: boolean
      order:
        type: string
      page:
        description: Page number, starting from 0
        example: 0
        minimum: 0
        type: integer
      para_id:
        type: integer
      row:
        description: Data size per page
        example: 10
        maximum: 100
        minimum: 1
        type: integer
      status:
        items:
          type: string
        type: array
    type: object
  internal_server_http.parachainInfoParams:
    properties:
      filter_anonymous:
        type: boolean
      order:
        type: string
      page:
        description: Page number, starting from 0
        example: 0
        minimum: 0
        type: integer
      para_id:
        type: integer
      row:
        description: Data size per page
        example: 10
        maximum: 100
        minimum: 1
        type: integer
      status:
        items:
          type: string
        type: array
    type: object
  subscan_internal_model.ParaChainSample:
    properties:
      begin_period:
        type: integer
      bid_id:
        type: string
      first_period:
        type: integer
      fund_id:
        type: string
      last_period:
        type: integer
      manager_display:
        $ref: '#/definitions/subscan_internal_model.AccountDisplay'
      open_channel_count:
        type: integer
      para_id:
        type: integer
      reserved_extrinsic_index:
        type: string
      status:
        type: string
      xcm_receive_message_count:
        type: integer
      xcm_receive_transfer_count:
        type: integer
      xcm_send_message_count:
        type: integer
      xcm_send_transfer_count:
        type: integer
    type: object
  subscan_internal_model.EvmAccountDisplay:
    properties:
      contract_name:
        type: string
      verify_source:
        type: string
    type: object
  subscan_internal_model.RegistrationJudgementJson:
    properties:
      index:
        type: integer
      judgement:
        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: '#/definitions/subscan_internal_model.EvmAccountDisplay'
      identity:
        type: boolean
      judgements:
        items:
          $ref: '#/definitions/subscan_internal_model.RegistrationJudgementJson'
        type: array
      merkle:
        $ref: '#/definitions/subscan_internal_model.MerkleTag'
      parent:
        allOf:
        - $ref: '#/definitions/subscan_internal_model.AccountParentJson'
        description: Parent account
      people:
        $ref: '#/definitions/subscan_internal_model.SampleIdentity'
    type: object