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, locked CELO and staking/delegation info, browse governance delegates (Celo Mondo directory), humanness status, 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, GoodDollar UBI, governance (lock/vote/unlock), staking (stake/delegate), GoodDollar identity connect, and generic contract writes. Prepared flows return chainId 42220.

On-chain attribution

ERC-8021 Schema 0 (celina + app codes). Set attributionTags on createCelinaClient or createAAClient. Prefer check_attribution_tag for unified custom tags; verify still surfaces historical CELINA|… when present.

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.

createCelinaClient never holds CELO wallet keys — pass prepared steps to wagmi. For sponsored UserOps, createAAClient uses an owner key and your app-owned gas sponsorship credentials. Optional-address defaults and get_wallet_address are celina-mcp only (local stdio + server key).

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, account registration status	`register Celo account`
`token`	balances, token info, stablecoins	—
`ens`	resolve ENS names	—
`gooddollar`	whitelist status, UBI entitlement, reserve quote/estimate, face verification link	`claim UBI, reserve swap, identity connect/disconnect; MCP execute: executeReserveSwap, connectIdentity`
`transaction`	gas fees, estimates	`send`
`mentoFx`	getFxQuote, estimateFx	`FX swap`
`uniswap`	getSwapQuote, estimateSwap	`swap`
`aave`	getBalances (supplied aToken positions)	`supply, withdraw`
`governance`	proposals, locked balance, pending withdrawals, votable proposals	`lock/unlock/relock/withdraw CELO, vote (humanness-gated)`
`staking`	balances, validator groups, delegation info, Celo Mondo delegate directory (getGovernanceDelegates)	`stake/unstake/activate, delegate/undelegate (humanness-gated)`
`humanness`	checkHumanness (Self Agent ID or GoodDollar IdentityV4)	`gates governance and staking writes`
`nft`	NFT info, balance	—
`contract`	callFunction, estimateGas	`prepareFunction`

Full method signatures are in the Wallet signing flows, Account Abstraction, On-chain attribution, plus the API reference.

Related packages

MCP server

@andrewkimjoseph/celina-mcp

MCP server for IDE / CLI agents — registers the shared SDK tool catalog. 45 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).