SDK · Shared tool catalog

Celina SDK

One mainnet library for Celo agents — reads, unsigned wallet flows, and a shared /tools export that powers celina-mcp and browser wallet apps from the same definitions. Pair with wagmi / viem when users sign in their wallet.

Read the docs View on npm

What you can do

Reads

Token balances, Mento FX quotes, GoodDollar reserve quotes (G$ ↔ USDm), governance proposals, ENS resolution.

Estimates

Gas for sends, FX swaps, and generic contract calls.

Wallet signing

Unsigned tx flows for sends, Mento FX, GoodDollar reserve (G$ ↔ USDm), Uniswap v4, Aave, and GoodDollar UBI.

Sign-time simulation

Import @andrewkimjoseph/celina-sdk/simulation — simulatePreparedStep dry-runs each PreparedTx before wagmi send; celina-mcp uses the same helper in executePreparedFlow.

Tool catalog

Import @andrewkimjoseph/celina-sdk/tools — filter by surface (mcp or browser), family (read/execute). Same schemas celina-mcp registers.

The SDK never holds or uses private keys. Build unsigned flows with the user's wallet address, then pass the returned steps to wagmi for signing. Optional-address defaults and get_wallet_address are celina-mcp only (local stdio + server key), not this package.

Browser surface apps use surface: "browser" and pass the connected wallet on every call — no server keys. MCP hosts use surface: "mcp" with optional executors when CELO_PRIVATE_KEY is configured.

Tool catalog for agent hosts

From v0.5.0, the /tools export ships Zod schemas, descriptions, and handlers for every LLM tool. celina-mcp registers them via registerSdkTools; browser chat apps filter with surface: "browser". Use dynamicTool when registering many tools in AI SDK hosts to avoid TypeScript OOM.

import { createCelinaClient } from "@andrewkimjoseph/celina-sdk";
import {
  ALL_TOOL_DEFINITIONS,
  filterToolDefinitions,
} from "@andrewkimjoseph/celina-sdk/tools";

const celina = createCelinaClient({ rpcUrl: "https://forno.celo.org" });

// Browser wallet app — user signs in wallet
const browserTools = filterToolDefinitions(ALL_TOOL_DEFINITIONS, {
  surface: "browser",
});

// MCP server — full catalog with executors when CELO_PRIVATE_KEY is set
const mcpTools = filterToolDefinitions(ALL_TOOL_DEFINITIONS, {
  surface: "mcp",
});

Full guide: LLM tool catalog.

Install

$npm i @andrewkimjoseph/celina-sdk@latest

Quick start

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

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

// Reads
await celina.token.getStablecoinBalances("0xYourAddress");
await celina.mentoFx.getFxQuote("USDm", "EURm", "100");

// Unsigned txs (user signs in wallet)
const flow = await celina.transaction.prepareSend(
  "0xFrom",
  "0xTo",
  "USDm",
  "10",
);
// flow.steps → pass to wagmi sendTransactionAsync

See Quick start , wagmi integration, and prepared-step simulation for the full signing flow.

API overview

Service	Reads	Wallet signing (unsigned)
`blockchain`	network status, blocks, transactions	—
`account`	CELO balance, nonce	—
`token`	balances, token info, stablecoins	—
`ens`	resolve ENS names	—
`gooddollar`	whitelist status, UBI entitlement, reserve quote/estimate	`claim UBI, reserve swap; MCP execute: executeReserveSwap`
`transaction`	gas fees, estimates	`send`
`mentoFx`	getFxQuote, estimateFx	`FX swap`
`uniswap`	getSwapQuote, estimateSwap	`swap`
`aave`	getBalances (supplied aToken positions)	`supply, withdraw`
`governance`	proposals list, details	—
`staking`	balances, validator groups	—
`nft`	NFT info, balance	—
`contract`	callFunction, estimateGas	—

Full method signatures are in the Wallet signing flows on GitBook, plus the API reference.

Related packages

MCP server

@andrewkimjoseph/celina-mcp

MCP server for IDE / CLI agents — registers the shared SDK tool catalog. 34 tools on remote hosted (reads, GoodDollar reserve quote, AgentKarma reputation), full stdio with CELO_PRIVATE_KEY for execute/write.

MCP hub npm

Self Agent ID

@selfxyz/agent-sdk

Self Agent ID toolkit (separate from this SDK).