Ogmios

The Ogmios JSON-RPC bridge to a Cardano node, hosted by Demeter.

What it is for

Submitting and evaluating transactions, querying the ledger state (UTxOs, protocol parameters, stake, the tip) and following the chain, over WebSocket or HTTP JSON-RPC. Lucid Evolution's Kupmios provider pairs an Ogmios port with a Kupo port, and @cardano-ogmios/client is the Ogmios TypeScript client.

For the protocol itself, see the API reference.

Hosts

The pattern, where {network} is cardano-mainnet, cardano-preprod or cardano-preview, and {version} is the Ogmios major version you picked for the port, 6 or 7:

wss://{network}-v{version}.ogmios-m1.dmtr.host

On preprod, Ogmios 6:

wss://cardano-preprod-v6.ogmios-m1.dmtr.host

The authenticated form puts the key in the host:

wss://{key}.{network}-v{version}.ogmios-m1.dmtr.host

TLS is on port 443. The same hosts answer HTTP JSON-RPC on https://, which is what Kupmios uses.

Authentication

Send the key in the dmtr-api-key header:

dmtr-api-key: <your key>

Or use the authenticated host, with no header. Browser WebSockets and Node's built-in WebSocket cannot set headers, so they need it.

Networks

cardano-mainnet, cardano-preprod and cardano-preview, each with Ogmios 6 and 7. Each port serves one network and one version, chosen when you create it.

Limits

Usage is counted per 100,000 messages, and service is capped by concurrent open connections. Minimum fees apply only to the tiers that reserve throughput.

Getting a key

Create an Ogmios port at https://console.demeter.run. The port's page shows its endpoint, its authenticated endpoint and its API key.

Example

Set the key in your shell:

export DEMETER_API_KEY=...   # the API key from the port's page

The chain tip on preprod, with Node 22's built-in WebSocket and the authenticated host:

const socket = new WebSocket(
  `wss://${process.env.DEMETER_API_KEY}.cardano-preprod-v6.ogmios-m1.dmtr.host`,
);

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({ jsonrpc: "2.0", method: "queryNetwork/tip", id: 1 }));
});

socket.addEventListener("message", (event) => {
  console.log(JSON.parse(event.data).result);
  socket.close();
});

The same query over HTTP, with the header:

curl -H "dmtr-api-key: $DEMETER_API_KEY" -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","method":"queryNetwork/tip","id":1}' \
  https://cardano-preprod-v6.ogmios-m1.dmtr.host

Kupmios with Lucid Evolution

Kupmios takes the Kupo and Ogmios URLs and a header for each. The two ports have separate keys, so this reads two variables (checked against @lucid-evolution/lucid 0.8.2):

import { Kupmios, Lucid } from "@lucid-evolution/lucid";

const provider = new Kupmios(
  "https://cardano-preprod-v2.kupo-m1.dmtr.host",
  "https://cardano-preprod-v6.ogmios-m1.dmtr.host",
  {
    kupoHeader: { "dmtr-api-key": process.env.DEMETER_KUPO_API_KEY! },
    ogmiosHeader: { "dmtr-api-key": process.env.DEMETER_OGMIOS_API_KEY! },
  },
);

console.log(await provider.getProtocolParameters());

const lucid = await Lucid(provider, "Preprod");