openapi.yaml

openapi: 3.1.0
servers:
  - url: http://localhost:20443
    description: Local
info:
  title: Stacks 3.0+ RPC API
  version: '1.0.0'
  description: |
    This is the documentation for the `stacks-node` RPC interface.
  license:
    name: CC-0

paths:
  /v2/transactions:
    post:
      summary: Broadcast raw transaction
      tags:
        - Transactions
      description: Broadcast raw transactions on the network. You can use the [@stacks/transactions](https://github.com/blockstack/stacks.js) project to generate a raw transaction payload.
      operationId: post_core_node_transactions
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
            example: binary format of 00000000010400bed38c2aadffa348931bcb542880ff79d607afec000000000000000000000000000000c800012b0b1fff6cccd0974966dcd665835838f0985be508e1322e09fb3d751eca132c492bda720f9ef1768d14fdabed6127560ba52d5e3ac470dcb60b784e97dc88c9030200000000000516df0ba3e79792be7be5e50a370289accfc8c9e032000000000000303974657374206d656d6f00000000000000000000000000000000000000000000000000
      responses:
        "200":
          description: Transaction ID of successful post of a raw tx to the node's mempool
          content:
            text/plain:
              schema:
                type: string
                example: '"e161978626f216b2141b156ade10501207ae535fa365a13ef5d7a7c9310a09f2"'
        "400":
          description: Rejections result in a 400 error
          content:
            application/json:
              schema:
                $ref: ./api/transaction/post-core-node-transactions-error.schema.json
              example:
                $ref: ./api/transaction/post-core-node-transactions-error.example.json

  /v2/contracts/interface/{contract_address}/{contract_name}:
    get:
      summary: Get contract interface
      description: Get contract interface using a `contract_address` and `contract name`
      tags:
        - Smart Contracts
      operationId: get_contract_interface
      responses:
        "200":
          description: Contract interface
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-contract-interface.schema.json
              example:
                $ref: ./api/core-node/get-contract-interface.example.json
    parameters:
      - name: contract_address
        in: path
        required: true
        description: Stacks address
        schema:
          type: string
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
      - name: tip
        in: query
        schema:
          type: string
        description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
          known tip (includes unconfirmed state).
  /v2/map_entry/{contract_address}/{contract_name}/{map_name}:
    post:
      summary: Get specific data-map inside a contract
      tags:
        - Smart Contracts
      operationId: get_contract_data_map_entry
      description: |
        Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The map is identified with [Map Name].

        The key to lookup in the map is supplied via the POST body. This should be supplied as the hex string serialization of the key (which should be a Clarity value). Note, this is a JSON string atom.

        In the response, `data` is the hex serialization of the map response. Note that map responses are Clarity option types, for non-existent values, this is a serialized none, and for all other responses, it is a serialized (some ...) object.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-contract-data-map-entry.schema.json
              example:
                $ref: ./api/core-node/get-contract-data-map-entry.example.json
        "400":
          description: Failed loading data map
      parameters:
        - name: contract_address
          in: path
          required: true
          description: Stacks address
          schema:
            type: string
        - name: contract_name
          in: path
          required: true
          description: Contract name
          schema:
            type: string
        - name: map_name
          in: path
          required: true
          description: Map name
          schema:
            type: string
        - name: proof
          in: query
          description: Returns object without the proof field when set to 0
          schema:
            type: integer
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
            known tip (includes unconfirmed state).
      x-codegen-request-body-name: key
      requestBody:
        description: Hex string serialization of the lookup key (which should be a Clarity value)
        required: true
        content:
          application/json:
            schema:
              type: string

  /v2/contracts/source/{contract_address}/{contract_name}:
    get:
      summary: Get contract source
      tags:
        - Smart Contracts
      operationId: get_contract_source
      description: Returns the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-contract-source.schema.json
              example:
                $ref: ./api/core-node/get-contract-source.example.json
    parameters:
      - name: contract_address
        in: path
        required: true
        description: Stacks address
        schema:
          type: string
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
      - name: proof
        in: query
        description: Returns object without the proof field if set to 0
        schema:
          type: integer
      - name: tip
        in: query
        schema:
          type: string
        description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
          known tip (includes unconfirmed state).
        required: false

  /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}:
    post:
      summary: Call read-only function
      tags:
        - Smart Contracts
      operationId: call_read_only_function
      description: |
        Call a read-only public function on a given smart contract.

        The smart contract and function are specified using the URL path. The arguments and the simulated tx-sender are supplied via the POST body in the following JSON format:
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/contract/post-call-read-only-fn.schema.json
              examples:
                success:
                  $ref: ./api/contract/post-call-read-only-fn-success.example.json
                fail:
                  $ref: ./api/contract/post-call-read-only-fn-fail.example.json
      parameters:
        - name: contract_address
          in: path
          required: true
          description: Stacks address
          schema:
            type: string
        - name: contract_name
          in: path
          required: true
          description: Contract name
          schema:
            type: string
        - name: function_name
          in: path
          required: true
          description: Function name
          schema:
            type: string
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
            known tip (includes unconfirmed state).
          required: false
      requestBody:
        description: map of arguments and the simulated tx-sender where sender is either a Contract identifier or a normal Stacks address, and arguments is an array of hex serialized Clarity values.
        required: true
        content:
          application/json:
            schema:
              $ref: './entities/contracts/read-only-function-args.schema.json'
              example:
                sender: 'SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info'
                arguments:
                  - '0x0011...'
                  - '0x00231...'

  /v2/accounts/{principal}:
    get:
      summary: Get account info
      tags:
        - Accounts
      operationId: get_account_info
      description: |
        Get the account data for the provided principal

        Where balance is the hex encoding of a unsigned 128-bit integer (big-endian), nonce is a unsigned 64-bit integer, and the proofs are provided as hex strings.

        For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0.
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: proof
          in: query
          description: Returns object without the proof field if set to 0
          schema:
            type: integer
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
            known tip (includes unconfirmed state).
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-account-data.schema.json
              example:
                $ref: ./api/core-node/get-account-data.example.json

  /v2/fees/transaction:
    post:
      summary: Get approximate fees for the given transaction
      tags:
        - Fees
      description: |
        Get an estimated fee for the supplied transaction.  This
        estimates the execution cost of the transaction, the current
        fee rate of the network, and returns estimates for fee
        amounts.

        * `transaction_payload` is a hex-encoded serialization of
          the TransactionPayload for the transaction.
        * `estimated_len` is an optional argument that provides the
          endpoint with an estimation of the final length (in bytes)
          of the transaction, including any post-conditions and
          signatures

        If the node cannot provide an estimate for the transaction
        (e.g., if the node has never seen a contract-call for the
        given contract and function) or if estimation is not
        configured on this node, a 400 response is returned.
        The 400 response will be a JSON error containing a `reason`
        field which can be one of the following:

        * `DatabaseError` - this Stacks node has had an internal
          database error while trying to estimate the costs of the
          supplied transaction.
        * `NoEstimateAvailable` - this Stacks node has not seen this
          kind of contract-call before, and it cannot provide an
          estimate yet.
        * `CostEstimationDisabled` - this Stacks node does not perform
          fee or cost estimation, and it cannot respond on this
          endpoint.

        The 200 response contains the following data:

        * `estimated_cost` - the estimated multi-dimensional cost of
          executing the Clarity VM on the provided transaction.
        * `estimated_cost_scalar` - a unitless integer that the Stacks
          node uses to compare how much of the block limit is consumed
          by different transactions. This value incorporates the
          estimated length of the transaction and the estimated
          execution cost of the transaction. The range of this integer
          may vary between different Stacks nodes. In order to compute
          an estimate of total fee amount for the transaction, this
          value is multiplied by the same Stacks node's estimated fee
          rate.
        * `cost_scalar_change_by_byte` - a float value that indicates how
          much the `estimated_cost_scalar` value would increase for every
          additional byte in the final transaction.
        * `estimations` - an array of estimated fee rates and total fees to
          pay in microSTX for the transaction. This array provides a range of
          estimates (default: 3) that may be used. Each element of the array
          contains the following fields:
            * `fee_rate` - the estimated value for the current fee
              rates in the network
            * `fee` - the estimated value for the total fee in
              microSTX that the given transaction should pay. These
              values are the result of computing:
              `fee_rate` x `estimated_cost_scalar`.
              If the estimated fees are less than the minimum relay
              fee `(1 ustx x estimated_len)`, then that minimum relay
              fee will be returned here instead.


        Note: If the final transaction's byte size is larger than
        supplied to `estimated_len`, then applications should increase
        this fee amount by:

          `fee_rate` x `cost_scalar_change_by_byte` x (`final_size` - `estimated_size`)

      operationId: post_fee_transaction
      requestBody:
        content:
          application/json:
            schema:
              $ref: ./api/core-node/post-fee-transaction.schema.json
            example:
              $ref: ./api/core-node/post-fee-transaction.example.json
      responses:
        "200":
          description: Estimated fees for the transaction
          content:
            application/json:
              schema:
                $ref: ./api/core-node/post-fee-transaction-response.schema.json
              example:
                $ref: ./api/core-node/post-fee-transaction-response.example.json

  /v2/fees/transfer:
    get:
      summary: Get estimated fee
      tags:
        - Fees
      operationId: get_fee_transfer
      description: Get an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-fee-transfer.schema.json
              example:
                $ref: ./api/core-node/get-fee-transfer.example.json

  /v2/info:
    get:
      summary: Get Core API info
      description: Get Core API information
      tags:
        - Info
      operationId: get_core_api_info
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-info.schema.json
              example:
                $ref: ./api/core-node/get-info.example.json

  /v2/pox:
    get:
      summary: Get PoX details
      description: Get Proof of Transfer (PoX) information. Can be used for Stacking.
      tags:
        - Info
      operationId: get_pox_info
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-pox.schema.json
              example:
                $ref: ./api/core-node/get-pox.example.json
      parameters:
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
            known tip (includes unconfirmed state).

  /v2/traits/{contract_address}/{contract_name}/{trait_contract_address}/{trait_contract_name}/{trait_name}:
    get:
      summary: Get trait implementation details
      description: Determine whether or not a specified trait is implemented (either explicitly or implicitly) within a given contract.
      tags:
        - Smart Contracts
      operationId: get_is_trait_implemented
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/trait/get-is-trait-implemented.schema.json
              example:
                $ref: ./api/trait/get-is-trait-implemented.example.json
    parameters:
      - name: contract_address
        in: path
        required: true
        description: Stacks address
        schema:
          type: string
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
      - name: trait_contract_address
        in: path
        required: true
        description: Trait Stacks address
        schema:
          type: string
      - name: trait_contract_name
        in: path
        required: true
        description: Trait contract name
        schema:
          type: string
      - name: trait_name
        in: path
        required: true
        description: Trait name
        schema:
          type: string
      - name: tip
        in: query
        schema:
          type: string
        description: |
          The Stacks chain tip to query from.
          If tip == "latest", the query will be run from the latest known tip (includes unconfirmed state).
          If the tip is left unspecified, the stacks chain tip will be selected (only includes confirmed state).

  /v2/clarity/marf/{clarity_marf_key}:
    post:
      summary: Get the MARF value for a given key
      tags:
        - Smart Contracts
      operationId: get_clarity_marf_value
      description: |
        Attempt to fetch the value of a MARF key.

        In the response, `data` is the hex serialization of the value.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-clarity-marf-value.schema.json
              example:
                $ref: ./api/core-node/get-clarity-marf-value.example.json
        400:
          description: Failed to retrieve MARF key
      parameters:
        - name: clarity_marf_key
          in: path
          required: true
          description: MARF key
          schema:
            type: string
        - name: proof
          in: query
          description: Returns object without the proof field when set to 0
          schema:
            type: integer
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
            known tip (includes unconfirmed state).

  /v2/clarity/metadata/{contract_address}/{contract_name}/{clarity_metadata_key}:
    post:
      summary: Get the contract metadata for the metadata key
      tags:
        - Smart Contracts
      operationId: get_clarity_metadata_key
      description: |
        Attempt to fetch the metadata of a contract. The contract is identified with [Contract Address] and [Contract Name] in the URL path. The metadata key is identified with [Clarity Metadata Key].

        In the response, `data` is formatted as JSON.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-clarity-metadata.schema.json
              example:
                $ref: ./api/core-node/get-clarity-metadata.example.json
        400:
          description: Failed to retrieve constant value from contract
      parameters:
        - name: contract_address
          in: path
          required: true
          description: Stacks address
          schema:
            type: string
        - name: contract_name
          in: path
          required: true
          description: Contract name
          schema:
            type: string
        - name: clarity_metadata_key
          in: path
          required: true
          description: Metadata key
          schema:
            type: string
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
            known tip (includes unconfirmed state).

  /v2/constant_val/{contract_address}/{contract_name}/{constant_name}:
    post:
      summary: Get the value of a constant inside a contract
      tags:
        - Smart Contracts
      operationId: get_constant_val
      description: |
        Attempt to fetch the value of a constant inside a contract. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The constant is identified with [Constant Name].

        In the response, `data` is the hex serialization of the constant value.
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-constant-val.schema.json
              example:
                $ref: ./api/core-node/get-constant-val.example.json
        "400":
          description: Failed to retrieve constant value from contract
      parameters:
        - name: contract_address
          in: path
          required: true
          description: Stacks address
          schema:
            type: string
        - name: contract_name
          in: path
          required: true
          description: Contract name
          schema:
            type: string
        - name: constant_name
          in: path
          required: true
          description: Constant name
          schema:
            type: string
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest, the query will be run from the latest
            known tip (includes unconfirmed state).

  /v3/block_proposal:
    post:
      summary: Validate a proposed Stacks block
      tags:
        - Mining
      operationId: post_block_proposal
      description: |
        Used by stackers to validate a proposed Stacks block from a miner.

        **This API endpoint requires a basic Authorization header.**
      responses:
        "202":
          description: Block proposal has been accepted for processing.
            The result will be returned via the event observer.
          content:
            application/json:
              example:
                $ref: ./api/core-node/post-block-proposal-response.example.json
        "400":
          description: Endpoint not enabled.
        "401":
          description: Unauthorized.
        "429":
          description: There is an ongoing proposal validation being processed,
            the new request cannot be accepted until the prior request has been processed.
          content:
            application/json:
              example:
                $ref: ./api/core-node/post-block-proposal-response.429.json
      requestBody:
        content:
          application/json:
            example:
              $ref: ./api/core-node/post-block-proposal-req.example.json

  /v3/stacker_set/{cycle_number}:
    get:
      summary: Fetch the stacker and signer set information for a given cycle.
      tags:
        - Mining
      operationId: get_stacker_set
      description: |
        Used to get stacker and signer set information for a given cycle.

        This will only return information for cycles started in Epoch-2.5 where PoX-4 was active and subsequent cycles.
      parameters:
        - name: cycle_number
          in: path
          required: true
          description: reward cycle number
          schema:
            type: integer
      responses:
        "200":
          description: Information for the given reward cycle
          content:
            application/json:
              example:
                $ref: ./api/core-node/get_stacker_set.example.json
        "400":
          description: Could not fetch the given reward set
          content:
            application/json:
              example:
                $ref: ./api/core-node/get_stacker_set.400.example.json

  /v3/blocks/{block_id}:
    get:
      summary: Fetch a Nakamoto block
      tags:
        - Blocks
      operationId: get_block_v3
      description:
        Fetch a Nakamoto block by its index block hash.
      parameters:
        - name: block_id
          in: path
          description: The block's ID hash
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The raw SIP-003-encoded block will be returned.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: The block could not be found
          content:
            application/text-plain: {}

  /v3/blocks/height/{block_height}:
    get:
      summary: Fetch a Nakamoto block by its height and optional tip
      tags:
        - Blocks
      operationId: get_block_v3_by_height
      description:
        Fetch a Nakamoto block by its height and optional tip.
      parameters:
        - name: block_height
          in: path
          description: The block's height
          required: true
          schema:
            type: integer
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from. If tip == latest or empty, the query will be run
            from the latest known tip.
      responses:
        "200":
          description: The raw SIP-003-encoded block will be returned.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: The block could not be found
          content:
            application/text-plain: {}

  /v3/tenures/info:
    get:
      summary: Fetch metadata about the ongoing Nakamoto tenure
      tags:
        - Blocks
      operationId: get_tenure_info
      description:
        Fetch metadata about the ongoing Nakamoto tenure. This information is sufficient to obtain and authenticate the highest complete tenure, as well as obtain new tenure blocks.
      responses:
        "200":
          description: Metadata about the ongoing tenure
          content:
            application/json:
              example:
                $ref: ./api/core-node/get_tenure_info.json

  /v3/tenures/{block_id}:
    get:
      summary: Fetch a sequence of Nakamoto blocks in a tenure
      tags:
        - Blocks
      operationId: get_tenures
      description:
        Fetch a sequence of Nakamoto blocks in a tenure.  The blocks will be served in order from highest to lowest.  The blocks will be encoded in their SIP-003 wire format, and concatenated together.
      responses:
        "200":
          description: SIP-003-encoded Nakamoto blocks, concatenated together
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
    parameters:
      - name: block_id
        in: path
        description:
          The tenure-start block ID of the tenure to query
        required: true
        schema:
          type: string
      - name: stop
        in: query
        description:
          The block ID hash of the highest block in this tenure that is already known to the caller.  Neither the corresponding block nor any of its ancestors will be served.  This is used to fetch tenure blocks that the caller does not have.
        required: false
        schema:
          type: string

  /v3/sortitions/{lookup_kind}/{lookup}:
    get:
      summary: Fetch information about evaluated burnchain blocks (i.e., sortitions).
      tags:
        - Blocks
      operationId: get_sortitions
      description:
        Fetch sortition information about a burnchain block. If the `lookup_kind` and `lookup` parameters are empty, it will return information about the latest burn block.
      responses:
        "200":
          description: Information for the burn block or in the case of `latest_and_last`, multiple burn blocks
          content:
            application/json:
              examples:
                Latest:
                  description: A single element list is returned when just one sortition is requested
                  value:
                    $ref: ./api/core-node/get_sortitions.example.json
                LatestAndLast:
                  description: Sortition information about the latest burn block with a winning miner, and the previous such burn block.
                  value:
                    $ref: ./api/core-node/get_sortitions_latest_and_prior.example.json
    parameters:
      - name: lookup_kind
        in: path
        description: |-
          The style of lookup that should be performed. If not given, the most recent burn block processed will be returned.
          Otherwise, the `lookup_kind` should be one of the following strings:
            * `consensus` - find the burn block using the consensus hash supplied in the `lookup` field.
            * `burn_height` - find the burn block using the burn block height supplied in the `lookup` field.
            * `burn` - find the burn block using the burn block hash supplied in the `lookup` field.
            * `latest_and_last` - return information about the latest burn block with a winning miner *and* the previous such burn block
        required: false
        schema:
          type: string
      - name: lookup
        in: path
        description: The value to use for the lookup if `lookup_kind` is `consensus`, `burn_height`, or `burn`
        required: false
        schema:
          type: string
  /v3/signer/{signer}/{cycle_number}:
    get:
      summary: Get number of blocks signed by signer during a given reward cycle
      tags:
        - Blocks
        - Signers
      operationId: get_signer
      description: Get number of blocks signed by signer during a given reward cycle
      parameters:
        - name: signer
          in: path
          required: true
          description: Hex-encoded compressed Secp256k1 public key of signer
          schema:
            type: string
        - name: cycle_number
          in: path
          required: true
          description: Reward cycle number
          schema:
            type: integer
      responses:
        200:
          description: Number of blocks signed
          content:
            text/plain:
              schema:
                type: integer
                example: 7
  /v3/transaction/{txid}:
    post:
      summary: Retrieve transaction details by TXID
      tags:
        - Transactions
      description: Get a JSON with the transaction details including the `index_block_hash`, the hex-encoded transaction body, and the `result`.
      operationId: get_transaction
      parameters:
      - name: txid
        in: path
        required: true
        description: Transaction ID
        schema:
          type: string
      responses:
        "200":
          description: Transaction JSON with index_block_hash, transaction body and result
          content:
            application/json:
              example:
                $ref: ./api/core-node/get_transaction.json
        "404":
          description: Transaction not found
          content:
            application/text-plain: {}
        "501":
          description: Transaction indexing not enabled
          content:
            application/text-plain: {}