safehands-pharos 1.3.0 → 1.5.0

package/README.md

@@ -1,445 +1,444 @@
-<p align="center">
-  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" />
-  <img src="https://img.shields.io/badge/MCP_Skill-000000?style=for-the-badge" />
-  <img src="https://img.shields.io/badge/Pharos_Atlantic-688689-blueviolet?style=for-the-badge" />
-  <img src="https://img.shields.io/badge/Tools-27-orange?style=for-the-badge" />
-  <img src="https://img.shields.io/badge/Testnet_Only-SAFE-blue?style=for-the-badge" />
-</p>
-
-# SafeHands-Pharos: Transaction Safety Firewall for AI Agents
-
-SafeHands-Pharos is a **Pharos Skill Engine-compatible MCP package** that protects AI agents before they execute payments, token approvals, swaps, x402 paid requests, or contract interactions.
-
-Before an AI agent sends a payment, approves tokens, swaps assets, publishes risk data, or pays an x402 resource, SafeHands runs a policy-based preflight check and returns a deterministic decision:
-
-```text
-ALLOW | WARN | BLOCK | REQUIRE_CONFIRMATION | REQUIRE_FUNDING | REQUIRE_TOKEN_REVIEW
-```
-
-Every decision includes a risk level, human-readable reasons, required next actions, environment metadata, and structured JSON that agents can parse.
-
-> **Testnet scope:** SafeHands targets **Pharos Atlantic Testnet only**. It is not audited for mainnet and should not be used with mainnet funds.
-
----
-
-## Why AI Agents Need Transaction Safety Middleware
-
-Autonomous agents can now hold wallets, call APIs, pay x402 resources, approve tokens, and interact on-chain. Generic Web3 tools usually answer: "Can this transaction be sent?" SafeHands answers a more important question first:
-
-> **Should this action be allowed at all?**
-
-Common agent-execution risks:
-
-| Risk | What can go wrong | SafeHands guardrail |
-|---|---|---|
-| Unlimited approval | Agent approves a malicious spender forever | Blocks unlimited approval by default |
-| Wrong chain | Agent signs on mainnet or the wrong testnet | Blocks mainnet and chain ID mismatch |
-| Risky x402 URL | Agent pays or fetches SSRF-sensitive endpoints | Blocks localhost/private IPs by default |
-| Overspending | Agent pays above configured limits | Blocks payments above limits |
-| Unknown token | Agent swaps/approves unverified token | Warns or requires token review |
-| Missing signer | Agent tries write action without safe signer | Returns structured signer error |
-
----
-
-## What SafeHands Is, and What It Is Not
-
-SafeHands is a **Transaction Safety Firewall / Guardrail Skill** for Pharos agents. SafeHands is a guardrail layer before execution, not a generic Web3 toolbox.
-
-It is **not** a generic Web3 toolbox and does not replace Pharos Skill Engine. It complements the Skill Engine by adding a safety layer before execution:
-
-```text
-User intent
-→ SafeHands preflight
-→ ALLOW / WARN / BLOCK
-→ Pharos Skill Engine or MCP execution if safe
-→ SafeHands risk report
-```
-
-### Difference from Reputation Systems
-
-SafeHands is also different from pure reputation systems:
-
-| System type | Main question |
-|---|---|
-| Agent reputation, such as AgentLeash-style trust systems | "Can I trust this agent?" |
-| SafeHands | "Can I trust this action right now?" |
-
-SafeHands can use reputation signals, but its core purpose is **action-level risk gating**.
-
----
-
-## Pharos Atlantic Testnet Context
-
-Default project configuration:
-
-| Item | Value |
-|---|---|
-| Environment | `atlantic-testnet` |
-| Chain ID | `688689` |
-| RPC URL | `https://atlantic.dplabs-internal.com` |
-| Explorer | `https://atlantic.pharosscan.xyz/` |
-| Mainnet support | `false` |
-| RiskRegistry | `0x61962a6c812ee9f57b207e1ea47c19ae70bb7141` |
-| Primary Pharos Skill Engine USDC | `0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8` |
-| Alternate Circle-referenced USDC | `0xcfC8330f4BCAB529c625D12781b1C19466A9Fc8B` |
-
-The project treats router and pool addresses that are not directly verified from official docs as **project-configured**, not universal canonical values.
-
-### 🧠 Smart Liquidity Fallback
-Testnet liquidity is often fragmented or missing. SafeHands includes a **Smart Fallback Engine** within its DODO API integration. 
-If an AI agent requests a swap to the primary `USDC` token and the routing engine returns `NO_ROUTE_AVAILABLE`, SafeHands will automatically and silently retry the route query using the `Alternate Circle-referenced USDC` address. This prevents unnecessary transaction failures during live agent demos.
-
----
-
-## Official Pharos Skill Engine Alignment
-
-- SafeHands follows the official `SKILL.md` + `references` + `assets` structure (found in the `skill/` package directory).
-- SafeHands complements Pharos Skill Engine by adding preflight safety checks before write actions.
-- Pharos Skill Engine provides general on-chain capabilities.
-- SafeHands answers: "Is this action safe to execute?"
-- Default network remains Pharos Atlantic Testnet.
-- No mainnet readiness is claimed.
-
----
-
-## Supported Usage Modes
-
-SafeHands supports three usage modes:
-
-1. **Pharos Skill Engine (Recommended for Agents):** Install directly into your AI agent project via GitHub:
-   ```bash
-   npx skills add SZtch/safehands-pharos
-   ```
-2. **MCP server usage:** Run directly as a standard MCP server for Claude Desktop, Anvita Flow, etc.
-3. **npm/npx CLI usage:** Run manually in the terminal for testing and CI checks.
-
----
-
-## Quick Start
-
-```bash
-npm install
-npm run build
-npm run test:all
-npm run demo
-```
-
-Run as MCP server:
-
-```bash
-npx safehands-pharos
-```
-
-Show CLI help:
-
-```bash
-npx safehands-pharos --help
-```
-
-Run deterministic demo:
-
-```bash
-npx safehands-pharos --demo
-```
-
-Run a Skill Engine-compatible CLI call:
-
-```bash
-npx safehands-pharos skill safehands_preflight_check --input-json '{"actionType":"approve_token","chainId":688689,"isMainnet":false,"approvalAmount":"max","spender":"0x0000000000000000000000000000000000000001"}'
-```
-
-The CLI returns the standard response envelope:
-
-```json
-{
-  "success": true,
-  "data": {
-    "decision": "BLOCK",
-    "riskLevel": "HIGH",
-    "safeToExecute": false,
-    "reasons": ["Unlimited approval requested."],
-    "requiredActions": ["Use a limited approval amount."],
-    "environment": "atlantic-testnet",
-    "chainId": 688689,
-    "isMainnet": false
-  },
-  "error": null,
-  "timestamp": "2026-06-12T00:00:00.000Z"
-}
-```
-
----
-
-## Environment Setup
-
-Copy `.env.example` if you need local configuration:
-
-```bash
-cp .env.example .env
-```
-
-Safe defaults:
-
-```env
-WALLET_MODE=none
-WRITE_TOOLS_ENABLED=false
-ALLOW_UNLIMITED_APPROVAL=false
-ALLOW_LOCAL_X402_FETCH=false
-```
-
-Read-only and preflight tools do not require a private key. Write tools require `WRITE_TOOLS_ENABLED=true` and a safe signer source.
-
-### 💾 Agent Wallet Backups
-By default, testnet wallets created via `create_agent_wallet` are strictly **In-Memory** and will not persist after the MCP server restarts.
-To enable persistent local storage for your AI agent wallets, set the following environment variable:
-```env
-WALLET_STORE_PATH=./.agents/wallets.json
-```
-This will securely XOR-obfuscate and save the agent's private key to your local `.agents` folder (which is explicitly ignored by Git to prevent accidental leakage).
-
----
-
-## MCP Tools: 27 Total
-
-SafeHands currently exposes **27 MCP tools**:
-
-- 17 legacy/core Web3 safety/execution tools
-- 3 managed testnet wallet tools
-- 7 branded SafeHands guardrail tools
-
-### Branded SafeHands Guardrail Tools
-
-| Tool | Purpose |
-|---|---|
-| `safehands_preflight_check` | Policy-based ALLOW/WARN/BLOCK check before execution |
-| `safehands_safe_execute` | Guarded wrapper around payment, approval, swap, and x402 execution |
-| `safehands_wallet_health` | Checks whether an agent wallet is ready to act |
-| `safehands_x402_preflight` | Checks URL, payment amount, token, signer, and x402 safety before paying |
-| `safehands_risk_report` | Generates a human-readable risk report for demos and judges |
-| `explain_risk` | Converts policy results into plain-English explanations |
-| `token_registry_status` | Classifies token addresses as canonical, test, custom, unknown, or invalid |
-
-### Core Safety and Execution Tools
-
-| Tool | Type | Purpose |
-|---|---|---|
-| `assess_risk` | Read / optional write | 5-dimension risk score |
-| `check_token_security` | Read | GoPlus token security profile |
-| `simulate_transaction` | Read | Dry-run transaction simulation |
-| `estimate_gas` | Read | Gas estimate and sufficiency check |
-| `execute_swap` | Write | FaroSwap/DODO swap with guardrails |
-| `send_payment` | Write | Native PHRS payment |
-| `approve_token` | Write | ERC-20 approval with unlimited-approval guard |
-| `get_token_price` | Read | Token price data |
-| `get_pool_info` | Read | DODO/FaroSwap pool and route info |
-| `get_gas_price` | Read | Current gas price |
-| `get_wallet_balance` | Read | Wallet balances |
-| `check_allowance` | Read | ERC-20 allowance check |
-| `get_transaction_status` | Read | Transaction status by hash |
-| `get_execution_history` | Read | Wallet transaction history |
-| `publish_risk_score` | Write | Publish score to RiskRegistry |
-| `query_risk_registry` | Read | Query on-chain risk score |
-| `x402_pay_and_fetch` | Write when HTTP 402 | Fetch x402 resources and pay only after a payment challenge |
-
-### Managed Testnet Wallet Tools
-
-| Tool | Purpose |
-|---|---|
-| `create_agent_wallet` | Explicitly create a managed testnet wallet |
-| `get_agent_wallet` | Return public wallet metadata, never private key |
-| `get_agent_wallet_balance` | Check managed wallet balances |
-
----
-
-## Policy Engine Behavior
-
-The reusable policy engine lives at:
-
-```text
-src/lib/policy/actionPolicyEngine.ts
-```
-
-Supported action types:
-
-```text
-send_payment
-approve_token
-execute_swap
-x402_pay_and_fetch
-publish_risk_score
-custom_contract_call
-```
-
-Key guardrails:
-
-- Block mainnet actions.
-- Block chain ID mismatch.
-- Block unlimited approvals by default.
-- Block SSRF-sensitive x402 URLs.
-- Block payment above configured limits.
-- Block x402 payment above `MAX_X402_PAYMENT_USDC`.
-- Block approvals above `MAX_APPROVAL_AMOUNT_USDC` unless consciously configured.
-- Warn when a token is custom, non-registry, or token-security provider is unavailable.
-- Require confirmation for medium-risk actions.
-- Allow low-risk Pharos Atlantic Testnet actions.
-
----
-
-## x402 Behavior
-
-SafeHands has both x402 client and server behavior:
-
-### Free endpoints
-
-- `GET /supported`
-- `GET /health`
-
-These do **not** require a user private key.
-
-### Paid endpoints
-
-- `GET /assess-risk`
-- `GET /check-token-security`
-- `GET /simulate-transaction`
-
-Expected demo price: `0.001 USDC`.
-
-Client flow:
-
-1. Fetch normally first.
-2. If HTTP 200, return `paymentExecuted=false`.
-3. If HTTP 402, run SafeHands x402 preflight.
-4. Request signer only after HTTP 402.
-5. Do not log or return signed payment payloads.
-
----
-
-## Using SafeHands with Pharos Skill Engine
-
-SafeHands includes a Pharos Skill Engine adapter under:
-
-> **Note:** The canonical publishable Skill package is in `skill/`. The `examples/pharos-skill-engine/` folder is retained as an integration example.
-
-```text
-examples/pharos-skill-engine/
-├── SKILL.safehands.md
-├── references/
-│   └── safehands.md
-└── assets/
-    └── safehands/
-        ├── policy-defaults.json
-        └── example-actions.json
-```
-
-The reference files teach the Skill Engine how to call SafeHands through terminal commands such as:
-
-```bash
-npx safehands-pharos skill safehands_preflight_check --input-json '<json>'
-npx safehands-pharos skill safehands_x402_preflight --input-json '<json>'
-npx safehands-pharos skill safehands_wallet_health --input-json '{}'
-npx safehands-pharos skill token_registry_status --input-json '{"tokenAddress":"0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8"}'
-```
-
-Use SafeHands before Pharos Skill Engine performs write actions. SafeHands complements the Skill Engine and should not be treated as a replacement.
-
----
-
-## Security Guardrails
-
-SafeHands defaults to defensive behavior:
-
-- `WRITE_TOOLS_ENABLED=false` by default.
-- `WALLET_MODE=none` by default.
-- No wallet is created on install, import, or startup.
-- Managed wallets are created only through `create_agent_wallet`.
-- Private keys are never returned in MCP or CLI responses.
-- Private keys and payment proofs are not logged.
-- Unlimited approvals are blocked unless explicitly allowed.
-- SSRF-sensitive x402 URLs are blocked unless local testing is explicitly enabled.
-- Mainnet actions are blocked.
-- External API failures return structured errors rather than crashing tool calls.
-
----
-
-## Demo
-
-Run:
-
-```bash
-npm run demo
-```
-
-or:
-
-```bash
-npx safehands-pharos --demo
-```
-
-The default demo is deterministic and non-destructive. It shows wallet health, allowed preflight, blocked approval, token registry status, x402 preflight, free x402 endpoint behavior, paid x402 without signer, SSRF blocking, write-tool blocking, and a human-readable risk explanation.
-
----
-
-## Real Testnet Verification
-
-SafeHands includes live verification commands that test against real Pharos Atlantic Testnet infrastructure:
-
-| Command | What it does | Requires |
-|---------|-------------|----------|
-| `npm run test:rpc:live` | Reads chain ID, block number, optional wallet balance from live RPC | Network access |
-| `npm run test:live:safehands` | Runs 7 CLI safety checks against built dist (no broadcast) | Built dist |
-| `npm run test:x402:live` | Tests x402 free/paid endpoint behavior locally | Nothing |
-| `npm run test:dodo:live` | Tests DODO API route if `DODO_API_KEY` set; skips cleanly if not | `DODO_API_KEY` (optional) |
-
-**Important distinctions:**
-
-1. **Live RPC checks** (`test:rpc`, `test:rpc:live`) connect to the real Pharos Atlantic Testnet RPC and read chain ID + block number.
-2. **Live CLI checks** (`test:live:safehands`) run real CLI invocations against built dist, testing policy decisions deterministically.
-3. **x402 behavior checks** (`test:x402:live`) use a **local test server** labeled `LOCAL_X402_SERVER_DOCS_BEHAVIOR_TEST`. They do not connect to a remote Pharos x402 endpoint.
-4. **DODO checks** (`test:dodo:live`) performs live read-only DODO/FaroSwap checks when `DODO_API_KEY` is configured. The public API key can be provided through an environment variable. The key is not required for the normal deterministic demo. A missing key results in a clean skip. A live API pass does not automatically make router addresses docs-verified.
-5. **Smoke tests** (`test:all`) are deterministic and do not require network connectivity (except DODO/RPC-dependent tools, which degrade gracefully).
-6. **Address verification statuses** (DOCS_VERIFIED, DOCS_DEMO_NON_OFFICIAL, PROJECT_CONFIGURED) are sourced from `docs/reports/OFFICIAL_DOCS_ALIGNMENT_REPORT.md`.
-7. **No real transactions are broadcast by default.** Write tools require explicit `WRITE_TOOLS_ENABLED=true`.
-
----
-
-## Tests and Validation
-
-```bash
-npm ci
-npm run build
-npx tsc -p tsconfig.all.json --pretty false
-npm run test:all                # 43-point smoke test suite
-npm audit --omit=dev --audit-level=high
-npm pack --dry-run
-```
-
-Live verification (requires network):
-
-```bash
-npm run test:rpc                # Basic RPC connectivity
-npm run test:rpc:live           # Full live RPC verification with structured output
-npm run test:live:safehands     # 7 CLI safety checks (read-only)
-npm run test:x402:live          # x402 behavior checks (local server)
-npm run test:dodo:live          # DODO API check (requires DODO_API_KEY, skips if missing)
-```
-
-`test:rpc` and `test:rpc:live` depend on DNS/network access to Pharos RPC and may fail in restricted environments. This should be reported honestly as a provider/network limitation, not hidden.
-
----
-
-## Known Limitations and TODOs
-
-- Testnet-only, not audited for mainnet use.
-- Managed wallet storage is testnet-grade unless a real KMS/Vault is integrated.
-- DODO/FaroSwap router addresses are project-configured unless official docs confirm them.
-- GoPlus/DODO/FaroSwap availability depends on external services and API limits.
-- `npm audit` for production dependencies is clean; full dev audit may report dev-only dependency issues depending on upstream packages.
-- Formal unit tests with mocked RPC/DODO/GoPlus providers would improve long-term maintainability.
-
----
-
-## Hackathon Summary
-
-**Project name:** SafeHands-Pharos: Transaction Safety Firewall for AI Agents
-
-**Short description:** SafeHands-Pharos is a Pharos Skill Engine-compatible MCP package that protects AI agents before they execute payments, token approvals, swaps, or x402 paid requests by returning ALLOW, WARN, or BLOCK decisions with human-readable risk explanations.
+# SafeHands-Pharos — Transaction Safety Firewall for AI Agents
+
+> **Most Pharos skills let an agent *do* things — check balances, swap, pay, deploy.**
+> **SafeHands is the one that decides whether the agent *should*.**
+
+```bash
+npx safehands-pharos skill safehands_preflight_check --input-json \
+  '{"actionType":"approve_token","chainId":688689,"tokenAddress":"0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8","spenderAddress":"0x000000000000000000000000000000000000dEaD","approvalAmount":"max"}'
+```
+
+Sample output:
+
+```json
+{
+  "success": true,
+  "data": {
+    "decision": "BLOCK",
+    "riskLevel": "HIGH",
+    "safeToExecute": false,
+    "reasons": [
+      "Unlimited approval requested."
+    ],
+    "requiredActions": [
+      "Use a limited approval amount."
+    ],
+    "checks": [
+      { "name": "mainnet_guard", "status": "pass", "message": "Action is not targeting mainnet." },
+      { "name": "chain_id", "status": "pass", "message": "Chain ID is Pharos Atlantic Testnet (688689)." },
+      { "name": "environment", "status": "pass", "message": "Environment is atlantic-testnet." },
+      { "name": "approval_amount", "status": "fail", "message": "Unlimited approval is blocked by default." }
+    ],
+    "environment": "atlantic-testnet",
+    "chainId": 688689,
+    "isMainnet": false,
+    "tokenRegistry": {
+      "symbol": "USDC",
+      "status": "SKILL_ENGINE_CANONICAL_TOKEN",
+      "verificationStatus": "DOCS_VERIFIED_FROM_PHAROS_SKILL_ENGINE"
+    },
+    "source": "safehands_preflight_check"
+  },
+  "error": null,
+  "timestamp": "2026-06-14T00:00:00.000Z"
+}
+```
+
+That's the whole idea: **before** an agent approves a token, swaps, sends a payment,
+or pays an x402 resource, SafeHands runs a policy check and returns `ALLOW`, `WARN`,
+or `BLOCK` — with a plain-English reason. If `BLOCK`, the agent stops. No transaction,
+no loss.
+
+**Live preflight examples:** see [DEMO.md](DEMO.md) — real ALLOW and BLOCK outputs.
+
+<p align="center">
+  <img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" />
+  <img src="https://img.shields.io/badge/MCP_Skill-000000?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Pharos_Atlantic-688689-blueviolet?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Tools-27-orange?style=for-the-badge" />
+  <img src="https://img.shields.io/badge/Testnet_Only-SAFE-blue?style=for-the-badge" />
+</p>
+
+> **Testnet only.** SafeHands targets Pharos Atlantic Testnet (Chain ID 688689). Not audited for mainnet use.
+
+---
+
+## Why AI Agents Need This
+
+Generic Web3 tools answer: *"Can this transaction be sent?"*
+SafeHands answers: **"Should this action be allowed at all?"**
+
+| Risk | What goes wrong without SafeHands | SafeHands guardrail |
+|------|----------------------------------|---------------------|
+| Unlimited approval | Agent approves malicious spender forever | Blocked by default |
+| Wrong chain | Agent signs on mainnet by mistake | Blocked |
+| Risky x402 URL | Agent pays a localhost / private IP | Blocked (SSRF guard) |
+| Overspending | Agent drains wallet in one session | Daily cap enforced |
+| Unknown token | Agent swaps unverified contract | Warns, requires review |
+| Missing signer | Agent attempts write without wallet | Structured error returned |
+
+SafeHands is a **Pharos Skill Engine-compatible MCP package** — a composable guardrail layer that any agent can add in front of any action, without modifying existing skill logic.
+
+---
+
+## Getting Started
+
+### Step 1 — Try it now (no setup, no wallet)
+
+```bash
+npx safehands-pharos --demo
+```
+
+Runs 10 live safety checks in your terminal: ALLOW/BLOCK decisions, wallet health, token registry, x402 preflight, risk report. No config, no private key, no transactions.
+
+---
+
+### Step 2 — Connect to your AI agent
+
+Pick **one** depending on how you use AI agents:
+
+#### Claude Desktop
+
+Add to your `claude_desktop_config.json`, then restart Claude Desktop:
+
+```json
+{
+  "mcpServers": {
+    "safehands": {
+      "command": "npx",
+      "args": ["safehands-pharos"]
+    }
+  }
+}
+```
+
+All 27 SafeHands tools appear automatically in every Claude conversation.
+
+#### Anvita Flow
+
+Add as an MCP server in Anvita Flow settings:
+
+```json
+{ "command": "npx", "args": ["safehands-pharos"] }
+```
+
+#### Terminal / scripts (CLI)
+
+Call any tool directly without connecting to an AI client:
+
+```bash
+npx safehands-pharos skill safehands_preflight_check \
+  '{"actionType":"send_payment","chainId":688689,"amount":"0.001","recipient":"0x1234567890123456789012345678901234567890"}'
+```
+
+---
+
+### Step 3 — (Optional) Enable write operations
+
+By default, SafeHands is **read-only**: preflight checks, risk scoring, token registry, wallet health. No private key needed.
+
+To unlock swaps, payments, and approvals, run the setup wizard:
+
+```bash
+npx safehands-pharos init
+```
+
+Or set manually in a `.env` file in your working directory:
+
+```env
+WALLET_MODE=env             # env | managed-testnet
+PRIVATE_KEY=0x...           # testnet key only — never mainnet
+WRITE_TOOLS_ENABLED=true
+MAX_TX_AMOUNT_PHRS=0.1      # per-transaction cap
+MAX_DAILY_SPEND_USD=10      # daily spend cap
+```
+
+---
+
+## Calling Tools from the CLI
+
+```bash
+# Short form (recommended)
+npx safehands-pharos skill <tool> '<json>'
+
+# With flag
+npx safehands-pharos skill <tool> -i '<json>'
+
+# Explicit flag
+npx safehands-pharos skill <tool> --input-json '<json>'
+```
+
+Examples:
+
+```bash
+# Preflight check before a swap
+npx safehands-pharos skill safehands_preflight_check \
+  '{"actionType":"execute_swap","tokenIn":"PHRS","tokenOut":"USDC","amount":"0.01","chainId":688689,"isMainnet":false}'
+
+# Check wallet balance
+npx safehands-pharos skill get_wallet_balance \
+  '{"walletAddress":"0xYourWallet"}'
+
+# Assess risk score
+npx safehands-pharos skill assess_risk \
+  '{"action":"swap","tokenIn":"PHRS","tokenOut":"USDC","amount":"0.01","walletAddress":"0xYourWallet"}'
+
+# Classify a token address
+npx safehands-pharos skill token_registry_status \
+  '{"tokenAddress":"0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8"}'
+```
+
+---
+
+## All 27 Tools
+
+All tools return the same response envelope:
+
+```json
+{
+  "success": true,
+  "data": { ... },
+  "error": null,
+  "timestamp": "2026-06-13T00:00:00.000Z"
+}
+```
+
+On failure: `success: false`, `data: null`, `error: { code, message, retryable }`.
+
+### SafeHands Guardrail Tools
+
+| Tool | What it does | CLI |
+|------|-------------|-----|
+| `safehands_preflight_check` | ALLOW / WARN / BLOCK before any action | ✓ |
+| `safehands_safe_execute` | Preflight + execute in one call | ✓ |
+| `safehands_wallet_health` | Wallet, signer, gas, x402 readiness | ✓ |
+| `safehands_x402_preflight` | URL safety + payment check before x402 | ✓ |
+| `safehands_risk_report` | Human-readable risk summary | ✓ |
+| `explain_risk` | Translate ALLOW/WARN/BLOCK into plain English | ✓ |
+| `token_registry_status` | Canonical / custom / unknown token check | ✓ |
+
+### Safety & Analysis Tools
+
+| Tool | What it does | CLI |
+|------|-------------|-----|
+| `assess_risk` | 5-dimension risk score (0–100) | ✓ |
+| `check_token_security` | GoPlus token security profile | ✓ |
+| `simulate_transaction` | Dry-run before broadcasting | ✓ |
+| `estimate_gas` | Gas estimate + sufficiency check | ✓ |
+| `check_allowance` | ERC-20 allowance check | MCP |
+
+### Market & Chain Data
+
+| Tool | What it does | CLI |
+|------|-------------|-----|
+| `get_wallet_balance` | PHRS / USDC / USDT balances | ✓ |
+| `get_token_price` | Token price via DODO | ✓ |
+| `get_gas_price` | Current network gas price | MCP |
+| `get_pool_info` | FaroSwap / DODO pool info | MCP |
+| `get_transaction_status` | TX status by hash | ✓ |
+| `get_execution_history` | Wallet transfer history (ERC-20 + native) | MCP |
+
+### Write Tools *(require `WRITE_TOOLS_ENABLED=true`)*
+
+| Tool | What it does | CLI |
+|------|-------------|-----|
+| `execute_swap` | Swap tokens via FaroSwap / DODO | MCP |
+| `send_payment` | Send native PHRS | MCP |
+| `approve_token` | ERC-20 approval (unlimited blocked by default) | MCP |
+| `publish_risk_score` | Publish risk score to RiskRegistry contract | MCP |
+| `x402_pay_and_fetch` | Fetch x402 resource, pay only after HTTP 402 | MCP |
+
+### Risk Registry
+
+| Tool | What it does | CLI |
+|------|-------------|-----|
+| `query_risk_registry` | Read on-chain risk score | ✓ |
+
+### Managed Wallet Tools
+
+| Tool | What it does | CLI |
+|------|-------------|-----|
+| `create_agent_wallet` | Create testnet wallet (AES-256-GCM encrypted) | ✓ |
+| `get_agent_wallet` | Wallet address + metadata (no private key) | ✓ |
+| `get_agent_wallet_balance` | Managed wallet balances | ✓ |
+
+> **CLI** = callable via `npx safehands-pharos skill <tool> '<json>'`  
+> **MCP** = available via Claude Desktop / Anvita Flow only
+
+---
+
+## Configuration
+
+If you cloned the repo, copy the example file:
+
+```bash
+cp .env.example .env   # then edit .env with your settings
+```
+
+If you installed via `npx` or `npm install`, create a `.env` in your working directory with these settings:
+
+```env
+# Wallet mode
+WALLET_MODE=none              # none | env | managed-testnet
+PRIVATE_KEY=                  # required when WALLET_MODE=env
+WALLET_STORE_PATH=            # optional: persist managed wallets to disk
+
+# Write gates (all off by default)
+WRITE_TOOLS_ENABLED=false
+ALLOW_UNLIMITED_APPROVAL=false
+
+# Spend limits
+MAX_TX_AMOUNT_PHRS=0.1        # max PHRS per transaction
+MAX_DAILY_SPEND_USD=10        # daily cap across all wallets
+PHRS_USD_PRICE=1.0            # used for daily spend accounting
+
+# DODO API (required for swaps and price data)
+DODO_API_KEY=
+```
+
+### Wallet modes explained
+
+| Mode | How it works |
+|------|-------------|
+| `none` | No signer — read-only tools only (safe default) |
+| `env` | Reads `PRIVATE_KEY` from `.env` |
+| `managed-testnet` | Uses wallet created via `create_agent_wallet` |
+
+### Persistent managed wallets
+
+By default, wallets created with `create_agent_wallet` are in-memory and lost on restart. To persist them:
+
+```env
+WALLET_STORE_PATH=./.agents/wallets.json
+WALLET_ENCRYPTION_KEY=your-strong-secret
+```
+
+Private keys are AES-256-GCM encrypted on disk. The `.agents/` folder is gitignored.
+
+---
+
+## Security Defaults
+
+SafeHands ships safe by default — nothing is enabled without explicit opt-in:
+
+- `WRITE_TOOLS_ENABLED=false` — no on-chain writes without opt-in
+- `WALLET_MODE=none` — no signer loaded on startup
+- Unlimited token approvals blocked
+- Mainnet actions blocked
+- SSRF-sensitive x402 URLs blocked
+- Private keys never returned in responses or logs
+- Daily spend cap enforced in-memory per wallet
+
+---
+
+## x402 Support
+
+SafeHands acts as both an x402 client and server.
+
+**Client** (`x402_pay_and_fetch`): Fetches a resource normally first. If the server returns HTTP 402, SafeHands runs a preflight check, requests the signer, pays, and retries — all in one tool call. Payment proofs are never logged.
+
+**Server** (`npm run x402-server`): Exposes paid endpoints. A live instance runs at:
+
+```
+https://safehands-pharos-production.up.railway.app
+```
+
+| Endpoint | Type | Price |
+|----------|------|-------|
+| `GET /supported` | Free | — |
+| `GET /health` | Free | — |
+| `GET /assess-risk` | Paid | 0.001 USDC |
+| `GET /check-token-security` | Paid | 0.001 USDC |
+| `GET /simulate-transaction` | Paid | 0.001 USDC |
+
+---
+
+## Examples
+
+**Prompt-injection attack scenario** — SafeHands blocking an unlimited token approval triggered by a simulated prompt-injection attack:
+
+```bash
+npx safehands-pharos skill safehands_preflight_check \
+  '{"actionType":"approve_token","chainId":688689,"approvalAmount":"max","spender":"0xBadActor12300000000000000000000000000000"}'
+```
+
+Expected output: `BLOCK` — `"Unlimited approval is blocked by default."`
+
+**Live server** — the SafeHands x402 server runs at:
+
+```
+https://safehands-pharos-production.up.railway.app
+```
+
+Hit `/preflight?actionType=send_payment&amount=0.001&chainId=688689&recipient=0x1234...` for a live ALLOW/WARN/BLOCK response with no setup required.
+
+---
+
+## Network Info
+
+| Item | Value |
+|------|-------|
+| Chain ID | `688689` |
+| RPC | `https://atlantic.dplabs-internal.com` |
+| Explorer | `https://atlantic.pharosscan.xyz` |
+| USDC | `0xE0BE08c77f415F577A1B3A9aD7a1Df1479564ec8` |
+| RiskRegistry | `0x61962a6c812ee9f57b207e1ea47c19ae70bb7141` |
+
+**Proof of life — live on-chain tx:**
+
+| What | Value |
+|------|-------|
+| Action | `publish_risk_score` → RiskRegistry |
+| Tx Hash | [`0x6a58f636...fdefc`](https://atlantic.pharosscan.xyz/tx/0x6a58f636814458c09304db3d7c4f5f48e764f6439649fbb786cddb32c77fdefc) |
+| Block | `24168297` |
+| Gas Used | `140,187` |
+
+---
+
+## Testing
+
+```bash
+npm run build    # compile TypeScript
+npm run demo     # run 10 live safety checks in terminal (no wallet needed)
+npm run dev      # run MCP server in dev mode (tsx, no build step)
+```
+
+For manual testing, use the CLI directly after building:
+
+```bash
+# Build first
+npm run build
+
+# Then call any tool
+node dist/index.js skill safehands_preflight_check \
+  '{"actionType":"approve_token","chainId":688689,"approvalAmount":"max"}'
+```
+
+---
+
+## Known Limitations
+
+- Testnet-only — not audited for mainnet
+- Managed wallet encryption is AES-256-GCM but not KMS/Vault grade
+- `get_token_price` and swap routing require a DODO API key
+- GoPlus token security does not support Pharos testnet (Chain 688689) — `check_token_security` returns a clear error
+- DODO reverse routes (e.g. USDT → PHRS) have no liquidity on testnet
+- x402 client and server are implemented with the official `@x402/fetch` and `@x402/evm` SDKs and verified against a local x402-compatible server. They have not yet been verified against live third-party x402 endpoints on Pharos.
+
+---
+
+## Roadmap
+
+SafeHands is designed to grow from a single-project guardrail into **shared safety infrastructure** for the Pharos agent economy.
+
+**Near-term**
+- **Per-agent spend limits** — a `set_spend_limits` / `get_spend_limits` tool pair so each agent carries its own policy instead of a shared global cap. Stored in the existing AES-256-GCM encrypted wallet store.
+- **x402 live endpoint verification** — validate SafeHands's x402 preflight against production third-party x402 endpoints on Pharos as they become available.
+
+**Medium-term**
+- **Community risk registry** — as more agents publish scores to the on-chain RiskRegistry (`0x61962a6c812ee9f57b207e1ea47c19ae70bb7141`), `query_risk_registry` becomes shared reputation infrastructure. A malicious contract blocked by one agent is flagged for all agents across the ecosystem.
+- **Cross-chain x402 guardrails** — SafeHands's x402 preflight logic is protocol-level, not Pharos-specific. The same guardrail pattern can protect agents making x402 payments on AgentCash (Base / Solana) or any other compatible network.
+
+**Long-term**
+- **Mainnet support** — currently testnet-only by design. Mainnet requires a full re-audit of every safety check, formal verification of the RiskRegistry contract, and KMS/Vault-grade key management before it can be trusted with real funds.
+- **Standardized guardrail interface** — a community spec so any Pharos skill can expose a `preflight(action) → ALLOW | WARN | BLOCK` interface and compose with SafeHands, rather than each skill reinventing safety logic independently.