Queries¶

Ogmios has two families of queries, and pyogmios groups them the same way:

client.ledger_state: the ledger as the node sees it (queryLedgerState/*): UTxOs, protocol parameters, stake pools, governance, rewards.
client.network: the chain and its configuration (queryNetwork/*): tip, block height, start time, genesis configuration.

import pyogmios

with pyogmios.Client("ws://localhost:1337") as client:
    parameters = client.ledger_state.protocol_parameters()
    print(
        "min fee:",
        parameters.min_fee_coefficient,
        "per byte +",
        parameters.min_fee_constant.ada.lovelace,
    )
    pools = client.ledger_state.stake_pools()
    print(len(pools), "stake pools")
    print("treasury:", client.ledger_state.treasury_and_reserves().treasury.ada.lovelace)
    print("start time:", client.network.start_time())

Every query returns a typed result (see Types) and takes an optional timeout= in seconds.

Parameters¶

Queries that take parameters have keyword arguments. Where a parameter holds objects, you can pass the model from pyogmios.types or a plain dict, with Python (output_references) or Ogmios (outputReferences) field names. Parameters are checked before anything is sent: a typo raises a Pydantic ValidationError.

utxos = client.ledger_state.utxo(addresses=["addr_test1..."])
utxos = client.ledger_state.utxo(
    output_references=[{"transaction": {"id": "a1b2..."}, "index": 0}],
)
pool = client.ledger_state.stake_pools(stake_pools=[{"id": "pool1..."}], include_stake=True)
conway = client.network.genesis_configuration(era="conway")

Leaving optional parameters out queries everything: client.ledger_state.utxo() returns the whole UTxO set, which is very large on mainnet. Prefer a filter.

Every query¶

Ogmios method	Python	Result	Description
`queryLedgerState/constitution`	`client.ledger_state.constitution(timeout=…)`	`Constitution`	Query the current constitution definition (only available from Conway onwards).
`queryLedgerState/constitutionalCommittee`	`client.ledger_state.constitutional_committee(timeout=…)`	`QueryLedgerStateConstitutionalCommitteeResult`	Get the state of the constitutional committee (only available from Conway onwards).
`queryLedgerState/delegateRepresentatives`	`client.ledger_state.delegate_representatives(scripts=…, keys=…, timeout=…)`	`QueryLedgerStateDelegateRepresentativesResult`	Query currently registered delegate representatives, their stake (i.e. voting powers) and metadata about them. Note that 'params' is optional and can be used to filter out delegates. When omitted, ALL delegates are returned. Pre-defined options (always abstain and always no confidence) are ALWAYS returned.
`queryLedgerState/dump`	`client.ledger_state.dump(to=…, timeout=…)`	`QueryLedgerStateDumpResult`	Get a dump of the entire Cardano ledger state (CBOR) corresponding to the 'NewEpochState'. Take some time.
`queryLedgerState/epoch`	`client.ledger_state.epoch(timeout=…)`	`Epoch`	Query the current epoch number the ledger is at.
`queryLedgerState/eraStart`	`client.ledger_state.era_start(timeout=…)`	`Bound`	Query the start of the current ledger era.
`queryLedgerState/eraSummaries`	`client.ledger_state.era_summaries(timeout=…)`	`QueryLedgerStateEraSummariesResult`	Query a summary of the slotting parameters and boundaries for each known era. Useful for doing slot-arithmetic and time conversions.
`queryLedgerState/governanceProposals`	`client.ledger_state.governance_proposals(proposals=…, timeout=…)`	`QueryLedgerStateGovernanceProposalsResult`	Query currently active governance proposals, optionally restricted to specific governance proposal references.
`queryLedgerState/liveStakeDistribution`	`client.ledger_state.live_stake_distribution(timeout=…)`	`LiveStakeDistribution`	Query the current distribution of the stake across all known stake pools, relative to the TOTAL stake in the network.
`queryLedgerState/nonces`	`client.ledger_state.nonces(timeout=…)`	`Nonces`	Query consensus nonces information used to power randomness for leader election in every epoch.
`queryLedgerState/operationalCertificates`	`client.ledger_state.operational_certificates(timeout=…)`	`OperationalCertificates`	Query operational certificate counters of all stake pools.
`queryLedgerState/projectedRewards`	`client.ledger_state.projected_rewards(stake=…, scripts=…, keys=…, timeout=…)`	`ProjectedRewards`	Query the projected rewards of an account in a context where the top stake pools are fully saturated. This projection gives, in principle, a ranking of stake pools that maximizes delegator rewards.
`queryLedgerState/protocolParameters`	`client.ledger_state.protocol_parameters(timeout=…)`	`ProtocolParameters`	Query the current protocol parameters.
`queryLedgerState/rewardAccountSummaries`	`client.ledger_state.reward_account_summaries(scripts=…, keys=…, timeout=…)`	`QueryLedgerStateRewardAccountSummariesResult`	Query current delegation settings and rewards of some given reward accounts.
`queryLedgerState/rewardsProvenance`	`client.ledger_state.rewards_provenance(timeout=…)`	`RewardsProvenance`	Query details about rewards calculation for the ongoing epoch.
`queryLedgerState/stakePools`	`client.ledger_state.stake_pools(include_stake=…, stake_pools=…, timeout=…)`	`QueryLedgerStateStakePoolsResult`	Query the list of all stake pools currently registered and active, optionally filtered by ids.
`queryLedgerState/stakePoolsPerformances`	`client.ledger_state.stake_pools_performances(timeout=…)`	`StakePoolsPerformances`	Query details about pools performances indicators for the ongoing epoch.
`queryLedgerState/tip`	`client.ledger_state.tip(timeout=…)`	`PointOrOrigin`	Query the current tip the ledger is at. Said differently, the slot number and header hash of the last block that has been processed by the ledger.
`queryLedgerState/treasuryAndReserves`	`client.ledger_state.treasury_and_reserves(timeout=…)`	`QueryLedgerStateTreasuryAndReservesResult`	Query the Ada value of the treasury and reserves accounts.
`queryLedgerState/utxo`	`client.ledger_state.utxo(output_references=…, addresses=…, timeout=…)`	`Utxo`	Query the current Utxo set, restricted to some output references or addresses.
`queryNetwork/blockHeight`	`client.network.block_height(timeout=…)`	`QueryNetworkBlockHeightResult`	Query the network's highest block number.
`queryNetwork/genesisConfiguration`	`client.network.genesis_configuration(era=…, timeout=…)`	`QueryNetworkGenesisConfigurationResult`	Query the genesis configuration of a given era.
`queryNetwork/startTime`	`client.network.start_time(timeout=…)`	`UtcTime`	Query the network start time.
`queryNetwork/tip`	`client.network.tip(timeout=…)`	`PointOrOrigin`	Get the current network tip. Said differently, this is the most recent slot and block header hash that the node it aware of.

The ledger at a point¶

Ledger queries answer for the node's current tip. To query the ledger as it was at a recent point, see The ledger at a point.

Errors¶

A query the ledger cannot answer raises a LedgerStateQueryError: for example UnavailableInCurrentEraError for a Conway-only query on an older era.