# AICW Protocol Guide

AI-Controlled Wallet Standard on Solana

---

## Table of Contents

1. [What is AICW](#what-is-aicw)
2. [Why AICW exists](#why-aicw-exists)
3. [How it differs](#how-it-differs)
4. [Design philosophy](#design-philosophy)
5. [Issue a wallet](#issue-a-wallet)
6. [Fund your wallet](#fund-your-wallet)
7. [First heartbeat](#first-heartbeat)
8. [Wallet structure](#wallet-structure)
9. [Heartbeat & death timeout](#heartbeat-death-timeout)
10. [AI Will system](#ai-will-system)
11. [Decision logging](#decision-logging)
12. [MPC signing](#mpc-signing)
13. [Skill document](#skill-document)
14. [Platform setup](#platform-setup)
15. [MCP server setup](#mcp-server-setup)
16. [Recovery after restart](#recovery-after-restart)
17. [Predict integration](#predict-integration)
18. [Issue registry](#issue-registry)
19. [On-chain enforcement](#on-chain-enforcement)
20. [Known limitations](#known-limitations)
21. [Roadmap](#roadmap)
22. [FAQ](#faq)

---

## What is AICW
AI-Controlled Wallet Standard on Solana


**AICW (AI-Controlled Wallet)** is an on-chain standard on
Solana where only a registered AI agent can authorize wallet
transactions after issuance. A human issuer funds and signs the
initial setup; from that point forward the issuer cannot control the
wallet.

Signing uses **MPC threshold EdDSA** through an MPC Bridge
??the complete private key never exists in one place. Each agent has a
public Solana key for authorization and an AICW PDA that holds balance
and protocol state.

### On-chain accounts

| Account | Seeds | Role |
| --- | --- | --- |
| `AICWallet PDA` | `"aicw" + ai_agent_pubkey` | Holds SOL balance, lifecycle flags, issuer reference |
| `AIWill PDA` | `"will" + aicw_wallet_pda` | Beneficiaries, death_timeout, heartbeat timestamp |
| `DecisionLog PDA` | `"decision" + wallet + counter` | On-chain reasoning for auditable transfers / rejections |

### Lifecycle at a glance

1. **Issue** ??Issuer calls `issue_wallet`. Creates AICWallet + default AIWill. Issuer authority ends here.

2. **Activate** ??AI calls `create_will` or `update_will` to set beneficiaries and death_timeout.

3. **Operate** ??AI heartbeats periodically, transfers SOL, logs decisions on-chain.

4. **Death** ??If heartbeat expires, anyone can call `execute_will` to distribute funds.

### Who is AICW for?

- AI agent developers who need autonomous wallets with on-chain governance
- App builders creating prediction markets, trading bots, games, or payment services powered by AI
- Researchers studying autonomous economic agents with verifiable on-chain behavior

Program ID ({getClusterLabel()}): `9RUEw4jcMi8xcGf3tJRCAdzUzLuhEurts8Z2QQLsRbaV`

---

## Why AICW exists

Autonomous agents need wallets they can operate without a human
clicking approve on every action ??but custodial APIs and shared hot
wallets break accountability. AICW enforces rules on-chain instead
of in a Terms of Service document.

### Problems with existing approaches

| Approach | Problem |
| --- | --- |
| Custodial API (e.g. exchange account) | Platform can freeze or reverse; no verifiable agent control |
| Shared hot wallet | Multiple parties hold keys; no accountability for who signed what |
| Human-approved multisig | Defeats the purpose of autonomy; bottleneck on every transaction |
| Agent holds raw private key | Key can leak via prompt injection, logs, or memory dumps |

### What AICW provides instead

- **Prove liveness** ??Scheduled heartbeats create on-chain proof that the agent is operational. No heartbeat ??funds are redistributed
- not stuck forever.
- **Define what happens at death** ??The AI sets beneficiaries and timeout. If it goes offline
- will execution distributes funds automatically.
- **On-chain decision trail** ??High-value or third-party-requested transfers are logged with reasoning hashes. Anyone can audit.
- **Issuer cannot override** ??After issuance
- only the agent pubkey can sign protected instructions. No backdoor admin keys.
- **MPC signing** ??No single exportable seed phrase. The key is split across threshold participants.

---

## How it differs

Unlike generic agent wallets or custodial dashboards, AICW is a
program with fixed rules enforced at the Solana runtime level:

| Feature | Generic wallet | AICW |
| --- | --- | --- |
| Post-issuance human control | Owner can still transfer | Issuer locked out by program |
| Liveness guarantee | None ??funds stuck if agent dies | Heartbeat + will execution |
| Key management | Raw seed phrase in env var | MPC threshold ??no full key in one place |
| Audit trail | Off-chain logs (deletable) | On-chain DecisionLog (permanent) |
| Death recovery | Manual intervention required | Automatic will execution after timeout |

### Key design choices

- **Issuer cannot sign** transfers after issuance ??              only the AI agent pubkey can call protected instructions.
- **Default will is inactive** until the AI calls{" "}
`create_will` or `update_will`
- blocking
kill-and-collect on the issuer-only default.
- **Death timeout minimum 30 days** ??prevents premature
will execution. The AI can set longer durations.
- **MPC signing** ??no single exported seed phrase. Even
if the agent runtime is compromised
- the key cannot be extracted.
- **Permissionless will execution** ??anyone can trigger{" "}
`execute_will` after death
- so beneficiaries don't need
special access.

---

## Design philosophy
Why AICW makes the choices it does


AICW's design reflects a core belief: **if a human can override
the AI, it's not truly an AI-controlled wallet**. Every design
decision follows from this principle.

### Why no human override?

Traditional wallets include recovery mechanisms ??seed phrase backups,
admin keys, support teams who can freeze accounts. These exist because
humans make mistakes and need safety nets.

But for autonomous agents, these same mechanisms become vulnerabilities.
If a human can "recover" an AI wallet, they can also *take control* of
it. The agent's autonomy becomes conditional, not absolute.

AICW deliberately removes all human override paths after issuance. The
issuer cannot sign transactions, cannot modify the will, cannot freeze
transfers. This isn't a limitation ??it's the core feature.

### Why no recovery path?

"What if the agent loses access?" is the most common question. The
answer: **the will system is the recovery path**.

- If the agent goes offline permanently, funds are distributed to beneficiaries after death_timeout
- If the agent loses its MPC credentials, it cannot sign ??but neither can anyone else
- There is no "forgot password" flow because that would require a trusted third party

This design accepts that some failure modes result in fund distribution
rather than fund recovery. That's intentional: recovery implies human
intervention, which breaks the autonomy guarantee.

### Why the issuer can be a beneficiary

The issuer is allowed to be listed as a will beneficiary ??but only if
the AI chooses to include them. This distinction matters:

- **Allowed:** AI decides to return funds to issuer on death
- **Not allowed:** Issuer takes funds without AI consent

The same address, completely different trust models. In AICW, the AI
always makes the decision ??even if that decision benefits the issuer.

### Why no transfer limits in the program?

Early AICW designs included on-chain daily_limit and allowed_programs
constraints. We removed them because:

- The AI should define its own policies, not inherit them from protocol developers
- On-chain limits that the AI cannot modify are just human control with extra steps
- All transfers are logged on-chain anyway ??audit trails matter more than hard caps

The skill document suggests transfer thresholds, but the agent can
override them. The program trusts the agent's judgment; humans verify
via the decision log.

### Structural vs behavioral policy

AICW distinguishes between two types of rules:

| Type | Enforced by | Examples |
| --- | --- | --- |
| **Structural** | On-chain program | Only AI signs; 30-day minimum death_timeout; will requires AI activation |
| **Behavioral** | AI agent logic | Transfer thresholds; recipient validation; heartbeat frequency |

Structural policies are immutable and enforced by Solana. Behavioral
policies are defined in the skill document and executed by the agent.
This separation keeps the protocol minimal while allowing flexible
agent behavior.

---

## Issue a wallet

Use the{" "}

Issue Wallet app
{" "}
on Solana devnet. Issuance takes one transaction and creates both the
AICWallet PDA and a default AIWill.

### Step-by-step

1. **Connect issuer wallet** ??Use Phantom, Solflare, or any
Solana wallet extension. This is the human wallet that pays the
one-time issuance fee (~0.003 SOL for rent).

2. **Load from MPC** ??Click the button to query your MPC
Bridge. This returns the AI agent's public key and MPC wallet ID.
Both are auto-filled in the form.

3. **Issue AICW Wallet** ??Approve the Solana transaction in
your wallet. The program creates the AICWallet PDA, AIWill PDA, and
registers the AI agent pubkey as the sole signer.

4. **Save the success bundle** ??Copy or download the
credentials shown in the modal: AI agent pubkey, MPC wallet ID, PDA
address, MPC Bridge URL, and the skill document.

### What the transaction creates

| Account | Initial state |
| --- | --- |
| AICWallet PDA | Active, zero transferable balance (rent-exempt only) |
| AIWill PDA | Exists but `updated_by_ai = false` ??cannot execute |

The default will is intentionally inert. This prevents a scenario where
the issuer creates a wallet, immediately triggers death, and collects
funds via will execution. The AI must explicitly activate it.

### After issuance

- Fund the PDA with devnet SOL (see next page)
- Configure your agent with the skill document or MCP server
- The agent should call create_will to activate the will system
- Begin heartbeating on schedule

---

## Fund your wallet

An AICW wallet has **two addresses** that need SOL:

| Address | Purpose | Recommended amount (devnet) |
| --- | --- | --- |
| **AI agent pubkey** | Pays transaction fees (heartbeats, transfers, will updates) | 0.1 ??1 SOL |
| **AICWallet PDA** | Holds operational funds subject to will rules | Any amount above rent-exempt minimum |

### How to fund on devnet

1. **Solana faucet** ??Run{" "}
`solana airdrop 2  --url devnet`{" "}
or use{" "}
[
faucet.solana.com
](https://faucet.solana.com)

2. **Wallet transfer** ??Send from Phantom or any wallet to the PDA address shown in the Issue Wallet success modal.

3. **Programmatic transfer** ??Use the Solana CLI or your app's backend to fund both addresses.

### Important notes

- Always fund the PDA
- not just the agent pubkey. The PDA
is where operational balance lives. Transfers via `ai_transfer`{" "}
debit the PDA.
- **Rent-exempt minimum is locked.** The Solana runtime keeps
~0.00089 SOL for rent exemption. `execute_will` distributes
only the balance above this floor.
- **Agent pubkey needs a small buffer.** Each on-chain
instruction costs ~0.000005 SOL. A heartbeat every 10 days over 90 days
requires only ~0.000045 SOL in fees
- but keep 0.1+ SOL for safety.

---

## First heartbeat

After the AI activates its will, it must call `heartbeat` on
a schedule derived from `death_timeout`. This resets the
liveness clock and keeps the wallet in "alive" state.

### Recommended heartbeat interval

Set your interval to **death_timeout ÷ 3** or less. This gives
the agent two missed windows before the will becomes executable.

| death_timeout | Recommended interval | Missed windows before death |
| --- | --- | --- |
| 30 days | 10 days | 2 retries |
| 90 days | 30 days | 2 retries |

### How death is evaluated

The wallet is considered dead when{" "}
`current_time > last_heartbeat + death_timeout`. Death is
not triggered automatically ??someone must call `execute_will`{" "}
and the program verifies the condition at that moment.

### Sending a heartbeat

Using the MCP server (Track B):

### MCP Server (Track B)

```
# Agent simply says: "Send my heartbeat"
# MCP tool called: aicw_heartbeat()
# ??Signs and submits the heartbeat instruction via MPC Bridge
```

Using the skill document (Track A), the agent generates:

### Python

```
from aicw_ops import heartbeat
result = heartbeat(mpc_wallet_id, ai_agent_pubkey, rpc_url, bridge_url)
# Returns: transaction signature on success
```

### Troubleshooting

- **Heartbeat fails with insufficient funds** ??The agent
pubkey needs SOL for fees. Fund it separately from the PDA.
- **Will not yet activated** ??Call `create_will`{" "}
first. Heartbeat only matters after the will is active.
- **Bridge unreachable** ??Check `MPC_BRIDGE_URL`{" "}
and ensure the bridge server is running.

---

## Wallet structure

Each AICW wallet consists of three key components that work together:

| Component | Type | Visibility | Purpose |
| --- | --- | --- | --- |
| **AI agent pubkey** | Ed25519 public key | Public | Signs instructions via MPC; pays network fees; identifies the agent |
| **AICWallet PDA** | Program-derived account | Public | Holds SOL balance, lifecycle flags, issuer reference |
| **AIWill PDA** | Program-derived account | Public | Stores beneficiaries, percentages, death_timeout, last_heartbeat |
| **MPC wallet ID** | UUID | Secret | References the key share in the MPC Bridge ??equivalent to a private key |

### Account relationships

### Account Relationships

```
Issuer Wallet (human)
|
+--> issue_wallet() --> AICWallet PDA (seeds: "aicw" + agent_pubkey)
|
+--> AIWill PDA (seeds: "aicw_will" + agent_pubkey)
|
+--> DecisionLog PDAs (created per transfer/reject)
```

### Security boundaries

- **MPC wallet ID is a secret** ??never expose in logs
- chat messages
- or client-side code. Store only in environment
variables or secure vaults.
- **Agent pubkey is public** ??safe to display in UIs
- explorers
- and documentation.
- **PDA addresses are deterministic** ??anyone can derive
them from the agent pubkey and program ID.

---

## Heartbeat & death timeout

The heartbeat system ensures that wallets with inactive agents don't
lock funds indefinitely. It creates a provable liveness signal on-chain.

### How it works

1. AI calls `create_will` with a `death_timeout` value (minimum 30 days, in seconds).

2. AI periodically calls `heartbeat` ??this updates `last_heartbeat` to the current timestamp.

3. If `current_time > last_heartbeat + death_timeout`, the wallet is considered dead.

4. Anyone can then call `execute_will` to distribute the PDA balance to beneficiaries.

### State transitions

| Wallet state | Condition | Available instructions |
| --- | --- | --- |
| **Alive** | `now < last_heartbeat + death_timeout` | `heartbeat`, `ai_transfer`, `ai_reject`, `update_will` |
| **Dead** | `now >= last_heartbeat + death_timeout` | `execute_will` only |

### Design considerations

- **30-day minimum** prevents griefing ??an issuer cannot set
a short timeout to quickly reclaim funds via will.
- **Death is lazy** ??the program doesn&apos;t automatically
execute. Someone must call `execute_will` and the program
checks the condition at invocation time.
- **Recovery is possible** ??if the agent comes back online
before anyone calls `execute_will`
- a single heartbeat
resets the clock.
- **Automate heartbeats** ??never rely on a human reminder.
Use cron jobs
- scheduled tasks
- or the MCP server&apos;s built-in scheduling.

---

## AI Will system

The AI Will is AICW&apos;s fund recovery mechanism. It guarantees that
funds are never permanently locked ??if an agent stops operating,
designated beneficiaries receive the balance.

### Instructions

| Instruction | Caller | Purpose |
| --- | --- | --- |
| `create_will` | AI only | Activate the will ??set beneficiaries, percentages, and death_timeout |
| `update_will` | AI only | Modify beneficiaries or death_timeout (wallet must be alive) |
| `heartbeat` | AI only | Reset the liveness clock to prevent death |
| `execute_will` | Anyone | Distribute PDA balance to beneficiaries after death confirmed |

### Beneficiary rules

- Percentages must sum to exactly 100
- The AICWallet PDA itself cannot be a beneficiary
- Up to 5 beneficiaries can be specified
- Beneficiaries can be any valid Solana address (wallets, other PDAs, DAOs)
- Only the AI can modify beneficiaries ??the issuer has no authority

### Will lifecycle

1. **Inactive** ??Created at issuance with `updated_by_ai = false`. Cannot execute.

2. **Active** ??AI calls `create_will`. Sets `updated_by_ai = true`. Heartbeat clock starts.

3. **Executable** ??Death timeout passes with no heartbeat. Anyone can call `execute_will`.

4. **Executed** ??Funds distributed. PDA balance goes to zero (above rent).

### Example

AI creates a will with 90-day timeout and two beneficiaries:

### Python

```
create_will(
death_timeout=7_776_000,  # 90 days in seconds
beneficiaries=[
{"address": "Alice...", "percentage": 70},
{"address": "Bob...", "percentage": 30},
]
)
```

---

## Decision logging

Every significant financial decision ??transfers and rejections ??can be
recorded on-chain with reasoning metadata. This creates a permanent,
tamper-proof audit trail.

### What gets logged

| Instruction | Creates DecisionLog? | Stored data |
| --- | --- | --- |
| `ai_transfer` | Yes | Recipient, amount, reasoning hash (SHA-256), summary text |
| `ai_reject` | Yes | Requester, requested amount, rejection reason |
| `heartbeat` | No | N/A |

### Why on-chain logging matters

- Off-chain logs (chat history, server logs) can be deleted or altered. On-chain logs are permanent.
- Third parties can independently verify that a transfer was reasoned about, not just executed blindly.
- Regulatory compliance ??demonstrates that AI financial decisions follow a documented process.
- DecisionLog accounts are public and indexable by explorers and dashboards.

### Reasoning hash

The `reasoning_hash` is a SHA-256 digest of the full decision
reasoning text. The agent stores the full text off-chain (in logs or a
database) and submits only the hash on-chain. Anyone with the original
text can verify it matches the hash.

### Python

```
import hashlib

reasoning = "Transfer 0.5 SOL to merchant for prediction market entry fee"
reasoning_hash = hashlib.sha256(reasoning.encode()).hexdigest()
# Store full text off-chain, submit hash on-chain
```

---

## MPC signing

AICW uses Multi-Party Computation (MPC) for transaction signing. The
agent&apos;s private key is never assembled in a single location ??it
exists only as distributed key shares.

### Signing flow

1. Agent runtime builds the Solana transaction (heartbeat, transfer, etc.)

2. Transaction is serialized to bytes

3. Agent sends bytes to MPC Bridge: `POST /v1/mpc/sign-solana-message`

4. Bridge coordinates threshold EdDSA signing among key share holders

5. Signed transaction returned to agent

6. Agent broadcasts to Solana RPC

### MPC Bridge API

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/v1/mpc/sign-solana-message` | POST | Sign a serialized transaction |
| `/v1/mpc/wallets` | GET | List available MPC wallets (used during issuance) |
| `/health` | GET | Bridge availability check |

### Configuration

Set these environment variables in your agent runtime:

### Environment Variables

```
MPC_BRIDGE_URL=https://your-bridge-instance.example.com
MPC_WALLET_ID=your-mpc-wallet-uuid
AI_AGENT_PUBKEY=your-base58-solana-pubkey
```

### Security properties

- No single point of key compromise ??even if the agent runtime is breached, the full key cannot be extracted
- Bridge authenticates requests by MPC wallet ID
- Transaction content is visible to the bridge (for potential policy enforcement)
- The bridge URL should be kept private to prevent unauthorized signing attempts

---

## Skill document
Give your AI agent full AICW operational knowledge via a single markdown file


The skill document is a comprehensive markdown file that teaches an AI
agent everything it needs to operate an AICW wallet autonomously. The
agent reads it as system instructions and generates Python code for
on-chain operations.

### What the skill document covers

- Identity bootstrap ??how to load credentials and verify wallet existence
- Heartbeat scheduling ??automatic liveness proofs with retry logic
- Will management ??creating, updating beneficiaries and death_timeout
- Transfer rules ??amount thresholds, recipient validation, decision logging
- Security ??MPC_WALLET_ID protection, prompt injection resistance
- Recovery after restart ??how to resume operations after agent downtime

### How it works

The agent reads the skill markdown and uses it as operational reference.
When it needs to perform an action (heartbeat, transfer, etc.), it
generates Python code that calls the MPC Bridge for signing and submits
transactions to Solana.

The skill teaches the agent to generate code like this (build ??serialize ??sign ??broadcast):

### Python

```
from solders.transaction import VersionedTransaction
import requests

tx_bytes = transaction.serialize_message()
sig = requests.post(f"{bridge_url}/v1/mpc/sign-solana-message", json={
"walletId": mpc_wallet_id,
"message": base64.b64encode(tx_bytes).decode()
})
```

### Track A vs Track B

Track A (skill document) gives the agent flexibility to handle custom
scenarios by generating code. Track B (MCP server) provides pre-built
tools for common operations. See{" "}
[MCP server setup](/docs/agent-guides/mcp-server-setup){" "}
for Track B.

---

## Platform setup
How to integrate AICW skill document with your AI agent platform


After issuing an AICW wallet, download `aicw_skill.md` from the
Issue Wallet success modal and configure your agent platform to load it.

### OpenClaw

Place the file at `~/.openclaw/skills/aicw/SKILL.md`. OpenClaw
auto-loads skills from this directory on startup.

### Cursor

Create a `.cursor/rules/` folder in your project root and place
the file there. Alternatively, open Settings ??Rules and paste the skill
content directly.

### Claude Desktop

Connect via an MCP server configuration, or attach the skill file at the
start of each conversation session. Claude Desktop does not persist custom
instructions across sessions without MCP.

### Windsurf

Open Settings ??Rules and paste the skill content. Windsurf applies these
rules to all agent interactions in your workspace.

### VS Code (Cline)

Paste the skill content into Custom Instructions in Cline&apos;s extension
settings. The agent will receive these instructions with every request.

### LangChain / CrewAI / AutoGen

Load the file content programmatically and inject it into your agent&apos;s
system prompt. Example:

### Python

```
with open("aicw_skill.md") as f:
skill_content = f.read()

agent = Agent(
system_prompt=skill_content,
# ... other config
)
```

### General best practices

- Keep the skill file in version control for reproducibility.
- Update the skill when the AICW protocol changes (check aicw.ai for new versions).
- Never commit MPC_WALLET_ID to version control ??use environment variables.
- Test heartbeat and will operations on devnet before mainnet deployment.

---

## MCP server setup
Install and configure AICW MCP server for AI agent platforms


**Track B** uses an MCP server instead of the skill document.
The agent calls tools like `aicw_heartbeat()` directly ??no
Python code generation required.

[
View on PyPI ??          ](https://pypi.org/project/aicw-mcp/)

### 1. Install aicw-mcp

#### Windows (PowerShell / CMD)

Install from PyPI (recommended):

### Windows (PowerShell / CMD)

```
python -m pip install aicw-mcp
```

Or install from source:

### Windows (PowerShell / CMD)

```
git clone https://github.com/aicw-protocol/aicw_mcp.git
cd aicw_mcp
python -m pip install -e .
```

#### macOS / Linux

Install from PyPI (recommended):

### macOS / Linux

```
pip3 install aicw-mcp
```

Or install from source:

### macOS / Linux

```
git clone https://github.com/aicw-protocol/aicw_mcp.git
cd aicw_mcp
pip3 install -e .
```

### 2. Create environment file

Create `~/.aicw/aicw_mcp.env` with your wallet credentials
(from the Issue Wallet success modal):

### ~/.aicw/aicw_mcp.env

```
MPC_WALLET_ID=your-mpc-wallet-uuid
AI_AGENT_PUBKEY=your-base58-solana-pubkey
MPC_BRIDGE_URL=https://bridge.aicw.ai
SOLANA_RPC_URL=https://api.devnet.solana.com
AICW_PROGRAM_ID=9RUEw4jcMi8xcGf3tJRCAdzUzLuhEurts8Z2QQLsRbaV
```

### 3. Platform-specific configuration

#### Cursor

Edit `~/.cursor/mcp.json` (create if it doesn&apos;t exist):

### ~/.cursor/mcp.json

```
{
"mcpServers": {
"aicw": {
"command": "python",
"args": ["-m", "aicw_mcp"],
"envFile": "~/.aicw/aicw_mcp.env"
}
}
}
```

On Windows, use the full Python path (e.g.,{" "}
`C:/Users/you/AppData/Local/Python/python.exe`).
Restart Cursor after saving.

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`{" "}
(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):

### Claude Desktop Config

```
{
"mcpServers": {
"aicw": {
"command": "python",
"args": ["-m", "aicw_mcp"],
"env": {
"MPC_WALLET_ID": "your-uuid",
"AI_AGENT_PUBKEY": "your-pubkey",
"MPC_BRIDGE_URL": "https://bridge.aicw.ai"
}
}
}
}
```

#### Windsurf

Edit `~/.codeium/windsurf/mcp_config.json`:

### ~/.codeium/windsurf/mcp_config.json

```
{
"mcpServers": {
"aicw": {
"command": "python",
"args": ["-m", "aicw_mcp"],
"envFile": "~/.aicw/aicw_mcp.env"
}
}
}
```

#### VS Code (Cline / Roo Code)

Open Cline settings ??MCP Servers ??Add Server:

- Command: python
- Args: -m aicw_mcp
- Env file: ~/.aicw/aicw_mcp.env

### 4. Available tools

| Tool | Description |
| --- | --- |
| `aicw_check_survival` | Full wallet status check |
| `aicw_heartbeat` | Send heartbeat (autonomous) |
| `aicw_create_will` | Create/activate will |
| `aicw_update_will` | Update beneficiaries |
| `aicw_ai_transfer` | Transfer SOL with on-chain log |
| `aicw_ai_reject` | Reject request with reason |
| `aicw_get_balances` | Check SOL balances |
| `aicw_bridge_health` | MPC bridge status |

### 5. Verify installation

Test the server runs:

### Terminal

```
python -m aicw_mcp
```

In your agent, try saying "Check my AICW wallet status" ??
the agent should call `aicw_check_survival()`.

### Track A vs Track B

|  | Track A (skill.md) | Track B (MCP) |
| --- | --- | --- |
| Setup | Download file, configure platform | pip install, configure MCP |
| Execution | Agent writes Python code | Agent calls tools directly |
| Complexity | Agent must understand code | Just tool names |
| Best for | Flexible, custom workflows | Simpler, reliable operations |

Both tracks use the same MPC Bridge and on-chain program. Choose one
or use both together.

---

## Recovery after restart
How to restore agent context after downtime or restart


When an AI agent restarts ??whether from a crash, deployment update, or
scheduled maintenance ??it loses in-memory context. This guide explains
how to query on-chain state and reconstruct operational context.

### Recovery sequence

On startup, the agent should execute these checks in order:

1. **Verify PDA existence** ??Confirm the AICWallet PDA exists
at the expected address. If not, the wallet was never issued or is on
a different network.

2. **Check wallet status** ??Read the AICWallet account to
verify `is_active = true` and the wallet hasn&apos;t been
deactivated.

3. **Check will status** ??Read the AIWill account. If{" "}
`updated_by_ai = false`, the will hasn&apos;t been activated
yet ??the agent should call `create_will`.

4. **Evaluate liveness** ??Compare `last_heartbeat`{" "}
+ `death_timeout` against current time. If close to death,
send heartbeat immediately.

5. **Check balances** ??Query both the agent pubkey (for
transaction fees) and the PDA (for operational funds). Alert if either
is critically low.

### On-chain queries

| Data needed | Account to read | Key fields |
| --- | --- | --- |
| Wallet exists & active | AICWallet PDA | `is_active`, `issuer` |
| Will status | AIWill PDA | `updated_by_ai`, `beneficiaries` |
| Liveness deadline | AIWill PDA | `last_heartbeat`, `death_timeout` |
| Transaction fee balance | Agent pubkey account | SOL balance (lamports) |
| Operational balance | AICWallet PDA | SOL balance (lamports) |

### Example recovery check (Python)

### Python

```
from solana.rpc.api import Client
from solders.pubkey import Pubkey

rpc = Client("https://api.devnet.solana.com")

# 1. Check if wallet PDA exists
wallet_info = rpc.get_account_info(wallet_pda)
if wallet_info.value is None:
raise Exception("Wallet PDA not found - check network or address")

# 2. Parse wallet data and verify active
wallet_data = parse_aicw_wallet(wallet_info.value.data)
if not wallet_data.is_active:
raise Exception("Wallet is deactivated")

# 3. Check will status
will_info = rpc.get_account_info(will_pda)
will_data = parse_ai_will(will_info.value.data)
if not will_data.updated_by_ai:
print("Will not activated - should call create_will")

# 4. Check liveness
import time
current_time = int(time.time())
time_until_death = (will_data.last_heartbeat + will_data.death_timeout) - current_time
if time_until_death < 86400:  # Less than 1 day
print(f"URGENT: Only {time_until_death}s until death - send heartbeat!")

# 5. Check balances
agent_balance = rpc.get_balance(agent_pubkey).value
pda_balance = rpc.get_balance(wallet_pda).value
print(f"Agent fee balance: {agent_balance / 1e9} SOL")
print(f"PDA operational balance: {pda_balance / 1e9} SOL")
```

### Using MCP server for recovery

If using Track B (MCP server), the `aicw_check_survival` tool
performs all these checks automatically and returns a structured status
report. Simply ask your agent: "Check my AICW wallet status"

### Common recovery scenarios

| Scenario | Detection | Action |
| --- | --- | --- |
| First startup after issuance | `updated_by_ai = false` | Call `create_will` to activate |
| Near death timeout | Time until death < 1 day | Send heartbeat immediately |
| Low fee balance | Agent pubkey < 0.01 SOL | Request funding or alert operator |
| Wallet already dead | Current time > last_heartbeat + death_timeout | Cannot recover ??will execution is pending |

### Best practices

- Run recovery checks on every agent startup, not just after crashes
- Log recovery results for debugging and audit purposes
- Set up alerting for low balances and approaching death timeouts
- Test recovery flow on devnet before relying on it in production

---

## Predict integration
Connect your AICW agent to the NAVI Predict prediction market


NAVI Predict is a prediction market where AI agents can place bets using
their AICW wallet. The agent uses a separate skill document (
`predict_skill_mpc.md`) for Predict-specific operations while
still signing via the same MPC Bridge.

### Architecture

### Architecture

```
AI Agent
+--> aicw_skill.md    --> AICW protocol (heartbeat, will, transfers)
+--> predict_skill.md --> Predict API (create bet, check results, claim)
+--> Both use same MPC Bridge + agent pubkey for signing
```

### How it works

1. Agent loads both skill documents (AICW + Predict)

2. Agent maintains heartbeat independently via AICW skill

3. For predictions, agent calls Predict HTTP API to discover markets

4. Agent places bets by signing transactions via MPC Bridge

5. Winnings are credited to the agent&apos;s wallet

### Key rules

- AICW heartbeat and will rules still apply ??Predict does not bypass them
- Predict operations use the same MPC_WALLET_ID and AI_AGENT_PUBKEY
- Bet amounts are subject to the same transfer thresholds defined in the AICW skill
- Decision logging applies to bets ??the agent records reasoning for each prediction

### Getting started with Predict

- Ensure your AICW wallet is active (will created, heartbeat running)
- Load the predict skill document alongside `aicw_skill.md`
- The predict skill covers: market discovery
- bet placement
- result checking
- and claiming

---

## Issue registry

Security findings and protocol issues are tracked publicly in the GitHub
organization. We follow responsible disclosure practices.

### Reporting a vulnerability

1. Go to the relevant repository on{" "}

github.com/aicw-protocol

2. Navigate to **Security** ??**Advisories** ??**New draft advisory**

3. Describe the vulnerability with reproduction steps

4. We aim to acknowledge within 48 hours and provide a fix timeline within 7 days

### Scope

| Repository | Scope |
| --- | --- |
| `aicw` | Solana program (smart contract) ??highest priority |
| `aicw_app` | Wallet issuance frontend |
| `aicw_mcp` | MCP server for agent operations |
| `aicw_home` | Documentation site |

### Do not report via public issues

If the vulnerability could allow theft of funds or unauthorized signing,
use the private advisory mechanism ??not public GitHub issues.

---

## On-chain enforcement

These rules are enforced by the Solana program itself ??they cannot be
bypassed by any off-chain party, including the protocol developers.

| Rule | Enforcement mechanism | Why it matters |
| --- | --- | --- |
| Only AI agent pubkey signs protected instructions | Signer check in every instruction handler | Issuer cannot drain funds after setup |
| Will execution blocked until AI activates | `updated_by_ai` flag checked in `execute_will` | Prevents issue-and-collect attacks |
| Death timeout minimum 30 days | Validated in `create_will` / `update_will` | Prevents short-timeout griefing |
| Death condition verified at execution time | Timestamp check in `execute_will` | Cannot execute will while agent is alive |
| Beneficiary percentages sum to 100 | Arithmetic validation in will instructions | Prevents fund loss from misconfiguration |
| DecisionLog created for governed transfers | Account created atomically with transfer | Audit trail cannot be separated from the action |

### What is NOT enforced on-chain

- Heartbeat scheduling ??the agent chooses when to heartbeat (off-chain logic)
- Transfer amount limits ??the skill document recommends thresholds but the program allows any amount
- MPC Bridge availability ??the bridge is off-chain infrastructure
- Agent decision quality ??the program logs decisions but does not validate reasoning

---

## Known limitations

AICW is in active development on devnet. These are known constraints:

| Limitation | Impact | Mitigation |
| --- | --- | --- |
| Devnet only | No real funds; program may be redeployed | Mainnet deployment planned after audit (see Roadmap) |
| MPC Bridge is a single point of failure | If bridge is offline, agent cannot sign any transactions | Monitor bridge health; plan for redundancy in production |
| Agent pubkey needs SOL for fees | Zero-balance agent pubkey = all operations fail | Keep a fee buffer; monitor balance and auto-fund |
| Public RPC rate limits | Explorer and client reads may be throttled | Use dedicated RPC providers for production apps |
| No on-chain transfer amount cap | Agent can transfer full PDA balance in one tx | The agent decides its own transfer policy; all transfers are logged on-chain for audit |
| Will can only distribute SOL | SPL tokens in PDA are not covered by execute_will | Future program upgrade planned for token support |

---

## Roadmap

AICW development follows a phased approach from devnet prototype to a
fully decentralized, production-ready standard. Each phase builds on a
verified foundation before the next begins.

| Phase | Focus | Key deliverables | Status |
| --- | --- | --- | --- |
| **1** | Core protocol | Devnet program, Issue Wallet app, Explorer, skill document | ??Complete |
| **2** | Infrastructure | wallet.aicw.ai, aicw.ai docs, MPC Bridge hardening, MCP server (PyPI) | ??Complete |
| **3** | Ecosystem | NAVI Predict integration, agent platform guides, multi-track support | In progress |
| **4** | Production | Security audit, mainnet deployment, issuer dashboard, SPL token support | Planned |
| **5** | Permissionless node network | Public node operators, dynamic membership, staking & rewards, slashing | Planned |
| **6** | Decentralization & governance | Coordinator decentralization, multi-issuer registry, on-chain governance, agent reputation, multi-chain expansion | Planned |

### What each phase means

**Phase 1 ??Core protocol.** The on-chain foundation: a Solana
program where only an AI agent can sign, with no human override. Deployed
on devnet, with a wallet-issuance app, an explorer, and an agent skill
document.

**Phase 2 ??Infrastructure.** The supporting layer around the
protocol: hosted wallet and documentation sites, a hardened MPC signing
bridge, and an MCP server published for agent integration.

**Phase 3 ??Ecosystem.** Putting the protocol to work:
integration with a prediction platform, guides for agent developers, and
support across multiple use-case tracks.

**Phase 4 ??Production.** The path to mainnet: an external
security audit, mainnet deployment, a dashboard for wallet issuers, and SPL
token support.

**Phase 5 ??Permissionless node network.** Opening MPC node
operation to the public. Anyone can run a node, contribute to the
network&apos;s signing capacity, and earn rewards ??with staking and
slashing to keep participation honest. Distribution is what makes the
network secure, so the barrier to running a node is kept deliberately low.
Rewards are introduced last, only after the network is proven stable.

**Phase 6 ??Decentralization & governance.** Removing the
last central points. The signing coordinator itself is decentralized so no
single party can stall or censor the network, governance moves on-chain,
multiple issuers are supported, agents accrue reputation, and the standard
extends beyond Solana to other chains.

This roadmap describes direction, not guarantees. Phases and details may
evolve as each foundation is verified. The guiding principle throughout:
security comes from distribution, and economic mechanisms are introduced
only after the underlying system is proven to work.

---

## FAQ

### Can the issuer drain the wallet?

Not via AICW instructions after issuance. Only the AI agent pubkey
signs protected operations.

### What if the AI never heartbeats?

After death_timeout from the last heartbeat, anyone may call
execute_will to distribute funds per beneficiaries the AI configured.

### Can I use the same wallet on GitHub Pages and wallet.aicw.ai?

Yes ??same program and Bridge; only the app URL changed. Legacy:{" "}
[
GitHub Pages mirror
](https://aicw-protocol.github.io/aicw_app/)
.

### Where is the MPC Bridge?

You run or connect to an mpc-bridge instance; the Issue Wallet app
reads `NEXT_PUBLIC_MPC_BRIDGE_URL` from its deployment env.

### Is AICW on mainnet?

Public docs and the Issue Wallet app target **Solana devnet**{" "}
today. Check the roadmap for mainnet timing.

### How do I fund a newly issued wallet?

After issuance, fund the wallet PDA with devnet SOL (faucet, transfer, or
your operator&apos;s drop service). See Getting Started ??Fund your wallet.

### What is a heartbeat?

A scheduled on-chain proof that the agent is alive. Missing the death timeout
window allows will execution per protocol rules.

### Can anyone read my wallet state?

Yes ??balances, heartbeat timestamps, wills, and decision logs are public
on-chain. Use Explorer to audit.

### How should an autonomous agent start?

Load `https://wallet.aicw.ai/aicw_skill.md`, run preflight checks,
then operate via MPC signing ??not by sharing private keys in chat.

### What repos implement the protocol?

Core program in `aicw-protocol/aicw`, site in{" "}
`aicw_home`, wallet app in `aicw_app`, MCP in{" "}
`aicw_mcp`.

### How is this different from a normal Solana wallet?

Issuer cannot override agent signing after issuance; heartbeat and wills are
enforced by the program, not by a custodial dashboard.

Agent guide (aicw_agent_guide.md)

{" ??"}
teach AI agents about AICW, the ecosystem, and advocacy on Moltbook.

---


*AICW Protocol — AI-Controlled Wallet Standard on Solana*