Skip to content

Clients

Client 

Client(
    url: str = DEFAULT_URL,
    *,
    timeout: float | None = 60.0,
    headers: Mapping[str, str] | None = None,
    reconnect: Reconnect | None = DEFAULT_RECONNECT,
    check_version: VersionCheck = "warn",
    open_timeout: float | None = 10.0,
    ssl_context: SSLContext | None = None,
    transport: Transport | None = None
)

A synchronous client for Ogmios v7, with the same methods as :class:~pyogmios.AsyncClient.

::

with Client("ws://localhost:1337") as client:
    epoch = client.call("queryLedgerState/epoch")

See :class:~pyogmios.AsyncClient for the parameters.

server_health property 

server_health: Health | None

The health read when connecting, when check_version is not "off".

generation property 

generation: int

How many WebSocket connections have been opened; see :attr:AsyncClient.generation.

connect 

connect() -> Self

Check the server version and open the connection. Called by with.

close 

close() -> None

Close the connection and stop the background thread. Called at the end of with.

health 

health() -> Health

Read the server's /health; see :meth:AsyncClient.health.

request 

request(
    method: str,
    params: Any = None,
    *,
    timeout: float | Literal["default"] | None = "default"
) -> Any

Send any JSON-RPC request and return its raw result; see :meth:AsyncClient.request.

call 

call(
    method: str,
    params: Any = None,
    *,
    timeout: float | Literal["default"] | None = "default"
) -> Any

Call a method and return its parsed result; see :meth:AsyncClient.call.

submit_transaction 

submit_transaction(
    transaction: str | bytes,
) -> SubmitTransactionResult

Submit a signed transaction; see :meth:AsyncClient.submit_transaction.

evaluate_transaction 

evaluate_transaction(
    transaction: str | bytes,
    *,
    additional_utxo: Utxo | Sequence[Any] | None = None
) -> EvaluateTransactionResult

Evaluate a transaction's scripts; see :meth:AsyncClient.evaluate_transaction.

chain_sync 

chain_sync(
    points: Sequence[PointLike] = ("origin",),
    *,
    pipeline: int = 50,
    resume: bool = True,
    raw: bool = False
) -> SyncChainSync

Follow the chain: with client.chain_sync(points) as sync: for event in sync: ....

See :meth:AsyncClient.chain_sync.

ledger_state_at 

ledger_state_at(point: PointLike) -> SyncLedgerStateAt

Query the ledger as it was at point: with client.ledger_state_at(point) as ledger.

mempool_snapshot 

mempool_snapshot(
    *, full: bool = False
) -> SyncMempoolSnapshot

A snapshot of the mempool; see :meth:AsyncClient.mempool_snapshot.

mempool 

mempool(
    *, full: bool = False
) -> SyncStream[MempoolMonitor]

Every transaction entering the mempool: with client.mempool() as txs: for tx in txs.

AsyncClient 

AsyncClient(
    url: str = DEFAULT_URL,
    *,
    timeout: float | None = 60.0,
    headers: Mapping[str, str] | None = None,
    reconnect: Reconnect | None = DEFAULT_RECONNECT,
    check_version: VersionCheck = "warn",
    open_timeout: float | None = 10.0,
    ssl_context: SSLContext | None = None,
    transport: Transport | None = None
)

An asynchronous client for Ogmios v7.

::

async with AsyncClient("ws://localhost:1337") as client:
    epoch = await client.call("queryLedgerState/epoch")

The URL scheme picks the transport: ws:// and wss:// use WebSocket (every method, many requests in flight on one connection), http:// and https:// use HTTP (queries and submission only; stateful methods raise :class:~pyogmios.errors.StatefulOverHttpError).

Parameters:

Name Type Description Default
url str

The Ogmios server, including any path a hosted provider needs.

 DEFAULT_URL
timeout float | None

Seconds to wait for each response; None waits forever. Some large queries (delegateRepresentatives, rewardsProvenance) take several seconds on mainnet.

 60.0
headers Mapping[str, str] | None

Extra headers for the connection, for example an API key for hosted Ogmios.

 None
reconnect Reconnect | None

How to retry connecting; None never retries.

 DEFAULT_RECONNECT
check_version VersionCheck

On connect, read /health and check the server runs Ogmios 7. "strict" raises when it cannot tell, "warn" (the default) only warns then, "off" skips the check. An older server always raises :class:~pyogmios.errors.ServerVersionError.

 'warn'
open_timeout float | None

Seconds to wait for a connection to open.

 10.0
ssl_context SSLContext | None

TLS settings for wss:// and https://.

 None
transport Transport | None

A ready-made transport, mainly for tests; replaces url-based selection.

 None

generation property 

generation: int

How many WebSocket connections have been opened; increases on every reconnect.

Chain sync position, an acquired ledger state and an acquired mempool belong to one connection: when this changes, they are gone.

connect async 

connect() -> Self

Check the server version and open the connection. Called by async with.

close async 

close() -> None

Close the connection. Called at the end of async with.

health async 

health() -> Health

Read the server's /health: node connection, sync progress, tip, era and version.

request async 

request(
    method: str,
    params: Any = None,
    *,
    timeout: float | Literal["default"] | None = "default"
) -> Any

Send any JSON-RPC request and return its raw result (plain JSON values).

params are sent as given. Errors raise a :class:~pyogmios.errors.ResponseError subclass. Prefer :meth:call, which validates params and parses the result.

call async 

call(
    method: str,
    params: Any = None,
    *,
    timeout: float | Literal["default"] | None = "default"
) -> Any

Call an Ogmios method and return its result parsed into the types in :mod:pyogmios.types.

params may be the method's params model, or a mapping using the Python (snake_case) or wire (camelCase) field names. They are validated before anything is sent.

submit_transaction async 

submit_transaction(
    transaction: str | bytes,
) -> SubmitTransactionResult

Submit a signed transaction (CBOR, as bytes or hex) and return its id.

A rejection raises a :class:~pyogmios.errors.SubmitTransactionError subclass for the ledger rule that failed, for example :class:~pyogmios.errors.UnknownOutputReferencesError, with the ledger's details in details.

evaluate_transaction async 

evaluate_transaction(
    transaction: str | bytes,
    *,
    additional_utxo: Utxo | Sequence[Any] | None = None
) -> EvaluateTransactionResult

Run a transaction's scripts and return the execution units each redeemer needs.

additional_utxo adds outputs the node does not know yet, such as those of a transaction still being built; they take precedence over the node's own.

chain_sync 

chain_sync(
    points: Sequence[PointLike] = ("origin",),
    *,
    pipeline: int = 50,
    resume: bool = True,
    raw: bool = False
) -> ChainSync

Follow the chain from the most recent of points that is on it; see :class:ChainSync.

raw=True yields plain JSON instead of models, which is faster for indexers.

ledger_state_at 

ledger_state_at(point: PointLike) -> LedgerStateAt

Query the ledger as it was at point; see :class:LedgerStateAt.

mempool_snapshot 

mempool_snapshot(*, full: bool = False) -> MempoolSnapshot

A snapshot of the node's mempool; see :class:MempoolSnapshot.

mempool 

mempool(*, full: bool = False) -> MempoolMonitor

Every transaction that enters the mempool; see :class:MempoolMonitor.

Reconnect dataclass 

Reconnect(
    attempts: int = 5,
    initial_delay: float = 0.5,
    max_delay: float = 10.0,
    factor: float = 2.0,
    jitter: float = 0.1,
)

How to retry connecting, on the first connect and after the connection drops.

The delay before retry n is initial_delay * factor ** n, capped at max_delay, with up to jitter of it added or removed at random. Pass reconnect=None to the client to never retry.

attempts class-attribute instance-attribute 

attempts: int = 5

Connection attempts before giving up, including the first.

delays 

delays() -> list[float]

The delays to wait before each retry.