openapi: 3.0.0
info:
  title: Anchor API
  description: |-
    # Introduction
    This document discusses Klaytn API Service (KAS) Anchor API. Anchor API features functions for sending metadata to prove data reliability and ensuring the reliability of service chain data to the Klaytn main chain.




    # Error Codes

    ## 400: Bad Request

     | Code | Messages | 
     | --- | --- | 
     | 1071010 | data don't exist
    1071615 | its value is out of range; size
    1072100 | same payload ID or payload was already anchored
    1072101 | all configured accounts have insufficient funds | 

    # Authentication

    <!-- ReDoc-Inject: <security-definitions> -->
paths:
  /v1/anchor:
    post:
      description: It is used to anchor blockchain data. A preconfigured operator is used to create and manage anchoring transactions.
      parameters:
        - description: Klaytn chain network ID (1001 or 8217)
          in: header
          name: x-chain-id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                200 - Success:
                  summary: 200 - Success
                  description: ''
                  value:
                    status: succeed
              schema:
                $ref: '#/components/schemas/AnchorBlockStatus'
        '400':
          description: ''
          content:
            application/json:
              examples:
                400 - Insufficient funds:
                  summary: 400 - Insufficient funds
                  description: ''
                  value:
                    code: 1072101
                    message: all configured accounts have insufficient funds
                400 - Duplicated payload:
                  summary: 400 - Duplicated payload
                  description: ''
                  value:
                    code: 1072100
                    message: same payload ID or payload was already anchored
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Create Anchoring Transaction
      operationId: AnchorBlock
      tags:
        - Data Anchoring Transaction
      requestBody:
        $ref: '#/components/requestBodies/AnchorBlockRequest'
  '/v1/operator/{operator-id}/tx':
    get:
      description: |-
        Specify an operator ID to search for a list of transactions that were created by the operator.<p></p>

        ## Size<p></p>

        * The `size` query parameter is optional (minimum = 1, maximum = 1000, default = 100).<br>
        * Submitting negative values result in errors.<br>
        * Submitting zero results in a query with `size=100`, which is the default value.<br>
        * Submitting values greater than 1000 result in queries with `size=1000`, which is the maximum value.<br>
      parameters:
        - description: Klaytn chain network ID (1001 or 8217)
          in: header
          name: x-chain-id
          required: true
          schema:
            type: string
        - description: Maximum size of account to search
          in: query
          name: size
          required: false
          schema:
            type: integer
            format: int64
            maximum: 1000
            default: 100
          example: 100
        - description: Information on last searched cursor
          in: query
          name: cursor
          required: false
          schema:
            type: string
          example: ''
        - description: Timestamp of the start time to be searched (in seconds)
          in: query
          name: from-timestamp
          required: false
          schema:
            type: integer
            format: int64
        - description: Timestamp of the end time to be searched (in seconds)
          in: query
          name: to-timestamp
          required: false
          schema:
            type: integer
            format: int64
        - description: Operator account address
          in: path
          name: operator-id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                200 - Success:
                  summary: 200 - Success
                  description: ''
                  value:
                    cursor: ''
                    items:
                      - createdAt: 1599142860
                        payloadId: c61cc0d0-5878-450e-bec8-bf73d6184798
                        transactionHash: '0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d'
                      - createdAt: 1599142859
                        payloadId: d4f1a11f-4609-40f5-9d59-2313a5799508
                        transactionHash: '0x70f6f6745ad0b0f4ce5908f40d20a1f44bd34871e0428be782d84f9a53ea2ba0'
                      - createdAt: 1599142857
                        payloadId: 48b59825-82b2-4595-abfb-c465112618cc
                        transactionHash: '0x3f90cd2e02576fd85572ab76aff49b87b9cf3efb623f34bb8d6354ee1b88869f'
                      - createdAt: 1599142841
                        payloadId: b315de34-52cb-41c0-9383-3260ceafd3b2
                        transactionHash: '0x8a73a00f04a1f6e8d8af101487bd35f8dbcce6fcb3ddd95059f42b8f7fbc3345'
              schema:
                $ref: '#/components/schemas/AnchorTransactions'
        '400':
          description: ''
          content:
            application/json:
              examples:
                400 - Out of Range:
                  summary: 400 - Out of Range
                  description: ''
                  value:
                    code: 1071615
                    message: its value is out of range; size
                400 - No content:
                  summary: 400 - No content
                  description: ''
                  value:
                    code: 1071010
                    message: data don't exist
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Search List of Anchoring Transactions with Operator
      operationId: RetrieveAnchorBlock
      tags:
        - Data Anchoring Transaction
  '/v1/operator/{operator-id}/tx/{transaction-hash}':
    get:
      description: 'Specify a transaction hash value and operator ID to search for a list of transactions that were created by the operator. When creating a transaction, you may check the payload that is added to a transaction.'
      parameters:
        - description: Klaytn chain network ID (1001 or 8217)
          in: header
          name: x-chain-id
          required: true
          schema:
            type: string
        - description: Operator account address
          in: path
          name: operator-id
          required: true
          schema:
            type: string
        - description: Transaction hash
          in: path
          name: transaction-hash
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                200 - Success:
                  summary: 200 - Success
                  description: ''
                  value:
                    payload:
                      custom_field1: field1
                      custom_field2: field2
                      id: c61cc0d0-5878-450e-bec8-bf73d6184798
                    transactionHash: '0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d'
              schema:
                $ref: '#/components/schemas/AnchorTransactionDetail'
        '400':
          description: ''
          content:
            application/json:
              examples:
                400 - No content:
                  summary: 400 - No content
                  description: ''
                  value:
                    code: 1071010
                    message: data don't exist
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Search Anchoring Transactions with Transaction Hash
      operationId: GetAnchorBlockByTx
      tags:
        - Data Anchoring Transaction
  '/v1/operator/{operator-id}/payload/{payload-id}':
    get:
      description: 'Specify a payload ID and operator ID to search for a list of transactions that were created by the operator. When creating a transaction, you may check the payload that is added to a transaction.'
      parameters:
        - description: Klaytn chain network ID (1001 or 8217)
          in: header
          name: x-chain-id
          required: true
          schema:
            type: string
        - description: Operator account address
          in: path
          name: operator-id
          required: true
          schema:
            type: string
        - description: Payload ID
          in: path
          name: payload-id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                200 - Success:
                  summary: 200 - Success
                  description: ''
                  value:
                    payload:
                      custom_field1: field1
                      custom_field2: field2
                      id: c61cc0d0-5878-450e-bec8-bf73d6184798
                    transactionHash: '0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d'
              schema:
                $ref: '#/components/schemas/AnchorTransactionDetail'
        '400':
          description: ''
          content:
            application/json:
              examples:
                400 - No content:
                  summary: 400 - No content
                  description: ''
                  value:
                    code: 1071010
                    message: data don't exist
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Search Anchoring Transactions with Payload
      operationId: GetAnchorBlockByPayloadID
      tags:
        - Data Anchoring Transaction
  /v1/operator:
    get:
      description: |-
        Search for a list of created operators and the settings of each of them.<p></p>

        ## Size<p></p>

        * The `size` query parameter is optional (minimum = 1, maximum = 1000, default = 100).<br>
        * Submitting negative values result in errors.<br>
        * Submitting zero results in a query with `size=100`, which is the default value.<br>
        * Submitting values greater than 1000 result in queries with `size=1000`, which is the maximum value.<br>
      parameters:
        - description: Klaytn chain network ID (1001 or 8217)
          in: header
          name: x-chain-id
          required: true
          schema:
            type: string
        - description: Maximum size of account to search
          in: query
          name: size
          required: false
          schema:
            type: integer
            format: int64
            maximum: 1000
            default: 100
          example: 10
        - description: Information on last searched cursor
          in: query
          name: cursor
          required: false
          schema:
            type: string
          example: ''
        - description: Timestamp of the start time to be searched (in seconds)
          in: query
          name: from-timestamp
          required: false
          schema:
            type: integer
            format: int64
        - description: Timestamp of the end time to be searched (in seconds)
          in: query
          name: to-timestamp
          required: false
          schema:
            type: integer
            format: int64
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                200 - Success:
                  summary: 200 - Success
                  description: ''
                  value:
                    cursor: ''
                    items:
                      - createdAt: 1600156363
                        operator: '0x36C144b998FbEF7faf092b01815194a18e1a1163'
                        setting:
                          useGlobalFeePayer: true
                          useOperator: true
                      - createdAt: 1600156362
                        operator: '0xfD522BE38Ae3Ec4F84A7A411A9e2b3Aee81317b5'
                        setting:
                          useGlobalFeePayer: true
                          useOperator: true
                      - createdAt: 1600156361
                        operator: '0xA54579E74e4709600AA7fb91D4cfefb1aECFF9ee'
                        setting:
                          useGlobalFeePayer: true
                          useOperator: true
                      - createdAt: 1600156360
                        operator: '0xBBe7d40917d99eF1581b3abc7cdA69492C860F1F'
                        setting:
                          useGlobalFeePayer: true
                          useOperator: true
                      - createdAt: 1600156359
                        operator: '0xc72408058DAC1343B8C99Ca90Cb58Ea89637C1eE'
                        setting:
                          useGlobalFeePayer: true
                          useOperator: true
                      - createdAt: 1600156351
                        operator: '0x8f315315F90B0b3dEA038FC659F07bac62Fcb2f6'
                        setting:
                          useGlobalFeePayer: true
                          useOperator: true
              schema:
                $ref: '#/components/schemas/Operators'
        '400':
          description: ''
          content:
            application/json:
              examples:
                400 - Out of Range:
                  summary: 400 - Out of Range
                  description: ''
                  value:
                    code: 1071615
                    message: its value is out of range; size
                400 - No content:
                  summary: 400 - No content
                  description: ''
                  value:
                    code: 1071010
                    message: data don't exist
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      summary: Search List of All Operators
      operationId: RetrieveOperators
      tags:
        - Operator
  '/v1/operator/{operator-id}':
    get:
      description: Search for the settings of a specific operator.
      parameters:
        - description: Klaytn chain network ID (1001 or 8217)
          in: header
          name: x-chain-id
          required: true
          schema:
            type: string
        - description: Operator account address
          in: path
          name: operator-id
          required: true
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              examples:
                200 - Success:
                  summary: 200 - Success
                  description: ''
                  value:
                    operator: '0x6945B46Add33ABD0576b4D99B4c86Fe28c0Ad026'
                    setting:
                      useGlobalFeePayer: true
                      useOperator: true
              schema:
                $ref: '#/components/schemas/Operator'
      summary: Search Specific Operator
      operationId: GetOperator
      tags:
        - Operator
tags: []
servers:
  - url: 'https://anchor-api.klaytnapi.com'
components:
  schemas:
    AnchorBlockStatus:
      type: object
      description: Anchoring state response
      properties:
        status:
          type: string
          example: succeed
          description: Anchoring success/failure
      title: AnchorBlockStatus
      required:
        - status
    ErrorResponse:
      type: object
      description: This response contains error description.
      properties:
        code:
          type: integer
          format: int64
          example: 1072101
          description: Service code (first 3 digits) and error code (last 4 digits)
        message:
          type: string
          example: all configured accounts have insufficient funds
          description: Error message
      title: ErrorResponse
      required:
        - code
        - message
    AnchorBlockRequest:
      type: object
      description: Anchor block request schema
      properties:
        operator:
          type: string
          example: '0x426Cd8fF0672225c7e96E0bD2f9175B05790653d'
          description: Operator account address
        payload:
          $ref: '#/components/schemas/AnchorBlockPayload'
      title: AnchorBlockRequest
      required:
        - operator
        - payload
    AnchorBlockPayload:
      type: object
      description: Anchor data. ID is set to SHA256 (payload) by default if an ID is not provided. It receives a string-type ID value and determines that it is not set if it is not a string type.
      title: AnchorBlockPayload
      additionalProperties: {}
    AnchorTransactions:
      type: object
      description: List of anchoring transactions
      properties:
        cursor:
          type: string
          example: ''
          description: Cursor information on last searched location
        items:
          type: array
          items:
            $ref: '#/components/schemas/AnchorTransaction'
      title: AnchorTransactions
      required:
        - cursor
    AnchorTransaction:
      type: object
      description: Anchoring transaction information
      properties:
        createdAt:
          type: integer
          format: int64
          example: 1599142860
          description: Anchoring transaction creation time
        payloadId:
          type: string
          example: c61cc0d0-5878-450e-bec8-bf73d6184798
          description: Payload ID
        transactionHash:
          type: string
          example: '0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d'
          description: Transaction hash of anchoring transaction
      title: AnchorTransaction
      required:
        - createdAt
        - payloadId
        - transactionHash
    AnchorTransactionDetail:
      type: object
      description: Anchoring transaction information
      properties:
        payload:
          $ref: '#/components/schemas/AnchorBlockPayload'
        transactionHash:
          type: string
          example: '0x5aeb4ddc5d77b9ce977a87461573da00c0aed0ac59962892ecf58ec09296e79d'
          description: Transaction hash of anchoring transaction
      title: AnchorTransactionDetail
      required:
        - payload
        - transactionHash
    Operators:
      type: object
      description: List of operators
      properties:
        cursor:
          type: string
          example: ''
          description: Cursor information on last searched location
        items:
          type: array
          items:
            $ref: '#/components/schemas/Operator'
      title: Operators
      required:
        - cursor
    Operator:
      type: object
      description: Operator information
      properties:
        createdAt:
          type: integer
          format: int64
          example: 1600156363
          description: Operator creation time
        operator:
          type: string
          example: '0x36C144b998FbEF7faf092b01815194a18e1a1163'
          description: Operator’s Klaytn account address
        setting:
          $ref: '#/components/schemas/OperatorSetting'
      title: Operator
      required:
        - createdAt
        - operator
    OperatorSetting:
      type: object
      description: Operator payment information
      properties:
        useGlobalFeePayer:
          type: boolean
          example: true
          description: Global fee delegation account enabled/disabled
        useOperator:
          type: boolean
          example: true
          description: Operator payment enabled/disabled
      title: OperatorSetting
      required:
        - useGlobalFeePayer
        - useOperator
  securitySchemes:
    basic:
      description: |+
        KAS uses Basic HTTP Auth. All requests MUST have a valid Authorization header where its value is derived from KAS account's access key ID (as `username`) and secret access key (as `password`).
        Please note that it is your responsibility to keep your KAS API access keys safe. Do not share your KAS credentials with others as they provide full access to all KAS services and APIs including executing transactions and transferring your KLAY and KCT funds deposited in accounts managed by KAS Wallet API.
        ### cURL
        ```
          curl --location --request GET 'https://https://anchor-api.klaytnapi.com/v1/operator/:operator-id/tx' \
          -u ${your_accessKeyId}:${your_secretAccessKey} \
          --header 'x-chain-id: {{chain-id}}' \
          --header 'Content-Type: application/json'
        ```

      type: http
      scheme: basic
  requestBodies:
    AnchorBlockRequest:
      content:
        application/json:
          examples:
            200 - Success:
              value:
                operator: '0x426Cd8fF0672225c7e96E0bD2f9175B05790653d'
                payload:
                  id: unique_custom_id
                  custom_field1: field1
                  custom_field2: field2
            400 - Insufficient funds:
              value:
                operator: '0x84ddfb88a28de014d5fea114dc1efb06ce99cc42'
                payload:
                  id: custom_id
                  custom_field1: field1
                  custom_field2: field2
            400 - Duplicated payload:
              value:
                operator: '0x426Cd8fF0672225c7e96E0bD2f9175B05790653d'
                payload:
                  id: custom_id
                  custom_field1: field1
                  custom_field2: field2
          schema:
            $ref: '#/components/schemas/AnchorBlockRequest'
security:
  - basic: []
