Hiro Smart Contracts API
Read-only endpoints to obtain Clarity smart contract details
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics Accounts Smart Contracts API
description: Welcome to the API reference overview for the Signer Metrics API.
version: 1.0.3
servers:
- url: https://api.hiro.so/
description: mainnet
- url: https://api.testnet.hiro.so/
description: testnet
tags:
- name: Smart Contracts
description: Read-only endpoints to obtain Clarity smart contract details
externalDocs:
description: Stacks Documentation - Clarity Smart Contracts
url: https://docs.stacks.co/clarity/overview
paths:
/extended/v1/contract/by_trait:
get:
operationId: get_contracts_by_trait
summary: Get contracts by trait
tags:
- Smart Contracts
description: Retrieves a list of contracts based on the following traits listed in JSON format - functions, variables, maps, fungible tokens and non-fungible tokens
parameters:
- schema:
type: string
in: query
name: trait_abi
required: true
description: JSON abi of the trait.
- schema:
minimum: 0
default: 20
maximum: 50
title: Limit
type: integer
in: query
name: limit
required: false
description: max number of contracts fetch
- schema:
minimum: 0
default: 0
title: Offset
type: integer
in: query
name: offset
required: false
description: index of first contract event to fetch
responses:
'200':
description: GET list of contracts
content:
application/json:
schema:
title: ContractListResponse
description: GET list of contracts
type: object
properties:
limit:
type: integer
example: 20
offset:
type: integer
example: 0
results:
type: array
items:
title: SmartContract
description: A Smart Contract Detail
type: object
properties:
tx_id:
type: string
canonical:
type: boolean
contract_id:
type: string
block_height:
type: integer
clarity_version:
anyOf:
- type: integer
- type: 'null'
source_code:
type: string
abi:
anyOf:
- type: string
- type: 'null'
required:
- tx_id
- canonical
- contract_id
- block_height
- clarity_version
- source_code
- abi
required:
- limit
- offset
- results
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/extended/v1/contract/{contract_id}:
get:
operationId: get_contract_by_id
summary: Get contract info
tags:
- Smart Contracts
description: Retrieves details of a contract with a given `contract_id`
parameters:
- schema:
type: string
example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles
in: path
name: contract_id
required: true
description: Contract identifier formatted as `<contract_address>.<contract_name>`
responses:
'200':
description: A Smart Contract Detail
content:
application/json:
schema:
title: SmartContract
description: A Smart Contract Detail
type: object
properties:
tx_id:
type: string
canonical:
type: boolean
contract_id:
type: string
block_height:
type: integer
clarity_version:
anyOf:
- type: integer
- type: 'null'
source_code:
type: string
abi:
anyOf:
- type: string
- type: 'null'
required:
- tx_id
- canonical
- contract_id
- block_height
- clarity_version
- source_code
- abi
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/extended/v1/contract/{contract_id}/events:
get:
operationId: get_contract_events_by_id
summary: Get contract events
tags:
- Smart Contracts
description: Retrieves a list of events that have been triggered by a given `contract_id`
parameters:
- schema:
minimum: 0
default: 20
maximum: 50
title: Limit
type: integer
in: query
name: limit
required: false
description: max number of events to fetch
- schema:
minimum: 0
default: 0
title: Offset
type: integer
in: query
name: offset
required: false
description: Result offset
- schema:
type: string
example: SP6P4EJF0VG8V0RB3TQQKJBHDQKEF6NVRD1KZE3C.satoshibles
in: path
name: contract_id
required: true
description: Contract identifier formatted as `<contract_address>.<contract_name>`
responses:
'200':
description: List of events
content:
application/json:
schema:
description: List of events
type: object
properties:
limit:
type: integer
offset:
type: integer
results:
type: array
items:
anyOf:
- title: SmartContractLogTransactionEvent
description: Only present in `smart_contract` and `contract_call` tx types.
type: object
allOf:
- title: AbstractTransactionEvent
type: object
properties:
event_index:
type: integer
required:
- event_index
- type: object
properties:
event_type:
type: string
enum:
- smart_contract_log
tx_id:
type: string
contract_log:
type: object
properties:
contract_id:
type: string
topic:
type: string
value:
type: object
properties:
hex:
type: string
repr:
type: string
required:
- hex
- repr
required:
- contract_id
- topic
- value
required:
- event_type
- tx_id
- contract_log
- title: StxLockTransactionEvent
description: Only present in `smart_contract` and `contract_call` tx types.
type: object
allOf:
- title: AbstractTransactionEvent
type: object
properties:
event_index:
type: integer
required:
- event_index
- type: object
properties:
event_type:
type: string
enum:
- stx_lock
tx_id:
type: string
stx_lock_event:
type: object
properties:
locked_amount:
type: string
unlock_height:
type: integer
locked_address:
type: string
required:
- locked_amount
- unlock_height
- locked_address
required:
- event_type
- tx_id
- stx_lock_event
- title: StxAssetTransactionEvent
description: Only present in `smart_contract` and `contract_call` tx types.
type: object
allOf:
- title: AbstractTransactionEvent
type: object
properties:
event_index:
type: integer
required:
- event_index
- type: object
properties:
event_type:
type: string
enum:
- stx_asset
tx_id:
type: string
asset:
type: object
properties:
asset_event_type:
anyOf:
- type: string
enum:
- transfer
- type: string
enum:
- mint
- type: string
enum:
- burn
sender:
type: string
recipient:
type: string
amount:
type: string
memo:
type: string
required:
- asset_event_type
- sender
- recipient
- amount
required:
- event_type
- tx_id
- asset
- title: FungibleTokenAssetTransactionEvent
type: object
allOf:
- title: AbstractTransactionEvent
type: object
properties:
event_index:
type: integer
required:
- event_index
- type: object
properties:
event_type:
type: string
enum:
- fungible_token_asset
tx_id:
type: string
asset:
type: object
properties:
asset_event_type:
anyOf:
- type: string
enum:
- transfer
- type: string
enum:
- mint
- type: string
enum:
- burn
asset_id:
type: string
sender:
type: string
recipient:
type: string
amount:
type: string
required:
- asset_event_type
- asset_id
- sender
- recipient
- amount
required:
- event_type
- tx_id
- asset
- title: NonFungibleTokenAssetTransactionEvent
type: object
allOf:
- title: AbstractTransactionEvent
type: object
properties:
event_index:
type: integer
required:
- event_index
- type: object
properties:
event_type:
type: string
enum:
- non_fungible_token_asset
tx_id:
type: string
asset:
type: object
properties:
asset_event_type:
anyOf:
- type: string
enum:
- transfer
- type: string
enum:
- mint
- type: string
enum:
- burn
asset_id:
type: string
sender:
type: string
recipient:
type: string
value:
type: object
properties:
hex:
type: string
repr:
type: string
required:
- hex
- repr
required:
- asset_event_type
- asset_id
- sender
- recipient
- value
required:
- event_type
- tx_id
- asset
required:
- limit
- offset
- results
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/extended/v2/smart-contracts/status:
get:
operationId: get_smart_contracts_status
summary: Get smart contracts status
tags:
- Smart Contracts
description: Retrieves the deployment status of multiple smart contracts.
parameters:
- schema:
anyOf:
- type: array
items:
pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
title: Smart Contract ID
description: Smart Contract ID
examples:
- SP000000000000000000002Q6VF78.pox-3
type: string
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$
title: Smart Contract ID
description: Smart Contract ID
examples:
- SP000000000000000000002Q6VF78.pox-3
type: string
in: query
name: contract_id
required: true
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
additionalProperties:
anyOf:
- type: object
properties:
found:
const: true
type: boolean
result:
type: object
properties:
status:
description: Smart contract deployment transaction status
type: string
tx_id:
description: Deployment transaction ID
type: string
contract_id:
description: Smart contract ID
type: string
block_height:
description: Height of the transaction confirmation block
type: integer
required:
- status
- tx_id
- contract_id
required:
- found
- result
- type: object
properties:
found:
const: false
type: boolean
required:
- found
4XX:
description: Default Response
content:
application/json:
schema:
title: Error Response
additionalProperties: true
type: object
properties:
error:
type: string
message:
type: string
required:
- error
/v2/contracts/interface/{deployer_address}/{contract_name}:
get:
summary: Get contract interface
description: Get contract interface using a `deployer_address` and `contract name`
tags:
- Smart Contracts
security: []
operationId: getContractInterface
parameters:
- $ref: ./components/parameters/deployer-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- $ref: ./components/parameters/tip.yaml
responses:
'200':
description: Contract interface
content:
application/json:
schema:
$ref: '#/components/schemas/ContractInterface'
examples:
contract-interface:
$ref: ./components/examples/contract-interface.example.json
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/map_entry/{deployer_address}/{contract_name}/{map_name}:
post:
summary: Get specific data-map inside a contract
tags:
- Smart Contracts
security: []
operationId: getContractDataMapEntry
description: "Attempt to fetch data from a contract data map. The contract is\nidentified with [Stacks Address] and [Contract Name] in the URL path.\nThe map is identified with [Map Name].\n\nThe key to lookup in the map is supplied via the POST body. This should\nbe supplied as the hex string serialization of the key (which should be\na Clarity value). Note, this is a JSON string.\n\nThe response is a JSON object with the following properties:\n- `data`: The hex serialization of the map response. Note that map\n responses are Clarity option types, for non-existent values, this is\n a serialized none, and for all other responses, it is a serialized\n (some ...) object.\n- `proof`: The hex serialization of the Merkle proof for the data.\n"
parameters:
- $ref: ./components/parameters/deployer-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: map_name
in: path
required: true
schema:
$ref: '#/components/schemas/ClarityName'
- $ref: ./components/parameters/proof.yaml
- $ref: ./components/parameters/tip.yaml
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
minLength: 2
pattern: ^(0x)?([0-9a-fA-F]{2})+$
description: Hex-encoded Clarity value (e.g. "0x0100000000000000000000000000000001")
example: '0x0100000000000000000000000000000001'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ClarityData'
examples:
clarity-data:
$ref: ./components/examples/clarity-data.example.json
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/contracts/source/{deployer_address}/{contract_name}:
get:
summary: Get contract source
tags:
- Smart Contracts
security: []
operationId: getContractSource
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.
'
parameters:
- $ref: ./components/parameters/deployer-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- $ref: ./components/parameters/proof.yaml
- $ref: ./components/parameters/tip.yaml
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ContractSource'
examples:
contract-source:
$ref: ./components/examples/contract-source.example.json
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/contracts/call-read/{deployer_address}/{contract_name}/{function_name}:
post:
summary: Call read-only function
description: 'Call a read-only public function on a given contract.
The contract is identified with [Stacks Address] and [Contract Name] in the URL path.
The function is identified with [Function Name].
The arguments to the function are supplied via the POST body.
This should be a JSON object with two main properties:
- `sender` which should be a Stacks address or contract principal
- `arguments` which should be an array of hex-encoded Clarity values.
'
tags:
- Smart Contracts
security: []
operationId: callReadOnlyFunction
parameters:
- $ref: ./components/parameters/deployer-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: function_name
in: path
required: true
schema:
$ref: '#/components/schemas/ClarityName'
- $ref: ./components/parameters/tip.yaml
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ReadOnlyFunctionArgs'
responses:
'200':
description: Function executed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ReadOnlyFunctionResult'
examples:
success:
$ref: ./components/examples/read-only-function-success.example.json
failure:
$ref: ./components/examples/read-only-function-failure.example.json
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
'500':
$ref: '#/components/responses/InternalServerError'
/v3/contracts/fast-call-read/{deployer_address}/{contract_name}/{function_name}:
post:
summary: Call read-only function in fast mode (no cost and memory tracking)
description: 'Call a read-only public function on a given smart contract without cost tracking.
The contract is identified with [Stacks Address] and [Contract Name] in the URL path.
The function is identified with [Function Name].
The arguments to the function are supplied via the POST body.
This should be a JSON object with two main properties:
- `sender` which should be a Stacks address or contract principal
- `arguments` which should be an array of hex-encoded Clarity values.
**This API endpoint requires a basic Authorization header.**
'
tags:
- Smart Contracts
security:
- rpcAuth: []
operationId: fastCallReadOnlyFunction
parameters:
- $ref: ./components/parameters/deployer-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: function_name
in: path
required: true
schema:
$ref: '#/components/schemas/ClarityName'
- $ref: ./components/parameters/tip.yaml
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: '#/components/schemas/ReadOnlyFunctionArgs'
examples:
fast-call-request:
summary: Fast call read-only function request
value:
sender: SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info
arguments:
- 0x0011...
- 0x00231...
responses:
'200':
description: Function executed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ReadOnlyFunctionResult'
examples:
success:
$ref: ./components/examples/read-only-function-success.example.json
failure:
$ref: ./components/examples/read-only-function-failure.example.json
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'408':
$ref: '#/components/responses/Timeout'
'500':
$ref: '#/components/responses/InternalServerError'
/v2/traits/{deployer_address}/{contract_name}/{trait_deployer_address}/{trait_contract_name}/{trait_name}:
get:
summary: Get trait implementation details
description: 'Determine whether or not a specified trait is implemented (either
explicitly or implicitly) within a given contract.
'
tags:
- Smart Contracts
security: []
operationId: checkTraitImplementation
parameters:
- $ref: ./components/parameters/deployer-address.yaml
- $ref: ./components/parameters/contract-name.yaml
- name: trait_deployer_address
in: path
required: true
description: 'Stacks address of the trait-defining contract.
'
schema:
$ref: ./components/schemas/standard-principal.schema.yaml
- name: trait_contract_name
in: path
required: true
description: Contract name of the trait-defining contract.
schema:
type: string
pattern: ^[a-zA-Z]([a-zA-Z0-9]|[-_]){0,127}$
minLength: 1
maxLength: 128
example: some-trait
- name: trait_name
in: path
required: true
schema:
$ref: '#/components/schemas/ClarityName'
example: some-trait
- $ref: ./components/parameters/tip.yaml
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/IsTraitImplemented'
examples:
is-trait-implemented:
$ref: ./components/examples/is-trait-implemented.example.json
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
/v2/clarity/marf/{marf_key_hash}:
get:
summary: Get the MARF value for a given key
tags:
- Smart Contracts
security: []
operationId: getClarityMarfValue
description: 'Attempt to fetch the value of a MARF key. The key is a 64-character
hex string representing the MARF node hash.
'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ClarityData'
examples:
clarity-data:
$ref: ./components/examples/clarity-data.example.json
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
parameters:
- nam
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-smart-contracts-api-openapi.yml