TOP Group (The Open Platform) Lite Server API

openapi: 3.0.0
info:
  title: REST api to TON blockchain explorer Accounts Lite Server API
  version: 2.0.0
  description: Provide access to indexed TON blockchain
  contact:
    name: Support
    email: support@tonkeeper.com
servers:
- url: https://tonapi.io
- url: https://testnet.tonapi.io
- url: http://localhost:8081
tags:
- name: Lite Server
  externalDocs:
    description: Additional documentation
    url: https://docs.tonconsole.com/tonapi/rest-api/lite-server
paths:
  /v2/liteserver/get_masterchain_info:
    get:
      description: Get raw masterchain info
      operationId: getRawMasterchainInfo
      tags:
      - Lite Server
      responses:
        '200':
          description: raw masterchain info
          content:
            application/json:
              schema:
                type: object
                required:
                - last
                - state_root_hash
                - init
                properties:
                  last:
                    $ref: '#/components/schemas/BlockRaw'
                  state_root_hash:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  init:
                    $ref: '#/components/schemas/InitStateRaw'
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_masterchain_info_ext:
    get:
      description: Get raw masterchain info ext
      operationId: getRawMasterchainInfoExt
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/modeQuery'
      responses:
        '200':
          description: raw masterchain info ext
          content:
            application/json:
              schema:
                type: object
                required:
                - mode
                - version
                - capabilities
                - last
                - last_utime
                - now
                - state_root_hash
                - init
                properties:
                  mode:
                    type: integer
                    format: int32
                    example: 0
                  version:
                    type: integer
                    format: int32
                    example: 257
                  capabilities:
                    type: integer
                    format: int64
                    example: 7
                  last:
                    $ref: '#/components/schemas/BlockRaw'
                  last_utime:
                    type: integer
                    format: int32
                    example: 1687938199
                  now:
                    type: integer
                    format: int32
                    example: 1687938204
                  state_root_hash:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  init:
                    $ref: '#/components/schemas/InitStateRaw'
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_time:
    get:
      description: Get raw time
      operationId: getRawTime
      tags:
      - Lite Server
      responses:
        '200':
          description: raw time
          content:
            application/json:
              schema:
                type: object
                required:
                - time
                properties:
                  time:
                    type: integer
                    format: int32
                    example: 1687146728
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_block/{block_id}:
    get:
      description: Get raw blockchain block
      operationId: getRawBlockchainBlock
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      responses:
        '200':
          description: raw blockchain block
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - data
                properties:
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  data:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_state/{block_id}:
    get:
      description: Get raw blockchain block state
      operationId: getRawBlockchainBlockState
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      responses:
        '200':
          description: raw blockchain block state
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - root_hash
                - file_hash
                - data
                properties:
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  root_hash:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  file_hash:
                    type: string
                    example: A6A0BD6608672B11B79538A50B2204E748305C12AA0DED9C16CF0006CE3AF8DB
                  data:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_block_header/{block_id}:
    get:
      description: Get raw blockchain block header
      operationId: getRawBlockchainBlockHeader
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      - $ref: '#/components/parameters/modeQuery'
      responses:
        '200':
          description: raw blockchain block header
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - mode
                - header_proof
                properties:
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  mode:
                    type: integer
                    format: int32
                    example: 0
                  header_proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/send_message:
    post:
      description: Send raw message to blockchain
      operationId: sendRawMessage
      tags:
      - Lite Server
      requestBody:
        $ref: '#/components/requestBodies/LiteServerSendMessageRequest'
      responses:
        '200':
          description: code
          content:
            application/json:
              schema:
                type: object
                required:
                - code
                properties:
                  code:
                    type: integer
                    format: int32
                    example: 200
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_account_state/{account_id}:
    get:
      description: Get raw account state
      operationId: getRawAccountState
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/accountIDParameter'
      - $ref: '#/components/parameters/targetBlockIDExtQuery'
      responses:
        '200':
          description: raw account state
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - shardblk
                - shard_proof
                - proof
                - state
                properties:
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  shardblk:
                    $ref: '#/components/schemas/BlockRaw'
                  shard_proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  state:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_shard_info/{block_id}:
    get:
      description: Get raw shard info
      operationId: getRawShardInfo
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      - $ref: '#/components/parameters/workchainQuery'
      - $ref: '#/components/parameters/shardQuery'
      - $ref: '#/components/parameters/exactQuery'
      responses:
        '200':
          description: raw shard info
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - shardblk
                - shard_proof
                - shard_descr
                properties:
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  shardblk:
                    $ref: '#/components/schemas/BlockRaw'
                  shard_proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  shard_descr:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_all_shards_info/{block_id}:
    get:
      description: Get all raw shards info
      operationId: getAllRawShardsInfo
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      responses:
        '200':
          description: all raw shards info
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - proof
                - data
                properties:
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  data:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_transactions/{account_id}:
    get:
      description: Get raw transactions
      operationId: getRawTransactions
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/accountIDParameter'
      - $ref: '#/components/parameters/countQuery'
      - $ref: '#/components/parameters/ltMustQuery'
      - $ref: '#/components/parameters/hashQuery'
      responses:
        '200':
          description: raw transactions
          content:
            application/json:
              schema:
                type: object
                required:
                - ids
                - transactions
                properties:
                  ids:
                    type: array
                    items:
                      $ref: '#/components/schemas/BlockRaw'
                  transactions:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/list_block_transactions/{block_id}:
    get:
      description: Get raw list block transactions
      operationId: getRawListBlockTransactions
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      - $ref: '#/components/parameters/modeQuery'
      - $ref: '#/components/parameters/countQuery'
      - $ref: '#/components/parameters/accountIDQuery'
      - $ref: '#/components/parameters/ltQuery'
      responses:
        '200':
          description: a list of raw block transactions
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - req_count
                - incomplete
                - ids
                - proof
                properties:
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  req_count:
                    type: integer
                    format: int32
                    example: 100
                  incomplete:
                    type: boolean
                    example: true
                  ids:
                    type: array
                    items:
                      type: object
                      required:
                      - mode
                      properties:
                        mode:
                          type: integer
                          format: int32
                          example: 0
                        account:
                          type: string
                          example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                        lt:
                          type: integer
                          format: int64
                          x-js-format: bigint
                        hash:
                          type: string
                          example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_block_proof:
    get:
      description: Get raw block proof
      operationId: getRawBlockProof
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/knownBlockIDExtQuery'
      - $ref: '#/components/parameters/targetBlockIDExtQuery'
      - $ref: '#/components/parameters/modeQuery'
      responses:
        '200':
          description: raw block proof
          content:
            application/json:
              schema:
                type: object
                required:
                - complete
                - from
                - to
                - steps
                properties:
                  complete:
                    type: boolean
                    example: true
                  from:
                    $ref: '#/components/schemas/BlockRaw'
                  to:
                    $ref: '#/components/schemas/BlockRaw'
                  steps:
                    type: array
                    items:
                      type: object
                      required:
                      - lite_server_block_link_back
                      - lite_server_block_link_forward
                      properties:
                        lite_server_block_link_back:
                          type: object
                          required:
                          - to_key_block
                          - from
                          - to
                          - dest_proof
                          - proof
                          - state_proof
                          properties:
                            to_key_block:
                              type: boolean
                              example: false
                            from:
                              $ref: '#/components/schemas/BlockRaw'
                            to:
                              $ref: '#/components/schemas/BlockRaw'
                            dest_proof:
                              type: string
                              example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                            proof:
                              type: string
                              example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                            state_proof:
                              type: string
                              example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                        lite_server_block_link_forward:
                          type: object
                          required:
                          - to_key_block
                          - from
                          - to
                          - dest_proof
                          - config_proof
                          - signatures
                          properties:
                            to_key_block:
                              type: boolean
                              example: false
                            from:
                              $ref: '#/components/schemas/BlockRaw'
                            to:
                              $ref: '#/components/schemas/BlockRaw'
                            dest_proof:
                              type: string
                              example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                            config_proof:
                              type: string
                              example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                            signatures:
                              type: object
                              required:
                              - validator_set_hash
                              - catchain_seqno
                              - signatures
                              properties:
                                validator_set_hash:
                                  type: integer
                                  format: int64
                                catchain_seqno:
                                  type: integer
                                  format: int32
                                signatures:
                                  type: array
                                  items:
                                    type: object
                                    required:
                                    - node_id_short
                                    - signature
                                    properties:
                                      node_id_short:
                                        type: string
                                        example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                                      signature:
                                        type: string
                                        example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_config_all/{block_id}:
    get:
      description: Get raw config
      operationId: getRawConfig
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      - $ref: '#/components/parameters/modeQuery'
      responses:
        '200':
          description: raw config
          content:
            application/json:
              schema:
                type: object
                required:
                - mode
                - id
                - state_proof
                - config_proof
                properties:
                  mode:
                    type: integer
                    format: int32
                    example: 0
                  id:
                    $ref: '#/components/schemas/BlockRaw'
                  state_proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
                  config_proof:
                    type: string
                    example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_shard_block_proof/{block_id}:
    get:
      description: Get raw shard block proof
      operationId: getRawShardBlockProof
      tags:
      - Lite Server
      parameters:
      - $ref: '#/components/parameters/blockchainBlockIDExtParameter'
      responses:
        '200':
          description: raw shard block proof
          content:
            application/json:
              schema:
                type: object
                required:
                - masterchain_id
                - links
                properties:
                  masterchain_id:
                    $ref: '#/components/schemas/BlockRaw'
                  links:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - proof
                      properties:
                        id:
                          $ref: '#/components/schemas/BlockRaw'
                        proof:
                          type: string
                          example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        default:
          $ref: '#/components/responses/Error'
  /v2/liteserver/get_out_msg_queue_sizes:
    get:
      description: Get out msg queue sizes
      operationId: getOutMsgQueueSizes
      tags:
      - Lite Server
      responses:
        '200':
          description: out msg queue sizes
          content:
            application/json:
              schema:
                type: object
                required:
                - ext_msg_queue_size_limit
                - shards
                properties:
                  ext_msg_queue_size_limit:
                    type: integer
                    format: uint32
                  shards:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - size
                      properties:
                        id:
                          $ref: '#/components/schemas/BlockRaw'
                        size:
                          type: integer
                          format: uint32
        default:
          $ref: '#/components/responses/Error'
components:
  parameters:
    blockchainBlockIDExtParameter:
      in: path
      name: block_id
      required: true
      description: 'block ID: (workchain,shard,seqno,root_hash,file_hash)'
      schema:
        type: string
        example: (-1,8000000000000000,4234234,3E575DAB1D25...90D8,47192E5C46C...BB29)
    knownBlockIDExtQuery:
      in: query
      name: known_block
      required: true
      description: 'known block: (workchain,shard,seqno,root_hash,file_hash)'
      schema:
        type: string
        example: (-1,8000000000000000,4234234,3E575DAB1D25...90D8,47192E5C46C...BB29)
    ltQuery:
      in: query
      name: lt
      description: lt
      schema:
        type: integer
        format: int64
        example: 23814011000000
    countQuery:
      in: query
      name: count
      required: true
      description: count
      schema:
        type: integer
        format: int32
        example: 100
    modeQuery:
      in: query
      name: mode
      required: true
      description: mode
      schema:
        type: integer
        format: int32
        example: 0
    shardQuery:
      in: query
      name: shard
      required: true
      description: shard
      schema:
        type: integer
        format: int64
        example: 1
    hashQuery:
      in: query
      name: hash
      required: true
      description: hash
      schema:
        type: string
        example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
    exactQuery:
      in: query
      name: exact
      required: true
      description: exact
      schema:
        type: boolean
        example: false
    ltMustQuery:
      in: query
      name: lt
      required: true
      description: lt
      schema:
        type: integer
        format: int64
        example: 23814011000000
    targetBlockIDExtQuery:
      in: query
      name: target_block
      required: false
      description: 'target block: (workchain,shard,seqno,root_hash,file_hash)'
      schema:
        type: string
        example: (-1,8000000000000000,4234234,3E575DAB1D25...90D8,47192E5C46C...BB29)
    accountIDQuery:
      in: query
      name: account_id
      required: false
      description: account ID
      explode: false
      schema:
        type: string
        format: address
        example: 0:97264395BD65A255A429B11326C84128B7D70FFED7949ABAE3036D506BA38621
    workchainQuery:
      in: query
      name: workchain
      required: true
      description: workchain
      schema:
        type: integer
        format: int32
        example: 1
    accountIDParameter:
      in: path
      name: account_id
      required: true
      description: account ID
      schema:
        type: string
        format: address
        example: 0:97264395BD65A255A429B11326C84128B7D70FFED7949ABAE3036D506BA38621
  requestBodies:
    LiteServerSendMessageRequest:
      description: Data that is expected
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - body
            properties:
              body:
                type: string
                format: cell-base64
  schemas:
    BlockRaw:
      type: object
      required:
      - workchain
      - shard
      - seqno
      - root_hash
      - file_hash
      properties:
        workchain:
          type: integer
          example: 4294967295
          format: int32
        shard:
          type: string
          example: '800000000000000'
        seqno:
          type: integer
          example: 30699640
          format: int32
        root_hash:
          type: string
          example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        file_hash:
          type: string
          example: A6A0BD6608672B11B79538A50B2204E748305C12AA0DED9C16CF0006CE3AF8DB
    InsufficientFunds:
      type: object
      description: 'Present on an error when a request failed because the source wallet does not hold enough TON to cover the required gas (error_code 50000).

        '
      required:
      - required
      - available
      properties:
        required:
          type: integer
          format: int64
          description: TON in nanotons required to cover transfer gas
          x-js-format: bigint
        available:
          type: integer
          format: int64
          description: TON in nanotons currently available on the source wallet
          x-js-format: bigint
    InitStateRaw:
      type: object
      required:
      - workchain
      - root_hash
      - file_hash
      properties:
        workchain:
          type: integer
          example: 4294967295
          format: int32
        root_hash:
          type: string
          example: 131D0C65055F04E9C19D687B51BC70F952FD9CA6F02C2801D3B89964A779DF85
        file_hash:
          type: string
          example: A6A0BD6608672B11B79538A50B2204E748305C12AA0DED9C16CF0006CE3AF8DB
  responses:
    Error:
      description: Some error during request processing
      content:
        application/json:
          schema:
            type: object
            required:
            - error
            properties:
              error:
                type: string
              error_code:
                type: integer
                format: int64
              details:
                $ref: '#/components/schemas/InsufficientFunds'