Stacks Blockchain API — Accounts

naftiko: 1.0.0-alpha2
info:
  label: Stacks Blockchain API — Accounts
  description: 'Stacks Blockchain API — Accounts. 11 operations. Lead operation: Get account assets. Self-contained Naftiko
    capability covering one Hiro business surface.'
  tags:
  - Hiro
  - Accounts
  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-accounts
    baseUri: https://api.hiro.so
    description: Stacks Blockchain API — Accounts business capability. Self-contained, no shared references.
    resources:
    - name: extended-v1-address-principal-assets
      path: /extended/v1/address/{principal}/assets
      operations:
      - name: getaccountassets
        method: GET
        description: Get account assets
        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: until_block
          in: query
          type: string
          description: Block hash or block height. Return data representing the state up until that point in time, rather
            than the current block. Note - Use either of the query parame
        - name: principal
          in: path
          type: string
          required: true
    - name: extended-v1-address-principal-balances
      path: /extended/v1/address/{principal}/balances
      operations:
      - name: getaccountbalance
        method: GET
        description: Get account balances
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: until_block
          in: query
          type: string
          description: Block hash or block height. Return data representing the state up until that point in time, rather
            than the current block. Note - Use either of the query parame
        - name: principal
          in: path
          type: string
          required: true
    - name: extended-v1-address-principal-nonces
      path: /extended/v1/address/{principal}/nonces
      operations:
      - name: getaccountnonces
        method: GET
        description: Get the latest nonce used by an account
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: block_height
          in: query
          type: integer
          description: Optionally get the nonce at a given block height.
        - name: block_hash
          in: query
          type: string
          description: Optionally get the nonce at a given block hash. Note - Use either of the query parameters but not both
            at a time.
        - name: principal
          in: path
          type: string
          required: true
    - name: extended-v1-address-principal-stx
      path: /extended/v1/address/{principal}/stx
      operations:
      - name: getaccountstxbalance
        method: GET
        description: Get account STX balance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: until_block
          in: query
          type: string
          description: Block hash or block height. Return data representing the state up until that point in time, rather
            than the current block. Note - Use either of the query parame
        - name: principal
          in: path
          type: string
          required: true
    - name: extended-v1-address-principal-stx_inbound
      path: /extended/v1/address/{principal}/stx_inbound
      operations:
      - name: getaccountinbound
        method: GET
        description: Get inbound STX transfers
        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
          in: query
          type: integer
          description: Filter for transactions only at this given block height
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: until_block
          in: query
          type: string
          description: Block hash or block height. Return data representing the state up until that point in time, rather
            than the current block. Note - Use either of the query parame
        - name: principal
          in: path
          type: string
          required: true
    - name: extended-v1-address-principal-transactions
      path: /extended/v1/address/{principal}/transactions
      operations:
      - name: getaccounttransactions
        method: GET
        description: Get account 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: height
          in: query
          type: integer
          description: Filter for transactions only at this given block height
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: until_block
          in: query
          type: string
          description: Block hash or block height. Return data representing the state up until that point in time, rather
            than the current block. Note - Use either of the query parame
        - 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-address-principal-transactions_with_transfers
      path: /extended/v1/address/{principal}/transactions_with_transfers
      operations:
      - name: getaccounttransactionswithtransfers
        method: GET
        description: Get account transactions including STX transfers for each 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: height
          in: query
          type: integer
          description: Filter for transactions only at this given block height
        - name: unanchored
          in: query
          type: boolean
          description: Include data from unanchored (i.e. unconfirmed) microblocks
        - name: until_block
          in: query
          type: string
          description: Block hash or block height. Return data representing the state up until that point in time, rather
            than the current block. Note - Use either of the query parame
        - name: principal
          in: path
          type: string
          required: true
    - name: extended-v1-address-principal-tx_id-with_transfers
      path: /extended/v1/address/{principal}/{tx_id}/with_transfers
      operations:
      - name: getsingletransactionwithtransfers
        method: GET
        description: Get account transaction information for specific transaction
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: principal
          in: path
          type: string
          required: true
        - name: tx_id
          in: path
          type: string
          description: Transaction ID
          required: true
    - name: extended-v2-addresses-principal-balances-ft
      path: /extended/v2/addresses/{principal}/balances/ft
      operations:
      - name: getprincipalftbalances
        method: GET
        description: Get principal FT balances
        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: principal
          in: path
          type: string
          required: true
    - name: extended-v2-addresses-principal-balances-ft-token
      path: /extended/v2/addresses/{principal}/balances/ft/{token}
      operations:
      - name: getprincipalftbalance
        method: GET
        description: Get principal FT balance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: principal
          in: path
          type: string
          required: true
        - name: token
          in: path
          type: string
          description: fungible token identifier, e.g. `SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token::sbtc-token`
          required: true
    - name: extended-v2-addresses-principal-balances-stx
      path: /extended/v2/addresses/{principal}/balances/stx
      operations:
      - name: getprincipalstxbalance
        method: GET
        description: Get principal STX balance
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: include_mempool
          in: query
          type: boolean
          description: Include pending mempool transactions in the balance calculation
        - name: principal
          in: path
          type: string
          required: true
  exposes:
  - type: rest
    namespace: stacks-blockchain-accounts-rest
    port: 8080
    description: REST adapter for Stacks Blockchain API — Accounts. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/extended/v1/address/{principal}/assets
      name: extended-v1-address-principal-assets
      description: REST surface for extended-v1-address-principal-assets.
      operations:
      - method: GET
        name: getaccountassets
        description: Get account assets
        call: stacks-blockchain-accounts.getaccountassets
        with:
          limit: rest.limit
          offset: rest.offset
          unanchored: rest.unanchored
          until_block: rest.until_block
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/address/{principal}/balances
      name: extended-v1-address-principal-balances
      description: REST surface for extended-v1-address-principal-balances.
      operations:
      - method: GET
        name: getaccountbalance
        description: Get account balances
        call: stacks-blockchain-accounts.getaccountbalance
        with:
          unanchored: rest.unanchored
          until_block: rest.until_block
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/address/{principal}/nonces
      name: extended-v1-address-principal-nonces
      description: REST surface for extended-v1-address-principal-nonces.
      operations:
      - method: GET
        name: getaccountnonces
        description: Get the latest nonce used by an account
        call: stacks-blockchain-accounts.getaccountnonces
        with:
          block_height: rest.block_height
          block_hash: rest.block_hash
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/address/{principal}/stx
      name: extended-v1-address-principal-stx
      description: REST surface for extended-v1-address-principal-stx.
      operations:
      - method: GET
        name: getaccountstxbalance
        description: Get account STX balance
        call: stacks-blockchain-accounts.getaccountstxbalance
        with:
          unanchored: rest.unanchored
          until_block: rest.until_block
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/address/{principal}/stx-inbound
      name: extended-v1-address-principal-stx-inbound
      description: REST surface for extended-v1-address-principal-stx_inbound.
      operations:
      - method: GET
        name: getaccountinbound
        description: Get inbound STX transfers
        call: stacks-blockchain-accounts.getaccountinbound
        with:
          limit: rest.limit
          offset: rest.offset
          height: rest.height
          unanchored: rest.unanchored
          until_block: rest.until_block
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/address/{principal}/transactions
      name: extended-v1-address-principal-transactions
      description: REST surface for extended-v1-address-principal-transactions.
      operations:
      - method: GET
        name: getaccounttransactions
        description: Get account transactions
        call: stacks-blockchain-accounts.getaccounttransactions
        with:
          limit: rest.limit
          offset: rest.offset
          height: rest.height
          unanchored: rest.unanchored
          until_block: rest.until_block
          exclude_function_args: rest.exclude_function_args
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/address/{principal}/transactions-with-transfers
      name: extended-v1-address-principal-transactions-with-transfers
      description: REST surface for extended-v1-address-principal-transactions_with_transfers.
      operations:
      - method: GET
        name: getaccounttransactionswithtransfers
        description: Get account transactions including STX transfers for each transaction.
        call: stacks-blockchain-accounts.getaccounttransactionswithtransfers
        with:
          limit: rest.limit
          offset: rest.offset
          height: rest.height
          unanchored: rest.unanchored
          until_block: rest.until_block
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v1/address/{principal}/{tx-id}/with-transfers
      name: extended-v1-address-principal-tx-id-with-transfers
      description: REST surface for extended-v1-address-principal-tx_id-with_transfers.
      operations:
      - method: GET
        name: getsingletransactionwithtransfers
        description: Get account transaction information for specific transaction
        call: stacks-blockchain-accounts.getsingletransactionwithtransfers
        with:
          principal: rest.principal
          tx_id: rest.tx_id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v2/addresses/{principal}/balances/ft
      name: extended-v2-addresses-principal-balances-ft
      description: REST surface for extended-v2-addresses-principal-balances-ft.
      operations:
      - method: GET
        name: getprincipalftbalances
        description: Get principal FT balances
        call: stacks-blockchain-accounts.getprincipalftbalances
        with:
          limit: rest.limit
          offset: rest.offset
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v2/addresses/{principal}/balances/ft/{token}
      name: extended-v2-addresses-principal-balances-ft-token
      description: REST surface for extended-v2-addresses-principal-balances-ft-token.
      operations:
      - method: GET
        name: getprincipalftbalance
        description: Get principal FT balance
        call: stacks-blockchain-accounts.getprincipalftbalance
        with:
          principal: rest.principal
          token: rest.token
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/extended/v2/addresses/{principal}/balances/stx
      name: extended-v2-addresses-principal-balances-stx
      description: REST surface for extended-v2-addresses-principal-balances-stx.
      operations:
      - method: GET
        name: getprincipalstxbalance
        description: Get principal STX balance
        call: stacks-blockchain-accounts.getprincipalstxbalance
        with:
          include_mempool: rest.include_mempool
          principal: rest.principal
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: stacks-blockchain-accounts-mcp
    port: 9090
    transport: http
    description: MCP adapter for Stacks Blockchain API — Accounts. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: get-account-assets
      description: Get account assets
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getaccountassets
      with:
        limit: tools.limit
        offset: tools.offset
        unanchored: tools.unanchored
        until_block: tools.until_block
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account-balances
      description: Get account balances
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getaccountbalance
      with:
        unanchored: tools.unanchored
        until_block: tools.until_block
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-latest-nonce-used-account
      description: Get the latest nonce used by an account
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getaccountnonces
      with:
        block_height: tools.block_height
        block_hash: tools.block_hash
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account-stx-balance
      description: Get account STX balance
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getaccountstxbalance
      with:
        unanchored: tools.unanchored
        until_block: tools.until_block
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-inbound-stx-transfers
      description: Get inbound STX transfers
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getaccountinbound
      with:
        limit: tools.limit
        offset: tools.offset
        height: tools.height
        unanchored: tools.unanchored
        until_block: tools.until_block
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account-transactions
      description: Get account transactions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getaccounttransactions
      with:
        limit: tools.limit
        offset: tools.offset
        height: tools.height
        unanchored: tools.unanchored
        until_block: tools.until_block
        exclude_function_args: tools.exclude_function_args
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account-transactions-including-stx
      description: Get account transactions including STX transfers for each transaction.
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getaccounttransactionswithtransfers
      with:
        limit: tools.limit
        offset: tools.offset
        height: tools.height
        unanchored: tools.unanchored
        until_block: tools.until_block
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-account-transaction-information-specific
      description: Get account transaction information for specific transaction
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getsingletransactionwithtransfers
      with:
        principal: tools.principal
        tx_id: tools.tx_id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-principal-ft-balances
      description: Get principal FT balances
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getprincipalftbalances
      with:
        limit: tools.limit
        offset: tools.offset
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.
    - name: get-principal-ft-balance
      description: Get principal FT balance
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getprincipalftbalance
      with:
        principal: tools.principal
        token: tools.token
      outputParameters:
      - type: object
        mapping: $.
    - name: get-principal-stx-balance
      description: Get principal STX balance
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-blockchain-accounts.getprincipalstxbalance
      with:
        include_mempool: tools.include_mempool
        principal: tools.principal
      outputParameters:
      - type: object
        mapping: $.