openapi: 3.0.3
info:
  description: |-
    The Chia node and services come with a JSON RPC API server that allows you to access information and control the services.  These are accessible via HTTPS, WebSockets, or via client SDKs. The ports can be configured in `~/.chia/mainnet/config/config.yaml`.  The RPC ports should not be exposed to the internet. TLS certificates are used to secure the communication  [using mutualTLS](https://github.com/dkackman/chia-api/wiki/Mutual-TLS).
    The farmer uses port 8559 by default.
  version: 2.0.0
  title: Chia RPC
  termsOfService: https://www.chia.net/assets/legal/Guidelines-for-Using-Chia-Network.pdf
  contact:
    name: Chia Network
    url: https://www.chia.net/
    email: hello@chia.net
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://localhost:8559
    description: Farmer RPC
security:
  - bearerAuth: []
tags:
  - name: Shared
    description: Methods shared by all services.
  - name: Farmer
    description: The farmer RPC API is exposed, by default, on port 8559 and contains methods for managing the farmer.
externalDocs:
  description: Find out more about chia
  url: https://chia.net
paths:
  /stop_node:
    post:
      tags:
        - Shared
      summary: Stop the node.
      description: Stop the node.
      operationId: stop_node
      requestBody:
        description: Empty request body
        required: true
        content: &ref_1
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: OK response without return values
          content: &ref_0
            application/json:
              schema:
                type: object
                description: Success indicator and optional error message included in all responses
                required: &ref_2
                  - success
                properties: &ref_3
                  success:
                    type: boolean
                    description: Success/failure indicator
                  error:
                    type: string
                    description: Only present when success is false
  /open_connection:
    post:
      tags:
        - Shared
      summary: Add a connection to another node.
      description: Add a connection to another node.
      operationId: open_connection
      requestBody:
        required: true
        description: the address of the connection
        content:
          application/json:
            schema:
              type: object
              required:
                - ip
                - port
              properties:
                ip:
                  type: string
                  format: ipaddress
                port:
                  type: integer
      responses:
        '200':
          description: OK response without return values
          content: *ref_0
  /close_connection:
    post:
      tags:
        - Shared
      summary: Removes a connection.
      description: Removes a connection.
      operationId: close_connection
      requestBody:
        required: true
        description: the node id of the connection
        content:
          application/json:
            schema:
              type: object
              required:
                - node_id
              properties:
                node_id:
                  type: string
      responses:
        '200':
          description: OK response without return values
          content: *ref_0
  /get_connections:
    post:
      tags:
        - Shared
      summary: Retrieve the list of connections.
      description: Retrieve the list of connections.
      operationId: get_connections
      requestBody:
        description: Empty request body
        required: true
        content: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      connections:
                        type: array
                        items:
                          type: object
                          description: Chia's representation of a connection from node to node.
                          properties: &ref_11
                            bytes_read:
                              type: integer
                              format: uint32
                              nullable: true
                            bytes_written:
                              type: integer
                              format: uint32
                              nullable: true
                            creation_time:
                              type: number
                              format: double
                            last_message_time:
                              type: number
                              format: double
                            local_port:
                              type: integer
                              format: int32
                            node_id:
                              type: string
                            peak_hash:
                              type: string
                            peak_height:
                              type: integer
                              format: uint64
                              nullable: true
                            peak_weight:
                              type: integer
                              format: uint64
                              nullable: true
                            peer_host:
                              type: string
                            peer_port:
                              type: integer
                              format: int32
                            peer_server_port:
                              type: integer
                              format: int32
                            type:
                              type: integer
                              enum: &ref_18
                                - 1
                                - 2
                                - 3
                                - 4
                                - 5
                                - 6
                                - 7
                              description: |-
                                The type of node:
                                  * 1 FULL_NODE
                                  * 2 HARVESTER
                                  * 3 FARMER
                                  * 4 TIMELORD
                                  * 5 INTRODUCER
                                  * 6 WALLET
                                  * 7 DATA_LAYER
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /healthz:
    post:
      tags:
        - Shared
      summary: Heartbeat.
      description: Heartbeat.
      operationId: healthz
      requestBody:
        description: Empty request body
        required: true
        content: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: Success indicator and optional error message included in all responses
                required: *ref_2
                properties: *ref_3
  /get_routes:
    post:
      tags:
        - Shared
      summary: Retrieve the list of routes exposed by the service.
      description: Retrieve the list of routes/endpoints exposed by the service.
      operationId: get_routes
      requestBody:
        description: Empty request body
        required: true
        content: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      routes:
                        type: array
                        items:
                          type: string
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /set_reward_targets:
    post:
      tags:
        - Farmer
      summary: Set the farm and pool reward targets.
      description: Set the farm and pool reward targets.
      operationId: set_reward_targets
      requestBody:
        description: The updated targets
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                farmer_target:
                  type: string
                pool_target:
                  type: string
      responses:
        '200':
          description: OK response without return values
          content: *ref_0
  /get_reward_targets:
    post:
      tags:
        - Farmer
      summary: Get the farm and pool reward targets.
      description: Get the farm and pool reward targets.
      operationId: get_reward_targets
      requestBody:
        description: indicator of whether to include private keys in the search
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - search_for_private_key
              properties:
                search_for_private_key:
                  type: boolean
                max_ph_to_search:
                  type: integer
                  format: int32
                  default: 500
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    required:
                      - farmer_target
                      - pool_target
                    properties:
                      farmer_target:
                        type: string
                      pool_target:
                        type: string
                      have_farmer_sk:
                        type: boolean
                      have_pool_sk:
                        type: boolean
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_harvesters:
    post:
      tags:
        - Farmer
      summary: Get the list of harvesters.
      description: Get the list of harvesters.
      operationId: get_harvesters
      requestBody:
        description: Empty request body
        required: true
        content: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      harvesters:
                        type: array
                        items:
                          type: object
                          properties: &ref_12
                            connection:
                              type: object
                              properties: &ref_4
                                host:
                                  type: string
                                node_id:
                                  type: string
                                port:
                                  type: integer
                                  format: int32
                            last_sync_time:
                              type: number
                              format: double
                            total_plot_size:
                              type: integer
                              format: int64
                            syncing:
                              type: object
                              properties:
                                initial:
                                  type: boolean
                                plot_files_processed:
                                  type: integer
                                  format: uint32
                                plot_files_total:
                                  type: integer
                                  format: uint32
                            failed_to_open_filenames:
                              type: array
                              items:
                                type: string
                            no_key_filenames:
                              type: array
                              items:
                                type: string
                            plots:
                              type: array
                              items:
                                type: object
                                description: Info about a plot file
                                properties: &ref_5
                                  file_size:
                                    type: integer
                                    format: uint64
                                  filename:
                                    type: string
                                  plot_id:
                                    type: string
                                  plot_public_key:
                                    type: string
                                    nullable: true
                                  pool_contract_puzzle_hash:
                                    type: string
                                  pool_public_key:
                                    type: string
                                    nullable: true
                                  size:
                                    type: integer
                                    description: Defines the size of a plot. 25 is used for testing only. https://github.com/Chia-Network/chia-blockchain/wiki/k-sizes
                                    default: 32
                                    enum: &ref_9
                                      - 25
                                      - 32
                                      - 33
                                      - 34
                                      - 35
                                  time_modified:
                                    type: number
                                    format: double
                            duplicates:
                              type: array
                              items:
                                type: string
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_harvesters_summary:
    post:
      tags:
        - Farmer
      summary: Get a summary of harvesters.
      description: Get a summary of harvesters, similar to get_harvests but with plot counts only.
      operationId: get_harvesters_summary
      requestBody:
        description: Empty request body
        required: true
        content: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      harvesters:
                        type: array
                        items:
                          type: object
                          properties: &ref_13
                            connection:
                              type: object
                              properties: *ref_4
                            last_sync_time:
                              type: number
                              format: double
                            total_plot_size:
                              type: integer
                              format: int64
                            syncing:
                              type: object
                              properties:
                                initial:
                                  type: boolean
                                plot_files_processed:
                                  type: integer
                                  format: uint32
                                plot_files_total:
                                  type: integer
                                  format: uint32
                            plots:
                              type: integer
                              format: int32
                            failed_to_open_filenames:
                              type: integer
                              format: int32
                            no_keys_filenames:
                              type: integer
                              format: int32
                            duplicates:
                              type: integer
                              format: int32
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_harvester_plots_valid:
    post:
      tags:
        - Farmer
      summary: Get a paginated list of valid plots.
      description: Get a paginated list of valid plots.
      operationId: get_harvester_plots_valid
      requestBody:
        description: Search filter parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_15
                node_id:
                  type: string
                  format: hex
                page:
                  type: integer
                  format: int32
                page_size:
                  type: integer
                  format: int32
                filter:
                  type: array
                  items:
                    type: object
                    properties: &ref_19
                      key:
                        type: string
                      value:
                        type: string
                sort_key:
                  type: string
                  default: filename
                reverse:
                  type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties: &ref_6
                      node_id:
                        type: string
                        format: hex
                      page:
                        type: integer
                        format: int32
                      page_count:
                        type: integer
                        format: int32
                      total_count:
                        type: integer
                        format: int32
                      plots:
                        type: array
                        items:
                          type: object
                          description: Info about a plot file
                          properties: *ref_5
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_harvester_plots_invalid:
    post:
      tags:
        - Farmer
      summary: Get a paginated list of invalid plots.
      description: Get a paginated list of invalid plots.
      operationId: get_harvester_plots_invalid
      requestBody:
        description: Search filter parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_7
                node_id:
                  type: string
                  format: hex
                page:
                  type: integer
                  format: int32
                page_size:
                  type: integer
                  format: int32
                filter:
                  type: array
                  items:
                    type: string
                reverse:
                  type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties: *ref_6
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_harvester_plots_keys_missing:
    post:
      tags:
        - Farmer
      summary: Get a paginated list of plots with missing keys.
      description: Get a paginated list of invalid plots with missing keys.
      operationId: get_harvester_plots_keys_missing
      requestBody:
        description: Search filter parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: *ref_7
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties: *ref_6
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_harvester_plots_duplicates:
    post:
      tags:
        - Farmer
      summary: Get a paginated list of duplicate plots.
      description: Get a paginated list of duplicate plots.
      operationId: get_harvester_plots_duplicates
      requestBody:
        description: Search filter parameters
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: *ref_7
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties: *ref_6
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_pool_login_link:
    post:
      tags:
        - Farmer
      summary: Get's the pool login link, if any.
      description: Get's the pool login link, if any.
      operationId: get_pool_login_link
      requestBody:
        description: The id of the pool launcher
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - launcher_id
              properties:
                launcher_id:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      login_link:
                        type: string
                        format: url
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_pool_state:
    post:
      tags:
        - Farmer
      summary: Get's the state of the pool.
      description: Get's the state of the pool.
      operationId: get_pool_state
      requestBody:
        description: Empty request body
        required: true
        content: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      pool_state:
                        type: object
                        properties: &ref_14
                          authentication_token_timeout:
                            type: integer
                            format: uint8
                            nullable: true
                          current_difficulty:
                            type: integer
                            format: uint64
                            nullable: true
                          current_points:
                            type: integer
                            format: uint64
                          next_farmer_update:
                            type: number
                            format: double
                          next_pool_info_update:
                            type: number
                            format: double
                          points_acknowledged24h:
                            type: array
                            items:
                              type: object
                              properties: &ref_8
                                time_found:
                                  type: number
                                  format: double
                                difficulty:
                                  type: integer
                                  format: uint64
                          points_acknowledged_since_start:
                            type: integer
                            format: uint64
                          points_found24h:
                            type: array
                            items:
                              type: object
                              properties: *ref_8
                          points_found_since_start:
                            type: integer
                            format: uint64
                          pool_config:
                            type: object
                            description: This is what goes into the user's config file, to communicate between the wallet and the farmer processes.
                            properties: &ref_20
                              launcher_id:
                                type: string
                              pool_url:
                                type: string
                                format: url
                              payout_instructions:
                                type: string
                              target_puzzle_hash:
                                type: string
                              p2_singleton_puzzle_hash:
                                type: string
                              owner_public_key:
                                type: string
                              authentication_public_key:
                                type: string
                          pool_errors24h:
                            type: array
                            items:
                              type: object
                              description: Response in error case for all endpoints of the pool protocol
                              properties: &ref_21
                                error_code:
                                  type: integer
                                  format: uint16
                                error_message:
                                  type: string
                          plot_count:
                            type: integer
                            format: int32
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /set_payout_instructions:
    post:
      tags:
        - Farmer
      summary: Set's a pool's payout instructions.
      description: Set's a pool's payout instructions.
      operationId: set_payout_instructions
      requestBody:
        description: The id of the pool launcher and payout instructions
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - launcher_id
                - payout_instructions
              properties:
                launcher_id:
                  type: string
                payout_instructions:
                  type: string
      responses:
        '200':
          description: OK response without return values
          content: *ref_0
  /get_signage_point:
    post:
      tags:
        - Farmer
      summary: Get's a signage point by hash.
      description: Get's a signage point by hash.
      operationId: get_signage_point
      requestBody:
        description: The signage point hash
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - sp_hash
              properties:
                sp_hash:
                  type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties: &ref_10
                      signage_point:
                        type: object
                        description: The farmer api's defintion of a signage point. Not the same as signage_point.
                        properties: &ref_17
                          challenge_chain_sp:
                            type: string
                          challenge_hash:
                            type: string
                          difficulty:
                            type: integer
                            format: uint64
                          reward_chain_sp:
                            type: string
                          signage_point_index:
                            type: integer
                            format: uint8
                          sub_slot_iters:
                            type: integer
                            format: uint64
                      proofs:
                        type: array
                        items:
                          oneOf:
                            - type: string
                            - type: object
                              properties: &ref_16
                                challenge:
                                  type: string
                                  example: '0xad43c12b5c5a480ee93992697bd8c9153d536007b0ffac024341cd8ca853a9e3'
                                public_pool_key:
                                  type: string
                                pool_contract_puzzle_hash:
                                  type: string
                                  example: '0x71afdce401a0f2a6f03de6287902eacfa38502d6667b04da36e32c3930171ce4'
                                plot_public_key:
                                  type: string
                                  example: '0x8b5f3cd22bf5073e12f285d2a0e9bbfb485fea8f3ede2f5573e44168fadbb91b71cef1dffc03758a5241c47b105df81a'
                                size:
                                  type: integer
                                  description: Defines the size of a plot. 25 is used for testing only. https://github.com/Chia-Network/chia-blockchain/wiki/k-sizes
                                  default: 32
                                  enum: *ref_9
                                proof:
                                  type: string
                                  example: '0xa84606d3dba86cbc1c2f56d05175bbbcb970629380bec5c49ad46f0c5f067e4ba74101ac24f0e09fb73ce0ebc9249436c528b5fab689d94c4213072e2acfc1c3a6f17763b16304234002ce471da4ce7e888e2f5abadf4d7f48cd157294ce03cb28df0f45597ca5460cd66c772c7650f2d170d08a5898fe65623b33aac864f44d2a39bcf074e62866edccf9b424f9a8ca56c9a98e87d48fb02b933af951284d610ff1eb71e730a05c2f6c7be86fd4df7efb26e8fb2e573981d8ad866adc02a82ffb0d7ff106c9c78f9cea08f4a2de9db2607266edf6e807924edf9af0f36b8938d97865072126011b67646b4d0e206b706d3a3e67e8862cb0502520f1ad1b4341'
                          minItems: 2
                          maxItems: 2
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
  /get_signage_points:
    post:
      tags:
        - Farmer
      summary: Get signage points.
      description: Get signage points.
      operationId: get_signage_points
      requestBody:
        description: Empty request body
        required: true
        content: *ref_1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      signage_points:
                        type: array
                        items:
                          type: object
                          properties: *ref_10
                  - type: object
                    description: Success indicator and optional error message included in all responses
                    required: *ref_2
                    properties: *ref_3
components:
  requestBodies:
    empty:
      description: Empty request body
      required: true
      content: *ref_1
  responses:
    empty:
      description: OK response without return values
      content: *ref_0
  schemas:
    connection_info:
      type: object
      description: Chia's representation of a connection from node to node.
      properties: *ref_11
    harvester_info:
      type: object
      properties: *ref_12
    harvester_summary:
      type: object
      properties: *ref_13
    paginated_plot_request:
      type: object
      properties: *ref_6
    pool_state_info:
      type: object
      properties: *ref_14
    plot_info_request_data:
      type: object
      properties: *ref_15
    plot_path_request_data:
      type: object
      properties: *ref_7
    proof_of_space:
      type: object
      properties: *ref_16
    farmer_signage_point:
      type: object
      description: The farmer api's defintion of a signage point. Not the same as signage_point.
      properties: *ref_17
    signage_point_bundle:
      type: object
      properties: *ref_10
    apiResponse:
      type: object
      description: Success indicator and optional error message included in all responses
      required: *ref_2
      properties: *ref_3
    node_type:
      type: integer
      enum: *ref_18
      description: |-
        The type of node:
          * 1 FULL_NODE
          * 2 HARVESTER
          * 3 FARMER
          * 4 TIMELORD
          * 5 INTRODUCER
          * 6 WALLET
          * 7 DATA_LAYER
    harvester_connection:
      type: object
      properties: *ref_4
    k_size:
      type: integer
      description: Defines the size of a plot. 25 is used for testing only. https://github.com/Chia-Network/chia-blockchain/wiki/k-sizes
      default: 32
      enum: *ref_9
    plot_info:
      type: object
      description: Info about a plot file
      properties: *ref_5
    filter_item:
      type: object
      properties: *ref_19
    pool_point:
      type: object
      properties: *ref_8
    pool_wallet_config:
      type: object
      description: This is what goes into the user's config file, to communicate between the wallet and the farmer processes.
      properties: *ref_20
    error_response:
      type: object
      description: Response in error case for all endpoints of the pool protocol
      properties: *ref_21
  securitySchemes:
    bearerAuth:
      type: http
      scheme: mutual
      description: '-> Chia uses [mutualTLS bearerAuth](https://github.com/dkackman/chia-api/wiki/Mutual-TLS) where client and server share TLS keys.'