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 2.0 Blockchain API
  version: 'STACKS_API_VERSION'
  description: |
    This is the documentation for the Stacks 2.0 Blockchain API.

    It is comprised of two parts; the Stacks Blockchain API and the Stacks Core API.

    <a href="collection.json" download="collection.json">Download Postman collection</a>

paths:
  /extended/v1/faucets/stx:
    parameters:
      - name: address
        in: query
        description: STX address
        required: true
        schema:
          type: string
      - name: stacking
        in: query
        description: Request the amount of STX needed for stacking
        required: false
        schema:
          type: boolean
          default: false
    post:
      summary: Get STX tokens
      description: Get STX tokens for the testnet
      tags:
        - Faucets
      operationId: run_faucet_stx
      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: Failed to run faucet
  /extended/v1/faucets/btc:
    parameters:
      - name: address
        in: query
        description: BTC address
        required: true
        schema:
          type: string
    post:
      summary: Get BTC tokens
      description: Get BTC tokens for the testnet
      tags:
        - Faucets
      operationId: run_faucet_btc
      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: Failed to run faucet

  /extended/v1/tx:
    get:
      summary: Get recent transactions
      tags:
        - Transactions
      operationId: get_transaction_list
      description: |
        Get 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
        - 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: Get all recently-broadcast mempool transactions
      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
        - 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: Get all recently-broadcast mempool transactions
      parameters:
        - name: limit
          in: query
          description: max number of mempool transactions to fetch
          required: false
          schema:
            type: integer
        - 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: |
        Get an array of transactions by 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: |
        Get a specific transaction by 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: |
        Get raw transaction by 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: Broadcast raw transactions on the network. You can use the [@stacks/transactions](https://github.com/hirosystems/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
      parameters:
        - name: limit
          in: query
          description: Max number of microblocks to fetch
          required: false
          schema:
            type: integer
        - 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: Get 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: This contains 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: Get all 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
        - 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
      description: Get a specific block by hash
      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
      description: Get a specific block by 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
      description: Get a specific block by 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
      description: Get a specific block by 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: Array of the Bitcoin addresses that would validly receive PoX commitments.
      tags:
        - Burnchain
      operationId: get_burnchain_reward_slot_holders
      parameters:
        - 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/reward_slot_holders/{address}:
    get:
      summary: Get recent reward slot holder entries for the given address
      description: Array of the Bitcoin addresses that would validly receive PoX commitments.
      tags:
        - Burnchain
      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: Get a list of recent burnchain (e.g. Bitcoin) reward recipients with the associated amounts and block info
      tags:
        - Burnchain
      operationId: get_burnchain_reward_list
      parameters:
        - 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}:
    get:
      summary: Get recent burnchain reward for the given recipient
      description: Get a list of recent burnchain (e.g. Bitcoin) rewards for the given recipient with the associated amounts and block info
      tags:
        - Burnchain
      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: Get the total burnchain (e.g. Bitcoin) rewards for the given recipient
      tags:
        - Burnchain
      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: Get contract info using the 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/{contract_id}/events:
    get:
      summary: Get contract events
      description: Get contract events using a contract ID
      tags:
        - Smart Contracts
      operationId: get_contract_events_by_id
      parameters:
        - 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: 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
      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: Get contract interface using a `contract_address` and `contract name`
      tags:
        - Smart Contracts
      operationId: get_contract_interface
      responses:
        200:
          description: Contract interface
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-contract-interface.schema.json
              example:
                $ref: ./api/core-node/get-contract-interface.example.json
    parameters:
      - name: contract_address
        in: path
        required: true
        description: Stacks address
        schema:
          type: string
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
      - name: tip
        in: query
        schema:
          type: string
        description: The Stacks chain tip to query from

  /v2/map_entry/{contract_address}/{contract_name}/{map_name}:
    post:
      summary: Get specific data-map inside a contract
      tags:
        - Smart Contracts
      operationId: get_contract_data_map_entry
      description: |
        Attempt to fetch data from a contract data map. The contract is identified with [Stacks Address] and [Contract Name] in the URL path. The map is identified with [Map Name].

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

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

  /v2/contracts/source/{contract_address}/{contract_name}:
    get:
      summary: Get contract source
      tags:
        - Smart Contracts
      operationId: get_contract_source
      description: Returns the Clarity source code of a given contract, along with the block height it was published in, and the MARF proof for the data
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-contract-source.schema.json
              example:
                $ref: ./api/core-node/get-contract-source.example.json
    parameters:
      - name: contract_address
        in: path
        required: true
        description: Stacks address
        schema:
          type: string
      - name: contract_name
        in: path
        required: true
        description: Contract name
        schema:
          type: string
      - name: proof
        in: query
        description: Returns object without the proof field if set to 0
        schema:
          type: integer
      - name: tip
        in: query
        schema:
          type: string
        description: The Stacks chain tip to query from
        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
      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
      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
      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
      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
      tags:
        - Accounts
      operationId: get_account_transactions
      parameters:
        - 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: principal
          in: path
          description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - 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
      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
      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.
      tags:
        - Accounts
      operationId: get_account_transactions_with_transfers
      parameters:
        - 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: principal
          in: path
          description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - 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
      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 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
      tags:
        - Accounts
      operationId: get_account_assets
      parameters:
        - 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: 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
      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: |
        Get 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: 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: principal
          in: path
          description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - 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
      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: |
        Get 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: 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: 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
      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: |
        Get the account data for the provided principal

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

        For non-existent accounts, this does not 404, rather it returns an object with balance and nonce of 0.
      parameters:
        - name: principal
          in: path
          description: Stacks address or a Contract identifier (e.g. `SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info`)
          required: true
          schema:
            type: string
        - name: proof
          in: query
          description: Returns object without the proof field if set to 0
          schema:
            type: integer
        - name: tip
          in: query
          schema:
            type: string
          description: The Stacks chain tip to query from
      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: Get an estimated fee rate for STX transfer transactions. This a a fee rate / byte, and is returned as a JSON integer
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-fee-transfer.schema.json
              example:
                $ref: ./api/core-node/get-fee-transfer.example.json

  /v2/info:
    get:
      summary: Get Core API info
      description: Get Core API information
      tags:
        - Info
      operationId: get_core_api_info
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-info.schema.json
              example:
                $ref: ./api/core-node/get-info.example.json
  /extended/v1/status:
    get:
      summary: Get Blockchain API status
      description: Get Blockchain API status
      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
      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
      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
      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
      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
      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)
      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 PoX details
      description: Get Proof of Transfer (PoX) information. Can be used for Stacking.
      tags:
        - Info
      operationId: get_pox_info
      responses:
        200:
          description: Success
          content:
            application/json:
              schema:
                $ref: ./api/core-node/get-pox.schema.json
              example:
                $ref: ./api/core-node/get-pox.example.json

  /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
      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: This endpoint returns 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: |
        This endpoint returns 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: |
        This endpoint returns 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: A BlockRequest is utilized to make a block request on the /block endpoint.
      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: A BlockTransactionRequest is used to fetch 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: Get all Transaction Identifiers in the mempool.
      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: A MempoolTransactionRequest is utilized to retrieve a transaction from the mempool.
      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: TODO
      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: TODO
      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: TODO
      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: Get the price of a namespace. The `amount` given will be in the smallest possible units of the currency.
      tags:
        - BNS
      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: Get the price of a name. The `amount` given will be in the smallest possible units of the currency.
      tags:
        - BNS
      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: Fetch a list of all namespaces known to the node.
      tags:
        - BNS
      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: Fetch a list of names from the namespace.
      tags:
        - BNS
      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: Fetch a list of all names known to the node.
      tags:
        - BNS
      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
      tags:
        - BNS
      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: Get a history of all blockchain records of a registered name.
      tags:
        - BNS
      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: Fetch Zone File
      description: Fetch 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:
        - BNS
      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: Fetches the historical zonefile specified by the username and zone hash.
      tags:
        - BNS
      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:
        - BNS
      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: Fetch a list of all subdomains known to the node.
      tags:
        - BNS
      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: Fetches 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:
        - BNS
      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 in a block
      description: Get all transactions in block
      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 in a block
      description: Get all transactions in block by 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: Get all transactions for address 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: Get list of fungible tokens metadata
      tags:
        - 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: Get list of non fungible tokens metadata
      tags:
        - 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: Get non fungible tokens metadata for given contract id
      tags:
        - 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: Get fungible tokens metadata for given contract id
      tags:
        - 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: Fetch fee rate information.
      tags:
        - fee_rate
      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