Instantiate Lucid

Lucid Evolution is a library for transaction building and designing the way you want to frame your off-chain. It can be used with or without a provider or a certain network for different purposes. The library supports the Mainnet, Preprod, Preview and Custom networks

To be able to query UTxOs, datums, and protocol parameters, you need to choose a provider and a provider is a service that allows Lucid Evolution to interact with the Cardano blockchain.

Provider selection

You can choose one of the following providers to use with Lucid Evolution

Blockfrost

import { Lucid, Blockfrost } from "@lucid-evolution/lucid";
 
const lucid = await Lucid(
  new Blockfrost("https://cardano-preprod.blockfrost.io/api/v0", "<projectId>"),
  "Preprod"
);

Kupmios

import { Lucid, Kupmios } from "@lucid-evolution/lucid";
 
const lucid = await Lucid(
  new Kupmios(
    "http://localhost:1442", // Kupo endpoint
    "http://localhost:1337" // Ogmios endpoint
  ),
  "Preview"
);

with API keys

const lucid = await Lucid(
  new Kupmios(
    "http://localhost:1442",
    "http://localhost:1337",
    {
      kupoHeader: { "priv-api-key": "<kupo-api-key>" }, // for example: "dmtr-api-key": "<kupo-api-key>" 
      ogmiosHeader: { "priv-api-key": "<ogmios-api-key>" }
    }
  ),
  "Preview"
);

Kupmios is a mix of Ogmios (opens in a new tab) and Kupo (opens in a new tab).

Maestro

import { Lucid, Maestro } from "@lucid-evolution/lucid";
 
const lucid = await Lucid(
  new Maestro({
    network: "Preprod", // For MAINNET: "Mainnet" (1)
    apiKey: "<Your-API-Key>", // Get yours by visiting https://docs.gomaestro.org/docs/Getting-started/Sign-up-login
    turboSubmit: false, // Read about paid turbo transaction submission feature at https://docs.gomaestro.org/docs/Dapp%20Platform/Turbo%20Transaction
  }),
  "Preprod" // For MAINNET: "Mainnet" (2)
);

Koios

import { Lucid, Koios } from "@lucid-evolution/lucid";
 
const lucid = await Lucid(
  new Koios("https://preprod.koios.rest/api/v1"),
  "Preprod"
);

with bearer token

const lucid = await Lucid(
  new Koios(
    "<koios-api-url>",
    "<koios-bearer-token>"
  ),
  "Preprod"
);

YACI DevKit

YACI DevKit provides a local development environment with configurable block times and network parameters. For detailed setup instructions, visit the YACI DevKit documentation (opens in a new tab).

// Configure custom network slot settings for YACI DevKit
SLOT_CONFIG_NETWORK['Custom'] = {
  zeroTime: 1664060800000, // Unix timestamp in milliseconds
  zeroSlot: 0,
  slotLength: 1000,
};
 
const lucid = await Lucid(
  new Kupmios(
    "http://localhost:1442",
    "http://localhost:1337" 
  ),
  "Custom" // Use custom network type for DevKit
);

UTxORPC

//TODO: https://github.com/utxorpc/lucid-evolution-provider

Query the provider

By querying the provider you are essentially asking "what's on the blockchain?", this way you can query any on-chain data.

The provider in lucid.provider is the provider instance you passed to Lucid() when selecting your provider (Blockfrost, Kupmios, Maestro, Koios, etc.).

UTxOs

UTxOs (Unspent Transaction Outputs) are the fundamental building blocks in Cardano's eUTxO model. One of its differentiator from account-based models is that your wallet's balance is the sum of all UTxOs at your address.

Using provider

const utxos = await lucid.provider.getUtxos("addr_test...");

or using convenience method

const utxos = await lucid.utxosAt("addr_test...");

This convenience method internally uses lucid.provider.getUtxos().

Datums

In Cardano, datums are pieces of data attached to UTxOs. Lets get some terminology out of the way.

  • Inline datums: When the complete datum is stored directly in the UTxO
  • Datum hashes: When only a hash of the datum is stored on-chain

Using Provider

const datum = await lucid.provider.getDatum("<datum_hash>");

or using convenience method

const datum = await lucid.datumOf("<datum_hash>");

or querying a datum from a scriptUTxO

const [scriptUtxo] = await lucid.utxosAt("addr_test...");
const datum = await lucid.datumOf(scriptUtxo);

lucid.datumOf(utxo) is a convenience method that handles both inline datums and datum hashes:

  1. For UTxOs with inline datums → returns the datum directly
  2. For UTxOs with datum hashes → fetches the full datum using provider.getDatum()

Once fetched, the datum is cached in the UTxO object for subsequent queries, avoiding additional network requests.

Protocol Parameters

Protocol parameters define the rules and constraints of the Cardano network like tx fees, max block size, max tx size, plutus execution costs, minimum UTxO ada value

Using the provider directly:

const protocolParameters = await lucid.provider.getProtocolParameters();

Remember that you can switch providers using the switchProvider method if needed.

Choose Wallet