Quick start

Server-side only. This package includes server-native dependencies (@agentkarma/sdk, @celo/attribution-tags) that cannot be bundled for the browser. Import it only from Node.js environments — API routes, background workers (BullMQ / Vercel Cron), or CLI scripts.

1. Create a client

import { createCelinaClient } from "@andrewkimjoseph/celina-sdk";

const celina = createCelinaClient({
  rpcUrl: "https://forno.celo.org",
  ethRpcUrl: "https://ethereum.publicnode.com", // optional, for ENS
});

2. Read on-chain data

// Stablecoin balances for an address
const balances = await celina.token.getStablecoinBalances("0xYourAddress");

// Mento FX quote (no wallet needed)
const quote = await celina.mentoFx.getFxQuote("USDm", "EURm", "100");

// Uniswap v4 quote (no wallet needed)
const swapQuote = await celina.uniswap.getSwapQuote("USDC", "USDT", "100");

// GoodDollar reserve quote — G$ ↔ USDm (no wallet needed)
const reserveQuote = await celina.gooddollar.getReserveQuote("GoodDollar", "USDm", "1000");

3. Prepare an unsigned transaction

const flow = await celina.transaction.prepareSend(
  "0xFromAddress",
  "0xToAddress",
  "USDm",
  "10",
);

console.log(flow.summary);
// "Send 10 USDm to 0xToAddress"

console.log(flow.steps.length);
// 1 (single ERC-20 transfer)

4. Simulate and sign with wagmi

Simulate each step immediately before signing to catch reverts before gas is spent. usePublicClient() returns a viem PublicClient — the same type simulatePreparedStep expects.

import { simulatePreparedStep } from "@andrewkimjoseph/celina-sdk/simulation";
import { useSendTransaction, usePublicClient } from "wagmi";

const { sendTransactionAsync } = useSendTransaction();
const publicClient = usePublicClient();

for (const step of flow.steps) {
  await simulatePreparedStep(publicClient!, {
    account: fromAddress,
    step,
  });

  const hash = await sendTransactionAsync({
    to: step.to,
    data: step.data,
    value: step.value ? BigInt(step.value) : undefined,
  });

  const receipt = await publicClient!.waitForTransactionReceipt({ hash });
  if (receipt.status === "reverted") {
    throw new Error(`Transaction reverted: ${hash}`);
  }
}

See Prepared-step simulation and wagmi integration for error handling, multi-step flows, and React patterns.

Next steps

• Configuration — RPC URLs and client options
• Prepared flows — flow shape and step fields
• Send tokens — CELO vs ERC-20 sends