> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/reference/api/stacks-blockchain-api/search.md). # Search Read-only endpoints to search for accounts, blocks, smart contracts, and transactions ## Search > Searches for the blocks, transactions, addresses, smart contracts, and token assets that a term refers to. The term can be a complete identifier or the beginning of one: a block or transaction hash, a Stacks or Bitcoin block height, an address, a contract id, or an asset identifier. Contract and asset names are matched anywhere in the name, so a term like \`arkadiko\` finds the contracts and tokens named after it. Names must contain the term; misspellings are not matched. At most 20 results are returned, best match first; there is no pagination, so narrow the term to see something that did not surface. A term that matches nothing returns an empty list rather than an error. Only canonical, mined entities are searched. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Search","description":"Read-only endpoints to search for accounts, blocks, smart contracts, and transactions"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/search":{"get":{"operationId":"search","summary":"Search","tags":["Search"],"description":"Searches for the blocks, transactions, addresses, smart contracts, and token assets that a term refers to. The term can be a complete identifier or the beginning of one: a block or transaction hash, a Stacks or Bitcoin block height, an address, a contract id, or an asset identifier. Contract and asset names are matched anywhere in the name, so a term like `arkadiko` finds the contracts and tokens named after it. Names must contain the term; misspellings are not matched. At most 20 results are returned, best match first; there is no pagination, so narrow the term to see something that did not surface. A term that matches nothing returns an empty list rather than an error. Only canonical, mined entities are searched.","parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":true,"description":"The term to search for. Hex terms need at least 8 characters, addresses at least 6, and contract or asset names at least 3; block heights have no minimum."},{"schema":{"uniqueItems":true,"type":"array","items":{"title":"SearchEntityType","description":"The kind of entity a search result refers to","anyOf":[{"type":"string","enum":["block"]},{"type":"string","enum":["bitcoin_block"]},{"type":"string","enum":["transaction"]},{"type":"string","enum":["address"]},{"type":"string","enum":["smart_contract"]},{"type":"string","enum":["token"]}]}},"in":"query","name":"type","required":false,"description":"Restricts results to these entity types. Provide them as repeated querystring values (`?type=block&type=transaction`) or as a single comma-separated value (`?type=block,transaction`). Defaults to every type the term could match."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"SearchResponse","type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"title":"SearchResult","anyOf":[{"title":"BlockSearchResult","type":"object","required":["type","result"],"properties":{"type":{"type":"string","enum":["block"]},"result":{"title":"BlockSummary","type":"object","required":["height","hash","index_hash","time","time_iso"],"properties":{"height":{"title":"Block height","description":"Block height","type":"integer"},"hash":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Block hash","description":"Block hash","type":"string"},"index_hash":{"description":"Index block hash of the block","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}}}},{"title":"BitcoinBlockSearchResult","type":"object","required":["type","result"],"properties":{"type":{"type":"string","enum":["bitcoin_block"]},"result":{"title":"BitcoinBlockSummary","type":"object","required":["height","hash"],"properties":{"height":{"description":"Height of the Bitcoin block","type":"integer"},"hash":{"description":"Hash of the Bitcoin block","type":"string"}}}}},{"title":"TransactionSearchResult","type":"object","required":["type","result"],"properties":{"type":{"type":"string","enum":["transaction"]},"result":{"anyOf":[{"title":"TokenTransferTransactionSummary","description":"Token transfer transaction summary","type":"object","required":["tx_id","sender","sponsor","fee_rate","block","bitcoin_block","status","type","token_transfer"],"properties":{"tx_id":{"description":"Transaction ID","type":"string"},"sender":{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},"sponsor":{"anyOf":[{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},{"type":"null"}]},"fee_rate":{"description":"Transaction fee as Integer string (64-bit unsigned integer).","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"status":{"description":"Status of the transaction","anyOf":[{"type":"string","enum":["success"]},{"type":"string","enum":["abort_by_response"]},{"type":"string","enum":["abort_by_post_condition"]},{"type":"string","enum":["problematic_skipped"]}]},"type":{"type":"string","enum":["token_transfer"]},"token_transfer":{"type":"object","required":["recipient","amount","memo"],"properties":{"recipient":{"type":"string"},"amount":{"description":"Transfer amount as Integer string (64-bit unsigned integer)","type":"string"},"memo":{"anyOf":[{"type":"object","required":["hex","repr"],"properties":{"hex":{"type":"string"},"repr":{"type":"string"}}},{"type":"null"}]}}}}},{"title":"SmartContractTransactionSummary","description":"Smart contract transaction summary","type":"object","required":["tx_id","sender","sponsor","fee_rate","block","bitcoin_block","status","type","smart_contract"],"properties":{"tx_id":{"description":"Transaction ID","type":"string"},"sender":{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},"sponsor":{"anyOf":[{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},{"type":"null"}]},"fee_rate":{"description":"Transaction fee as Integer string (64-bit unsigned integer).","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"status":{"description":"Status of the transaction","anyOf":[{"type":"string","enum":["success"]},{"type":"string","enum":["abort_by_response"]},{"type":"string","enum":["abort_by_post_condition"]},{"type":"string","enum":["problematic_skipped"]}]},"type":{"type":"string","enum":["smart_contract"]},"smart_contract":{"type":"object","required":["clarity_version","contract_id"],"properties":{"clarity_version":{"anyOf":[{"description":"The Clarity version of the contract. Versioned contract transactions declare it; for the rest it is the version the node resolved from the epoch the contract was deployed in. Null only when it could not be determined, which happens for contracts indexed from a chainstate predating the point where the Stacks node began reporting it.","type":"number"},{"type":"null"}]},"contract_id":{"description":"Contract identifier formatted as `.`","type":"string"}}}}},{"title":"ContractCallTransactionSummary","description":"Contract call transaction summary","type":"object","required":["tx_id","sender","sponsor","fee_rate","block","bitcoin_block","status","type","contract_call"],"properties":{"tx_id":{"description":"Transaction ID","type":"string"},"sender":{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},"sponsor":{"anyOf":[{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},{"type":"null"}]},"fee_rate":{"description":"Transaction fee as Integer string (64-bit unsigned integer).","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"status":{"description":"Status of the transaction","anyOf":[{"type":"string","enum":["success"]},{"type":"string","enum":["abort_by_response"]},{"type":"string","enum":["abort_by_post_condition"]},{"type":"string","enum":["problematic_skipped"]}]},"type":{"type":"string","enum":["contract_call"]},"contract_call":{"type":"object","required":["contract_id","function_name"],"properties":{"contract_id":{"description":"Contract identifier formatted as `.`","type":"string"},"function_name":{"description":"Name of the Clarity function to be invoked","type":"string"}}}}},{"title":"PoisonMicroblockTransactionSummary","description":"Poison microblock transaction summary","type":"object","required":["tx_id","sender","sponsor","fee_rate","block","bitcoin_block","status","type"],"properties":{"tx_id":{"description":"Transaction ID","type":"string"},"sender":{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},"sponsor":{"anyOf":[{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},{"type":"null"}]},"fee_rate":{"description":"Transaction fee as Integer string (64-bit unsigned integer).","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"status":{"description":"Status of the transaction","anyOf":[{"type":"string","enum":["success"]},{"type":"string","enum":["abort_by_response"]},{"type":"string","enum":["abort_by_post_condition"]},{"type":"string","enum":["problematic_skipped"]}]},"type":{"type":"string","enum":["poison_microblock"]}}},{"title":"CoinbaseTransactionSummary","description":"Coinbase transaction summary","type":"object","required":["tx_id","sender","sponsor","fee_rate","block","bitcoin_block","status","type","coinbase"],"properties":{"tx_id":{"description":"Transaction ID","type":"string"},"sender":{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},"sponsor":{"anyOf":[{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},{"type":"null"}]},"fee_rate":{"description":"Transaction fee as Integer string (64-bit unsigned integer).","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"status":{"description":"Status of the transaction","anyOf":[{"type":"string","enum":["success"]},{"type":"string","enum":["abort_by_response"]},{"type":"string","enum":["abort_by_post_condition"]},{"type":"string","enum":["problematic_skipped"]}]},"type":{"type":"string","enum":["coinbase"]},"coinbase":{"type":"object","required":["alt_recipient"],"properties":{"alt_recipient":{"anyOf":[{"description":"A principal that will receive the miner rewards for this coinbase transaction. Can be either a standard principal or contract principal. Only specified for `coinbase-to-alt-recipient` transaction types, otherwise null.","type":"string"},{"type":"null"}]}}}}},{"title":"TenureChangeTransactionSummary","description":"Tenure change transaction summary","type":"object","required":["tx_id","sender","sponsor","fee_rate","block","bitcoin_block","status","type","tenure_change"],"properties":{"tx_id":{"description":"Transaction ID","type":"string"},"sender":{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},"sponsor":{"anyOf":[{"type":"object","required":["address","nonce"],"properties":{"address":{"description":"Address of the transaction initiator","type":"string"},"nonce":{"description":"Nonce of the transaction initiator","type":"integer"}}},{"type":"null"}]},"fee_rate":{"description":"Transaction fee as Integer string (64-bit unsigned integer).","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"status":{"description":"Status of the transaction","anyOf":[{"type":"string","enum":["success"]},{"type":"string","enum":["abort_by_response"]},{"type":"string","enum":["abort_by_post_condition"]},{"type":"string","enum":["problematic_skipped"]}]},"type":{"type":"string","enum":["tenure_change"]},"tenure_change":{"type":"object","required":["cause"],"properties":{"cause":{"description":"Cause of change in mining tenure. Depending on cause, tenure can be ended or extended.","anyOf":[{"type":"string","enum":["block_found"]},{"type":"string","enum":["extended"]},{"type":"string","enum":["extended_runtime"]},{"type":"string","enum":["extended_read_count"]},{"type":"string","enum":["extended_read_length"]},{"type":"string","enum":["extended_write_count"]},{"type":"string","enum":["extended_write_length"]}]}}}}}]}}},{"title":"AddressSearchResult","type":"object","required":["type","result"],"properties":{"type":{"type":"string","enum":["address"]},"result":{"title":"AddressSummary","type":"object","required":["principal"],"properties":{"principal":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"}}}}},{"title":"SmartContractSearchResult","type":"object","required":["type","result"],"properties":{"type":{"type":"string","enum":["smart_contract"]},"result":{"title":"SmartContract","type":"object","required":["contract_id","clarity_version","tx_id","block","bitcoin_block"],"properties":{"contract_id":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"},"clarity_version":{"anyOf":[{"description":"The Clarity version the contract runs under. Contracts deployed with a versioned payload declare their own version; for the rest it is the version the node resolved from the epoch they were deployed in. Null when it could not be determined, which only happens for contracts indexed from a chainstate predating the point where the Stacks node began reporting it.","type":"integer"},{"type":"null"}]},"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"ID of the transaction that deployed this contract","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"source_code":{"description":"The Clarity source code of the contract. Only present when requested via the `include=source_code` query param.","type":"string"}}}}},{"title":"TokenSearchResult","type":"object","required":["type","result"],"properties":{"type":{"type":"string","enum":["token"]},"result":{"title":"TokenAsset","type":"object","required":["asset_identifier","asset_type","contract_id","asset_name"],"properties":{"asset_identifier":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}::[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*]){0,127}$","title":"Asset Identifier","description":"Asset Identifier","type":"string"},"asset_type":{"description":"Whether the asset is a fungible or non-fungible token","anyOf":[{"type":"string","enum":["ft"]},{"type":"string","enum":["nft"]}]},"contract_id":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"},"asset_name":{"description":"The name the asset is declared with on-chain. This is the identifier from the contract's token definition, not the display name or symbol the contract reports through `get-name` and `get-symbol`.","type":"string"}}}}}]}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.stacks.co/reference/api/stacks-blockchain-api/search.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.