swagger.yml

openapi: 3.0.1
info:
  title: Fantom explorer api
  description: Work in progress
  version: '0.1'
servers:
  - url: 'http://3.136.216.35:3100'
paths:
  /api/v1/get-blocks:
    get:
      description: Returns blocks list with pagination. Max count = 30, order may be -1 or 1.
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
          example: 0
        - name: count
          in: query
          schema:
            type: integer
          example: 1
        - name: order
          in: query
          schema:
            type: integer
          example: -1
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      maxBlockHeight:
                        type: integer
                      total:
                        type: integer
                        description: total number of blocks in database by provided (or not) conditions
                      offset:
                        type: integer
                        description: offset of pagination
                      count:
                        type: integer
                        description: number of blocks per page
                      blocks:
                        type: array
                        items:
                          $ref: '#/components/schemas/Block'
      servers:
        - url: 'http://3.136.216.35:3100'
      tags:
        - block
      summary: Blocks list
    servers:
      - url: 'http://3.136.216.35:3100'
  /api/v1/get-transaction:
    get:
      description: Get transaction by hash
      parameters:
        - name: transactionHash
          in: query
          schema:
            type: string
          required: true
          example: '0x506a50cd7ecf27c3834a045d5e7501bc3bfb56b6bae03637c093c6c8d9735b8e'
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      transaction:
                        $ref: '#/components/schemas/Transaction'
      servers:
        - url: 'http://3.136.216.35:3100'
      tags:
        - transaction
      summary: Get transaction by hash
    servers:
      - url: 'http://3.136.216.35:3100'
  /api/v1/get-block:
    servers:
      - url: 'http://3.136.216.35:3100'
    get:
      summary: Get block by block number
      tags:
        - block
      description: Returns block with provided number
      parameters:
        - name: blockNumber
          in: query
          schema:
            type: number
          required: true
          example: 5
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      block:
                        $ref: '#/components/schemas/Block'
      servers:
        - url: 'http://3.136.216.35:3100'
  /api/v1/get-account:
    get:
      description: Returns account with transactions array in it with pagination.  You may filter transactions by query field 'trxsFilter' with values 'from' or 'to'. Without values filter not applied to result.
      parameters:
        - name: address
          in: query
          schema:
            type: string
          required: true
          example: '0x239fa7623354ec26520de878b52f13fe84b06971'
        - name: offset
          in: query
          schema:
            type: integer
          example: 0
          description: default 0
        - name: count
          in: query
          schema:
            type: integer
          example: 10
          description: default 10
        - name: trxsFilter
          in: query
          schema:
            type: string
          example: from
          description: Accept params "from", "to", "contract". Filter supports multiple parameters at the same time, but they can be mutually exclusive, for example "to" and "contract" - contract creation transaction's parameter "to" is always null.
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      account:
                        type: object
                        properties:
                          address:
                            type: string
                          balance:
                            type: number
                          nonce:
                            type: integer
                          totalTrxs:
                            type: integer
                          offsetTrxs:
                            type: integer
                          countTrxs:
                            type: integer
                          transactions:
                            type: array
                            items:
                              $ref: '#/components/schemas/TransactionForAccountEndpoint'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Get account by address
      tags:
        - account
    servers:
      - url: 'http://3.136.216.35:3100'
  /api/v1/get-transactions:
    get:
      description: Returns transactions list with pagination. Max count = 30, order may be -1 or 1.
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
          example: 0
        - name: count
          in: query
          schema:
            type: integer
          example: 1
        - name: order
          in: query
          schema:
            type: integer
          example: -1
        - name: block
          in: query
          schema:
            type: integer
          example: 15232
        - name: from
          in: query
          schema:
            type: string
          example: "0x239fa7623354ec26520de878b52f13fe84b06971"
          description: Add filter by sender address
        - name: to
          in: query
          schema:
            type: string
          example: "0x239fa7623354ec26520de878b52f13fe84b06971"
          description: Add filter by recipient address
        - name: contractCreation
          in: query
          schema:
            type: boolean
          example: false
          description: Exclude contract creation trxs or select only ctonract creation trxs. Omitting this parameter will cause including all types of trxs in selection.
        - name: contractAddress
          in: query
          schema:
            type: string
          example: "0x1234567890123456789012345678901234567891"
          description: Add filter by contract address
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      maxBlockHeight:
                        type: integer
                      total:
                        type: integer
                        description: total number of transactions in database by provided (or not) conditions
                      offset:
                        type: integer
                        description: offset of pagination
                      count:
                        type: integer
                        description: number of transactions per page
                      transactions:
                        type: array
                        items:
                          $ref: '#/components/schemas/Transaction'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Transactions list
      tags:
        - transaction
    servers:
      - url: 'http://3.136.216.35:3100'
  /api/v1/get-latest-data:
    get:
      description: Returns latest blocks and transactions with pagination. Max count = 30.
      parameters:
        - name: count
          in: query
          schema:
            type: integer
          example: 1
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      maxBlockHeight:
                        type: integer
                      count:
                        type: integer
                        description: number of blocks and transactions per page
                      blocks:
                        type: array
                        items:
                          $ref: '#/components/schemas/Block'
                      transactions:
                        type: array
                        items:
                          $ref: '#/components/schemas/Transaction'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Get latest data
      tags:
        - latest data
    servers:
      - url: 'http://3.136.216.35:3100'
  
  /api/v1/epoch/latest:
    get:
      description: Returns info about latest ended epoch.
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      epochNumber:
                        type: string
                      totalTxFee:
                        type: string
                      endTime:
                        type: string
                        format: date-time
                      duration:
                        type: integer
                        description: duration in milliseconds
                      totalBaseRewardWeight:
                        type: string
                      totalTxRewardWeight:
                        type: string
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Latest ended epoch
      tags:
        - epoch
    servers:
      - url: 'http://3.136.216.35:3100'
      
  /api/v1/delegator/address/{address}:
    get:
      description: Returns delegator by its address
      parameters:
        - name: address
          in: path
          schema:
            type: string
          example: '0x71981d82370e8cffd831003fa961b172e4c129d2'
          required: true
        - name: verbosity
          in: query
          schema:
            type: number
          example: 2
          description: If 1, then include base fields. If 2, then include metrics.
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    $ref: '#/components/schemas/DelegatorObject'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Delegator by address
      tags:
        - delegator
    servers:
      - url: 'http://3.136.216.35:3100'
      
  /api/v1/delegator/staker/{id}:
    get:
      description: Returns all the delegators which delegated to the specified staker.
      parameters:
        - name: id
          in: path
          schema:
            type: number
          example: 1
          required: true
        - name: verbosity
          in: query
          schema:
            type: number
          example: 2
          description: If 0, then include only addresses. If 1, then include base fields. If 2, then include metrics.
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      delegators:
                        type: array
                        items:
                          $ref: '#/components/schemas/DelegatorObject'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Delegators by staker id
      tags:
        - delegator
    servers:
      - url: 'http://3.136.216.35:3100'

  /api/v1/staker/id/{id}/downtime:
    get:
      description: Period of time in nanoseconds for which validator didn’t participate in blocks.
      parameters:
        - name: id
          in: path
          schema:
            type: number
          example: 1
          required: true
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      downtime:
                        type: string
                      missedBlocks:
                        type: string
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Staker's downtime
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'
      
  /api/v1/staker/id/{id}/origination-score:
    get:
      description: Returns staker's origination score
      parameters:
        - name: id
          in: path
          schema:
            type: number
          example: 1
          required: true
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      originationScore:
                        type: string
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Staker's origination score
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'
      
  /api/v1/staker/id/{id}/poi:
    get:
      description: Returns staker's proof of importance
      parameters:
        - name: id
          in: path
          schema:
            type: number
          example: 1
          required: true
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      poi:
                        type: string
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Staker's PoI
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'

  /api/v1/staker/id/{id}/validation-score:
    get:
      description: Returns staker's validating score
      parameters:
        - name: id
          in: path
          schema:
            type: number
          example: 1
          required: true
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      validationScore:
                        type: string
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Staker's validating score
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'
      
  /api/v1/staker/id/{id}:
    get:
      description: Returns staker by its id
      parameters:
        - name: id
          in: path
          schema:
            type: number
          example: 1
          required: true
        - name: verbosity
          in: query
          schema:
            type: number
          example: 2
          description: If 1, then include base fields. If 2, then include metrics.
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    $ref: '#/components/schemas/StakerObject'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Staker by id
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'
      
      
  /api/v1/staker/address/{address}:
    get:
      description: Returns staker by its address
      parameters:
        - name: address
          in: path
          schema:
            type: string
          example: '0xf88d5892faf084dcf4143566d9c9b3f047c153ca'
          required: true
        - name: verbosity
          in: query
          schema:
            type: number
          example: 2
          description: If 0, then include only stakerID. If 1, then include base field. If 2, then include metrics.
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    $ref: '#/components/schemas/StakerObject'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Staker by address
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'
      
  /api/v1/staker/:
    get:
      description: Returns list of stakers.
      parameters:
        - name: verbosity
          in: query
          schema:
            type: number
          example: 2
          description: If 0, then include only stakerIDs. If 1, then include base field. If 2, then include metrics (including downtime if validator).

      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      stakers:
                        type: array
                        items:
                          $ref: '#/components/schemas/StakerObject'
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Stakers list
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'
      
  /api/v1/staker/id/{id}/reward-weights:
    get:
      description: Returns staker's baseRewardWeight and txRewardWeight.
      parameters:
        - name: id
          in: path
          schema:
            type: number
          example: 1
          required: true
      responses:
        '200':
          description: ok
          content:
            application/json; charset=utf-8:
              schema:
                type: object
                properties:
                  meta:
                    $ref: '#/components/schemas/meta'
                  data:
                    type: object
                    properties:
                      baseRewardWeight:
                        type: string
                      txRewardWeight:
                        type: string
      servers:
        - url: 'http://3.136.216.35:3100'
      summary: Staker's reward weights
      tags:
        - staker
    servers:
      - url: 'http://3.136.216.35:3100'
      
components:
  schemas:
    meta:
      type: object
      properties:
        success:
          type: boolean
          description: is operation successful
      required:
        - success
    Block:
      type: object
      properties:
        gasUsed:
          type: integer
          description: The total used gas by all transactions in this block.
        hash:
          type: string
          description: Hash of the block.
        number:
          type: integer
          description: The block number.
        parentHash:
          type: string
          description: Hash of the parent block.
        stateRoot:
          type: string
          description: The root of the final state trie of the block.
        timestamp:
          type: integer
          description: The unix timestamp for when the block was collated.
        transactions:
          type: integer
          description: number of transactions in block
    Transaction:
      type: object
      properties:
        blockHash:
          type: string
        blockNumber:
          type: integer
        from:
          type: string
        hash:
          type: string
        value:
          type: string
        nonce:
          type: integer
        r:
          type: string
        s:
          type: string
        v:
          type: string
        gas:
          type: integer
        gasUsed:
          type: integer
        gasPrice:
          type: string
        input:
          type: string
        transactionIndex:
          type: integer
        timestamp:
          type: integer
        cumulativeGasUsed:
          type: integer
        fee:
          type: integer
        status:
          type: boolean
        to:
          type: string
        contractAddress:
          type: string
    TransactionForAccountEndpoint:
      type: object
      properties:
        from:
          type: string
        hash:
          type: string
        value:
          type: string
        nonce:
          type: integer
        gasUsed:
          type: integer
        gasPrice:
          type: string
        timestamp:
          type: integer
        fee:
          type: integer
        to:
          type: string
        contractAddress:
          type: string
    Response with validation error:
      type: object
      properties:
        meta:
          type: object
          properties:
            code:
              type: integer
            success:
              type: boolean
            message:
              type: string
        data:
          type: object
          properties:
            additional:
              type: array
              items: 
                $ref: '#/components/schemas/ValidationErrorAdditionalObject'
    ValidationErrorAdditionalObject:
      type: object
      properties:
        value:
          type: string
        msg:
          type: string
        param:
          type: string
        location:
          type: string
    DelegatorObject:
      type: object
      properties:
        address:
          type: string
        amount:
          type: string
        claimedRewards:
          type: string
        createdEpoch:
          type: string
        createdTime:
          type: string
        deactivatedEpoch:
          type: string
        deactivatedTime:
          type: string
        toStakerID:
          type: string
        claimedReward:
          type: string
    StakerObject:
      type: object
      properties:
        address:
          type: string
        claimedRewards:
          type: string
        createdEpoch:
          type: string
        createdTime:
          type: string
        deactivatedEpoch:
          type: string
        deactivatedTime:
          type: string
        delegatedMe:
          type: string
        delegatorsClaimedRewards:
          type: string
        downtime:
          type: string
        id:
          type: string
        isCheater:
          type: boolean
        isValidator:
          type: boolean
        missedBlocks:
          type: string
        originationScore:
          type: string
        poi:
          type: string
        stake:
          type: string
        totalStake:
          type: string
        validationScore:
          type: string
        isActive:
          type: boolean
        isOffline:
          type: boolean
        baseRewardWeight:
          type: string
        txRewardWeight:
          type: string