UTxO RPC

The UTxO RPC gRPC interface for Cardano, hosted by Demeter.

What it is for

Streaming blocks and following the tip, watching transactions that match a pattern, querying UTxOs and protocol parameters, and submitting transactions, over gRPC. @utxorpc/sdk is the TypeScript client, there are SDKs for other languages, and any gRPC tool such as grpcurl can call it through server reflection.

For the interface itself, see the specification.

Hosts

The pattern, where {network} is cardano-mainnet, cardano-preprod or cardano-preview:

{network}.utxorpc-m1.demeter.run:443

On preprod:

cardano-preprod.utxorpc-m1.demeter.run:443

It is gRPC over TLS on port 443. Clients that take a URI use https://cardano-preprod.utxorpc-m1.demeter.run. There is no authenticated host form.

Authentication

Send the key in the dmtr-api-key header (gRPC metadata) on every call, reflection included:

dmtr-api-key: <your key>

Networks

cardano-mainnet, cardano-preprod and cardano-preview. Each port serves one network, chosen when you create it.

Limits

Usage is counted per 100,000 requests, and throughput is capped by requests per second. Minimum fees apply only to the tiers that reserve throughput.

Getting a key

Create a UTxO RPC port at https://console.demeter.run. The port's page shows its endpoint and its API key.

Example

Set the key in your shell:

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

With grpcurl, list the services and describe one method:

grpcurl -H "dmtr-api-key: $DEMETER_API_KEY" \
  cardano-preprod.utxorpc-m1.demeter.run:443 list

grpcurl -H "dmtr-api-key: $DEMETER_API_KEY" \
  cardano-preprod.utxorpc-m1.demeter.run:443 \
  describe utxorpc.v1alpha.sync.SyncService.ReadTip

grpcurl can stall on unary calls such as ReadTip against this host. Use an SDK, as below, for calls that return data.

@utxorpc/sdk

The tip, then every block applied or undone from there on (checked against @utxorpc/sdk 0.9.0):

import { CardanoSyncClient } from "@utxorpc/sdk";

const client = new CardanoSyncClient({
  uri: "https://cardano-preprod.utxorpc-m1.demeter.run",
  headers: { "dmtr-api-key": process.env.DEMETER_API_KEY! },
});

console.log(await client.readTip());

for await (const event of client.followTip()) {
  if (event.action === "reset") console.log("reset", event.point);
  else console.log(event.action, event.block.header?.slot);
}