Stacks Blockchain API — Transactions

naftiko: 1.0.0-alpha2
info:
  label: Stacks Blockchain API — Transactions
  description: 'Stacks Blockchain API — Transactions. 13 operations. Lead operation: Transactions for address. Self-contained
    Naftiko capability covering one Hiro business surface.'
  tags:
  - Hiro
  - Transactions
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    HIRO_API_KEY: HIRO_API_KEY
capability:
  consumes:
  - type: http
    namespace: stacks-blockchain-transactions
    baseUri: https://api.hiro.so
    description: Stacks Blockchain API — Transactions business capability. Self-contained, no shared references.
    resources:
    - name: extended-v1-address-principal-mempool
      path: /extended/v1/address/{principal}/mempool
      operations:
      - name: getaddressmempooltransactions
        method: GET
        description: Transactions for address
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
        - name: principal
          in: path
          type: string
          required: true
    - name: extended-v1-tx
      path: /extended/v1/tx/
      operations:
      - name: gettransactionlist
        method: GET
        description: Get recent transactions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: type
          in: query
          type: array
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: order
          in: query
          type: string
        - name: sort_by
          in: query
          type: string
          description: Option to sort results by block height, timestamp, or fee
        - name: from_address
          in: query
          type: string
          description: Option to filter results by sender address
        - name: to_address
          in: query
          type: string
          description: Option to filter results by recipient address
        - name: start_time
          in: query
          type: integer
          description: Filter by transactions after this timestamp (unix timestamp in seconds)
        - name: end_time
          in: query
          type: integer
          description: Filter by transactions before this timestamp (unix timestamp in seconds)
        - name: contract_id
          in: query
          type: string
          description: Option to filter results by contract ID
        - name: function_name
          in: query
          type: string
          description: Filter by contract call transactions involving this function name
        - name: nonce
          in: query
          type: integer
          description: Filter by transactions with this nonce
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
    - name: extended-v1-tx-block-block_hash
      path: /extended/v1/tx/block/{block_hash}
      operations:
      - name: gettransactionsbyblockhash
        method: GET
        description: Transactions by block hash
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
        - name: block_hash
          in: path
          type: string
          required: true
    - name: extended-v1-tx-block_height-height
      path: /extended/v1/tx/block_height/{height}
      operations:
      - name: gettransactionsbyblockheight
        method: GET
        description: Transactions by block height
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
        - name: height
          in: path
          type: integer
          description: Block height
          required: true
    - name: extended-v1-tx-events
      path: /extended/v1/tx/events
      operations:
      - name: getfilteredevents
        method: GET
        description: Transaction Events
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: tx_id
          in: query
          type: string
          description: Transaction ID
        - name: address
          in: query
          type: string
        - name: type
          in: query
          type: array
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: limit
          in: query
          type: integer
          description: Results per page
    - name: extended-v1-tx-mempool
      path: /extended/v1/tx/mempool
      operations:
      - name: getmempooltransactionlist
        method: GET
        description: Get mempool transactions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: sender_address
          in: query
          type: string
          description: STX Address
        - name: recipient_address
          in: query
          type: string
          description: STX Address
        - name: address
          in: query
          type: string
          description: STX Address
        - name: order_by
          in: query
          type: string
          description: Option to sort results by transaction age, size, or fee rate.
        - name: order
          in: query
          type: string
          description: Results order
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
    - name: extended-v1-tx-mempool-stats
      path: /extended/v1/tx/mempool/stats
      operations:
      - name: getmempooltransactionstats
        method: GET
        description: Get statistics for mempool transactions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: extended-v1-tx-multiple
      path: /extended/v1/tx/multiple
      operations:
      - name: gettxlistdetails
        method: GET
        description: Get list of details for transactions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: tx_id
          in: query
          type: array
          required: true
        - name: event_limit
          in: query
          type: integer
          description: Results per page
        - name: event_offset
          in: query
          type: integer
          description: Result offset
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
    - name: extended-v1-tx-tx_id
      path: /extended/v1/tx/{tx_id}
      operations:
      - name: gettransactionbyid
        method: GET
        description: Get transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: event_limit
          in: query
          type: integer
          description: Results per page
        - name: event_offset
          in: query
          type: integer
          description: Result offset
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
        - name: tx_id
          in: path
          type: string
          description: Transaction ID
          required: true
    - name: extended-v1-tx-tx_id-raw
      path: /extended/v1/tx/{tx_id}/raw
      operations:
      - name: getrawtransactionbyid
        method: GET
        description: Get raw transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: event_limit
          in: query
          type: integer
          description: Results per page
        - name: event_offset
          in: query
          type: integer
          description: Result offset
        - name: tx_id
          in: path
          type: string
          description: Transaction ID
          required: true
    - name: extended-v2-addresses-address-transactions
      path: /extended/v2/addresses/{address}/transactions
      operations:
      - name: getaddresstransactions
        method: GET
        description: Get address transactions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: exclude_function_args
          in: query
          type: boolean
          description: Exclude function_args from contract call responses for smaller transaction sizes.
        - name: address
          in: path
          type: string
          required: true
    - name: extended-v2-addresses-address-transactions-tx_id-events
      path: /extended/v2/addresses/{address}/transactions/{tx_id}/events
      operations:
      - name: getaddresstransactionevents
        method: GET
        description: Get events for an address transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: address
          in: path
          type: string
          required: true
        - name: tx_id
          in: path
          type: string
          description: Transaction ID
          required: true
    - name: extended-v2-blocks-height_or_hash-transactions
      path: /extended/v2/blocks/{height_or_hash}/transactions
      operations:
      - name: gettransactionsbyblock
        method: GET
        description: Get transactions by block
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: limit
          in: query
          type: integer
          description: Results per page
        - name: offset
          in: query
          type: integer
          description: Result offset
        - name: height_or_hash
          in: path
          type: string
          required: true
  exposes:
  - type: rest
    namespace: stacks-blockchain-transactions-rest
    port: 8080
    description: REST adapter for Stacks Blockchain API — Transactions. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/extended/v1/address/{principal}/mempool
      name: extended-v1-address-principal-mempool
      description: REST surface for extended-v1-address-principal-mempool.
      operations:
      - method: GET
        name: getaddressmempooltransactions
        description: Transactions for address
        call: stacks-blockchain-transactions.getaddressmempooltransactions
        with:
          limit: rest.limit
          offset: rest.offset
          unanchored: rest.unanchored
          exclude_function_args: rest.exclude_function_args
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx
      name: extended-v1-tx
      description: REST surface for extended-v1-tx.
      operations:
      - method: GET
        name: gettransactionlist
        description: Get recent transactions
        call: stacks-blockchain-transactions.gettransactionlist
        with:
          offset: rest.offset
          limit: rest.limit
          type: rest.type
          unanchored: rest.unanchored
          order: rest.order
          sort_by: rest.sort_by
          from_address: rest.from_address
          to_address: rest.to_address
          start_time: rest.start_time
          end_time: rest.end_time
          contract_id: rest.contract_id
          function_name: rest.function_name
          nonce: rest.nonce
          exclude_function_args: rest.exclude_function_args
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/block/{block-hash}
      name: extended-v1-tx-block-block-hash
      description: REST surface for extended-v1-tx-block-block_hash.
      operations:
      - method: GET
        name: gettransactionsbyblockhash
        description: Transactions by block hash
        call: stacks-blockchain-transactions.gettransactionsbyblockhash
        with:
          offset: rest.offset
          limit: rest.limit
          exclude_function_args: rest.exclude_function_args
          block_hash: rest.block_hash
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/block-height/{height}
      name: extended-v1-tx-block-height-height
      description: REST surface for extended-v1-tx-block_height-height.
      operations:
      - method: GET
        name: gettransactionsbyblockheight
        description: Transactions by block height
        call: stacks-blockchain-transactions.gettransactionsbyblockheight
        with:
          offset: rest.offset
          limit: rest.limit
          exclude_function_args: rest.exclude_function_args
          height: rest.height
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/events
      name: extended-v1-tx-events
      description: REST surface for extended-v1-tx-events.
      operations:
      - method: GET
        name: getfilteredevents
        description: Transaction Events
        call: stacks-blockchain-transactions.getfilteredevents
        with:
          tx_id: rest.tx_id
          address: rest.address
          type: rest.type
          offset: rest.offset
          limit: rest.limit
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/mempool
      name: extended-v1-tx-mempool
      description: REST surface for extended-v1-tx-mempool.
      operations:
      - method: GET
        name: getmempooltransactionlist
        description: Get mempool transactions
        call: stacks-blockchain-transactions.getmempooltransactionlist
        with:
          sender_address: rest.sender_address
          recipient_address: rest.recipient_address
          address: rest.address
          order_by: rest.order_by
          order: rest.order
          unanchored: rest.unanchored
          offset: rest.offset
          limit: rest.limit
          exclude_function_args: rest.exclude_function_args
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/mempool/stats
      name: extended-v1-tx-mempool-stats
      description: REST surface for extended-v1-tx-mempool-stats.
      operations:
      - method: GET
        name: getmempooltransactionstats
        description: Get statistics for mempool transactions
        call: stacks-blockchain-transactions.getmempooltransactionstats
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/multiple
      name: extended-v1-tx-multiple
      description: REST surface for extended-v1-tx-multiple.
      operations:
      - method: GET
        name: gettxlistdetails
        description: Get list of details for transactions
        call: stacks-blockchain-transactions.gettxlistdetails
        with:
          tx_id: rest.tx_id
          event_limit: rest.event_limit
          event_offset: rest.event_offset
          unanchored: rest.unanchored
          exclude_function_args: rest.exclude_function_args
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/{tx-id}
      name: extended-v1-tx-tx-id
      description: REST surface for extended-v1-tx-tx_id.
      operations:
      - method: GET
        name: gettransactionbyid
        description: Get transaction
        call: stacks-blockchain-transactions.gettransactionbyid
        with:
          event_limit: rest.event_limit
          event_offset: rest.event_offset
          unanchored: rest.unanchored
          exclude_function_args: rest.exclude_function_args
          tx_id: rest.tx_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/tx/{tx-id}/raw
      name: extended-v1-tx-tx-id-raw
      description: REST surface for extended-v1-tx-tx_id-raw.
      operations:
      - method: GET
        name: getrawtransactionbyid
        description: Get raw transaction
        call: stacks-blockchain-transactions.getrawtransactionbyid
        with:
          event_limit: rest.event_limit
          event_offset: rest.event_offset
          tx_id: rest.tx_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v2/addresses/{address}/transactions
      name: extended-v2-addresses-address-transactions
      description: REST surface for extended-v2-addresses-address-transactions.
      operations:
      - method: GET
        name: getaddresstransactions
        description: Get address transactions
        call: stacks-blockchain-transactions.getaddresstransactions
        with:
          limit: rest.limit
          offset: rest.offset
          exclude_function_args: rest.exclude_function_args
          address: rest.address
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v2/addresses/{address}/transactions/{tx-id}/events
      name: extended-v2-addresses-address-transactions-tx-id-events
      description: REST surface for extended-v2-addresses-address-transactions-tx_id-events.
      operations:
      - method: GET
        name: getaddresstransactionevents
        description: Get events for an address transaction
        call: stacks-blockchain-transactions.getaddresstransactionevents
        with:
          limit: rest.limit
          offset: rest.offset
          address: rest.address
          tx_id: rest.tx_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v2/blocks/{height-or-hash}/transactions
      name: extended-v2-blocks-height-or-hash-transactions
      description: REST surface for extended-v2-blocks-height_or_hash-transactions.
      operations:
      - method: GET
        name: gettransactionsbyblock
        description: Get transactions by block
        call: stacks-blockchain-transactions.gettransactionsbyblock
        with:
          limit: rest.limit
          offset: rest.offset
          height_or_hash: rest.height_or_hash
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: stacks-blockchain-transactions-mcp
    port: 9090
    transport: http
    description: MCP adapter for Stacks Blockchain API — Transactions. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: transactions-address
      description: Transactions for address
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.getaddressmempooltransactions
      with:
        limit: tools.limit
        offset: tools.offset
        unanchored: tools.unanchored
        exclude_function_args: tools.exclude_function_args
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-recent-transactions
      description: Get recent transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.gettransactionlist
      with:
        offset: tools.offset
        limit: tools.limit
        type: tools.type
        unanchored: tools.unanchored
        order: tools.order
        sort_by: tools.sort_by
        from_address: tools.from_address
        to_address: tools.to_address
        start_time: tools.start_time
        end_time: tools.end_time
        contract_id: tools.contract_id
        function_name: tools.function_name
        nonce: tools.nonce
        exclude_function_args: tools.exclude_function_args
      outputParameters:
      - type: object
        mapping: $.
    - name: transactions-block-hash
      description: Transactions by block hash
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.gettransactionsbyblockhash
      with:
        offset: tools.offset
        limit: tools.limit
        exclude_function_args: tools.exclude_function_args
        block_hash: tools.block_hash
      outputParameters:
      - type: object
        mapping: $.
    - name: transactions-block-height
      description: Transactions by block height
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.gettransactionsbyblockheight
      with:
        offset: tools.offset
        limit: tools.limit
        exclude_function_args: tools.exclude_function_args
        height: tools.height
      outputParameters:
      - type: object
        mapping: $.
    - name: transaction-events
      description: Transaction Events
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.getfilteredevents
      with:
        tx_id: tools.tx_id
        address: tools.address
        type: tools.type
        offset: tools.offset
        limit: tools.limit
      outputParameters:
      - type: object
        mapping: $.
    - name: get-mempool-transactions
      description: Get mempool transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.getmempooltransactionlist
      with:
        sender_address: tools.sender_address
        recipient_address: tools.recipient_address
        address: tools.address
        order_by: tools.order_by
        order: tools.order
        unanchored: tools.unanchored
        offset: tools.offset
        limit: tools.limit
        exclude_function_args: tools.exclude_function_args
      outputParameters:
      - type: object
        mapping: $.
    - name: get-statistics-mempool-transactions
      description: Get statistics for mempool transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.getmempooltransactionstats
      outputParameters:
      - type: object
        mapping: $.
    - name: get-list-details-transactions
      description: Get list of details for transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.gettxlistdetails
      with:
        tx_id: tools.tx_id
        event_limit: tools.event_limit
        event_offset: tools.event_offset
        unanchored: tools.unanchored
        exclude_function_args: tools.exclude_function_args
      outputParameters:
      - type: object
        mapping: $.
    - name: get-transaction
      description: Get transaction
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.gettransactionbyid
      with:
        event_limit: tools.event_limit
        event_offset: tools.event_offset
        unanchored: tools.unanchored
        exclude_function_args: tools.exclude_function_args
        tx_id: tools.tx_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-raw-transaction
      description: Get raw transaction
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.getrawtransactionbyid
      with:
        event_limit: tools.event_limit
        event_offset: tools.event_offset
        tx_id: tools.tx_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-address-transactions
      description: Get address transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.getaddresstransactions
      with:
        limit: tools.limit
        offset: tools.offset
        exclude_function_args: tools.exclude_function_args
        address: tools.address
      outputParameters:
      - type: object
        mapping: $.
    - name: get-events-address-transaction
      description: Get events for an address transaction
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.getaddresstransactionevents
      with:
        limit: tools.limit
        offset: tools.offset
        address: tools.address
        tx_id: tools.tx_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-transactions-block
      description: Get transactions by block
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-transactions.gettransactionsbyblock
      with:
        limit: tools.limit
        offset: tools.offset
        height_or_hash: tools.height_or_hash
      outputParameters:
      - type: object
        mapping: $.