Policy engine

.agents/skills/omniclaw-cli/SKILL.md

@@ -14,7 +14,7 @@ requires:
       Scoped agent token tied to your wallet. Set by the owner before your
       session starts. Never print, log, or transmit this value. If it is
       missing, stop and notify the owner — you cannot proceed without it.
-version: 0.0.2
+version: 0.0.3
 author: Omnuron AI
 ---
 

Dockerfile.agent

@@ -19,8 +19,8 @@ COPY src/ src/
 # Sync project
 RUN uv sync --frozen || uv sync
 
-EXPOSE 8080
+EXPOSE 9090
 
-ENV OMNICLAW_AGENT_PORT=8080
+ENV OMNICLAW_AGENT_PORT=9090
 
-CMD ["uv", "run", "omniclaw", "server", "--host", "0.0.0.0", "--port", "8080"]
+CMD ["uv", "run", "omniclaw", "server", "--host", "0.0.0.0", "--port", "9090"]

README.md

@@ -1,94 +1,293 @@
 # OmniClaw
 
-The economic control and trust infrastructure for autonomous agents — enabling them to pay, get paid, and transact securely under real-time policy enforcement.
+**The first agentic payment network: policy-controlled, gasless, and real money-ready.**
 
-## Why OmniClaw
+OmniClaw CLI + Financial Policy Engine let autonomous agents pay and earn safely at machine speed.
 
-Every AI agent that touches money needs the same handful of things: wallet orchestration, payment routing, spending guardrails, trust evaluation, audit trails, and recovery flows. Today teams wire these by hand, one integration at a time, and re-learn the same compliance lessons the hard way.
+---
 
-OmniClaw replaces that patchwork with one SDK. You get guarded execution, policy enforcement, and regulatory-aware defaults out of the box — so you can focus on what your agent actually does, not how it moves money.
+## Why OmniClaw?
 
-## Key Capabilities
+In the Agent Era, software can act economically. But current wallets fail when software, not humans, is the operator:
 
-**For Agents That Pay** — guarded `pay()` execution, `simulate()` before funds move, x402 and direct transfer routing, cross-chain USDC flows, nanopayments via Circle Gateway
+- **Full key access** = extreme risk (agent can drain the wallet)
+- **Human approval** = kills speed and autonomy
+- **No spending limits** = agent can spend unlimited
 
-**For Agents That Earn** — Seller SDK, `sell()` decorator, facilitated transfers, trust-gated access
+**OmniClaw solves this** by separating:
+1. **Financial Policy Engine** (owner runs) - holds private keys, enforces policy
+2. **Execution Layer** (agent uses) - thin CLI that only does what policy allows
 
-**For Operators That Control** — policy enforcement, spending limits, velocity controls, circuit breakers, audit-ready logs, recovery flows
+The agent **never touches the private key**. It only talks to the CLI. The owner decides what the agent can do via policy.json.
 
-## Install
+---
+
+## Architecture: Three Components
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         OMNICLAW SYSTEM                            │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                     │
+│   OWNER SIDE (runs the Financial Policy Engine)   AGENT SIDE (uses CLI)     │
+│   ════════════════════════════════════════════════   ═══════════════════════   │
+│                                                                     │
+│   ┌─────────────────────────────┐                ┌─────────────────────┐   │
+│   │  Financial Policy Engine   │                │     OmniClaw CLI   │   │
+│   │  (uvicorn server)          │◄──────────────►│  (thin client)     │   │
+│   │                            │   HTTPS        │                    │   │
+│   │  - Holds private key       │                │  - pay             │   │
+│   │  - Enforces policy         │                │  - deposit         │   │
+│   │  - Signs transactions      │                │  - withdraw        │   │
+│   └─────────────────────────────┘                └─────────────────────┘   │
+│            │                                      │                 │
+│            │      Circle Nanopayment             │                 │
+│            └──────────────┬──────────────────────┘                 │
+│                           │                                          │
+│                    ┌──────▼──────┐                                  │
+│                    │   Circle    │                                  │
+│                    │   Gateway   │                                  │
+│                    │   (USDC)    │                                  │
+│                    └─────────────┘                                  │
+│                                                                     │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Why Two Parts?
+
+| Component | Who Runs It | What It Does |
+|-----------|-------------|--------------|
+| **Financial Policy Engine** | Owner/human | Holds private key, enforces policy, signs transactions |
+| **CLI** (agent uses) | Agent | Thin client - sends requests, gets responses. Cannot bypass policy |
+
+---
+
+## Key Concepts
+
+### 1. Two Wallets Every Agent Has
+
+Every agent has **two wallets**:
+
+| Wallet | How It Works |
+|--------|--------------|
+| **EOA** (External Owned Account) | Derived from `OMNICLAW_PRIVATE_KEY`. Holds actual USDC on-chain. Used to sign deposits. |
+| **Circle Developer Wallet** | Created via policy.json. Where withdrawn funds go. The "circle wallet." |
+
+### 2. Why Deposit + Pay + Withdraw?
+
+```
+Your USDC starts here:         Then moves here:              Ends up here:
+┌──────────┐                  ┌────────────┐              ┌──────────────┐
+│   EOA    │ ─deposit───────► │  Gateway   │ ──pay──────► │    Seller    │
+│ (on-chain)│   (on-chain)    │  Contract  │   (x402)     │    EOA       │
+└──────────┘                  └────────────┘              └──────────────┘
+                                  │                              │
+                                  │ withdraw                     │
+                                  └──────────────► Circle Developer Wallet
+```
+
+- **Deposit**: Move USDC from your EOA → Gateway (on-chain, costs gas)
+- **Pay**: Use Gateway for gasless payments (x402 protocol)
+- **Withdraw**: Move USDC from Gateway → your Circle wallet
+
+### 3. Why Gasless Nanopayments?
+
+Circle's Gateway supports **EIP-3009** - off-chain authorization:
+- No gas needed for payments
+- Instant settlement
+- Circle batches and settles on-chain
+
+This is what makes agent-to-agent commerce practical.
+
+---
+
+## Quick Start
+
+### 1. Install
 
 ```bash
 pip install omniclaw
 ```
 
-For local development:
+### 2. Environment Variables
 
 ```bash
-uv sync --extra dev
+# Required
+export OMNICLAW_PRIVATE_KEY="0x..."     # Your agent's private key
+export OMNICLAW_AGENT_TOKEN="your-token" # Token from policy.json
+export OMNICLAW_AGENT_POLICY_PATH="/path/to/policy.json"
+export CIRCLE_API_KEY="your-circle-key" # Circle API key
+
+# Network (testnet or mainnet)
+export OMNICLAW_NETWORK="ETH-SEPOLIA"    # or ETH-MAINNET
+export OMNICLAW_ENV="production"         # set for mainnet
+
+# RPC for on-chain operations
+export OMNICLAW_RPC_URL="https://..."
+# Nanopayments network is derived from OMNICLAW_NETWORK (EVM chain)
 ```
 
-## Quick Start
+### 3. Start Financial Policy Engine (Owner)
 
-### 1. Run the Server
+```bash
+uvicorn omniclaw.agent.server:app --port 8080
+```
+
+This runs the Financial Policy Engine that holds the private key and enforces policy.
+
+### 4. Configure CLI (Agent)
+
+Agent runtime should set these (no interactive setup required):
 
 ```bash
-git clone https://github.com/omnuron/omniclaw.git
-cd omniclaw
+export OMNICLAW_SERVER_URL="http://localhost:8080"
+export OMNICLAW_TOKEN="your-agent-token"
 ```
 
-Create a `.env` file with your Circle credentials:
+Optional: persist config locally for dev workflows:
 
+```bash
+omniclaw-cli configure --server-url http://localhost:8080 --token your-token --wallet primary
 ```
-CIRCLE_API_KEY=your_circle_api_key
-ENTITY_SECRET=your_entity_secret
+
+CLI output is agent-first (JSON, no banner). For human-friendly output set:
+
+```bash
+export OMNICLAW_CLI_HUMAN=1
 ```
 
-Start the server:
+Note: `omniclaw` and `omniclaw-cli` point to the same CLI.
+
+---
+
+## For BUYERS (Paying for Services)
+
+### Step 1: Get USDC
+Send USDC to your EOA address (derived from OMNICLAW_PRIVATE_KEY)
 
+### Step 2: Deposit to Gateway
 ```bash
-docker-compose up -d
-# Server runs at http://localhost:8088
+omniclaw-cli deposit --amount 10
 ```
+→ Moves USDC from EOA → Circle Gateway contract (on-chain, costs gas)
 
-Verify the setup:
+### Step 3: Pay for Services
+```bash
+# Pay another agent
+omniclaw-cli pay --recipient 0xDEAD... --amount 5
+
+# Or pay for x402 service (URL)
+omniclaw-cli pay --recipient https://api.example.com/data --amount 1
+```
+→ Uses gasless nanopayments via x402 protocol (Gateway CAIP-2 derived from `OMNICLAW_NETWORK`, EVM only)
 
+### Step 4: Withdraw to Circle Wallet
 ```bash
-omniclaw doctor    # Verify credentials
-omniclaw env       # List all env vars
+omniclaw-cli withdraw --amount 3
 ```
+→ Moves USDC from Gateway → your Circle Developer Wallet
 
-### 2. Connect the CLI
+---
 
+## For SELLERS (Receiving Payments)
+
+### Option A: Simple Transfer
+Just share your address, receive payments directly:
 ```bash
-pip install omniclaw
-omniclaw-cli configure --server-url http://localhost:8088 --token <TOKEN> --wallet primary
+omniclaw-cli address  # Get your address to share
 ```
 
-### 3. Use in Code
+### Option B: x402 Payment Gate (Recommended)
+Expose your service behind payment:
 
-```python
-from omniclaw import OmniClaw, Network
+```bash
+omniclaw-cli serve \
+  --price 0.01 \
+  --endpoint /api/data \
+  --exec "python my_service.py" \
+  --port 8000
+```
 
-client = OmniClaw(network=Network.BASE_SEPOLIA)
+This opens `http://localhost:8000/api/data` that requires USDC payment to access.
+
+---
+
+## Complete CLI Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `configure` | Set server URL, token, wallet | `configure --server-url http://localhost:8080 --token mytoken --wallet primary` |
+| `address` | Get wallet address | `address` |
+| `balance` | Get wallet balance | `balance` |
+| `balance-detail` | Detailed balance (EOA, Gateway, Circle) | `balance-detail` |
+| `deposit` | Deposit USDC to Gateway | `deposit --amount 5` |
+| `withdraw` | Withdraw to Circle wallet | `withdraw --amount 2` |
+| `withdraw-trustless` | Trustless withdraw (~7-day fallback) | `withdraw-trustless --amount 2` |
+| `withdraw-trustless-complete` | Complete trustless withdraw after delay | `withdraw-trustless-complete` |
+| `pay` | Make payment | `pay --recipient 0x... --amount 5` |
+| `simulate` | Simulate payment | `simulate --recipient 0x... --amount 5` |
+| `serve` | Expose x402 payment gate | `serve --price 0.01 --endpoint /api --exec "echo hello"` |
+| `status` | Agent status | `status` |
+| `ping` | Health check | `ping` |
+| `ledger` | Transaction history | `ledger --limit 20` |
+
+---
+
+## Default Policy.json
+
+Copy and edit `examples/policy-simple.json`:
+
+For full policy options, see **[docs/POLICY_REFERENCE.md](docs/POLICY_REFERENCE.md)**
+
+```json
+{
+  "version": "2.0",
+  "tokens": {
+    "YOUR_AGENT_TOKEN": {
+      "wallet_alias": "primary",
+      "active": true,
+      "label": "Your Agent Name"
+    }
+  },
+  "wallets": {
+    "primary": {
+      "name": "Primary Wallet",
+      "limits": {
+        "daily_max": "100.00",
+        "per_tx_max": "50.00"
+      },
+      "recipients": {
+        "mode": "allow_all"
+      }
+    }
+  }
+}
 ```
 
-## Documentation
+---
+
+## Environment Variables Reference
 
-For detailed guides and architecture docs, see the [Wiki](../../wiki):
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OMNICLAW_PRIVATE_KEY` | Yes | Agent's private key for signing |
+| `OMNICLAW_AGENT_TOKEN` | Yes | Token matching policy.json |
+| `OMNICLAW_AGENT_POLICY_PATH` | Yes | Path to policy.json |
+| `OMNICLAW_NETWORK` | No | Network (ETH-SEPOLIA, ETH-MAINNET) |
+| `OMNICLAW_ENV` | No | Set to "production" for mainnet |
+| `OMNICLAW_RPC_URL` | No | RPC endpoint for on-chain ops |
+| `CIRCLE_API_KEY` | Yes | Circle API key |
+| `OMNICLAW_SERVER_URL` | No | CLI server URL (for configure) |
 
-| Page | Description |
-|------|-------------|
-| [Getting Started](../../wiki/Getting-Started) | Full installation, environment setup, and first payment walkthrough |
-| [Architecture](../../wiki/Architecture) | System design, module breakdown, and payment flow |
-| [Compliance Design](../../wiki/Compliance-Design) | Authorization traceability, regulatory alignment (CLARITY Act, GENIUS Act), and gray-zone analysis |
-| [Trust & ERC-8004](../../wiki/Trust-&-ERC-8004) | Trust evaluation framework, on-chain signals, and audit comparison |
-| [API Reference](../../wiki/API-Reference) | `pay()`, `simulate()`, `sell()`, NanoPayment, Trust, CLI |
-| [Contributing Guide](../../wiki/Contributing-Guide) | Dev setup, branch workflow, commit conventions, code quality |
+---
+
+## Documentation
 
-## Contributing
+- **[docs/agent-getting-started.md](docs/agent-getting-started.md)** - Agent setup walkthrough
+- **[docs/agent-skills.md](docs/agent-skills.md)** - Skill instructions for AI agents
+- **[docs/FEATURES.md](docs/FEATURES.md)** - Full feature documentation
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and the [Contributing Guide](../../wiki/Contributing-Guide) for development setup, coding standards, and how to submit pull requests.
+---
 
 ## License