> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/products/agentic-wallet/manual/llms.txt
> Use this file to discover all available pages before exploring further.

# Technical architecture

> How the Cobo Agentic Wallet service, owner controls, and developer integrations fit together for agents and automations that operate onchain.

For most developers, this page is background context. The canonical onboarding path is still:

1. [CLI](/products/agentic-wallet/manual/developer/cli)
2. [Python SDK](/products/agentic-wallet/manual/developer/api-client-python) or [TypeScript SDK](/products/agentic-wallet/manual/developer/api-client-typescript)
3. Add a framework or MCP layer only after that first run works

## Component overview

```mermaid theme={null}
flowchart TD
    subgraph AI["**Your Runtime**"]
        sdk["MCP + CLI + SDK & integrations<br/>LangChain / OpenAI / Agno / TypeScript"]
    end

    subgraph Human["**Human (You)**"]
        im["Cobo Agentic Wallet app<br/>Pair · Approve · Policies · Notifications"]
    end

    nl["**Human Interface Service**"]

    core["**Cobo Agentic Wallet Service**<br/>Identity · Wallet · Delegation · Policy Engine..."]

    AI -->|"REST API (X-API-Key)"| core
    Human -->|"mobile app"| nl
    nl -->|"REST API"| core
```

## Platform responsibilities

| Platform                    | Primary role                                                                                                                  |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **CLI (`caw`)**             | Create wallets, execute transactions, generate pairing codes, submit pacts — the program-native interface                     |
| **Cobo Agentic Wallet app** | Pair agents, manage owner guardrails, approve pacts and over-limit transactions, freeze/revoke, review activity, back up keys |

## Cobo Agentic Wallet Service

The Cobo Agentic Wallet service is the single source of truth for all wallet, identity, delegation, policy, and audit state.

### Modules

| Module             | Responsibility                                                                                                                            |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Identity**       | Principal CRUD, API key issuance and verification, scope enforcement                                                                      |
| **Wallets**        | Wallet + address lifecycle; executing on-chain transactions                                                                               |
| **Transactions**   | Transfer and contract call submission; fee estimation; WaaS webhook handling                                                              |
| **Delegations**    | Owner → Operator scoped permission grants with expiry and freeze/unfreeze                                                                 |
| **Pact**           | Pact lifecycle management — runtimes submit pacts, owners approve them, system creates delegations and API keys automatically on approval |
| **Policy Engine**  | Three-stage gate: ① permission check → ② policy rule evaluation → ③ counter limits                                                        |
| **Audit Pipeline** | Logs every allow/deny/approval decision; delivers events via webhook outbox                                                               |

### Authentication

| Method      | Header      | Who uses it                      | Scope                   |
| ----------- | ----------- | -------------------------------- | ----------------------- |
| **API Key** | `X-API-Key` | Owners, Operators, SDK, CLI, MCP | All business operations |

## SDK & integrations

From a developer perspective, CAW splits into two layers:

* a **control layer** you call from your program
* an **owner layer** that handles pairing, approvals, and guardrails

You write the program logic. CAW owns authorization enforcement and owner control surfaces.

The Python SDK is a pure Python client library that all Python developer-facing integrations build on. The TypeScript SDK provides equivalent functionality for Node.js and TypeScript environments.

| Layer                            | What it is                                                                                                                                                                  |
| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `WalletAPIClient` (Python)       | Async HTTP client — direct access to all Cobo Agentic Wallet service endpoints                                                                                              |
| TypeScript SDK (raw API classes) | Promise-based HTTP client with full TypeScript types — instantiate individual API classes (`TransactionsApi`, `PactsApi`, `WalletsApi`, etc.) from `@cobo/agentic-wallet`   |
| `AgentWalletToolkit`             | 20 canonical runtime tools covering wallet discovery, pact flows, transfers, contract calls, signing, payments, fee estimation, transaction tracking, audit, and delegation |
| Framework adapters               | LangChain, OpenAI Agents — each wraps the toolkit in the framework's tool format                                                                                            |
| CLI (`caw`)                      | Shell command interface for developers and AI coding assistants                                                                                                             |

The MCP Server (`cobo-agentic-wallet[mcp]`) is a separate stdio server that exposes the same wallet tools to any MCP-compatible client (Claude Desktop, Cursor, etc.).

## Integration modes

For nearly all developers in these docs, the only mode that matters is **Agent Mode**.

In Agent Mode, your runtime integrates with the CAW service and Cobo provides the owner-facing controls, pairing flow, policy management, and approval UX.

| Mode           | You build                                                                     | Cobo provides                                                                        | Status                 |
| -------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ---------------------- |
| **Agent Mode** | Your runtime, CLI usage, SDK usage, MCP integration, or framework integration | Cobo Agentic Wallet app, owner approvals, policy management, wallet control surfaces | Available now          |
| **Core Mode**  | Your full custom stack, including your own owner-facing control surface       | Core engine APIs only                                                                | Available upon request |
| **Owner Mode** | Your own owner-facing interface                                               | Agent-side framework abstractions                                                    | Available upon request |

For the developer experience in these docs, Agent Mode is the default path because it lets you focus on runtime logic instead of rebuilding the owner layer. Core Mode and Owner Mode should be treated as advanced deployment options, not the main onboarding story.

## Human Interface

A separate service that provides the owner-facing experience.

|                        |                                                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Primary channel**    | Cobo Agentic Wallet app — iOS / Android                                                                                             |
| **Owner tools**        | Pair agent, manage owner guardrails, approve/reject pacts, approve/reject over-limit transactions, freeze/unfreeze, review activity |
| **Push notifications** | Delivered to the Cobo Agentic Wallet app for pact approvals and over-limit transaction reviews                                      |

The Human Interface service holds an owner's API key and acts on behalf of the owner when calling the Cobo Agentic Wallet service.

For developers, this is the key separation to understand: your runtime never needs to implement owner pairing, approval UI, or policy-management UI in the default integration mode.

## Security architecture

### Signing layer is isolated from the AI layer

Your program interacts with the Cobo Agentic Wallet service through the REST API using an API key. The API key grants permission to submit transaction requests — it does not give the runtime access to private key material. Signing happens inside the Cobo Agentic Wallet service using Multi-Party Computation, which requires cooperation from multiple independent parties. The LLM component of your agent, if you have one, never sees, holds, or derives private keys.

### Policy engine as a structural guard

Every transaction request passes through a three-stage policy gate before anything executes on-chain:

1. **Permission check** — does this API key have permission to perform this operation type?
2. **Policy rule evaluation** — does this operation satisfy the owner's configured rules?
3. **Counter check** — does this operation stay within rolling spend limits?

This gate runs server-side and cannot be bypassed by the runtime. Even if an attacker manipulates your agent into submitting a malicious transaction, the policy engine blocks it if it violates the owner's rules. The runtime's intent is not trusted — only the request is evaluated against the rules.

### Prompt injection

Prompt injection — where malicious content in an external source hijacks an agent into performing unauthorized actions — is a real threat for agents that read external data. The policy engine provides structural protection: a successfully injected instruction cannot cause unauthorized onchain activity unless the resulting request passes the owner's spending limits, allowlists, and contract-call controls.

For stronger protection at the agent layer, limit your agent's access to external data sources that are not necessary for the task, and keep spending limits and address allowlists as tight as possible for the operations your agent needs to perform.