Query Module

The Query module provides an interface for querying the state of the ledger with the main goal of constructing new transactions.

Sequence Example

The following diagram describes the message exchange between a client and service where the client queries protocol parameters, reads UTxOs, and queries UTxOs.

Operations

Important: All byte fields in grpcurl examples (like hashes, addresses, assets) must be base64 encoded. For more details and installation of grpcurl, refer to the grpcurl guide.

The following code samples assume that the UTxORPC node is running locally on localhost:50051. If your node is hosted remotely or on a different server, replace "http://localhost:50051" with the appropriate server URL and port for your environment.

For more details on configuring your node, refer to the UTxORPC Ecosystem Servers Documentation.

ReadParams

Try it out

Retrieves the current protocol parameters for the chain, including important values like fees, epoch information, and other consensus settings.

grpcurl -plaintext \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.ReadParams

ReadUtxos

Try it out

Fetches specific UTxOs by their output reference (hash and index). Useful when you need to look up known UTxOs directly.

grpcurl -plaintext \
  -d '{
    "keys": [{
      "hash": "p4WAOb31UfCR2qsqVlBLiUrsVwZoGPVOmYOjavDuEPs=",
      "index": 0
    }]
  }' \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.ReadUtxos

SearchUtxos

Try it out

Search for UTxOs using various filtering patterns. The following search methods are available:

By Address

Search for all UTxOs controlled by a specific Cardano address. The address must be base64 encoded.

grpcurl -plaintext \
  -d '{
    "predicate": {
      "match": {
        "cardano": {
          "address": {
            "exact_address": "AJs7DC2gQcMrCyDdI49iEvCVlVjxfyrYvmj76rLmODCCS9vyMxgygxirZgrESIt1j2tbOSqOku8e"
          }
        }
      }
    }
  }' \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.SearchUtxos

By Address Payment Part

Search for UTxOs by just the payment credential part of an address. Useful when you want to find UTxOs regardless of stake credential.

grpcurl -plaintext \
  -d '{
    "predicate": {
      "match": {
        "cardano": {
          "address": {
            "payment_part": "mzsMLaBBwysLIN0jj2IS8JWVWPF/Kti+aPvqsg=="
          }
        }
      }
    }
  }' \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.SearchUtxos

By Address Delegation Part

Search for UTxOs by just the stake credential (delegation part) of an address. Helps find all UTxOs delegated to a specific stake key.

grpcurl -plaintext \
  -d '{
    "predicate": {
      "match": {
        "cardano": {
            "address": {
                "delegation_part": "5jgwgkvb8jMYMoMYq2YKxEiLdY9rWzkqjpLvHg=="
            }
        }
      }
    }
  }' \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.SearchUtxos

By Asset Policy

Search for UTxOs containing tokens from a specific policy ID. The policy ID must be base64 encoded.

grpcurl -plaintext \
  -d '{
    "predicate": {
      "match": {
        "cardano": {
          "asset": {
            "policy_id": "BH4PkSxCYP5mriceWuSU3NX3ljW7uxOGvhlfTg=="
          }
        }
      }
    }
  }' \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.SearchUtxos

By Specific Asset

Search for UTxOs containing a specific token, identified by both policy ID and asset name (combined and base64 encoded).

grpcurl -plaintext \
  -d '{
    "predicate": {
      "match": {
        "cardano": {
          "asset": {
            "asset_name": "BH4PkSxCYP5mriceWuSU3NX3ljW7uxOGvhlfTkFMTEVZS0FUWjAwMDYw"
          }
        }
      }
    }
  }' \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.SearchUtxos

ReadData

Try it out

Read specific data (plural of datum) by hash.

⚠️

This operation is currently under development in Dolos and is not yet available.

grpcurl -plaintext \
  -d '{
    "keys": [
      "/u066600mYdRq1Xjf3d1UOSguQ8umzvtplb6DymjDeA="
    ]
  }' \
  localhost:50051 \
  utxorpc.v1alpha.query.QueryService.ReadData

The schema details can be found in the spec reference.

Introduction Spec