Stacks 3.0+ RPC API — Smart Contracts

naftiko: 1.0.0-alpha2
info:
  label: Stacks 3.0+ RPC API — Smart Contracts
  description: 'Stacks 3.0+ RPC API — Smart Contracts. 10 operations. Lead operation: Get the MARF value for a given key.
    Self-contained Naftiko capability covering one Hiro business surface.'
  tags:
  - Hiro
  - Smart Contracts
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    HIRO_API_KEY: HIRO_API_KEY
capability:
  consumes:
  - type: http
    namespace: stacks-node-rpc-smart-contracts
    baseUri: http://localhost:20443
    description: Stacks 3.0+ RPC API — Smart Contracts business capability. Self-contained, no shared references.
    resources:
    - name: v2-clarity-marf-marf_key_hash
      path: /v2/clarity/marf/{marf_key_hash}
      operations:
      - name: getclaritymarfvalue
        method: GET
        description: Get the MARF value for a given key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: marf_key_hash
          in: path
          type: string
          description: The 64-character hex-encoded hash of the MARF key.
          required: true
    - name: v2-clarity-metadata-deployer_address-contract_name-clarity_metadata_key
      path: /v2/clarity/metadata/{deployer_address}/{contract_name}/{clarity_metadata_key}
      operations:
      - name: getclaritymetadata
        method: GET
        description: Get the contract metadata for the metadata key
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: clarity_metadata_key
          in: path
          type: string
          description: 'Metadata key. Must be either:'
          required: true
    - name: v2-constant_val-deployer_address-contract_name-constant_name
      path: /v2/constant_val/{deployer_address}/{contract_name}/{constant_name}
      operations:
      - name: getconstantvalue
        method: GET
        description: Get the value of a constant inside a contract
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: constant_name
          in: path
          type: string
          required: true
    - name: v2-contracts-call-read-deployer_address-contract_name-function_name
      path: /v2/contracts/call-read/{deployer_address}/{contract_name}/{function_name}
      operations:
      - name: callreadonlyfunction
        method: POST
        description: Call read-only function
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: function_name
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-contracts-interface-deployer_address-contract_name
      path: /v2/contracts/interface/{deployer_address}/{contract_name}
      operations:
      - name: getcontractinterface
        method: GET
        description: Get contract interface
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v2-contracts-source-deployer_address-contract_name
      path: /v2/contracts/source/{deployer_address}/{contract_name}
      operations:
      - name: getcontractsource
        method: GET
        description: Get contract source
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: v2-data_var-principal-contract_name-var_name
      path: /v2/data_var/{principal}/{contract_name}/{var_name}
      operations:
      - name: getcontractdatavariable
        method: GET
        description: Get contract data variable
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: var_name
          in: path
          type: string
          description: Variable name (must be a valid Clarity name)
          required: true
    - name: v2-map_entry-deployer_address-contract_name-map_name
      path: /v2/map_entry/{deployer_address}/{contract_name}/{map_name}
      operations:
      - name: getcontractdatamapentry
        method: POST
        description: Get specific data-map inside a contract
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: map_name
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: v2-traits-deployer_address-contract_name-trait_deployer_address-trait_contract_n
      path: /v2/traits/{deployer_address}/{contract_name}/{trait_deployer_address}/{trait_contract_name}/{trait_name}
      operations:
      - name: checktraitimplementation
        method: GET
        description: Get trait implementation details
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: trait_deployer_address
          in: path
          type: string
          description: Stacks address of the trait-defining contract.
          required: true
        - name: trait_contract_name
          in: path
          type: string
          description: Contract name of the trait-defining contract.
          required: true
        - name: trait_name
          in: path
          type: string
          required: true
    - name: v3-contracts-fast-call-read-deployer_address-contract_name-function_name
      path: /v3/contracts/fast-call-read/{deployer_address}/{contract_name}/{function_name}
      operations:
      - name: fastcallreadonlyfunction
        method: POST
        description: Call read-only function in fast mode (no cost and memory tracking)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: function_name
          in: path
          type: string
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: apikey
      key: authorization
      value: '{{env.HIRO_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: stacks-node-rpc-smart-contracts-rest
    port: 8080
    description: REST adapter for Stacks 3.0+ RPC API — Smart Contracts. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/v2/clarity/marf/{marf-key-hash}
      name: v2-clarity-marf-marf-key-hash
      description: REST surface for v2-clarity-marf-marf_key_hash.
      operations:
      - method: GET
        name: getclaritymarfvalue
        description: Get the MARF value for a given key
        call: stacks-node-rpc-smart-contracts.getclaritymarfvalue
        with:
          marf_key_hash: rest.marf_key_hash
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/clarity/metadata/{deployer-address}/{contract-name}/{clarity-metadata-key}
      name: v2-clarity-metadata-deployer-address-contract-name-clarity-metadata-key
      description: REST surface for v2-clarity-metadata-deployer_address-contract_name-clarity_metadata_key.
      operations:
      - method: GET
        name: getclaritymetadata
        description: Get the contract metadata for the metadata key
        call: stacks-node-rpc-smart-contracts.getclaritymetadata
        with:
          clarity_metadata_key: rest.clarity_metadata_key
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/constant-val/{deployer-address}/{contract-name}/{constant-name}
      name: v2-constant-val-deployer-address-contract-name-constant-name
      description: REST surface for v2-constant_val-deployer_address-contract_name-constant_name.
      operations:
      - method: GET
        name: getconstantvalue
        description: Get the value of a constant inside a contract
        call: stacks-node-rpc-smart-contracts.getconstantvalue
        with:
          constant_name: rest.constant_name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/contracts/call-read/{deployer-address}/{contract-name}/{function-name}
      name: v2-contracts-call-read-deployer-address-contract-name-function-name
      description: REST surface for v2-contracts-call-read-deployer_address-contract_name-function_name.
      operations:
      - method: POST
        name: callreadonlyfunction
        description: Call read-only function
        call: stacks-node-rpc-smart-contracts.callreadonlyfunction
        with:
          function_name: rest.function_name
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/contracts/interface/{deployer-address}/{contract-name}
      name: v2-contracts-interface-deployer-address-contract-name
      description: REST surface for v2-contracts-interface-deployer_address-contract_name.
      operations:
      - method: GET
        name: getcontractinterface
        description: Get contract interface
        call: stacks-node-rpc-smart-contracts.getcontractinterface
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/contracts/source/{deployer-address}/{contract-name}
      name: v2-contracts-source-deployer-address-contract-name
      description: REST surface for v2-contracts-source-deployer_address-contract_name.
      operations:
      - method: GET
        name: getcontractsource
        description: Get contract source
        call: stacks-node-rpc-smart-contracts.getcontractsource
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/data-var/{principal}/{contract-name}/{var-name}
      name: v2-data-var-principal-contract-name-var-name
      description: REST surface for v2-data_var-principal-contract_name-var_name.
      operations:
      - method: GET
        name: getcontractdatavariable
        description: Get contract data variable
        call: stacks-node-rpc-smart-contracts.getcontractdatavariable
        with:
          var_name: rest.var_name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/map-entry/{deployer-address}/{contract-name}/{map-name}
      name: v2-map-entry-deployer-address-contract-name-map-name
      description: REST surface for v2-map_entry-deployer_address-contract_name-map_name.
      operations:
      - method: POST
        name: getcontractdatamapentry
        description: Get specific data-map inside a contract
        call: stacks-node-rpc-smart-contracts.getcontractdatamapentry
        with:
          map_name: rest.map_name
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v2/traits/{deployer-address}/{contract-name}/{trait-deployer-address}/{trait-contract-name}/{trait-name}
      name: v2-traits-deployer-address-contract-name-trait-deployer-address-trait-contract-n
      description: REST surface for v2-traits-deployer_address-contract_name-trait_deployer_address-trait_contract_n.
      operations:
      - method: GET
        name: checktraitimplementation
        description: Get trait implementation details
        call: stacks-node-rpc-smart-contracts.checktraitimplementation
        with:
          trait_deployer_address: rest.trait_deployer_address
          trait_contract_name: rest.trait_contract_name
          trait_name: rest.trait_name
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/v3/contracts/fast-call-read/{deployer-address}/{contract-name}/{function-name}
      name: v3-contracts-fast-call-read-deployer-address-contract-name-function-name
      description: REST surface for v3-contracts-fast-call-read-deployer_address-contract_name-function_name.
      operations:
      - method: POST
        name: fastcallreadonlyfunction
        description: Call read-only function in fast mode (no cost and memory tracking)
        call: stacks-node-rpc-smart-contracts.fastcallreadonlyfunction
        with:
          function_name: rest.function_name
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: stacks-node-rpc-smart-contracts-mcp
    port: 9090
    transport: http
    description: MCP adapter for Stacks 3.0+ RPC API — Smart Contracts. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: get-marf-value-given-key
      description: Get the MARF value for a given key
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-node-rpc-smart-contracts.getclaritymarfvalue
      with:
        marf_key_hash: tools.marf_key_hash
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contract-metadata-metadata-key
      description: Get the contract metadata for the metadata key
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-node-rpc-smart-contracts.getclaritymetadata
      with:
        clarity_metadata_key: tools.clarity_metadata_key
      outputParameters:
      - type: object
        mapping: $.
    - name: get-value-constant-inside-contract
      description: Get the value of a constant inside a contract
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-node-rpc-smart-contracts.getconstantvalue
      with:
        constant_name: tools.constant_name
      outputParameters:
      - type: object
        mapping: $.
    - name: call-read-only-function
      description: Call read-only function
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: stacks-node-rpc-smart-contracts.callreadonlyfunction
      with:
        function_name: tools.function_name
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contract-interface
      description: Get contract interface
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-node-rpc-smart-contracts.getcontractinterface
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contract-source
      description: Get contract source
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-node-rpc-smart-contracts.getcontractsource
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contract-data-variable
      description: Get contract data variable
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-node-rpc-smart-contracts.getcontractdatavariable
      with:
        var_name: tools.var_name
      outputParameters:
      - type: object
        mapping: $.
    - name: get-specific-data-map-inside
      description: Get specific data-map inside a contract
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: stacks-node-rpc-smart-contracts.getcontractdatamapentry
      with:
        map_name: tools.map_name
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-trait-implementation-details
      description: Get trait implementation details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: stacks-node-rpc-smart-contracts.checktraitimplementation
      with:
        trait_deployer_address: tools.trait_deployer_address
        trait_contract_name: tools.trait_contract_name
        trait_name: tools.trait_name
      outputParameters:
      - type: object
        mapping: $.
    - name: call-read-only-function-fast
      description: Call read-only function in fast mode (no cost and memory tracking)
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: stacks-node-rpc-smart-contracts.fastcallreadonlyfunction
      with:
        function_name: tools.function_name
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.