Skip to main content
The shortest path from an empty Next.js app to a live on-chain ADA/USD price in your browser.
1

Create a Next.js app

npx create-next-app@latest my-oracle-app
cd my-oracle-app
Pick any options. App Router is recommended.
2

Install the SDK

npm install charli3-js
No extra setup. Preprod and mainnet presets ship with each release, so just update the package when addresses change.
3

Read a price from a Server Component

Edit app/page.tsx:
app/page.tsx
import { Charli3 } from "charli3-js";

export const revalidate = 30;

export default async function Page() {
  const c3 = new Charli3({ network: "preprod" });
  const { price, outRef } = await c3.getOdvReference("ADA/USD");

  return (
    <main style={{ padding: 48, fontFamily: "ui-sans-serif" }}>
      <h1>ADA/USD on chain</h1>
      <p style={{ fontSize: 56, margin: 0 }}>
        ${price.value.toFixed(6)}
      </p>
      <p>
        {price.isExpired ? "stale, pull a fresh one" : "fresh"} /
        posted {price.createdAt.toISOString()}
      </p>
      <p style={{ opacity: 0.6, fontFamily: "monospace" }}>
        utxo {outRef.txHash.slice(0, 16)}...#{outRef.outputIndex}
      </p>
    </main>
  );
}
4

Run it

npm run dev
Open http://localhost:3000. You should see the current ADA/USD price read directly from the Cardano preprod chain.

​
What just happened

getOdvReference asks a public indexer (Kupo) for the UTXO at Charli3’s oracle address, reads the datum, and returns the price. No API key, no login, no subscription.
price.isExpired tells you if the price is past its 5-minute window on preprod. If it is, call c3.submitRound2(lucid, "ADA/USD") to post a fresh one. See Refreshing a price.
Not for reading. You only need a wallet when you want to post a fresh price yourself. Reading is free and keyless.

​
Next steps

How the SDK works

Round 1, Round 2, picking a price, and why the time window matters.

Sample app

A fuller example: Lace wallet, deposit and claim, AI invoice agent.

Refresh on-chain

Post a fresh price with Lucid and a funded wallet.

AI agents

One markdown file to teach any tool-calling LLM how to use Charli3.