stacks-blockchain-api/docs/openapi.yaml

openapi: 3.0.2
servers:
  - url: https://api.mainnet.hiro.so/
    description: Mainnet
  - url: https://api.testnet.hiro.so/
    description: Testnet
  - url: http://localhost:3999/
    description: Local
info:
  title: Stacks Blockchain API
  version: 'STACKS_API_VERSION'
  description: |
    Welcome to the API reference overview for the <a href="https://docs.hiro.so/get-started/stacks-blockchain-api">Stacks Blockchain API</a>.

    <a href="https://hirosystems.github.io/stacks-blockchain-api/collection.json" download="stacks-api-collection.json">Download Postman collection</a>
tags:
  - name: Accounts
    description: Read-only endpoints to obtain Stacks account details
    externalDocs:
      description: Stacks Documentation - Accounts
      url: https://docs.stacks.co/understand-stacks/accounts
  - name: Blocks
    description: Read-only endpoints to obtain Stacks block details
  - name: Faucets
    description: Endpoints to request STX or BTC tokens (not possible on Mainnet)
  - name: Fees
    description: Read-only endpoints to obtain fee details
  - name: Fungible Tokens
    description: Read-only endpoints to obtain fungible token details
    externalDocs:
      description: Stacks Documentation - Tokens
      url: https://docs.stacks.co/write-smart-contracts/tokens
  - name: Info
    description: Read-only endpoints to obtain network, Proof-of-Transfer, Stacking, STX token, and node information
  - name: Microblocks
    description: Read-only endpoints to obtain microblocks details
    externalDocs:
      description: Stacks Documentation - Microblocks
      url: https://docs.stacks.co/understand-stacks/microblocks
  - name: Names
    description: Read-only endpoints realted to the Blockchain Naming System on Stacks
    externalDocs:
      description: Stacks Documentation - Blockchain Naming System
      url: https://docs.stacks.co/build-apps/references/bns
  - name: Non-Fungible Tokens
    description: Read-only endpoints to obtain non-fungible token details
    externalDocs:
      description: Stacks Documentation - Tokens
      url: https://docs.stacks.co/write-smart-contracts/tokens
  - name: Rosetta
    description: Endpoints to support the Rosetta API open blockchain standard
    externalDocs:
      description: Hiro Documentation - Rosetta Support
      url: https://docs.hiro.so/get-started/stacks-blockchain-api#rosetta-support
  - name: Search
    description: Read-only endpoints to search for accounts, blocks, smart contracts, and transactions
  - name: Smart Contracts
    description: Read-only endpoints to obtain Clarity smart contract details
    externalDocs:
      description: Stacks Documentation - Clarity Smart Contracts
      url: https://docs.stacks.co/write-smart-contracts/overview
  - name: Stacking Rewards
    description: Read-only endpoints to obtain Stacking reward details
    externalDocs:
      description: Stacks Documentation - Stacking
      url: https://docs.stacks.co/understand-stacks/stacking
  - name: Transactions
    description: Endpoints to obtain transaction details and to broadcast transactions to the network
    externalDocs:
      description: Hiro Documentation - Transactions
      url: https://docs.hiro.so/get-started/transactions

paths:
  /extended/v1/faucets/stx:
    parameters:
      - name: address
        in: query
        description: A valid testnet STX address
        required: true
        schema:
          type: string
          example: ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ
      - name: stacking
        in: query
        description: Request the amount of STX tokens needed for individual address stacking
        required: false
        schema:
          type: boolean
          default: false
    post:
      summary: Get STX testnet tokens
      description: |
        Add 500 STX tokens to the specified testnet address. Testnet STX addresses begin with `ST`. If the `stacking`
        parameter is set to `true`, the faucet will add the required number of tokens for individual stacking to the
        specified testnet address.

        The endpoint returns the transaction ID, which you can use to view the transaction in the
        [Stacks Explorer](https://explorer.hiro.so/?chain=testnet). The tokens are delivered once the transaction has
        been included in an anchor block.

        A common reason for failed faucet transactions is that the faucet has run out of tokens. If you are experiencing
        failed faucet transactions to a testnet address, you can get help in [Discord](https://stacks.chat).

        **Note:** This is a testnet only endpoint. This endpoint will not work on the mainnet.
      tags:
        - Faucets
      operationId: run_faucet_stx
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  description: STX testnet address
                  type: string
                stacking:
                  description: Use required number of tokens for stacking
                  type: boolean
              example:
                address: ST3M7N9Q9HDRM7RVP1Q26P0EE69358PZZAZD7KMXQ
                stacking: false
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/faucet/run-faucet.schema.json
              example:
                $ref: ./api/faucet/run-faucet.example.json
        500:
          description: Faucet call failed
  /extended/v1/faucets/btc:
    parameters:
      - name: address
        in: query
        description: A valid testnet BTC address
        required: true
        schema:
          type: string
          example: "2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts"
    post:
      summary: Add testnet BTC tokens to address
      description: |
        Add 1 BTC token to the specified testnet BTC address.

        The endpoint returns the transaction ID, which you can use to view the transaction in a testnet Bitcoin block
        explorer. The tokens are delivered once the transaction has been included in a block.

        **Note:** This is a testnet only endpoint. This endpoint will not work on the mainnet.
      tags:
        - Faucets
      operationId: run_faucet_btc
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                address:
                  description: BTC testnet address
                  type: string
              example:
                address: 2N4M94S1ZPt8HfxydXzL2P7qyzgVq7MHWts
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/faucet/run-faucet.schema.json
              example:
                $ref: ./api/faucet/run-faucet.example.json
        403:
          description: BTC Faucet not fully configured
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  success:
                    type: boolean
              example:
                error: BTC Faucet not fully configured
                success: false

        500:
          description: Faucet call failed

  /extended/v1/tx:
    get:
      summary: Get recent transactions
      tags:
        - Transactions
      operationId: get_transaction_list
      description: |
        Retrieves all recently mined transactions

        If using TypeScript, import typings for this response from our types package:

        `import type { TransactionResults } from '@stacks/stacks-blockchain-api-types';`
      parameters:
        - name: limit
          in: query
          description: max number of transactions to fetch
          required: false
          schema:
            type: integer
            default: 96
            maximum: 200
            example: 100
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: type
          in: query
          description: Filter by transaction type
          required: false
          schema:
            type: array
            example: coinbase
            items:
              type: string
              enum: [coinbase, token_transfer, smart_contract, contract_call, poison_microblock, tenure_change]
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
      responses:
        200:
          description: List of transactions
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-transactions.schema.json
              example:
                $ref: ./api/transaction/get-transactions.example.json

  /extended/v1/tx/mempool:
    get:
      summary: Get mempool transactions
      tags:
        - Transactions
      operationId: get_mempool_transaction_list
      description: |
          Retrieves all transactions that have been recently broadcast to the mempool. These are pending transactions awaiting confirmation.

          If you need to monitor new transactions, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
      parameters:
        - name: sender_address
          in: query
          description: Filter to only return transactions with this sender address.
          required: false
          schema:
            type: string
            example: "SP1GPBP8NBRXDRJBFQBV7KMAZX1Z7W2RFWJEH0V10"
        - name: recipient_address
          in: query
          description: Filter to only return transactions with this recipient address (only applicable for STX transfer tx types).
          required: false
          schema:
            type: string
        - name: address
          in: query
          description: Filter to only return transactions with this address as the sender or recipient (recipient only applicable for STX transfer tx types).
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: max number of mempool transactions to fetch
          required: false
          schema:
            type: integer
            default: 20
            maximum: 50
            example: 20
        - name: offset
          in: query
          description: index of first mempool transaction to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
      responses:
        200:
          description: List of mempool transactions
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-mempool-transactions.schema.json
              example:
                $ref: ./api/transaction/get-mempool-transactions.example.json

  /extended/v1/tx/mempool/dropped:
    get:
      summary: Get dropped mempool transactions
      tags:
        - Transactions
      operationId: get_dropped_mempool_transaction_list
      description: |
        Retrieves all recently-broadcast transactions that have been dropped from the mempool.

        Transactions are dropped from the mempool if:
         * they were stale and awaiting garbage collection or,
         * were expensive,  or
         * were replaced with a new fee
      parameters:
        - name: limit
          in: query
          description: max number of mempool transactions to fetch
          required: false
          schema:
            type: integer
            default: 96
            maximum: 200
        - name: offset
          in: query
          description: index of first mempool transaction to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of dropped mempool transactions
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-mempool-transactions.schema.json
              example:
                $ref: ./api/transaction/get-mempool-transactions.example.json

  /extended/v1/tx/mempool/stats:
    get:
      summary: Get statistics for mempool transactions
      tags:
        - Transactions
      operationId: get_mempool_transaction_stats
      description: |
        Queries for transactions counts, age (by block height), fees (simple average), and size.
        All results broken down by transaction type and percentiles (p25, p50, p75, p95).
      responses:
        200:
          description: Statistics for mempool transactions
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-mempool-stats.schema.json
              example:
                $ref: ./api/transaction/get-mempool-stats.example.json

  /extended/v1/tx/multiple:
    parameters:
      - name: tx_id
        in: query
        description: Array of transaction ids
        required: true
        schema:
          type: array
          example: "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0"
          items:
            type: string
      - name: event_offset
        in: query
        schema:
          type: integer
          default: 0
        description: The number of events to skip
      - name: event_limit
        in: query
        schema:
          type: integer
          default: 96
        description: The numbers of events to return
      - name: unanchored
        in: query
        description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
        required: false
        schema:
          type: boolean
          example: true
          default: false
    get:
      summary: Get list of details for transactions
      tags:
        - Transactions
      operationId: get_tx_list_details
      description: |
        Retrieves a list of transactions for a given list of transaction IDs

        If using TypeScript, import typings for this response from our types package:

        `import type { Transaction } from '@stacks/stacks-blockchain-api-types';`
      responses:
        200:
          description: Returns list of transactions with their details for corresponding requested tx_ids.
          content:
            application/json:
              schema:
                $ref: ./entities/transactions/transaction-list.schema.json
              example:
                $ref: ./entities/transactions/transactions-list-detail.example.json
        404:
          description: Could not find any transaction by ID

  /extended/v1/tx/{tx_id}:
    parameters:
      - name: tx_id
        in: path
        description: Hash of transaction
        required: true
        schema:
          type: string
          example: "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0"
      - name: event_offset
        in: query
        schema:
          type: integer
          default: 0
        description: The number of events to skip
      - name: event_limit
        in: query
        schema:
          type: integer
          default: 96
        description: The numbers of events to return
      - name: unanchored
        in: query
        description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
        required: false
        schema:
          type: boolean
          example: true
          default: false
    get:
      summary: Get transaction
      tags:
        - Transactions
      operationId: get_transaction_by_id
      description: |
        Retrieves transaction details for a given transaction ID

        `import type { Transaction } from '@stacks/stacks-blockchain-api-types';`
      responses:
        200:
          description: Transaction
          content:
            application/json:
              schema:
                $ref: ./entities/transactions/transaction.schema.json
              example:
                $ref: ./entities/transactions/transaction-4-coinbase.example.json
        404:
          description: Cannot find transaction for given ID

  /extended/v1/tx/{tx_id}/raw:
    parameters:
      - name: tx_id
        in: path
        description: Hash of transaction
        required: true
        schema:
          type: string
          example: "0x0a411719e3bfde95f9e227a2d7f8fac3d6c646b1e6cc186db0e2838a2c6cd9c0"
    get:
      summary: Get Raw Transaction
      tags:
        - Transactions
      operationId: get_raw_transaction_by_id
      description: |
        Retrieves a hex encoded serialized transaction for a given ID
      responses:
        200:
          description: Hex encoded serialized transaction
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-raw-transaction.schema.json
              example:
                $ref: ./api/transaction/get-raw-transaction.example.json
        404:
          description: Cannot find transaction for given ID

  /v2/transactions:
    post:
      summary: Broadcast raw transaction
      tags:
        - Transactions
      description: Broadcasts 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

  /extended/v1/microblock:
    get:
      summary: Get recent microblocks
      tags:
        - Microblocks
      operationId: get_microblock_list
      description: |
          Retrieves a list of microblocks.

          If you need to actively monitor new microblocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
      parameters:
        - name: limit
          in: query
          description: Max number of microblocks to fetch
          required: false
          schema:
            type: integer
            default: 20
            maximum: 200
            example: 100
        - name: offset
          in: query
          description: Index of the first microblock to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of microblocks
          content:
            application/json:
              schema:
                $ref: ./api/microblocks/get-microblocks.schema.json

  /extended/v1/microblock/{hash}:
    parameters:
      - name: hash
        in: path
        description: Hash of the microblock
        required: true
        schema:
          type: string
          example: "0x3bfcdf84b3012adb544cf0f6df4835f93418c2269a3881885e27b3d58eb82d47"

    get:
      summary: Get microblock
      description: Retrieves a specific microblock by `hash`
      tags:
        - Microblocks
      operationId: get_microblock_by_hash
      responses:
        200:
          description: Microblock
          content:
            application/json:
              schema:
                $ref: ./entities/microblocks/microblock.schema.json
        404:
          description: Cannot find microblock with given hash
          content:
            application/json:
              example:
                $ref: ./api/errors/microblock-not-found.example.json

  /extended/v1/microblock/unanchored/txs:
    get:
      summary: Get the list of current transactions that belong to unanchored microblocks
      description: Retrieves transactions that have been streamed in microblocks but not yet accepted or rejected in an anchor block
      tags:
        - Microblocks
      operationId: get_unanchored_txs
      responses:
        200:
          description: Transactions
          content:
            application/json:
              schema:
                $ref: ./api/microblocks/get-unanchored-txs.schema.json

  /extended/v1/burn_block:
    get:
      summary: Get recent burn blocks
      description: |
          Retrieves a list of recent burn blocks
      tags:
        - Blocks
      operationId: get_burn_block_list
      parameters:
        - name: limit
          in: query
          description: max number of burn blocks to fetch
          required: false
          schema:
            type: integer
            default: 20
            maximum: 30
        - name: offset
          in: query
          description: index of first burn block to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: height
          in: query
          description: filter by burn block height
          required: false
          schema:
            type: integer
            example: 42000
        - name: hash
          in: query
          description: filter by burn block hash or the constant 'latest' to filter for the most recent burn block
          required: false
          schema:
            type: string
            example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79"
      responses:
        200:
          description: List of burn blocks
          content:
            application/json:
              schema:
                $ref: ./api/blocks/get-burn-blocks.schema.json
              example:
                $ref: ./api/blocks/get-burn-blocks.example.json

  /extended/v2/blocks:
    get:
      summary: Get blocks
      description: |
        Retrieves a list of recently mined blocks
      tags:
        - Blocks
      operationId: get_blocks
      parameters:
        - name: limit
          in: query
          description: max number of blocks to fetch
          required: false
          schema:
            type: integer
            example: 20
        - name: offset
          in: query
          description: index of first burn block to fetch
          required: false
          schema:
            type: integer
            example: 0
        - name: burn_block_hash
          in: query
          description: filter blocks by burn block hash
          required: false
          schema:
            type: string
            example: "0xb154c008df2101023a6d0d54986b3964cee58119eed14f5bed98e15678e18fe2"
        - name: burn_block_height
          in: query
          description: filter blocks by burn block height
          required: false
          schema:
            type: integer
            example: 810344
      responses:
        200:
          description: List of blocks
          content:
            application/json:
              schema:
                $ref: ./api/blocks/get-nakamoto-blocks.schema.json
              example:
                $ref: ./api/blocks/get-nakamoto-blocks.example.json

  /extended/v1/block:
    get:
      summary: Get recent blocks
      deprecated: true
      description: |
          **NOTE:** This endpoint is deprecated in favor of [Get blocks](#operation/get_blocks).

          Retrieves a list of recently mined blocks

          If you need to actively monitor new blocks, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
      tags:
        - Blocks
      operationId: get_block_list
      parameters:
        - name: limit
          in: query
          description: max number of blocks to fetch
          required: false
          schema:
            type: integer
            default: 20
            maximum: 30
        - name: offset
          in: query
          description: index of first block to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of blocks
          content:
            application/json:
              schema:
                $ref: ./api/blocks/get-blocks.schema.json
              example:
                $ref: ./api/blocks/get-blocks.example.json
  /extended/v1/block/{hash}:
    parameters:
      - name: hash
        in: path
        description: Hash of the block
        required: true
        schema:
          type: string
          example: "0x4839a8b01cfb39ffcc0d07d3db31e848d5adf5279d529ed5062300b9f353ff79"
    get:
      summary: Get block by hash
      description: Retrieves block details of a specific block for a given chain height. You can use the hash from your latest block ('get_block_list' API) to get your block details.
      tags:
        - Blocks
      operationId: get_block_by_hash
      responses:
        200:
          description: Block
          content:
            application/json:
              schema:
                $ref: ./entities/blocks/block.schema.json
              example:
                $ref: ./entities/blocks/block.example.json
        404:
          description: Cannot find block with given ID
          content:
            application/json:
              example:
                $ref: ./api/errors/block-not-found.example.json
  /extended/v1/block/by_height/{height}:
    parameters:
      - name: height
        in: path
        description: Height of the block
        required: true
        schema:
          type: number
          example: 10000
    get:
      summary: Get block by height
      description: Retrieves block details of a specific block at a given block height
      tags:
        - Blocks
      operationId: get_block_by_height
      responses:
        200:
          description: Block
          content:
            application/json:
              schema:
                $ref: ./entities/blocks/block.schema.json
              example:
                $ref: ./entities/blocks/block.example.json
        404:
          description: Cannot find block with given height
          content:
            application/json:
              example:
                $ref: ./api/errors/block-not-found.example.json
  /extended/v1/block/by_burn_block_hash/{burn_block_hash}:
    parameters:
      - name: burn_block_hash
        in: path
        description: Hash of the burnchain block
        required: true
        schema:
          type: string
          example: "0x00000000000000000002bba732926cf68b6eda3e2cdbc2a85af79f10efeeeb10"
    get:
      summary: Get block by burnchain block hash
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of [Get blocks](#operation/get_blocks).

        Retrieves block details of a specific block for a given burnchain block hash
      tags:
        - Blocks
      operationId: get_block_by_burn_block_hash
      responses:
        200:
          description: Block
          content:
            application/json:
              schema:
                $ref: ./entities/blocks/block.schema.json
              example:
                $ref: ./entities/blocks/block.example.json
        404:
          description: Cannot find block with given height
          content:
            application/json:
              example:
                $ref: ./api/errors/block-not-found.example.json

  /extended/v1/block/by_burn_block_height/{burn_block_height}:
    parameters:
      - name: burn_block_height
        in: path
        description: Height of the burn chain block
        required: true
        schema:
          type: number
          example: 744603
    get:
      summary: Get block by burnchain height
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of [Get blocks](#operation/get_blocks).

        Retrieves block details of a specific block for a given burn chain height
      tags:
        - Blocks
      operationId: get_block_by_burn_block_height
      responses:
        200:
          description: Block
          content:
            application/json:
              schema:
                $ref: ./entities/blocks/block.schema.json
              example:
                $ref: ./entities/blocks/block.example.json
        404:
          description: Cannot find block with given height
          content:
            application/json:
              example:
                $ref: ./api/errors/block-not-found.example.json

  /extended/v1/burnchain/reward_slot_holders:
    get:
      summary: Get recent reward slot holders
      description: Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments.
      tags:
        - Stacking Rewards
      operationId: get_burnchain_reward_slot_holders
      parameters:
        - name: limit
          in: query
          description: max number of items to fetch
          required: false
          schema:
            type: integer
            default: 96
            maximum: 250
        - name: offset
          in: query
          description: index of the first items to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of burnchain reward recipients and amounts
          content:
            application/json:
              schema:
                $ref: ./api/burnchain/get-reward-slot-holders.schema.json
              example:
                $ref: ./api/burnchain/get-reward-slot-holders.example.json

  /extended/v1/burnchain/reward_slot_holders/{address}:
    get:
      summary: Get recent reward slot holder entries for the given address
      description: Retrieves a list of the Bitcoin addresses that would validly receive Proof-of-Transfer commitments for a given reward slot holder recipient address.
      tags:
        - Stacking Rewards
      operationId: get_burnchain_reward_slot_holders_by_address
      parameters:
        - name: address
          in: path
          description: Reward slot holder recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format
          required: true
          schema:
            type: string
            example: "36hQtSEXBMevo5chpxhfAGiCTSC34QKgda"
        - name: limit
          in: query
          description: max number of items to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of the first items to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of burnchain reward recipients and amounts
          content:
            application/json:
              schema:
                $ref: ./api/burnchain/get-reward-slot-holders.schema.json
              example:
                $ref: ./api/burnchain/get-reward-slot-holders.example.json

  /extended/v1/burnchain/rewards:
    get:
      summary: Get recent burnchain reward recipients
      description: Retrieves a list of recent burnchain (e.g. Bitcoin) reward recipients with the associated amounts and block info
      tags:
        - Stacking Rewards
      operationId: get_burnchain_reward_list
      parameters:
        - name: limit
          in: query
          description: max number of rewards to fetch
          required: false
          schema:
            type: integer
            default: 96
            maximum: 250
        - name: offset
          in: query
          description: index of first rewards to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of burnchain reward recipients and amounts
          content:
            application/json:
              schema:
                $ref: ./api/burnchain/get-rewards.schema.json
              example:
                $ref: ./api/burnchain/get-rewards.example.json
  /extended/v1/burnchain/rewards/{address}:
    get:
      summary: Get recent burnchain reward for the given recipient
      description: Retrieves a list of recent burnchain (e.g. Bitcoin) rewards for the given recipient with the associated amounts and block info
      tags:
        - Stacking Rewards
      operationId: get_burnchain_reward_list_by_address
      parameters:
        - name: address
          in: path
          description: Reward recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format
          required: true
          schema:
            type: string
            example: "36hQtSEXBMevo5chpxhfAGiCTSC34QKgda"
        - name: limit
          in: query
          description: max number of rewards to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first rewards to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of burnchain reward recipients and amounts
          content:
            application/json:
              schema:
                $ref: ./api/burnchain/get-rewards.schema.json
              example:
                $ref: ./api/burnchain/get-rewards.example.json
  /extended/v1/burnchain/rewards/{address}/total:
    get:
      summary: Get total burnchain rewards for the given recipient
      description: Retrieves the total burnchain (e.g. Bitcoin) rewards for a given recipient `address`
      tags:
        - Stacking Rewards
      operationId: get_burnchain_rewards_total_by_address
      parameters:
        - name: address
          in: path
          description: Reward recipient address. Should either be in the native burnchain's format (e.g. B58 for Bitcoin), or if a STX principal address is provided it will be encoded as into the equivalent burnchain format
          required: true
          schema:
            type: string
            example: "36hQtSEXBMevo5chpxhfAGiCTSC34QKgda"
      responses:
        200:
          description: List of burnchain reward recipients and amounts
          content:
            application/json:
              schema:
                $ref: ./entities/burnchain/rewards-total.schema.json
              example:
                $ref: ./entities/burnchain/rewards-total.example.json

  /extended/v1/contract/{contract_id}:
    get:
      summary: Get contract info
      description: Retrieves details of a contract with a given `contract_id`
      tags:
        - Smart Contracts
      operationId: get_contract_by_id
      responses:
        200:
          description: Contract found
          content:
            application/json:
              schema:
                $ref: ./entities/contracts/smart-contract.schema.json
              example:
                $ref: ./entities/contracts/smart-contract.example.json
        404:
          description: Cannot find contract of given ID
    parameters:
      - name: contract_id
        in: path
        description: Contract identifier formatted as `<contract_address>.<contract_name>`
        required: true
        schema:
          type: string
          example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles"
      - name: unanchored
        in: query
        description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
        required: false
        schema:
          type: boolean
          example: true
          default: false

  /extended/v1/contract/by_trait:
    get:
      summary: Get contracts by trait
      description: Retrieves a list of contracts based on the following traits listed in JSON format -  functions, variables, maps, fungible tokens and non-fungible tokens
      tags:
        - Smart Contracts
      operationId: get_contracts_by_trait
      responses:
        200:
          description: List of contracts implement given trait
          content:
            application/json:
              schema:
                $ref: ./api/contract/smart-contract-list-response.schema.json
              example:
                $ref: ./api/contract/smart-contract-list-response.example.json
      parameters:
        - name: trait_abi
          in: query
          description: JSON abi of the trait.
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: max number of contracts fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first contract event to fetch
          required: false
          example: 42000
          schema:
            type: integer

  /extended/v1/contract/{contract_id}/events:
    get:
      summary: Get contract events
      description: Retrieves a list of events that have been triggered by a given `contract_id`
      tags:
        - Smart Contracts
      operationId: get_contract_events_by_id
      parameters:
        - name: contract_id
          in: path
          description: Contract identifier formatted as `<contract_address>.<contract_name>`
          required: true
          schema:
            type: string
            example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles"
        - name: limit
          in: query
          description: max number of contract events to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first contract event to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
      responses:
        200:
          description: List of events
          content:
            application/json:
              schema:
                $ref: ./entities/transaction-events/transaction-event.schema.json
              example:
                $ref: ./entities/transaction-events/transaction-event-smart-contract-log.example.json

  /v2/contracts/interface/{contract_address}/{contract_name}:
    get:
      summary: Get contract interface
      description: Retrieves a contract interface with a given `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
        example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C
        schema:
          type: string
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
          example: "satoshibles"
      - name: tip
        in: query
        schema:
          type: string
        description: The Stacks chain tip to query from

  /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 `contract_address` and Contract Name `contract_address` 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
            example: "SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11"
        - name: contract_name
          in: path
          required: true
          description: Contract name
          schema:
            type: string
            example: newyorkcitycoin-core-v2
        - name: map_name
          in: path
          required: true
          description: Map name
          schema:
            type: string
            example: approved-contracts
        - 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
      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
            example: 
              $ref: ./entities/contracts/get-specific-data-map-inside-contract.example.json

  /v2/contracts/source/{contract_address}/{contract_name}:
    get:
      summary: Get contract source
      tags:
        - Smart Contracts
      operationId: get_contract_source
      description: Retrieves 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
          example: "SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C"
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
          example: satoshibles
      - 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
        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:
                  value:
                    $ref: ./api/contract/post-call-read-only-fn-success.example.json
                fail:
                  value:
                    $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
            example: "SP187Y7NRSG3T9Z9WTSWNEN3XRV1YSJWS81C7JKV7"
        - name: contract_name
          in: path
          required: true
          description: Contract name
          schema:
            type: string
            example: imaginary-friends-zebras
        - name: function_name
          in: path
          required: true
          description: Function name
          schema:
            type: string
            example: get-token-uri
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from
          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:
              $ref: './entities/contracts/read-only-function-args-request-body.example.json'

  /extended/v1/address/{principal}/balances:
    get:
      summary: Get account balances
      description: Retrieves total account balance information for a given Address or Contract Identifier. This includes the balances of  STX Tokens, Fungible Tokens and Non-Fungible Tokens for the account.
      tags:
        - Accounts
      operationId: get_account_balance
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: until_block
          in: query
          description: returned data representing the state up until that point in time, rather than the current block.
          required: false
          schema:
            type: string
            example: 60000
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/address/get-address-balances.schema.json
              example:
                $ref: ./api/address/get-address-balances.example.json

  /extended/v1/address/{principal}/stx:
    get:
      summary: Get account STX balance
      description: Retrieves STX token balance for a given Address or Contract Identifier.
      tags:
        - Accounts
      operationId: get_account_stx_balance
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier.
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks.
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: until_block
          in: query
          description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
          required: false
          schema:
            type: string
            example: 60000
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/address/get-address-stx-balance.schema.json
              example:
                $ref: ./api/address/get-address-stx-balance.example.json

  /extended/v1/address/{principal}/transactions:
    get:
      summary: Get account transactions
      description: |
          Retrieves a list of all Transactions for a given Address or Contract Identifier. More information on Transaction types can be found [here](https://docs.stacks.co/understand-stacks/transactions#types).

          If you need to actively monitor new transactions for an address or contract id, we highly recommend subscribing to [WebSockets or Socket.io](https://github.com/hirosystems/stacks-blockchain-api/tree/master/client) for real-time updates.
      tags:
        - Accounts
      operationId: get_account_transactions
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: limit
          in: query
          description: max number of account transactions to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: offset
          in: query
          description: index of first account transaction to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: height
          in: query
          description: Filter for transactions only at this given block height
          required: false
          schema:
            type: number
            example: 42000
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: until_block
          in: query
          description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
          required: false
          schema:
            type: string
            example: 60000
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/address/get-address-transactions.schema.json
              example:
                $ref: ./api/address/get-address-transactions.example.json

  /extended/v1/address/{principal}/{tx_id}/with_transfers:
    get:
      summary: Get account transaction information for specific transaction
      description: Retrieves transaction details for a given Transaction Id `tx_id`, for a given account or contract Identifier.
      tags:
        - Accounts
      operationId: get_single_transaction_with_transfers
      parameters:
        - name: principal
          in: path
          description: Stacks address or a contract identifier
          required: true
          schema:
            type: string
            example: "SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE"
        - name: tx_id
          in: path
          description: Transaction id
          required: true
          schema:
            type: string
            example: "0x34d79c7cfc2fe525438736733e501a4bf0308a5556e3e080d1e2c0858aad7448"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./entities/address/transaction-with-transfers.schema.json
              example:
                $ref: ./api/address/get-address-single-transaction-with-transfers.example.json
        404:
          description: Not found
          content:
            application/json:
              example:
                $ref: ./api/errors/transaction-not-found.example.json

  /extended/v1/address/{principal}/transactions_with_transfers:
    get:
      summary: Get account transactions including STX transfers for each transaction.
      description: Retrieve all transactions for an account or contract identifier including STX transfers for each transaction.
      tags:
        - Accounts
      operationId: get_account_transactions_with_transfers
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: limit
          in: query
          description: max number of account transactions to fetch
          required: false
          schema:
            type: integer
            example: 20
        - name: offset
          in: query
          description: index of first account transaction to fetch
          required: false
          schema:
            type: integer
            example: 10
        - name: height
          in: query
          description: Filter for transactions only at this given block height
          required: false
          schema:
            type: number
            example: 66119
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: until_block
          in: query
          description: returned data representing the state up until that point in time, rather than the current block.
          required: false
          schema:
            type: string
            example: 60000
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/address/get-address-transactions-with-transfers.schema.json
              example:
                $ref: ./api/address/get-address-transactions-with-transfers.example.json

  /extended/v1/address/{principal}/nonces:
    get:
      summary: Get the latest nonce used by an account
      description: Retrieves the latest nonce values used by an account by inspecting the mempool, microblock transactions, and anchored transactions.
      tags:
        - Accounts
      operationId: get_account_nonces
      parameters:
        - name: principal
          in: path
          description: Stacks address
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: block_height
          in: query
          description: Optionally get the nonce at a given block height.
          required: false
          schema:
            type: number
            example: 66119
        - name: block_hash
          in: query
          description: Optionally get the nonce at a given block hash. Note - Use either of the query parameters but not both at a time.
          required: false
          schema:
            type: string
            example: "0x72d53f3cba39e149dcd42708e535bdae03d73e60d2fe853aaf61c0b392f521e9"

      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./entities/address/address-nonces.schema.json
              example:
                $ref: ./entities/address/address-nonces.example.json

  /extended/v1/address/{principal}/assets:
    get:
      summary: Get account assets
      description: Retrieves a list of all assets events associated with an account or a Contract Identifier. This includes Transfers, Mints.
      tags:
        - Accounts
      operationId: get_account_assets
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: limit
          in: query
          description: max number of account assets to fetch
          required: false
          schema:
            type: integer
            example: 20
        - name: offset
          in: query
          description: index of first account assets to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: until_block
          in: query
          description: returned data representing the state at that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
          required: false
          schema:
            type: string
            example: 60000
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/address/get-address-assets.schema.json
              example:
                $ref: ./api/address/get-address-assets.example.json

  /extended/v1/address/{principal}/stx_inbound:
    get:
      summary: Get inbound STX transfers
      description: |
        Retrieves a list of STX transfers with memos to the given principal. This includes regular transfers from a stx-transfer transaction type,
        and transfers from contract-call transactions a the `send-many-memo` bulk sending contract.
      tags:
        - Accounts
      operationId: get_account_inbound
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: limit
          in: query
          description: number of items to return
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: number of items to skip
          required: false
          schema:
            type: integer
            example: 42000
        - name: height
          in: query
          description: Filter for transfers only at this given block height
          required: false
          schema:
            type: number
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: until_block
          in: query
          description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
          required: false
          schema:
            type: string
            example: 60000
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/address/get-address-stx-inbound.schema.json
              example:
                $ref: ./api/address/get-address-stx-inbound.example.json

  /extended/v1/address/{principal}/nft_events:
    get:
      summary: Get nft events
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of [Non-Fungible Token holdings](#operation/get_nft_holdings).

        Retrieves a list of all nfts owned by an address, contains the clarity value of the identifier of the nft.
      tags:
        - Accounts
      operationId: get_account_nft
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - name: limit
          in: query
          description: number of items to return
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: number of items to skip
          required: false
          schema:
            type: integer
            example: 42000
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: until_block
          in: query
          description: returned data representing the state up until that point in time, rather than the current block. Note - Use either of the query parameters but not both at a time.
          required: false
          schema:
            type: string
            example: 60000
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/address/get-address-nft-events.schema.json
              example:
                $ref: ./api/address/get-address-nft-events.example.json

  /v2/accounts/{principal}:
    get:
      summary: Get account info
      tags:
        - Accounts
      operationId: get_account_info
      description: |
        Retrieves the account data for a given Account or a Contract Identifier

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

        For non-existent accounts, this does not return a 404 error, rather it returns an object with balance and nonce of 0.
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier
          required: true
          schema:
            type: string
            example: "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0"
        - 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
      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/transfer:
    get:
      summary: Get estimated fee
      tags:
        - Fees
      operationId: get_fee_transfer
      description: Retrieves 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: Retrieves information about the Core API including the server version
      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

  /extended/v1/status:
    get:
      summary: API status
      description: Retrieves the running status of the Stacks Blockchain API, including the server version and current chain tip information.
      tags:
        - Info
      operationId: get_status
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/info/get-status.schema.json
              example:
                $ref: ./api/info/get-status.example.json

  /extended/v1/info/network_block_times:
    get:
      tags:
        - Info
      operationId: get_network_block_times
      summary: Get the network target block time
      description: Retrieves the target block times for mainnet and testnet. The block time is hardcoded and will change throughout the implementation phases of the testnet.
      responses:
        200:
          description: Success
          content:
            application/json:
              example:
                $ref: ./api/info/get-network-block-times.example.json
              schema:
                $ref: ./api/info/get-network-block-times.schema.json
  /extended/v1/info/network_block_time/{network}:
    get:
      tags:
        - Info
      operationId: get_network_block_time_by_network
      summary: Get a given network's target block time
      description: Retrieves the target block time for a given network. The network can be
        mainnet or testnet. The block time is hardcoded and will change
        throughout the implementation phases of the testnet.
      parameters:
        - in: path
          name: network
          required: true
          schema:
            type: string
            enum: [testnet, mainnet]
            example: mainnet
          description: the target block time for a given network (testnet, mainnet).
      responses:
        200:
          description: Success
          content:
            application/json:
              example:
                $ref: ./api/info/get-network-block-time-by-network.example.json
              schema:
                $ref: ./api/info/get-network-block-time-by-network.schema.json

  /extended/v1/stx_supply:
    get:
      tags:
        - Info
      operationId: get_stx_supply
      summary: Get total and unlocked STX supply
      description: |
        Retrieves the total and unlocked STX supply. More information on Stacking can be found [here] (https://docs.stacks.co/understand-stacks/stacking).
        **Note:** This uses the estimated future total supply for the year 2050.
      parameters:
        - in: query
          name: height
          required: false
          schema:
            type: number
            example: 200
          description: Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value. Note that the `block height` is referred to the stacks blockchain.
      responses:
        200:
          description: Success
          content:
            application/json:
              example:
                $ref: ./api/info/get-stx-supply.example.json
              schema:
                $ref: ./api/info/get-stx-supply.schema.json

  /extended/v1/stx_supply/total/plain:
    get:
      tags:
        - Info
      operationId: get_stx_supply_total_supply_plain
      summary: Get total STX supply in plain text format
      description: |
        Retrieves the total supply for STX tokens as plain text.
        **Note:** this uses the estimated future total supply for the year 2050.
      responses:
        200:
          description: success
          content:
            text/plain:
              example: '123.456789'
              schema:
                $ref: ./api/info/get-stx-supply-total-plain.schema.json

  /extended/v1/stx_supply/circulating/plain:
    get:
      tags:
        - Info
      operationId: get_stx_supply_circulating_plain
      summary: Get circulating STX supply in plain text format
      description: Retrieves the STX tokens currently in circulation that have been unlocked as plain text.
      responses:
        200:
          description: success
          content:
            text/plain:
              example: '123.456789'
              schema:
                $ref: ./api/info/get-stx-supply-circulating-plain.schema.json

  /extended/v1/stx_supply/legacy_format:
    get:
      tags:
        - Info
      operationId: get_total_stx_supply_legacy_format
      summary: Get total and unlocked STX supply (results formatted the same as the legacy 1.0 API)
      description: |
        Retrieves total supply of STX tokens including those currently in circulation that have been unlocked.
        **Note:** this uses the estimated future total supply for the year 2050.
      parameters:
        - in: query
          name: height
          required: false
          schema:
            type: number
            example: 200
          description: Supply details are queried from specified block height. If the block height is not specified, the latest block height is taken as default value.
      responses:
        200:
          description: Success
          content:
            application/json:
              example:
                $ref: ./api/info/get-stx-supply-legacy-format.example.json
              schema:
                $ref: ./api/info/get-stx-supply-legacy-format.schema.json

  /v2/pox:
    get:
      summary: Get Proof-of-Transfer details
      description: Retrieves 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

  /extended/v1/search/{id}:
    get:
      summary: Search
      description: Search blocks, transactions, contracts, or accounts by hash/ID
      tags:
        - Search
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            example: "0xcf8b233f19f6c07d2dc1963302d2436efd36e9afac127bf6582824a13961c06d"
          description: The hex hash string for a block or transaction, account address, or contract address
        - in: query
          name: include_metadata
          schema:
            type: boolean
          description: This includes the detailed data for purticular hash in the response
      operationId: search_by_id
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/search/search.schema.json
              example:
                $ref: ./api/search/search-contract.example.json
        404:
          description: Not found
          content:
            application/json:
              example:
                $ref: ./api/errors/search-not-found.example.json

  /rosetta/v1/network/list:
    post:
      tags:
        - Rosetta
      summary: Get List of Available Networks
      operationId: rosetta_network_list
      description: Retrieves a list of NetworkIdentifiers that the Rosetta server supports.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-network-list-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json

  /rosetta/v1/network/options:
    post:
      tags:
        - Rosetta
      summary: Get Network Options
      operationId: rosetta_network_options
      description: |
        Retrieves the version information and allowed network-specific types for a NetworkIdentifier.
        Any NetworkIdentifier returned by /network/list should be accessible here.
        Because options are retrievable in the context of a NetworkIdentifier, it is possible to define unique options for each network.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-network-options-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-network-options-request.schema.json
            example: 
              $ref: ./api/rosetta/rosetta-account-network-options-request-body.example.json

  /rosetta/v1/network/status:
    post:
      tags:
        - Rosetta
      summary: Get Network Status
      operationId: rosetta_network_status
      description: |
        Retrieves the current status of the network requested.
        Any NetworkIdentifier returned by /network/list should be accessible here.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-network-status-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-network-status-request.schema.json
            example: 
              $ref: ./api/rosetta/rosetta-account-network-options-request-body.example.json

  /rosetta/v1/account/balance:
    post:
      tags:
        - Rosetta
      summary: Get an Account Balance
      operationId: rosetta_account_balance
      description: |
        An AccountBalanceRequest is utilized to make a balance request on the /account/balance endpoint.
        If the block_identifier is populated, a historical balance query should be performed.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-account-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-account-balance-request.schema.json
            example: 
              $ref: ./api/rosetta/rosetta-account-balance-request-body.example.json

  /rosetta/v1/block:
    post:
      tags:
        - Rosetta
      summary: Get a Block
      operationId: rosetta_block
      description: Retrieves the Block information for a given block identifier including a list of all transactions in the block.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-block-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-block-request.schema.json
            example: 
              $ref: ./api/rosetta/rosetta-block-request-body.example.json

  /rosetta/v1/block/transaction:
    post:
      tags:
        - Rosetta
      summary: Get a Block Transaction
      operationId: rosetta_block_transaction
      description: Retrieves a Transaction included in a block that is not returned in a BlockResponse.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-block-transaction-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-block-transaction-request.schema.json
            example: 
              $ref: ./api/rosetta/rosetta-block-transaction-request-body.example.json

  /rosetta/v1/mempool:
    post:
      tags:
        - Rosetta
      summary: Get All Mempool Transactions
      operationId: rosetta_mempool
      description: Retrieves a list of transactions currently in the mempool for a given network.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-mempool-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-mempool-request.schema.json
            example: 
              $ref: ./api/rosetta/rosetta-account-network-options-request-body.example.json

  /rosetta/v1/mempool/transaction:
    post:
      tags:
        - Rosetta
      summary: Get a Mempool Transaction
      operationId: rosetta_mempool_transaction
      description: Retrieves transaction details from the mempool for a given transaction id from a given network.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-mempool-transaction-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-mempool-transaction-request.schema.json

  /rosetta/v1/construction/derive:
    post:
      tags:
        - Rosetta
      summary: Derive an AccountIdentifier from a PublicKey
      operationId: rosetta_construction_derive
      description: Retrieves the Account Identifier information based on a Public Key for a given network
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-derive-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-derive-request.schema.json
            example: 
              $ref: ./api/rosetta/rosetta-account-identifier-publickey-request-body.example.json

  /rosetta/v1/construction/hash:
    post:
      tags:
        - Rosetta
      summary: Get the Hash of a Signed Transaction
      operationId: rosetta_construction_hash
      description: Retrieves the network-specific transaction hash for a signed transaction.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-hash-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-hash-request.schema.json
            example:
              $ref: ./api/rosetta/rosetta-hash-signed-transaction-request-schema-body.example.json

  /rosetta/v1/construction/metadata:
    post:
      tags:
        - Rosetta
      summary: Get Metadata for Transaction Construction
      operationId: rosetta_construction_metadata
      description: To Do
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-metadata-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-metadata-request.schema.json
            example:
              $ref: ./api/rosetta/rosetta-construction-metadata-request-schema-body.example.json

  /rosetta/v1/construction/parse:
    post:
      tags:
        - Rosetta
      summary: Parse a Transaction
      operationId: rosetta_construction_parse
      description: TODO
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-parse-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-parse-request.schema.json

  /rosetta/v1/construction/preprocess:
    post:
      tags:
        - Rosetta
      summary: Create a Request to Fetch Metadata
      operationId: rosetta_construction_preprocess
      description: TODO
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-preprocess-response.schema.json

        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-preprocess-request.schema.json

  /rosetta/v1/construction/submit:
    post:
      tags:
        - Rosetta
      summary: Submit a Signed Transaction
      operationId: rosetta_construction_submit
      description: Submit a pre-signed transaction to the node. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-submit-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-submit-request.schema.json
            example:
              $ref: ./api/rosetta/rosetta-submit-signed-transaction-request.example.json

  /rosetta/v1/construction/payloads:
    post:
      tags:
        - Rosetta
      summary: Generate an Unsigned Transaction and Signing Payloads
      operationId: rosetta_construction_payloads
      description: Generate an unsigned transaction from operations and metadata. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-payloads-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-payloads-request.schema.json
            example:
              $ref: ./api/rosetta/rosetta-submit-unsigned-transaction-unsigned-payloads-request.example.json

  /rosetta/v1/construction/combine:
    post:
      tags:
        - Rosetta
      summary: Create Network Transaction from Signatures
      operationId: rosetta_construction_combine
      description: Take unsigned transaction and signature, combine both and return signed transaction. The examples below are illustrative only. You'll need to use your wallet to generate actual values to use them in the request payload.
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/rosetta/rosetta-construction-combine-response.schema.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./entities/rosetta/rosetta-error.schema.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/rosetta/rosetta-construction-combine-request.schema.json
            example:
              $ref: ./api/rosetta/rosetta-network-transaction-from-signarures-request.example.json

  /v2/prices/namespaces/{tld}:
    get:
      summary: Get Namespace Price
      description: Retrieves the price of a namespace. The `amount` given will be in the smallest possible units of the currency.
      tags:
        - Names
      operationId: get_namespace_price
      parameters:
        - name: tld
          in: path
          description: the namespace to fetch price for
          required: true
          schema:
            type: string
            example: id
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/namespace-operations/bns-get-namespace-price-response.schema.json

  /v2/prices/names/{name}:
    get:
      summary: Get Name Price
      description: Retrieves the price of a name. The `amount` given will be in the smallest possible units of the currency.
      tags:
        - Names
      operationId: get_name_price
      parameters:
        - name: name
          in: path
          description: the name to query price information for
          required: true
          schema:
            type: string
            example: muneeb.id
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/name-querying/bns-get-name-price-response.schema.json

  /v1/namespaces:
    get:
      summary: Get All Namespaces
      description: Retrieves a list of all namespaces known to the node.
      tags:
        - Names
      operationId: get_all_namespaces
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-response.schema.json
              example:
                $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-response.example.json

  /v1/namespaces/{tld}/names:
    get:
      summary: Get Namespace Names
      description: Retrieves a list of names within a given namespace.
      tags:
        - Names
      operationId: get_namespace_names
      parameters:
        - name: tld
          in: path
          description: the namespace to fetch names from.
          required: true
          schema:
            type: string
            example: id
        - name: page
          in: query
          description: namespace values are defaulted to page 1 with 100 results. You can query specific page results by using the 'page' query parameter.
          required: false
          schema:
            type: integer
            example: 22
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-names-response.schema.json
              example:
                $ref: ./api/bns/namespace-operations/bns-get-all-namespaces-names-response.example.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-invalid-page.example.json
        404:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-no-such-namespace.example.json

  /v1/names:
    get:
      summary: Get All Names
      description: Retrieves a list of all names known to the node.
      tags:
        - Names
      operationId: get_all_names
      parameters:
        - name: page
          in: query
          description: names are defaulted to page 1 with 100 results. You can query specific page results by using the 'page' query parameter.
          required: false
          schema:
            type: integer
            example: 22
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/name-querying/bns-get-all-names-response.schema.json
              example:
                $ref: ./api/bns/name-querying/bns-get-all-names-response.example.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-invalid-page.example.json

  /v1/names/{name}:
    get:
      summary: Get Name Details
      description: Retrieves details of a given name including the `address`, `status` and last transaction id - `last_txid`.
      tags:
        - Names
      operationId: get_name_info
      parameters:
        - name: name
          in: path
          description: fully-qualified name
          required: true
          schema:
            type: string
            example: muneeb.id
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/name-querying/bns-get-name-info.response.schema.json
              example:
                $ref: ./api/bns/name-querying/bns-get-name-info.response.example.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-invalid-name-subdomain.example.json
        404:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-no-such-name.example.json

  /v1/names/{name}/subdomains:
    get:
      summary: Get Name Subdomains
      description: Retrieves the list of subdomains for a specific name
      tags:
        - Names
      operationId: fetch_subdomains_list_for_name
      parameters:
        - name: name
          in: path
          description: fully-qualified name
          required: true
          schema:
            type: string
            example: id.blockstack
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/subdomains/subdomains-list.schema.json
              example:
                $ref: ./api/bns/subdomains/subdomains-list.example.json


  /v1/names/{name}/zonefile:
    get:
      summary: Get Zone File
      description: Retrieves a user’s raw zone file. This only works for RFC-compliant zone files. This method returns an error for names that have non-standard zone files.
      tags:
        - Names
      operationId: fetch_zone_file
      parameters:
        - name: name
          in: path
          description: fully-qualified name
          required: true
          schema:
            type: string
            example: bar.test
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/manage-names/bns-fetch-zone-file-response.schema.json
              example:
                $ref: ./api/bns/manage-names/bns-fetch-zone-file-response.example.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-invalid-name-subdomain.example.json
        404:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-no-zone-file.example.json

  /v1/names/{name}/zonefile/{zoneFileHash}:
    get:
      summary: Get Historical Zone File
      description: Retrieves the historical zonefile specified by the username and zone hash.
      tags:
        - Names
      operationId: get_historical_zone_file
      parameters:
        - name: name
          in: path
          description: fully-qualified name
          required: true
          schema:
            type: string
            example: muneeb.id
        - name: zoneFileHash
          in: path
          description: zone file hash
          required: true
          schema:
            type: string
            example: "b100a68235244b012854a95f9114695679002af9"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/name-querying/bns-get-historical-zone-file-response.schema.json
              example:
                $ref: ./api/bns/name-querying/bns-get-historical-zone-file-response.example.json
        400:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-invalid-name-subdomain.example.json
        404:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-no-zone-file.example.json

  /v1/addresses/{blockchain}/{address}:
    get:
      summary: Get Names Owned by Address
      description: Retrieves a list of names owned by the address provided.
      tags:
        - Names
      operationId: get_names_owned_by_address
      parameters:
        - name: blockchain
          in: path
          description: the layer-1 blockchain for the address
          required: true
          schema:
            type: string
            example: bitcoin
        - name: address
          in: path
          description: the address to lookup
          required: true
          schema:
            type: string
            example: "1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP"
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/name-querying/bns-get-names-owned-by-address-response.schema.json
              example:
                $ref: ./api/bns/name-querying/bns-get-names-owned-by-address-response.example.json
        404:
          description: Error
          content:
            application/json:
              schema:
                $ref: ./api/bns/errors/bns-error.schema.json
              example:
                $ref: ./api/bns/errors/bns-unsupported-blockchain.example.json

#  /v1/subdomains:
#    get:
#      summary: Get All Subdomains
#      description: Retrieves a list of all subdomains known to the node.
#      tags:
#        - Names
#      operationId: get_all_subdomains
#      parameters:
#        - name: page
#          in: query
#          description: names are returned in pages of size 100, so specify the page number.
#          required: true
#          example: 3
#          schema:
#            type: integer
#      responses:
#        200:
#          description: Success
#          content:
#            application/json:
#              schema:
#                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.schema.json
#              example:
#                $ref: ./api/bns/name-querying/bns-get-all-subdomains-response.example.json
#        400:
#          description: Error
#          content:
#            application/json:
#              schema:
#                $ref: ./api/bns/errors/bns-error.schema.json
#              example:
#                $ref: ./api/bns/errors/bns-invalid-page.example.json
#
#  /v1/subdomains/{txid}:
#    get:
#      summary: Get Subdomain at Transaction
#      description: Retrieves the list of subdomain operations processed by a given transaction. The returned array includes subdomain operations that have not yet been accepted as part of any subdomain’s history (checkable via the accepted field). If the given transaction ID does not correspond to a Stacks transaction that introduced new subdomain operations, and empty array will be returned.
#      tags:
#        - Names
#      operationId: get_subdomain_at_transaction
#      parameters:
#        - name: txid
#          in: path
#          description: transaction id
#          required: true
#          schema:
#            type: string
#            example: "d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe"
#      responses:
#        200:
#          description: Success
#          content:
#            application/json:
#              schema:
#                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.schema.json
#              example:
#                $ref: ./api/bns/name-querying/bns-get-subdomain-at-tx-response.example.json
#        400:
#          description: Error
#          content:
#            application/json:
#              schema:
#                $ref: ./api/bns/errors/bns-error.schema.json
#              example:
#                $ref: ./api/bns/errors/bns-invalid-tx-id.example.json

  /extended/v1/tx/block/{block_hash}:
    get:
      operationId: get_transactions_by_block_hash
      summary: Transactions by block hash
      description: Retrieves a list of all transactions within a block for a given block hash.
      tags:
        - Transactions
      parameters:
        - name: block_hash
          in: path
          description: Hash of block
          required: true
          schema:
            type: string
            example: "0x0a83d82a65460a9e711f85a44616350280040b75317dbe486a923c1131b5ff99"
        - name: limit
          in: query
          description: max number of transactions to fetch
          required: false
          schema:
            type: integer
            example: 10
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of Transactions
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-transactions.schema.json
              example:
                $ref: ./api/transaction/get-transactions.example.json

  /extended/v1/tx/block_height/{height}:
    get:
      operationId: get_transactions_by_block_height
      summary: Transactions by block height
      description: Retrieves all transactions within a block at a given height
      tags:
        - Transactions
      parameters:
        - name: height
          in: path
          description: Height of block
          required: true
          schema:
            type: integer
            example: 66119
        - name: limit
          in: query
          description: max number of transactions to fetch
          required: false
          schema:
            type: integer
            example: 10
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
      responses:
        200:
          description: List of Transactions
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-transactions.schema.json
              example:
                $ref: ./api/transaction/get-transactions.example.json

  /extended/v1/address/{address}/mempool:
    get:
      operationId: get_address_mempool_transactions
      summary: Transactions for address
      description: Retrieves all transactions for a given address that are currently in mempool
      tags:
        - Transactions
      parameters:
        - name: address
          in: path
          description: Transactions for the address
          required: true
          schema:
            type: string
            example: "SP197DVH8KTJGX4STM61QN0WJV8Y9QJWXV83ZGNR9"
        - name: limit
          in: query
          description: max number of transactions to fetch
          required: false
          schema:
            type: integer
            example: 90
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
            example: 42000
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            example: true
            default: false
      responses:
        200:
          description: List of Transactions
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-mempool-transactions.schema.json
              example:
                $ref: ./api/transaction/get-mempool-transactions.example.json

  /extended/v1/tokens/ft/metadata:
    get:
      operationId: get_ft_metadata_list
      summary: Fungible tokens metadata list
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service).

        Retrieves list of fungible tokens with their metadata. More information on Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#fungible-tokens).
      tags:
        - Fungible Tokens
      parameters:
        - name: limit
          in: query
          description: max number of tokens to fetch.
          required: false
          schema:
            type: integer
            example: 100
            maximum: 200
        - name: offset
          in: query
          description: index of first tokens to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of fungible tokens metadata
          content:
            application/json:
              schema:
                $ref: ./api/tokens/get-fungible-tokens-metadata-list.schema.json
              example:
                $ref: ./api/tokens/get-fungible-tokens-metadata-list.example.schema.json

  /extended/v1/tokens/nft/holdings:
    get:
      operationId: get_nft_holdings
      summary: Non-Fungible Token holdings
      description: |
        Retrieves the list of Non-Fungible Tokens owned by the given principal (STX address or Smart Contract ID).
        Results can be filtered by one or more asset identifiers and can include metadata about the transaction that made the principal own each token.

        More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
      tags:
        - Non-Fungible Tokens
      parameters:
        - name: principal
          in: query
          description: token owner's STX address or Smart Contract ID
          required: true
          schema:
            type: string
            example: "SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v3"
        - name: asset_identifiers
          in: query
          description: identifiers of the token asset classes to filter for
          required: false
          schema:
            type: array
            example: "SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy::candy"
            items:
              type: string
        - name: limit
          in: query
          description: max number of tokens to fetch
          required: false
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          description: index of first tokens to fetch
          required: false
          schema:
            type: integer
            default: 0
            example: 42000
        - name: unanchored
          in: query
          description: whether or not to include tokens from unconfirmed transactions
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: tx_metadata
          in: query
          description: whether or not to include the complete transaction metadata instead of just `tx_id`. Enabling this option can affect performance and response times.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        200:
          description: List of Non-Fungible Token holdings
          content:
            application/json:
              schema:
                $ref: ./api/tokens/get-non-fungible-token-holdings.schema.json
              examples:
                default:
                  value:
                    $ref: ./api/tokens/get-non-fungible-token-holdings.example.schema.json
                with transaction metadata:
                  value:
                    $ref: ./api/tokens/get-non-fungible-token-holdings-tx-metadata.example.schema.json

  /extended/v1/tokens/nft/history:
    get:
      operationId: get_nft_history
      summary: Non-Fungible Token history
      description: |
        Retrieves all events relevant to a Non-Fungible Token. Useful to determine the ownership history of a particular asset.

        More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
      tags:
        - Non-Fungible Tokens
      parameters:
        - name: asset_identifier
          in: query
          description: token asset class identifier
          required: true
          schema:
            type: string
            example: "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild"
        - name: value
          in: query
          description: hex representation of the token's unique value
          required: true
          schema:
            type: string
            example: "0x0100000000000000000000000000000803"
        - name: limit
          in: query
          description: max number of events to fetch
          required: false
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          description: index of first event to fetch
          required: false
          schema:
            type: integer
            default: 0
            example: 42000
        - name: unanchored
          in: query
          description: whether or not to include events from unconfirmed transactions
          required: false
          schema:
            type: boolean
            default: false
            example: true
        - name: tx_metadata
          in: query
          description: whether or not to include the complete transaction metadata instead of just `tx_id`. Enabling this option can affect performance and response times.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        200:
          description: Non-Fungible Token event history
          content:
            application/json:
              schema:
                $ref: ./api/tokens/get-non-fungible-token-history.schema.json
              examples:
                default:
                  value:
                    $ref: ./api/tokens/get-non-fungible-token-history.example.schema.json
                with transaction metadata:
                  value:
                    $ref: ./api/tokens/get-non-fungible-token-history-tx-metadata.example.schema.json

  /extended/v1/tokens/nft/mints:
    get:
      operationId: get_nft_mints
      summary: Non-Fungible Token mints
      description: |
        Retrieves all mint events for a Non-Fungible Token asset class. Useful to determine which NFTs of a particular collection have been claimed.

        More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
      tags:
        - Non-Fungible Tokens
      parameters:
        - name: asset_identifier
          in: query
          description: token asset class identifier
          required: true
          schema:
            type: string
            example: "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild"
        - name: limit
          in: query
          description: max number of events to fetch
          required: false
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          description: index of first event to fetch
          required: false
          schema:
            type: integer
            default: 0
            example: 42000
        - name: unanchored
          in: query
          description: whether or not to include events from unconfirmed transactions
          required: false
          schema:
            type: boolean
            example: true
            default: false
        - name: tx_metadata
          in: query
          description: whether or not to include the complete transaction metadata instead of just `tx_id`. Enabling this option can affect performance and response times.
          required: false
          schema:
            type: boolean
            default: false
      responses:
        200:
          description: Non-Fungible Token mints
          content:
            application/json:
              schema:
                $ref: ./api/tokens/get-non-fungible-token-mints.schema.json
              examples:
                default:
                  value:
                    $ref: ./api/tokens/get-non-fungible-token-mints.example.schema.json
                with transaction metadata:
                  value:
                    $ref: ./api/tokens/get-non-fungible-token-mints-tx-metadata.example.schema.json

  /extended/v1/tokens/nft/metadata:
    get:
      operationId: get_nft_metadata_list
      summary: Non fungible tokens metadata list
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service).

        Retrieves a list of non fungible tokens with their metadata. More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
      tags:
        - Non-Fungible Tokens
      parameters:
        - name: limit
          in: query
          description: max number of tokens to fetch
          required: false
          schema:
            type: integer
            example: 1
        - name: offset
          in: query
          description: index of first tokens to fetch
          required: false
          schema:
            type: integer
            example: 42000
      responses:
        200:
          description: List of non fungible tokens metadata
          content:
            application/json:
              schema:
                $ref: ./api/tokens/get-non-fungible-tokens-metadata-list.schema.json
              example:
                $ref: ./api/tokens/get-non-fungible-tokens-metadata-list.example.schema.json

  /extended/v1/tokens/{contractId}/nft/metadata:
    get:
      operationId: get_contract_nft_metadata
      summary: Non fungible tokens metadata for contract ID
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service).

        Retrieves metadata for non fungible tokens for a given contract id. More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/write-smart-contracts/tokens#non-fungible-tokens-nfts).
      tags:
        - Non-Fungible Tokens
      parameters:
        - name: contractId
          in: path
          description: token's contract id
          required: true
          schema:
            type: string
      responses:
        200:
          description: Non fungible tokens metadata for contract id
          content:
            application/json:
              schema:
                $ref: ./entities/tokens/non-fungible-token.schema.json
              example:
                $ref: ./entities/tokens/non-fungible-token.schema.example.json

  /extended/v1/tokens/{contractId}/ft/metadata:
    get:
      operationId: get_contract_ft_metadata
      summary: Fungible tokens metadata for contract id
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of the [Token Metadata Service](https://github.com/hirosystems/token-metadata-service).

        Retrieves the metadata for fungible tokens for a given contract id
      tags:
        - Fungible Tokens
      parameters:
        - name: contractId
          in: path
          description: token's contract id
          required: true
          schema:
            type: string
            example: "SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11.newyorkcitycoin-token-v2"
      responses:
        200:
          description: Fungible tokens metadata for contract id
          content:
            application/json:
              schema:
                $ref: ./entities/tokens/fungible-token.schema.json
              example:
                $ref: ./entities/tokens/fungible-token.schema.example.json

  /extended/v1/fee_rate:
    post:
      operationId: fetch_fee_rate
      summary: Fetch fee rate
      deprecated: true
      description: |
        **NOTE:** This endpoint is deprecated in favor of [Get approximate fees for a given transaction](#operation/post_fee_transaction).

        Retrieves estimated fee rate.
      tags:
        - Fees
      responses:
        200:
          description: Transaction fee rate
          content:
            application/json:
              schema:
                $ref: ./api/info/get-fee-rate-response.schema.json
              example:
                $ref: ./api/info/get-fee-rate-response.example.json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: ./api/info/get-fee-rate-request.schema.json
            example:
              $ref: ./api/info/get-fee-rate-request.example.json

  /v2/fees/transaction:
    post:
      summary: Get approximate fees for a 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
  /extended/v1/tx/events:
    get:
      summary: Transaction Events
      description: Retrieves the list of events filtered by principal (STX address or Smart Contract ID), transaction id or event types.
        The list of event types is ('smart_contract_log', 'stx_lock', 'stx_asset', 'fungible_token_asset', 'non_fungible_token_asset').
      tags:
        - Transactions
      operationId: get_filtered_events
      parameters:
        - name: tx_id
          in: query
          description: Hash of transaction
          required: false
          example: "0x29e25515652dad41ef675bd0670964e3d537b80ec19cf6ca6f1dd65d5bc642c5"
          schema:
            type: string
        - name: address
          in: query
          description: Stacks address or a Contract identifier
          required: false
          schema:
            type: string
            example: "ST1HB64MAJ1MBV4CQ80GF01DZS4T1DSMX20ADCRA4"
        - name: limit
          in: query
          description: number of items to return
          required: false
          schema:
            type: integer
            example: 100
        - name: offset
          in: query
          description: number of items to skip
          required: false
          schema:
            type: integer
            example: 42000
        - name: type
          in: query
          description: Filter the events on event type
          required: false
          schema:
            type: array
            example: stx_lock
            items:
              type: string
              enum: [smart_contract_log, stx_lock, stx_asset, fungible_token_asset, non_fungible_token_asset]
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/transaction/get-transaction-events.schema.json
              example:
                $ref: ./api/transaction/get-transaction-events.example.json
  /extended/beta/stacking/{pool_principal}/delegations:
    get:
      summary: Stacking pool members
      description: Retrieves the list of stacking pool members for a given delegator principal.
      tags:
        - Stacking
      operationId: get_pool_delegations
      parameters:
        - name: pool_principal
          in: path
          description: Address principal of the stacking pool delegator
          required: true
          example: "SPSCWDV3RKV5ZRN1FQD84YE1NQFEDJ9R1F4DYQ11"
          schema:
            type: string
        - name: after_block
          in: query
          description: If specified, only delegation events after the given block will be included
          required: false
          schema:
            type: integer
        - name: unanchored
          in: query
          description: whether or not to include Stackers from unconfirmed transactions
          required: false
          schema:
            type: boolean
            default: false
            example: true
        - name: limit
          in: query
          description: number of items to return
          required: false
          schema:
            type: integer
            example: 100
            default: 100
            maximum: 200
        - name: offset
          in: query
          description: number of items to skip
          required: false
          schema:
            type: integer
            example: 300
            default: 0
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/stacking/get-pool-delegations.schema.json
              example:
                $ref: ./api/stacking/get-pool-delegations.example.json