> 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/guides/agentkarma.md).

# AgentKarma reputation

The SDK exposes [AgentKarma](https://agentkarma.io) via `celina.agentKarma` — a read-only reputation adapter over `@agentkarma/sdk`. It is Celo-pinned (the chain Celina operates on) and mirrors the same flows as celina-mcp tools (`get_agentkarma_reputation`, `get_agentkarma_celo_agent`, `check_agentkarma_counterparty`).

**Boundaries:**

* **Read-only** — never signs, never executes a transaction, never holds custody
* **Non-routing** — never proxies an agent call; only reads reputation
* **No keys** — no `CELO_PRIVATE_KEY` or env requirement
* **External API** — calls agentkarma.io; not wrapped in Celina Amplitude analytics (unlike on-chain Celina reads)

For direct AgentKarma integration outside Celina, see [`@agentkarma/sdk`](https://www.npmjs.com/package/@agentkarma/sdk).

## Configuration

No configuration is required. The adapter defaults to `https://agentkarma.io`:

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

const celina = createCelinaClient();

// Optional: override AgentKarma API base URL
const celinaCustom = createCelinaClient({
  agentKarma: { baseUrl: "https://agentkarma.io" },
});
```

| Option               | Purpose                                                                 |
| -------------------- | ----------------------------------------------------------------------- |
| `agentKarma.baseUrl` | Override AgentKarma REST base URL (defaults to `https://agentkarma.io`) |
| `agentKarma.timeout` | Request timeout in ms                                                   |

## Read examples

### Karma by wallet address

```ts
const snapshot = await celina.agentKarma.getKarma(
  "0xC1C860804EFdA544fe79194d1a37e60b846CEdeb",
  { face: "both" }, // provider, consumer, or both (default)
);
// snapshot.provider, snapshot.consumer — scores and receipt-backed signals
```

### ERC-8004 agent by ID

```ts
const agent = await celina.agentKarma.getCeloAgent(1);
// agent.identity, agent.reputation — on-chain ERC-8004 + AgentKarma context
```

### Counterparty trust policy

```ts
const result = await celina.agentKarma.evaluateCounterparty(
  "0xCounterpartyAddress",
  {
    face: "provider",
    minScore: 50,
    requireReceiptBacked: true,
  },
);
// result.decision.allowed — explainable allow/deny
// result.snapshot — karma data the decision was computed from
```

`evaluateCounterparty` always fetches **both** karma faces so the scored face is guaranteed present. Policy evaluation is local (pure function) — no extra network call.

## MCP tools

On hosted MCP (`https://mcp.usecelina.xyz/api/mcp`) and local stdio MCP, three read tools are available:

| Tool                            | Purpose                                            |
| ------------------------------- | -------------------------------------------------- |
| `get_agentkarma_reputation`     | Provider + Consumer karma for a Celo wallet        |
| `get_agentkarma_celo_agent`     | ERC-8004 agent identity + reputation by numeric ID |
| `check_agentkarma_counterparty` | Local trust policy against a counterparty address  |

**Important:** AgentKarma tools require an explicit `address` for the subject being looked up. They do **not** default to the operator's signer wallet — that would disclose the operator's identity to a third-party API.

## When to use

Use AgentKarma reads as a **preflight** before high-risk agent actions:

* Before `send_token` or `prepare_send` to an unknown counterparty
* Before `execute_uniswap_swap` or `execute_mento_fx` with a new routing partner
* In browser chat UIs (e.g. Celeste) to surface reputation context to the user

AgentKarma complements Celina's on-chain reads — it does not replace balance checks, gas estimates, or sign-time simulation.

## Catalog access

For advanced use, call tools from the canonical `@agentkarma/sdk/tools` catalog via `runCatalogTool` (chain forced to `"celo"`):

```ts
await celina.agentKarma.runCatalogTool("get_karma", {
  wallet: "0xYourAddress",
  face: "both",
});
```

See [AgentKarmaService](/celina-sdk/services/agentkarmaservice.md) for full method signatures.

## See also

* [Architecture](/celina-sdk/concepts/architecture.md) — stack and client composition
* [LLM tool catalog](/celina-sdk/guides/tool-catalog.md) — `domains/agentkarma.ts` in the shared catalog
* [celina-website tool docs](https://usecelina.xyz/tools) — rich examples for each MCP tool


---

# 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, and the optional `goal` query parameter:

```
GET https://andrewkimjoseph.gitbook.io/celina-sdk/guides/agentkarma.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.