Hiro Non-Fungible Tokens API
Read-only endpoints to obtain non-fungible token details
OpenAPI Specification
openapi: 3.0.3
info:
title: Signer Metrics Accounts Non-Fungible Tokens 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: Non-Fungible Tokens
description: Read-only endpoints to obtain non-fungible token details
externalDocs:
description: Stacks Documentation - Tokens
url: https://docs.stacks.co/build/create-tokens
paths:
/extended/v1/tokens/nft/holdings:
get:
operationId: get_nft_holdings
summary: Non-Fungible Token holdings
tags:
- Non-Fungible Tokens
description: "Retrieves the list of Non-Fungible Tokens owned by the given principal (STX address or Smart Contract ID).\n Results can be filtered by one or more asset identifiers and can include metadata about the transaction that made the principal own each token.\n\n More information on Non-Fungible Tokens on the Stacks blockchain can be found [here](https://docs.stacks.co/build/create-tokens/creating-a-nft)."
parameters:
- schema:
anyOf:
- pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}
title: STX Address
description: STX Address
examples:
- SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP
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: principal
required: true
- schema:
type: array
items:
description: identifiers of the token asset classes to filter for
examples:
- SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy::candy
type: string
in: query
name: asset_identifiers
required: false
- schema:
minimum: 0
default: 50
maximum: 200
title: Limit
type: integer
in: query
name: limit
required: false
description: max number of tokens to fetch
- schema:
minimum: 0
default: 0
title: Offset
type: integer
in: query
name: offset
required: false
description: index of first tokens to fetch
- schema:
default: false
type: boolean
in: query
name: tx_metadata
required: true
description: whether or not to include the complete transaction metadata instead of just `tx_id`. Enabling this option can affect performance and response times.
responses:
'200':
description: List of Non-Fungible Token holdings
content:
application/json:
schema:
description: List of Non-Fungible Token holdings
type: object
properties:
limit:
type: integer
example: 20
offset:
type: integer
example: 0
total:
type: integer
example: 1
results:
type: array
items:
title: NonFungibleTokenHoldingsList
description: List of Non-Fungible Token holdings
anyOf:
- title: NonFungibleTokenHoldingWithTxId
description: Ownership of a Non-Fungible Token
type: object
properties:
asset_identifier:
type: string
value:
description: Non-Fungible Token value
type: object
properties:
hex:
description: Hex string representing the identifier of the Non-Fungible Token
type: string
repr:
description: Readable string of the Non-Fungible Token identifier
type: string
required:
- hex
- repr
block_height:
type: integer
tx_id:
type: string
required:
- asset_identifier
- value
- block_height
- tx_id
- title: NonFungibleTokenHoldingWithTxMetadata
description: Ownership of a Non-Fungible Token with transaction metadata
type: object
properties:
asset_identifier:
type: string
value:
description: Non-Fungible Token value
type: object
properties:
hex:
description: Hex string representing the identifier of the Non-Fungible Token
type: string
repr:
description: Readable string of the Non-Fungible Token identifier
type: string
required:
- hex
- repr
block_height:
type: integer
tx:
anyOf:
- title: TokenTransferTransaction
type: object
properties:
tx_id:
description: Transaction ID
type: string
nonce:
description: Used for ordering the transactions originating from and paying from an account. The nonce ensures that a transaction is processed at most once. The nonce counts the number of times an account's owner(s) have authorized a transaction. The first transaction from an account will have a nonce value equal to 0, the second will have a nonce value equal to 1, and so on.
type: integer
fee_rate:
description: Transaction fee as Integer string (64-bit unsigned integer).
type: string
sender_address:
description: Address of the transaction initiator
type: string
sponsor_nonce:
type: integer
sponsored:
description: Denotes whether the originating account is the same as the paying account
type: boolean
sponsor_address:
type: string
post_condition_mode:
anyOf:
- type: string
enum:
- allow
- type: string
enum:
- deny
post_conditions:
type: array
items:
anyOf:
- type: object
properties:
principal:
anyOf:
- type: object
properties:
type_id:
type: string
enum:
- principal_origin
required:
- type_id
- type: object
properties:
type_id:
type: string
enum:
- principal_standard
address:
type: string
required:
- type_id
- address
- type: object
properties:
type_id:
type: string
enum:
- principal_contract
address:
type: string
contract_name:
type: string
required:
- type_id
- address
- contract_name
condition_code:
anyOf:
- type: string
enum:
- sent_equal_to
- type: string
enum:
- sent_greater_than
- type: string
enum:
- sent_greater_than_or_equal_to
- type: string
enum:
- sent_less_than
- type: string
enum:
- sent_less_than_or_equal_to
amount:
type: string
type:
type: string
enum:
- stx
required:
- principal
- condition_code
- amount
- type
- type: object
properties:
principal:
anyOf:
- type: object
properties:
type_id:
type: string
enum:
- principal_origin
required:
- type_id
- type: object
properties:
type_id:
type: string
enum:
- principal_standard
address:
type: string
required:
- type_id
- address
- type: object
properties:
type_id:
type: string
enum:
- principal_contract
address:
type: string
contract_name:
type: string
required:
- type_id
- address
- contract_name
condition_code:
anyOf:
- type: string
enum:
- sent_equal_to
- type: string
enum:
- sent_greater_than
- type: string
enum:
- sent_greater_than_or_equal_to
- type: string
enum:
- sent_less_than
- type: string
enum:
- sent_less_than_or_equal_to
amount:
type: string
type:
type: string
enum:
- fungible
asset:
type: object
properties:
asset_name:
type: string
contract_address:
type: string
contract_name:
type: string
required:
- asset_name
- contract_address
- contract_name
required:
- principal
- condition_code
- amount
- type
- asset
- type: object
properties:
principal:
anyOf:
- type: object
properties:
type_id:
type: string
enum:
- principal_origin
required:
- type_id
- type: object
properties:
type_id:
type: string
enum:
- principal_standard
address:
type: string
required:
- type_id
- address
- type: object
properties:
type_id:
type: string
enum:
- principal_contract
address:
type: string
contract_name:
type: string
required:
- type_id
- address
- contract_name
condition_code:
anyOf:
- type: string
enum:
- sent
- type: string
enum:
- not_sent
type:
type: string
enum:
- non_fungible
asset_value:
type: object
properties:
hex:
type: string
repr:
type: string
required:
- hex
- repr
asset:
type: object
properties:
asset_name:
type: string
contract_address:
type: string
contract_name:
type: string
required:
- asset_name
- contract_address
- contract_name
required:
- principal
- condition_code
- type
- asset_value
- asset
anchor_mode:
description: '`on_chain_only`: the transaction MUST be included in an anchored block, `off_chain_only`: the transaction MUST be included in a microblock, `any`: the leader can choose where to include the transaction.'
anyOf:
- type: string
enum:
- on_chain_only
- type: string
enum:
- off_chain_only
- type: string
enum:
- any
block_hash:
description: Hash of the blocked this transactions was associated with
type: string
block_height:
description: Height of the block this transactions was associated with
type: integer
block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: number
block_time_iso:
description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) indicating when this block was mined.
type: string
burn_block_time:
description: Unix timestamp (in seconds) indicating when this block was mined.
type: integer
burn_block_height:
description: Height of the anchor burn block.
type: integer
burn_block_time_iso:
description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) timestamp indicating when this block was mined.
type: string
parent_burn_block_time:
description: Unix timestamp (in seconds) indicating when this parent block was mined
type: integer
parent_burn_block_time_iso:
description: An ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) timestamp indicating when this parent block was mined.
type: string
canonical:
description: Set to `true` if block corresponds to the canonical chain tip
type: boolean
tx_index:
description: Index of the transaction, indicating the order. Starts at `0` and increases with each transaction
type: integer
tx_status:
description: Status of the transaction
anyOf:
- type: string
enum:
- success
- type: string
enum:
- abort_by_response
- type: string
enum:
- abort_by_post_condition
tx_result:
description: Result of the transaction. For contract calls, this will show the value returned by the call. For other transaction types, this will return a boolean indicating the success of the transaction.
additionalProperties: false
type: object
properties:
hex:
description: Hex string representing the value fo the transaction result
type: string
repr:
description: Readable string of the transaction result
type: string
required:
- hex
- repr
event_count:
description: Number of transaction events
type: integer
parent_block_hash:
description: Hash of the previous block.
type: string
is_unanchored:
description: True if the transaction is included in a microblock that has not been confirmed by an anchor block.
type: boolean
microblock_hash:
description: The microblock hash that this transaction was streamed in. If the transaction was batched in an anchor block (not included within a microblock) then this value will be an empty string.
type: string
microblock_sequence:
description: The microblock sequence number that this transaction was streamed in. If the transaction was batched in an anchor block (not included within a microblock) then this value will be 2147483647 (0x7fffffff, the max int32 value), this value preserves logical transaction ordering on (block_height, microblock_sequence, tx_index).
type: integer
microblock_canonical:
description: Set to `true` if microblock is anchored in the canonical chain tip, `false` if the transaction was orphaned in a micro-fork.
type: boolean
execution_cost_read_count:
description: Execution cost read count.
type: integer
execution_cost_read_length:
description: Execution cost read length.
type: integer
execution_cost_runtime:
description: Execution cost runtime.
type: integer
execution_cost_write_count:
description: Execution cost write count.
type: integer
execution_cost_write_length:
description: Execution cost write length.
type: integer
vm_error:
anyOf:
- description: Clarity VM error produced by this transaction
type: string
- type: 'null'
events:
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
# --- truncated at 32 KB (705 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hiro/refs/heads/main/openapi/hiro-non-fungible-tokens-api-openapi.yml