---
title: "searchTransactions"
method: POST
path: "/search/transactions"
tags: ["Cardano - Rosetta"]
---

# searchTransactions

`POST /search/transactions`

`/search/transactions` allows the caller to search for
transactions that meet certain conditions. Some conditions
include matching a transaction hash, containing an
operation with a certain status, or containing an operation
that affects a certain account.

`/search/transactions` is considered an "indexer" endpoint
and Rosetta implementations are not required to complete it
to adhere to the Rosetta spec. However, any Rosetta "indexer"
MUST support this endpoint.

## Request body

- SearchTransactionsRequest — SearchTransactionsRequest is used to search for transactions matching a set of provided conditions in canonical blocks.
  - `network_identifier` NetworkIdentifier, required — The network_identifier specifies which network a particular object is associated with.
    - `blockchain` string, required
    - `network` string, required — If a blockchain has a specific chain-id or network identifier, it should go in this field. It is up to the client to determine which network-specific identifier is mainnet or testnet.
    - `sub_network_identifier` SubNetworkIdentifier — In blockchains with sharded state, the SubNetworkIdentifier is required to query some object on a specific shard. This identifier is optional for all non-sharded blockchains.
      - `network` string, required
      - `metadata` object
  - `operator` 'or' | 'and' — Operator is used by query-related endpoints to determine how to apply conditions. If this field is not populated, the default `and` value will be used.
  - `max_block` integer — max_block is the largest block index to consider when searching for transactions. If this field is not populated, the current block is considered the max_block. If you do not specify a max_block, it is possible a newly synced block will interfere with paginated transaction queries (as the offset could become invalid with newly added rows).
  - `offset` integer — offset is the offset into the query result to start returning transactions. If any search conditions are changed, the query offset will change and you must restart your search iteration.
  - `limit` integer — limit is the maximum number of transactions to return in one call. The implementation may return <= limit transactions.
  - `transaction_identifier` TransactionIdentifier — The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.
    - `hash` string, required — Any transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier. This should be normalized according to the case specified in the transaction_hash_case in network options.
  - `account_identifier` AccountIdentifier — The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).
    - `address` string, required — The address may be a cryptographic public key (or some encoding of it) or a provided username.
    - `sub_account` SubAccountIdentifier — An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.
      - `address` string, required — The SubAccount address may be a cryptographic value or some other identifier (ex: bonded) that uniquely specifies a SubAccount.
      - `metadata` object — If the SubAccount address is not sufficient to uniquely specify a SubAccount, any other identifying information can be stored here. It is important to note that two SubAccounts with identical addresses but differing metadata will not be considered equal by clients.
    - `metadata` object — Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata.
  - `coin_identifier` CoinIdentifier — CoinIdentifier uniquely identifies a Coin.
    - `identifier` string, required — Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index.
  - `currency` RpcCurrency — Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).
    - `symbol` string, required — Canonical symbol associated with a currency.
    - `decimals` integer, required — Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.
    - `metadata` object — Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token.
  - `status` string — status is the network-specific operation type.
  - `type` string — type is the network-specific operation type.
  - `address` string — address is AccountIdentifier.Address. This is used to get all transactions related to an AccountIdentifier.Address, regardless of SubAccountIdentifier.
  - `success` boolean — success is a synthetic condition populated by parsing network-specific operation statuses (using the mapping provided in `/network/options`).

## Response `200`

Expected response to a valid request

- SearchTransactionsResponse — SearchTransactionsResponse contains an ordered collection of BlockTransactions that match the query in SearchTransactionsRequest. These BlockTransactions are sorted from most recent block to oldest block.
  - `transactions` BlockTransaction[], required — transactions is an array of BlockTransactions sorted by most recent BlockIdentifier (meaning that transactions in recent blocks appear first). If there are many transactions for a particular search, transactions may not contain all matching transactions. It is up to the caller to paginate these transactions using the max_block field.
    - `block_identifier` BlockIdentifier, required — The block_identifier uniquely identifies a block in a particular network.
      - `index` integer, required — This is also known as the block height.
      - `hash` string, required — This should be normalized according to the case specified in the block_hash_case network options.
    - `transaction` Transaction, required — Transactions contain an array of Operations that are attributable to the same TransactionIdentifier.
      - `transaction_identifier` TransactionIdentifier, required — The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.
        - `hash` string, required — Any transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier. This should be normalized according to the case specified in the transaction_hash_case in network options.
      - `operations` Operation[], required
        - `operation_identifier` OperationIdentifier, required — The operation_identifier uniquely identifies an operation within a transaction.
          - `index` integer, required — The operation index is used to ensure each operation has a unique identifier within a transaction. This index is only relative to the transaction and NOT GLOBAL. The operations in each transaction should start from index 0. To clarify, there may not be any notion of an operation index in the blockchain being described.
          - `network_index` integer — Some blockchains specify an operation index that is essential for client use. For example, Bitcoin uses a network_index to identify which UTXO was used in a transaction. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains).
        - `related_operations` OperationIdentifier[] — Restrict referenced related_operations to identifier indices < the current operation_identifier.index. This ensures there exists a clear DAG-structure of relations. Since operations are one-sided, one could imagine relating operations in a single transfer or linking operations in a call tree.
          - `index` integer, required — The operation index is used to ensure each operation has a unique identifier within a transaction. This index is only relative to the transaction and NOT GLOBAL. The operations in each transaction should start from index 0. To clarify, there may not be any notion of an operation index in the blockchain being described.
          - `network_index` integer — Some blockchains specify an operation index that is essential for client use. For example, Bitcoin uses a network_index to identify which UTXO was used in a transaction. network_index should not be populated if there is no notion of an operation index in a blockchain (typically most account-based blockchains).
        - `type` string, required — Type is the network-specific type of the operation. Ensure that any type that can be returned here is also specified in the NetworkOptionsResponse. This can be very useful to downstream consumers that parse all block data.
        - `status` string — Status is the network-specific status of the operation. Status is not defined on the transaction object because blockchains with smart contracts may have transactions that partially apply (some operations are successful and some are not). Blockchains with atomic transactions (all operations succeed or all operations fail) will have the same status for each operation. On-chain operations (operations retrieved in the `/block` and `/block/transaction` endpoints) MUST have a populated status field (anything on-chain must have succeeded or failed). However, operations provided during transaction construction (often times called "intent" in the documentation) MUST NOT have a populated status field (operations yet to be included on-chain have not yet succeeded or failed).
        - `account` AccountIdentifier — The account_identifier uniquely identifies an account within a network. All fields in the account_identifier are utilized to determine this uniqueness (including the metadata field, if populated).
          - `address` string, required — The address may be a cryptographic public key (or some encoding of it) or a provided username.
          - `sub_account` SubAccountIdentifier — An account may have state specific to a contract address (ERC-20 token) and/or a stake (delegated balance). The sub_account_identifier should specify which state (if applicable) an account instantiation refers to.
            - `address` string, required — The SubAccount address may be a cryptographic value or some other identifier (ex: bonded) that uniquely specifies a SubAccount.
            - `metadata` object — If the SubAccount address is not sufficient to uniquely specify a SubAccount, any other identifying information can be stored here. It is important to note that two SubAccounts with identical addresses but differing metadata will not be considered equal by clients.
          - `metadata` object — Blockchains that utilize a username model (where the address is not a derivative of a cryptographic public key) should specify the public key(s) owned by the address in metadata.
        - `amount` Amount — Amount is some Value of a Currency. It is considered invalid to specify a Value without a Currency.
          - `value` string, required — Value of the transaction in atomic units represented as an arbitrary-sized signed integer. For example, 1 BTC would be represented by a value of 100000000.
          - `currency` RpcCurrency, required — Currency is composed of a canonical Symbol and Decimals. This Decimals value is used to convert an Amount.Value from atomic units (Satoshis) to standard units (Bitcoins).
            - `symbol` string, required — Canonical symbol associated with a currency.
            - `decimals` integer, required — Number of decimal places in the standard unit representation of the amount. For example, BTC has 8 decimals. Note that it is not possible to represent the value of some currency in atomic units that is not base 10.
            - `metadata` object — Any additional information related to the currency itself. For example, it would be useful to populate this object with the contract address of an ERC-20 token.
          - `metadata` object
        - `coin_change` CoinChange — CoinChange is used to represent a change in state of a some coin identified by a coin_identifier. This object is part of the Operation model and must be populated for UTXO-based blockchains. Coincidentally, this abstraction of UTXOs allows for supporting both account-based transfers and UTXO-based transfers on the same blockchain (when a transfer is account-based, don't populate this model).
          - `coin_identifier` CoinIdentifier, required — CoinIdentifier uniquely identifies a Coin.
            - `identifier` string, required — Identifier should be populated with a globally unique identifier of a Coin. In Bitcoin, this identifier would be transaction_hash:index.
          - `coin_action` 'coin_created' | 'coin_spent', required — CoinActions are different state changes that a Coin can undergo. When a Coin is created, it is coin_created. When a Coin is spent, it is coin_spent. It is assumed that a single Coin cannot be created or spent more than once.
        - `metadata` object
      - `related_transactions` RelatedTransaction[]
        - `network_identifier` NetworkIdentifier — The network_identifier specifies which network a particular object is associated with.
          - `blockchain` string, required
          - `network` string, required — If a blockchain has a specific chain-id or network identifier, it should go in this field. It is up to the client to determine which network-specific identifier is mainnet or testnet.
          - `sub_network_identifier` SubNetworkIdentifier — In blockchains with sharded state, the SubNetworkIdentifier is required to query some object on a specific shard. This identifier is optional for all non-sharded blockchains.
            - `network` string, required
            - `metadata` object
        - `transaction_identifier` TransactionIdentifier, required — The transaction_identifier uniquely identifies a transaction in a particular network and block or in the mempool.
          - `hash` string, required — Any transactions that are attributable only to a block (ex: a block event) should use the hash of the block as the identifier. This should be normalized according to the case specified in the transaction_hash_case in network options.
        - `direction` 'forward' | 'backward', required — Used by RelatedTransaction to indicate the direction of the relation (i.e. cross-shard/cross-network sends may reference `backward` to an earlier transaction and async execution may reference `forward`). Can be used to indicate if a transaction relation is from child to parent or the reverse.
      - `metadata` object — Transactions that are related to other transactions (like a cross-shard transaction) should include the tranaction_identifier of these transactions in the metadata.
  - `total_count` integer, required — total_count is the number of results for a given search. Callers typically use this value to concurrently fetch results by offset or to display a virtual page number associated with results.
  - `next_offset` integer — next_offset is the next offset to use when paginating through transaction results. If this field is not populated, there are no more transactions to query.

## Other responses

- `500` — unexpected error

---

[API](https://skmtc.net/tatum/apis/blockchain-data.md) · [All operations](https://skmtc.net/tatum/apis/blockchain-data/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tatum/blockchain-data/versions/8622ee4b8fae/schema)