> For the complete documentation index, see [llms.txt](https://andrewkimjoseph.gitbook.io/celina-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://andrewkimjoseph.gitbook.io/celina-sdk/readme.md).

# Introduction

<div align="center"><img src="/files/QTaYCKSK8mGPGnv3SP1c" alt="Celina — Give your LLM a wallet on Celo"></div>

## Celina SDK

**`@andrewkimjoseph/celina-sdk`** — Celo mainnet library for agent builders: **reads**, **unsigned transaction preparation**, and a shared **LLM tool catalog** (`/tools` export) that powers celina-mcp and browser wallet apps from one source of truth.

Pair with [wagmi](https://wagmi.sh) / viem when users sign in their wallet, or register the catalog in MCP / AI SDK hosts when building agents.

### Celina stack

```mermaid
flowchart TB
  sdk["celina-sdk<br/>reads + prepare* + /tools catalog"]
  mcp["celina-mcp<br/>registers catalog for MCP"]
  host["celina-mcp-host<br/>Streamable HTTP: read + prepare"]
  browser["Browser agent hosts<br/>surface: browser + wagmi"]

  sdk --> mcp
  mcp --> host
  sdk --> browser
```

| Layer                  | What it adds                                                                                                                                                                           |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **SDK** (this package) | Chain logic, `SerializedPreparedFlow`, CELINA calldata tag, and `@andrewkimjoseph/celina-sdk/tools` — shared Zod schemas and handlers for MCP and browser surfaces                     |
| **MCP**                | Registers filtered catalog via `registerSdkTools`; stdio `execute_*` with `CELO_PRIVATE_KEY`; optional address defaults via [session wallet](/celina-sdk/guides/mcp-session-wallet.md) |
| **MCP host**           | Public `https://mcp.usecelina.xyz/api/mcp` — **30 tools** (reads + prepare; no server-key writes)                                                                                      |
| **Browser hosts**      | `filterToolDefinitions(..., { surface: "browser" })` — user signs prepared txs in wallet; no server keys                                                                               |

Third-party apps can consume the programmatic client only, or wire the full tool catalog into Vercel AI SDK / custom orchestrators — see [LLM tool catalog](/celina-sdk/guides/tool-catalog.md).

### What you can do

| Category         | Examples                                                                                                           |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Reads**        | Token balances, Mento FX quotes, Uniswap v4 quotes, governance, ENS, GoodDollar whitelist/UBI                      |
| **Estimates**    | Gas for sends, FX swaps, Uniswap swaps, generic contract calls                                                     |
| **Prepare**      | Unsigned flows for sends, Mento FX, Uniswap v4, Aave, GoodDollar UBI claim                                         |
| **Tool catalog** | `ALL_TOOL_DEFINITIONS`, `filterToolDefinitions` — same tools as celina-mcp, filterable by `surface` and `families` |

The SDK never holds or uses CELO wallet keys. Call `prepare*` with the user's address, then pass `steps` to wagmi.

Prepared calldata includes a **CELINA attribution suffix** on every tagged step — see [Prepared flows](/celina-sdk/concepts/prepared-flows.md).

### Quick start

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

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

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

const flow = await celina.transaction.prepareSend("0xFrom", "0xTo", "USDm", "10");
// flow.steps → wagmi sendTransactionAsync
```

For agent hosts, import the shared catalog:

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

const tools = filterToolDefinitions(ALL_TOOL_DEFINITIONS, {
  surface: "browser",
});
```

See [Quick start](/celina-sdk/getting-started/quick-start.md), [LLM tool catalog](/celina-sdk/guides/tool-catalog.md), and [wagmi integration](/celina-sdk/guides/wagmi-integration.md).

### API overview

| Service       | Reads                                | Prepare (unsigned)                           |
| ------------- | ------------------------------------ | -------------------------------------------- |
| `blockchain`  | network status, blocks, transactions | —                                            |
| `account`     | CELO balance, nonce                  | —                                            |
| `token`       | balances, token info, stablecoins    | —                                            |
| `ens`         | resolve ENS names                    | —                                            |
| `gooddollar`  | whitelist status, UBI entitlement    | `prepareClaimUbi`                            |
| `transaction` | gas fees, estimates                  | `prepareSend`                                |
| `mentoFx`     | `getFxQuote`, `estimateFx`           | `prepareFx`                                  |
| `uniswap`     | `getSwapQuote`, `estimateSwap`       | `prepareSwap`                                |
| `aave`        | —                                    | `prepareSupply`, `prepareWithdraw`           |
| `governance`  | proposals list, details              | —                                            |
| `staking`     | balances, validator groups           | —                                            |
| `nft`         | NFT info, balance                    | —                                            |
| `contract`    | `callFunction`, `estimateGas`        | —                                            |
| `self`        | verify, lookup, session lifecycle    | agent signing (Node + `selfAgentPrivateKey`) |

Full method signatures: [API reference](/celina-sdk/api-reference/api-reference.md).

### Related packages

* [`@andrewkimjoseph/celina-mcp`](https://www.npmjs.com/package/@andrewkimjoseph/celina-mcp) — MCP server; registers SDK tool catalog
* [`celina-mcp-host`](https://github.com/andrewkimjoseph/celina-sdk/blob/main/celina-mcp-host/README.md) — hosted reads (`https://mcp.usecelina.xyz/api/mcp`); no server-key writes
* [`@selfxyz/agent-sdk`](https://www.npmjs.com/package/@selfxyz/agent-sdk)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://andrewkimjoseph.gitbook.io/celina-sdk/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.