z4p Documentation

Welcome to the documentation for z4p.

z4p is the local-first Rust trading harness that powers safe, observable, approval-gated AI trading agents. z4p Mobile is the upcoming Flutter app that gives traders portfolio visibility, markets, perps, and the critical approval surface.

🚀 Core Concepts

What is z4p: Rust-native agent harness with vault bible, bot scoping, policy engine, and MCP.
Getting Started: Install the binary and run your first observe-only agent.
Quickstart: From install to proposing and approving your first trade.
Supported Networks: Solana (Jupiter), EVM (Uniswap), Hyperliquid, and MCP-routed chains.
FAQ: Common questions about the harness and approval model.

🧠 The Agent Control Loop

z4p is built around a deliberate 5-step loop:

Compose — Load the agent's full vault bible every tick.
Retrieve — FTS5 + memory for relevant history and learnings.
Simulate — Dry-run routes across DEXes and perps venues.
Approve — Enforce scopes, budgets, policies; trader explicitly approves.
Execute — Submit, track, learn, and write outcomes back to the vault.

See Harness Architecture in the site or the architecture docs in the z4p repo.

🖥️ Surfaces

z4p exposes multiple surfaces:

CLI — Full control from one binary (z4p bot setup, agent-tick, approvals, etc.).
Vault UI — The gateway at /vault for browsing and editing the live bible.
Gateway + MCP — HTTP API + MCP server for external agents and tools.
On-chain Bots — Scoped loop runners (price_watcher, wallet_monitor, ...).

📱 z4p Mobile Companion

The z4p Mobile app (Flutter) is the trader's daily driver and safety net:

Portfolio and multi-chain balances
Hyperliquid perps and market views
AI research agents
Approval workflows for actions proposed by the z4p harness

The harness stays local and strict. The app keeps the human in the loop.

🔐 Security & Philosophy

"Observe first. Propose clearly. Approve deliberately."

z4p is intentionally not a fire-and-forget black box. Every write path goes through explicit policy checks and human approval by default.

Security Guide: Best practices
Glossary: Terms used across the system
For Developers: Extending skills, loops, and MCP tools