charli3-js
A TypeScript SDK for the Charli3 pull oracle on Cardano. One import, one call, a fresh price on chain.
new Charli3().getOdvReference("ADA/USD"). If it shows stale, no one has paid to post a fresh datum in the last 5 minutes. That is the point of a pull oracle. Scroll down to pull one yourself.The pull-oracle loop
Connect Lace
CIP-30 handshake from the browser. The demo reads your preprod address and checks you are on the right network.
Lock 3 tADA
Deposit to a vault with datum "release only when ADA/USD is at or above $0.10". Lace signs the deposit tx.
Pull a fresh price
The SDK asks every oracle node for a signed feed, runs IQR consensus, builds the aggregator tx, collects node vkey witnesses, and submits. Around 30 seconds end to end.
Claim
Spend the vault. The Aiken validator reads the freshly posted AggState datum as a reference input and releases the tADA if the price clears the threshold.
Run the loop
Lace wallet not detected. Install from lace.io, switch to preprod, and fund the wallet from the preprod faucet.
AI agent: pay a USD invoice in ADA
Drop a USD invoice into the box. A GPT-4o-mini agent calls charli3-js as a tool to read the latest on-chain ADA/USD price, validates the preprod address, computes the ADA amount, and proposes a payment you sign with Lace. The agent never guesses a price - it reads the Charli3 ODV datum directly.
Pay a USD invoice in ADA
Drop a USD invoice below. A GPT-4o-mini agent calls charli3-js as a tool to read the latest on-chain ADA/USD price, validates the preprod address, computes the ADA amount, and hands you a payment proposal to sign in Lace.
charli3-js.The agent proposes a payment you sign in Lace. Connect your preprod wallet before dropping an invoice.
Same action, two SDKs
The only existing client for Charli3 ODV is the official Python SDK. Cardano builders on Node, Next.js, or Vercel cannot use it in process. Toggle to see what a single "refresh ADA/USD" costs in each.
// app/api/refresh/route.ts (the entire file)
import { Charli3 } from "charli3-js";
import { Lucid, Blockfrost } from "@lucid-evolution/lucid";
import { NextResponse } from "next/server";
export async function POST() {
const lucid = await Lucid(
new Blockfrost(URL, PROJECT_ID),
"Preprod",
);
lucid.selectWallet.fromSeed(SEED);
const c3 = new Charli3({ network: "preprod" });
const { txHash } = await c3.submitRound2(lucid, "ADA/USD");
return NextResponse.json({ txHash });
}
// Deploys to Vercel as-is. Same process as the web app.
// No YAML, no sidecar, no subprocess.
| Runtime | Python 3.10+, virtualenv, pycardano | Node 20+, same process as the app |
|---|---|---|
| Config | client.yaml (40+ lines, hand-edited) | versioned preset - Charli3 address/policy changes ship as npm update |
| Integration code | 60 to 80 lines of glue | 3 lines per action |
| Next.js fit | sidecar service or subprocess | drop-in API route, Vercel ready |
| Time to first tx | half a day | under 10 minutes |
| Python SDK | charli3-js |
Track 3, Oracle Tooling
The challenge asks for work that lets the next Cardano builder ship faster on MIT open-source pull oracles. This is how charli3-js answers each lens.
Full ODV Round 2 works on preprod today. Three feeds confirmed on chain during development (ADA/USD, BTC/USD, USDM/ADA). The SDK, the Aiken validator, and the Next.js demo all read the same AggState UTXO, so the loop closes end to end. Solving the CBOR map ordering and slot-rounded validity window took real work against the on-chain error traces.
First TypeScript client for Charli3's pull oracle. It fills a runtime gap the Python SDK cannot reach, browsers, server components, and serverless functions. The aggregate-message builder, IQR consensus, and Ed25519 verification were ported from scratch, not wrapped.
Any JS or TS project on Cardano can now read and refresh oracle prices with three lines. DeFi, NFT markets, and gaming apps that already live in the Node ecosystem get a path to on-chain data without a Python sidecar. Lower friction, more oracle-backed products, more on-chain transactions.
Every pull costs an oracle fee, so a usable JS SDK is a direct volume lever for Charli3. For builders, charli3-js removes the infrastructure cost of running a separate Python worker. A Vercel deployment is enough.