> 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/mcp-servers/mcp-servers/owl_wallet.md).

# owl-wallet

The **owl-wallet** MCP server provides AI agents with direct access to the SmartWallet factory system. It enables agents to compute deterministic wallet addresses, generate deployment initCode, and query factory state — all without requiring direct smart contract interaction knowledge.

This server is designed for agents that need to:

* Deploy new smart wallets deterministically via ERC-4337
* Verify wallet addresses before deployment
* Generate UserOperation initCode for bundler submission
* Understand the wallet creation flow

***

## Architecture Overview

The owl-wallet server acts as a read-only interface layer between AI agents and the deployed `SmartWalletFactory` contract. It translates high-level agent requests into web3 RPC calls, handles CREATE2 address computation, and formats responses in agent-friendly JSON.

**Key capabilities:**

* **Deterministic address computation** — Agents can predict wallet addresses before deployment
* **initCode generation** — Produces the exact calldata needed for ERC-4337 UserOperation deployment
* **Factory state queries** — Checks EntryPoint configuration, implementation addresses, and pause status
* **Educational context** — Provides human-readable explanations of the wallet creation process

***

## Available Tools

| Tool Name             | Description                                                                                                            |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `get_factory_state`   | Returns factory configuration including EntryPoint address, wallet implementation, guardian contract, and pause status |
| `get_wallet_address`  | Computes the deterministic CREATE2 address for a wallet given owner, guardian, and salt parameters                     |
| `get_init_code`       | Generates the complete initCode bytes for UserOperation deployment (factory address + calldata)                        |
| `explain_create_flow` | Returns a detailed explanation of the wallet creation process, CREATE2 mechanics, and deployment requirements          |

***

## Setup and Configuration

### Requirements

* **Node.js 18+**
* **RPC URL** for the target network (e.g., Base Sepolia, Base mainnet)
* **Factory address** — deployed SmartWalletFactory contract
* **Chain ID** — expected network identifier for validation

### Installation

```bash
cd mcp/owl-wallet
npm install
```

### Environment Variables

```bash
# Required
export RPC_URL="https://base-sepolia-rpc.publicnode.com"
export FACTORY_ADDRESS="0x..."  # Deployed SmartWalletFactory address
export EXPECTED_CHAIN_ID="84532"  # 84532 for Base Sepolia, 8453 for Base mainnet
```

### Running the Server

**Standard mode (stdio):**

```bash
npm run dev
```

**SSE/HTTP mode (Express server):**

```bash
npm run start:sse
```

**Production build:**

```bash
npm run build
npm start
```

### Development Commands

```bash
npm run lint       # Run ESLint
npm run typecheck  # Run TypeScript type checking
```

***

## How AI Agents Use This Server

### Typical Agent Workflow

1. **Query factory state** to verify the factory is operational and retrieve configuration
2. **Compute wallet address** using the agent's owner key, guardian address, and a unique salt
3. **Check if wallet is deployed** (via on-chain code check or balance query)
4. **Generate initCode** if wallet does not exist
5. **Submit UserOperation** with initCode to bundler for deployment

### Example: Agent Deploying a New Wallet

```typescript
// Step 1: Check factory state
const factoryState = await agent.call_tool("get_factory_state", {});
// Returns: { entryPoint, walletImplementation, guardian, paused: false }

// Step 2: Compute deterministic address
const address = await agent.call_tool("get_wallet_address", {
  owner: "0x1234...",  // Agent's P256 or ECDSA public key
  guardian: "0x5678...",  // Guardian contract address
  salt: "0x00...01"  // 32-byte unique identifier
});
// Returns: { address: "0xABCD..." }

// Step 3: Generate initCode for deployment
const initCode = await agent.call_tool("get_init_code", {
  owner: "0x1234...",
  guardian: "0x5678...",
  salt: "0x00...01"
});
// Returns: { initCode: "0x..." }  // Factory address + createAccount calldata

// Step 4: Agent constructs UserOperation with initCode and submits to bundler
```

### Security Considerations

* **Factory pause status** — Agents must check `paused` state before attempting deployment
* **Address verification** — Always verify computed addresses match expected values
* **Salt uniqueness** — Using the same owner + guardian + salt will produce the same address; increment salt for multiple wallets
* **initCode usage** — initCode is only required for first-time deployment; omit for existing wallets

***

## Tool Reference

### get\_factory\_state

Returns the current configuration and operational status of the SmartWalletFactory.

**Parameters:** None

**Returns:**

```typescript
{
  entryPoint: string;           // ERC-4337 EntryPoint address
  walletImplementation: string; // SmartWallet implementation address
  guardian: string;             // Guardian contract address
  paused: boolean;              // Whether factory is paused
}
```

**Agent use case:** Verify factory is operational before computing addresses or generating initCode.

***

### get\_wallet\_address

Computes the deterministic CREATE2 address for a SmartWallet.

**Parameters:**

```typescript
{
  owner: string;     // Owner public key or address (P256 or ECDSA)
  guardian: string;  // Guardian contract address
  salt: string;      // 32-byte hex salt (e.g., "0x00...01")
}
```

**Returns:**

```typescript
{
  address: string;   // Computed wallet address
}
```

**Agent use case:** Predict wallet address before deployment, verify address matches expected value, check if wallet already exists.

***

### get\_init\_code

Generates the complete initCode for UserOperation deployment.

**Parameters:**

```typescript
{
  owner: string;     // Owner public key or address
  guardian: string;  // Guardian contract address
  salt: string;      // 32-byte hex salt
}
```

**Returns:**

```typescript
{
  initCode: string;  // Factory address + createAccount calldata
}
```

**Agent use case:** Populate UserOperation.initCode field for first-time wallet deployment via ERC-4337 bundler.

**Note:** initCode should only be included in UserOperations when the wallet does not yet exist on-chain. For existing wallets, use empty bytes (`0x`).

***

### explain\_create\_flow

Returns a human-readable explanation of the wallet creation process.

**Parameters:** None

**Returns:**

```typescript
{
  explanation: string;  // Detailed explanation of CREATE2 deployment flow
}
```

**Agent use case:** Understand the wallet creation process, troubleshoot deployment issues, generate educational content for users.

***

## Network Configuration

### Base Sepolia (Testnet)

```bash
export RPC_URL="https://base-sepolia-rpc.publicnode.com"
export EXPECTED_CHAIN_ID="84532"
export FACTORY_ADDRESS="0x..."  # See deployment artifacts
```

### Base Mainnet

```bash
export RPC_URL="https://mainnet.base.org"
export EXPECTED_CHAIN_ID="8453"
export FACTORY_ADDRESS="0x..."  # See deployment artifacts
```

***

## Deployment Notes

* **Factory must be unpaused** for wallet deployment to succeed
* **Wallet addresses are deterministic** — same owner + guardian + salt = same address
* **initCode is deployment-only** — only required for first UserOperation; omit for existing wallets
* **CREATE2 guarantees** — addresses can be computed off-chain and verified on-chain before deployment

***

## Related Documentation

* [SmartWalletFactory Contract](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/core/smartwalletfactory.md) — On-chain factory implementation
* [SmartWallet Contract](https://github.com/greenowl-money/owl-wallet-docs/blob/main/contracts/core/smartwallet.md) — Core wallet contract
* [ERC-4337 Overview](https://github.com/greenowl-money/owl-wallet-docs/blob/main/architecture/erc-4337.md) — Account abstraction standard
* [MCP Protocol](https://github.com/greenowl-money/owl-wallet-docs/blob/main/architecture/mcp.md) — Model Context Protocol specification


---

# 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/mcp-servers/mcp-servers/owl_wallet.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.