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

# Overview

**An ERC-4337 smart wallet designed for autonomous AI agents.**

***

## What is Owl Smart Wallet?

Owl Smart Wallet is a gas-optimized, ERC-4337 account abstraction wallet built for **AI agents to operate autonomously**. Unlike traditional wallets designed for human users, Owl is purpose-built for programmatic control through **MCP (Model Context Protocol) servers**, enabling AI agents to manage crypto assets, interact with DeFi protocols, and execute transactions without manual intervention.

The wallet combines **passkey-based ownership** (P256/WebAuthn), **session key delegation**, **guardian social recovery**, and **gasless transactions** into a unified system that gives AI agents secure, limited, time-bound access to on-chain operations.

***

## Key Features

### ERC-4337 Account Abstraction

* Full compliance with Account Abstraction v0.9 specification
* Gasless transactions via paymaster sponsorship
* Counterfactual deployment using CREATE2 deterministic addressing
* Bundler relay architecture protects API keys while enabling agent autonomy

### Dual Owner Types

* **P256 (secp256r1)** — Passkey/WebAuthn-compatible cryptography for hardware-backed security
* **ECDSA (secp256k1)** — Traditional Ethereum address support for EOA compatibility

### Session Key System

AI agents operate through **time-limited, scope-restricted session keys**:

* **Granular permissions** — allowlist specific targets, selectors, and value limits
* **Automatic expiration** — maximum 30-day validity window
* **Usage limits** — per-transaction caps, total value caps, and call count limits
* **Revocable** — owner can revoke session keys at any time
* **Dual signature types** — ECDSA and P256 session keys supported

### Guardian Social Recovery

* Multi-guardian approval workflow for owner recovery
* Configurable threshold (M-of-N guardians required)
* Time-delayed execution to prevent malicious takeovers
* Supports both ECDSA and P256 guardians

### Gas Sponsorship

* **WhitelistPaymaster** — sponsors gas for whitelisted targets
* Optional factory wallet enforcement
* Batch transaction support for gas efficiency

### ERC-1271 Signature Validation

* On-chain signature verification for both owner and session keys
* Enables smart contract wallet participation in protocols requiring signatures
* Supports WebAuthn/passkey signatures

***

## Architecture Overview

The Owl Smart Wallet system is composed of four layers:

### 1. Smart Contract Layer

Core on-chain components implementing ERC-4337 and wallet logic:

* **SmartWallet** — The account contract with P256/ECDSA owners, session keys, and recovery
* **SmartWalletFactory** — Deterministic CREATE2 deployment and wallet registry
* **WhitelistPaymaster** — Gas sponsorship policy enforcement
* **SessionKeyManager** — Reusable session key authorization subsystem
* **OwlLendingAdapter** — DeFi lending integration (Morpho)

### 2. MCP Server Layer

AI agent interface providing structured tools for wallet operations:

* **owl-wallet** — Core wallet management (session keys, deployment, guardians)
* **lendefi** — DeFi lending operations (Morpho integration)
* **mcp-acp-agent** — ACP (Access Control Policy) enforcement

### 3. Agent Layer

Autonomous AI agent with curated DeFi tooling:

* **OpenClaw Agent** — 23 curated tools for DeFi operations
* **Bundler Relay** — Secure ERC-4337 bundler API key protection

### 4. Payment Protocol Layer

HTTP-based microtransaction protocol:

* **x402 Protocol** — HTTP 402 payment-required flow with USDL settlement
* **Facilitator & Server Express** — Payment gateway infrastructure

***

## Component Map

### Smart Contracts

| Contract             | Purpose                                         |
| -------------------- | ----------------------------------------------- |
| `SmartWallet`        | ERC-4337 account with session keys and recovery |
| `SmartWalletFactory` | Deterministic deployment and registry           |
| `WhitelistPaymaster` | Gas sponsorship for whitelisted targets         |
| `SessionKeyManager`  | Time/scope-limited key authorization            |
| `OwlLendingAdapter`  | Morpho lending protocol integration             |

### Key Interfaces

| Interface            | Purpose                           |
| -------------------- | --------------------------------- |
| `ISmartWallet`       | Wallet operations interface       |
| `IWalletFactory`     | Factory deployment interface      |
| `IWalletRegistry`    | Wallet registration and lookup    |
| `IDaimoP256Verifier` | P256 signature verification       |
| `IMorpho`            | Morpho lending protocol interface |

### MCP Servers

| Server          | Tools Provided                                                 |
| --------------- | -------------------------------------------------------------- |
| `owl-wallet`    | Session key management, wallet deployment, guardian operations |
| `lendefi`       | Supply, withdraw, borrow, repay, market queries                |
| `mcp-acp-agent` | Access control policy enforcement                              |

### OpenClaw Components

| Component       | Purpose                                     |
| --------------- | ------------------------------------------- |
| `owl-agent`     | Autonomous DeFi agent with 23 curated tools |
| `bundler-relay` | Secure bundler API key relay                |

### x402 Components

| Component             | Purpose                             |
| --------------------- | ----------------------------------- |
| `facilitator-express` | Payment facilitator server          |
| `server-express`      | x402 protocol server implementation |

***

## Documentation Structure

### Smart Contract Reference

* [**SmartWallet**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/smart-wallet.md) — Account contract with session keys and recovery
* [**SmartWalletFactory**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/smart-wallet-factory.md) — Deterministic deployment
* [**WhitelistPaymaster**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/whitelist-paymaster.md) — Gas sponsorship
* [**SessionKeyManager**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/session-key-manager.md) — Session key authorization
* [**OwlLendingAdapter**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/owl-lending-adapter.md) — DeFi lending integration

### MCP Integration

* [**owl-wallet MCP Server**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/mcp-servers/owl-wallet.md) — Wallet management tools
* [**lendefi MCP Server**](/mcp-servers/mcp-servers/lendefi.md) — DeFi lending tools
* [**mcp-acp-agent MCP Server**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/mcp-servers/mcp-acp-agent.md) — Access control tools

### Agent & Infrastructure

* [**OpenClaw Agent**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/agents/openclaw.md) — Autonomous DeFi agent architecture
* [**Bundler Relay**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/infrastructure/bundler-relay.md) — Secure bundler API relay
* [**x402 Protocol**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/infrastructure/x402-protocol.md) — HTTP payment protocol

### Guides

* [**Session Key Guide**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/session-keys.md) — Creating and managing session keys
* [**Guardian Recovery**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/guardian-recovery.md) — Social recovery flow
* [**Agent Integration**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/agent-integration.md) — Integrating AI agents with the wallet
* [**Security Model**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/security.md) — Access control and permissions

***

## Quick Start

### For AI Agent Developers

1. Review the [**Agent Integration Guide**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/agent-integration.md)
2. Explore the [**owl-wallet MCP Server**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/mcp-servers/owl-wallet.md) tool reference
3. Study the [**Session Key Guide**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/session-keys.md) for permission management

### For Smart Contract Developers

1. Start with the [**SmartWallet Contract**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/smart-wallet.md) documentation
2. Review the [**Security Model**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/security.md) for access control patterns
3. Examine the [**SessionKeyManager**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/session-key-manager.md) for delegation logic

### For Security Auditors

1. Read the [**Security Model**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/guides/security.md) overview
2. Review access control in [**SmartWallet**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/smart-wallet.md)
3. Audit session key validation in [**SessionKeyManager**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/session-key-manager.md)
4. Examine upgrade patterns in [**SmartWalletFactory**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/smart-wallet-factory.md)

### For Protocol Integrators

1. Review the [**ISmartWallet Interface**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/smart-wallet.md#interfaces)
2. Study [**ERC-1271 signature validation**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/smart-wallet.md#erc-1271-signature-validation)
3. Explore [**WhitelistPaymaster**](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/whitelist-paymaster.md) for gas sponsorship integration

***

## Project Information

* **Version:** 1.0.0
* **License:** MIT
* **Account Abstraction:** ERC-4337 v0.9
* **Signature Standards:** ERC-1271
* **Cryptography:** P256 (secp256r1) and ECDSA (secp256k1)

***

## Support & Resources

* **GitHub Repository:** [OwlSmartWallet](https://github.com/yourorg/owl-smart-wallet)
* **MCP Protocol:** [Model Context Protocol](https://modelcontextprotocol.io)
* **ERC-4337 Spec:** [Account Abstraction](https://eips.ethereum.org/EIPS/eip-4337)


---

# 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://docs.greenowl.money/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.