stacks-blockchain-api/docs/openapi.yaml

openapi: 3.0.2
servers:
  - url: https://stacks-node-api.mainnet.stacks.co/
    description: Mainnet
  - url: https://stacks-node-api.testnet.stacks.co/
    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="/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.stacks.co/?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
        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
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
        - name: type
          in: query
          description: Filter by transaction type
          required: false
          schema:
            type: array
            items:
              type: string
              enum: [coinbase, token_transfer, smart_contract, contract_call, poison_microblock]
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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.
      parameters:
        - name: sender_address
          in: query
          description: Filter to only return transactions with this sender address.
          required: false
          schema:
            type: string
        - 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: 96
            maximum: 200
        - name: offset
          in: query
          description: index of first mempool transaction to fetch
          required: false
          schema:
            type: integer
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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
      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/multiple:
    parameters:
      - name: tx_id
        in: query
        description: Array of transaction ids
        required: true
        schema:
          type: array
          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
          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
      - 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
          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
    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.
      parameters:
        - name: limit
          in: query
          description: Max number of microblocks to fetch
          required: false
          schema:
            type: integer
            default: 20
            maximum: 200
        - name: offset
          in: query
          description: Index of the first microblock to fetch
          required: false
          schema:
            type: integer
      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
    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/block:
    get:
      summary: Get recent blocks
      description: Retrieves a list of recently mined blocks
      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: 200
        - name: offset
          in: query
          description: index of first block to fetch
          required: false
          schema:
            type: integer
      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
    get:
      summary: Get block by hash
      description: Retrieves block details of a specific block for a given chain height
      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
    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
    get:
      summary: Get block by burnchain block hash
      description: 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
    get:
      summary: Get block by burnchain height
      description: 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
      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
        - 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
      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
      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
        - 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
      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
      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/transactions/transaction-1-smart-contract.schema.json
              example:
                $ref: ./entities/transactions/transaction-1-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
      - name: unanchored
        in: query
        description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
        required: false
        schema:
          type: boolean
          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
          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
        - 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
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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
        schema:
          type: string
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
      - name: tip
        in: query
        schema:
          type: string
        description: The Stacks chain tip to query from

  /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
        - name: contract_name
          in: path
          required: true
          description: Contract name
          schema:
            type: string
        - name: map_name
          in: path
          required: true
          description: Map name
          schema:
            type: string
        - name: proof
          in: query
          description: Returns object without the proof field when set to 0
          schema:
            type: integer
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from
      x-codegen-request-body-name: key
      requestBody:
        description: Hex string serialization of the lookup key (which should be a Clarity value)
        required: true
        content:
          application/json:
            schema:
              type: string

  /v2/contracts/source/{contract_address}/{contract_name}:
    get:
      summary: Get contract source
      tags:
        - Smart Contracts
      operationId: get_contract_source
      description: 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
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
      - name: proof
        in: query
        description: Returns object without the proof field if set to 0
        schema:
          type: integer
      - name: tip
        in: query
        schema:
          type: string
        description: The Stacks chain tip to query from
        required: false

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

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

  /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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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
      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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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
      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).
      tags:
        - Accounts
      operationId: get_account_transactions
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: max number of account transactions to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first account transaction to fetch
          required: false
          schema:
            type: integer
        - name: height
          in: query
          description: Filter for transactions 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
            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
      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 Transcation 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
        - name: tx_id
          in: path
          description: Transaction id
          required: true
          schema:
            type: string
      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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: max number of account transactions to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first account transaction to fetch
          required: false
          schema:
            type: integer
        - name: height
          in: query
          description: Filter for transactions 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
            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
      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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0`)
          required: true
          schema:
            type: string
      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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: limit
          in: query
          description: max number of account assets to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first account assets to fetch
          required: false
          schema:
            type: integer
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            default: false
        - name: until_block
          in: query
          description: returned data representing the state at that point in time, rather than the current block.
          required: false
          schema:
            type: string
      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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - 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
        - 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
            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
      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
      description: |
        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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - 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
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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
      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 (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: proof
          in: query
          description: Returns object without the proof field if set to 0
          schema:
            type: integer
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from
      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: Get Blockchain API status
      description: Retrieves the current status of the blockchain API, including the server version
      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]
          description: Which network to retrieve the target block time of
      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).
      parameters:
        - in: query
          name: height
          required: false
          schema:
            type: number
          description: The block height at which to query supply details from, if not provided then the latest block height is used
      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.
      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.
      parameters:
        - in: query
          name: height
          required: false
          schema:
            type: number
          description: The block height at which to query supply details from, if not provided then the latest block height is used
      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
          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

  /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

  /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

  /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

  /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

  /rosetta/v1/mempool:
    post:
      tags:
        - Rosetta
      summary: Get All Mempool Transactions
      operationId: rosetta_mempool
      description: Retrieves a list of transcations 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

  /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

  /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

  /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

  /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.
      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

  /rosetta/v1/construction/payloads:
    post:
      tags:
        - Rosetta
      summary: Generate an Unsigned Transaction and Signing Payloads
      operationId: rosetta_construction_payloads
      description: Generate and unsigned transaction from operations and metadata
      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

  /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
      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

  /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
          example: id
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/namespace-operations/bns-get-namespace-price-response.schema.json
              example:
                $ref: ./api/bns/namespace-operations/bns-get-namespace-price-response.example.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
          example: muneeb.id
          schema:
            type: string
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/name-querying/bns-get-name-price-response.schema.json
              example:
                $ref: ./api/bns/name-querying/bns-get-name-price-response.example.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
          example: id
          schema:
            type: string
        - name: page
          in: query
          description: names are returned in pages of size 100, so specify the page number.
          required: true
          example: 23
          schema:
            type: integer
      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 returned in pages of size 100, so specify the page number.
          required: true
          example: 23
          schema:
            type: integer
      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
          example: muneeb.id
          schema:
            type: string
      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}/history:
    get:
      summary: Get Name History
      description: Retrieves a history of all blockchain records of a registered name.
      tags:
        - Names
      operationId: get_name_history
      parameters:
        - name: name
          in: path
          description: name to query
          required: true
          example: muneeb.id
          schema:
            type: string
        - name: page
          in: query
          description: the page (in 20-entry pages) of the history to fetch
          required: true
          example: 0
          schema:
            type: integer
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/bns/name-querying/bns-get-name-history-response.schema.json
              example:
                $ref: ./api/bns/name-querying/bns-get-name-history-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-name.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
          example: bar.test
          schema:
            type: string
      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
          example: muneeb.id
          schema:
            type: string
        - name: zoneFileHash
          in: path
          description: zone file hash
          required: true
          example: b100a68235244b012854a95f9114695679002af9
          schema:
            type: string
      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
          example: bitcoin
          schema:
            type: string
        - name: address
          in: path
          description: the address to lookup
          required: true
          example: 1QJQxDas5JhdiXhEbNS14iNjr8auFT96GP
          schema:
            type: string
      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
          example: d04d708472ea3c147f50e43264efdb1535f71974053126dc4db67b3ac19d41fe
          schema:
            type: string
      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
        - name: limit
          in: query
          description: max number of transactions to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
      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
        - name: limit
          in: query
          description: max number of transactions to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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
        - name: limit
          in: query
          description: max number of transactions to fetch
          required: false
          schema:
            type: integer
        - name: offset
          in: query
          description: index of first transaction to fetch
          required: false
          schema:
            type: integer
        - name: unanchored
          in: query
          description: Include transaction data from unanchored (i.e. unconfirmed) microblocks
          required: false
          schema:
            type: boolean
            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
      description: 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
        - name: offset
          in: query
          description: index of first tokens to fetch
          required: false
          schema:
            type: integer
      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/metadata:
    get:
      operationId: get_nft_metadata_list
      summary: Non fungible tokens metadata list
      description: 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
        - name: offset
          in: query
          description: index of first tokens to fetch
          required: false
          schema:
            type: integer
      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
      description: 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
      description: 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
      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
      description: 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