Technical architecture

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

1. CLI
2. Python SDK or TypeScript SDK
3. Add a framework or MCP layer only after that first run works

​

Component overview

​

Platform responsibilities

​

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

​

Authentication

​

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. 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. 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. 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.