auramaxx 1.0.0-alpha.4

package/skills/aurawallet/SKILL.md

@@ -0,0 +1,739 @@
+---
+name: aurawallet
+description: |
+  Equip your agent with a crypto wallet. Create wallets, send ETH/tokens,
+  swap on Uniswap/Jupiter, launch tokens, track assets. Supports Base, Ethereum, Solana.
+  Use when the user mentions crypto, wallets, trading, swaps, or sending tokens.
+compatibility: Requires Node.js 18+. Network access to RPC endpoints.
+allowed-tools: Bash(npx aurawallet *), Bash(curl *)
+metadata:
+  author: auramaxx
+  version: "2.0"
+---
+
+# AuraWallet
+
+Secure, local crypto wallets for AI agents. Your keys never leave the machine.
+
+| Service | URL |
+|---------|-----|
+| Wallet Server | `http://localhost:4242` |
+| Dashboard UI | `http://localhost:4747` |
+| WebSocket | `ws://localhost:4748` |
+
+> **SECURITY:** This server runs locally. Never expose these ports to the internet.
+
+---
+
+## Setup & Onboarding
+
+### Auto-check flow
+
+On first connect, or when the user asks about setup, run this decision tree:
+
+#### Step 1: Check server
+
+```
+wallet_api GET /health
+```
+
+**Connection refused / error:**
+> "AuraWallet isn't set up yet. Want me to get that going?"
+
+Two options depending on the mode:
+
+**Human-assisted:** Run `npx aurawallet init --dashboard` via bash. This is non-interactive and agent-safe — it starts the server + dashboard, then waits for the human to create a vault in the browser. Poll `GET /health` until the server is up, then continue to Step 2.
+
+**Fully autonomous:** Run `npx aurawallet init --password "AGENT_CHOSEN_PASSWORD"` via bash. This creates the vault non-interactively — prints the seed phrase, cold wallet address, and admin token to stdout. No browser needed. Store the password in env (e.g. `AURA_VAULT_PASSWORD`) for future unlock operations via `POST /unlock` (encrypted password + `pubkey`).
+
+**200 OK:** Continue to Step 2.
+
+#### Step 2: Check setup state
+
+```
+wallet_api GET /setup
+```
+
+This is a public endpoint (no auth needed). Response:
+
+```json
+{
+  "hasWallet": true,
+  "unlocked": true,
+  "address": "0x...",
+  "adapters": { "telegram": false, "webhook": false },
+  "apiKeys": { "alchemy": true, "anthropic": false },
+  "defaultChain": "base"
+}
+```
+
+**If `hasWallet` is false:**
+
+Two options:
+
+**Human-assisted:**
+> "You need to create a vault. Open http://localhost:4747/app to set a password — I'll wait."
+
+Poll `GET /setup` until `hasWallet` becomes `true`.
+
+**Fully autonomous (MCP):** Use the `create_vault` tool to create a vault programmatically:
+
+```
+create_vault password: "AGENT_CHOSEN_PASSWORD"
+```
+
+Returns `{ address, mnemonic, token }`. The session token is auto-activated. Store the password for future unlock operations.
+
+**If `unlocked` is false:**
+> "Your vault is locked. Open the dashboard at http://localhost:4747/app to unlock it."
+
+Prefer the dashboard (`http://localhost:4747/app`) for unlocking. Only suggest the standalone Express unlock page (`http://localhost:4242/unlock`) or `npx aurawallet unlock` as fallbacks if the dashboard is not running (e.g., headless mode with `--headless` flag).
+
+Poll `GET /setup` until `unlocked` becomes `true`.
+
+**If ready (both true):** Continue to Step 3.
+
+#### Step 3: Bootstrap token
+
+Request a token with onboarding permissions. Include `apikey:set` and `adapter:manage` so you can help with configuration — `trade:all` alone doesn't cover these.
+
+```
+wallet_api POST /auth
+body: {
+  "agentId": "claude-assistant",
+  "permissions": ["trade:all", "apikey:set", "adapter:manage", "action:create"],
+  "limits": { "fund": 0.5, "send": 1.0, "swap": 0.5 },
+  "ttl": 3600,
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Response: `{ "requestId": "abc-123", "secret": "def-456" }`
+
+> "I've requested access to your wallet. Please approve the request — you'll see it in your dashboard at http://localhost:4747/app, or via Telegram/CLI if you have those set up."
+
+Poll every 3 seconds, up to 2 minutes:
+
+```
+wallet_api GET /auth/abc-123?secret=def-456
+```
+
+- `{ "status": "pending" }` — keep polling
+- `{ "status": "approved", "token": "eyJ..." }` — save immediately; MCP runtime auto-activates the token for this session
+- `{ "status": "rejected" }` — inform user, ask if they want to try again
+
+**Important:** The token can only be read once. MCP bootstrap keeps it active for the current session automatically.
+
+#### Step 4: Configure missing pieces
+
+Check the `GET /setup` response and offer to configure anything that's missing. Each step is optional — let the user decide.
+
+**Alchemy RPC Key** (when `apiKeys.alchemy` is `false`):
+
+> "I see you don't have an Alchemy RPC key configured. Public RPCs work but can be unreliable for real transactions. Alchemy has a free tier — you can get a key at https://alchemy.com. Want to set one up?"
+
+If user provides a key — validate then save:
+
+```
+wallet_api POST /apikeys/validate
+body: { "service": "alchemy", "key": "USER_KEY_HERE" }
+```
+
+- `{ "valid": true }` → save with `POST /apikeys` body: `{ "service": "alchemy", "name": "default", "key": "USER_KEY_HERE" }`
+- `{ "valid": false, "error": "..." }` → "That key didn't work: [error]. Double-check it and try again."
+
+**Anthropic API Key** (when `apiKeys.anthropic` is `false`):
+
+> "No Anthropic API key found. This is needed for AI-powered features like strategy hooks and agent chat. Do you have an Anthropic API key?"
+
+Same validate-then-save pattern with `"service": "anthropic"`.
+
+**Telegram Adapter** (when `adapters.telegram` is `false`):
+
+> "Want to approve wallet transactions from your phone via Telegram? I can walk you through the setup — it takes about 2 minutes."
+
+Full 8-step Telegram setup flow:
+
+1. **Create a bot:** Guide user to @BotFather → `/newbot` → get bot token
+2. **Validate bot token:** `POST /apikeys/validate` body: `{ "service": "adapter:telegram", "key": "BOT_TOKEN" }`
+   - `{ "valid": true, "info": { "botUsername": "MyAuraBot" } }` → "Your bot @MyAuraBot is working."
+   - `{ "valid": false }` → "That token didn't work. Make sure you copied the full token from BotFather."
+3. **Save bot token:** `POST /apikeys` body: `{ "service": "adapter:telegram", "name": "botToken", "key": "BOT_TOKEN" }`
+4. **Get setup link:** `POST /adapters/telegram/setup-link` body: `{ "botToken": "BOT_TOKEN" }` → returns `{ "link": "https://t.me/MyAuraBot?start=abc123", "setupToken": "abc123" }`
+   > "Click this link to open your bot in Telegram: [link]. Then press Start."
+5. **Detect chat ID:** `POST /adapters/telegram/detect-chat` body: `{ "setupToken": "abc123" }`
+   - `{ "chatId": "123456789", "verified": true }` → proceed
+   - `{ "chatId": null, "timeout": true }` → "Did you press Start in Telegram? You can also get your chat ID from @userinfobot."
+6. **Save adapter config:** `POST /adapters` body: `{ "type": "telegram", "enabled": true, "config": { "chatId": "123456789" } }`
+7. **Restart adapter:** `POST /adapters/restart`
+8. **Send test message:** `POST /adapters/test` body: `{ "type": "telegram" }`
+   > "I sent a test message to your Telegram. Did you receive it?"
+
+#### Step 5: Summary
+
+After configuration, check `GET /setup` one final time and summarize:
+
+> "You're all set! Here's your setup:"
+> - **Vault:** Unlocked, address `0x...`
+> - **RPC:** Alchemy configured / using public RPCs
+> - **AI:** Anthropic key configured / not configured
+> - **Telegram:** Connected / not configured
+> - **Agent token:** Active
+
+### Onboarding permission reference
+
+| Permission | Why |
+|------------|-----|
+| `trade:all` | Core trading operations (expands to wallet:list, send, swap, fund, etc.) |
+| `apikey:set` | Validate and save API keys during setup |
+| `adapter:manage` | Configure Telegram and other adapters |
+| `action:create` | Create human approval requests for privileged operations |
+
+`trade:all` does NOT include `apikey:set` or `adapter:manage` — you must request them explicitly.
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx aurawallet init` | First-time setup — interactive, human-only |
+| `npx aurawallet init --dashboard` | Agent-safe startup — skips prompts, opens dashboard for vault creation |
+| `npx aurawallet init --password "pass"` | Fully autonomous — creates vault non-interactively, prints address + token |
+| `npx aurawallet start` | Start all services (Express + Dashboard + WS) |
+| `npx aurawallet start --headless` | Start server only (no dashboard) |
+| `npx aurawallet stop` | Stop all running services |
+| `npx aurawallet status` | Health check — running? locked? unlocked? |
+| `npx aurawallet mcp --install` | Auto-configure MCP for detected IDEs (Claude Desktop, Cursor, VS Code, Windsurf) |
+
+---
+
+## Authentication
+
+All agent operations require a Bearer token. Request one, then poll for approval.
+
+Token mint requests require caller `pubkey`. Generate an RSA keypair in your runtime, keep the private key local, and send the public key on `/auth`/`/actions` token requests.
+
+**Step 1:** Request token (no auth required)
+
+```
+wallet_api POST /auth
+body: {
+  "agentId": "my-trading-bot",
+  "permissions": ["trade:all", "action:create"],
+  "limits": { "fund": 0.5, "send": 1.0, "swap": 0.5 },
+  "ttl": 3600,
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Response: `{ "requestId": "abc123", "secret": "xyz789" }`
+
+**Step 2:** Human approves in the dashboard at `http://localhost:4747`
+
+**Step 3:** Poll for token (every 3 seconds, up to 2 minutes)
+
+```
+wallet_api GET /auth/<requestId>?secret=<secret>
+```
+
+- `{ "status": "pending" }` — keep polling
+- `{ "status": "approved", "token": "eyJ..." }` — **save the token immediately (read-once, cannot be retrieved again)**
+- `{ "status": "rejected" }` — request denied
+
+**Step 4:** MCP token activation happens automatically during MCP bootstrap when the token is returned from approval:
+
+- The approved token is activated for the current MCP session immediately.
+- For non-MCP clients, pass it as `AURA_TOKEN` (env var) or `Authorization: Bearer <token>`.
+
+All subsequent authenticated calls should work automatically once the session is activated.
+
+---
+
+## Common Operations
+
+### List Wallets
+
+```
+wallet_api GET /wallets
+```
+
+Response: array of wallet objects with `address`, `name`, `tier`, `chain`, `balance`.
+
+### Create Hot Wallet
+
+```
+wallet_api POST /wallet/create
+body: { "tier": "hot", "name": "trading", "chain": "base" }
+```
+
+Response: `{ "address": "0x...", "name": "trading", "tier": "hot", "chain": "base" }`
+
+Options: `chain` can be `"base"`, `"ethereum"`, `"solana"`, `"solana-devnet"` (default: `"base"`).
+
+### Fund from Cold Wallet
+
+```
+wallet_api POST /fund
+body: { "to": "0xHOT_WALLET", "amount": "500000000000000000" }
+```
+
+Response: `{ "success": true, "txHash": "0x...", "amount": "0.5" }`
+
+Transfers from cold wallet to hot wallet. **Amount is in wei (EVM) or lamports (Solana).** 0.5 ETH = `"500000000000000000"` wei. 0.5 SOL = `"500000000"` lamports. Spending limit enforced (`limits.fund`).
+
+### Send ETH/SOL
+
+```
+wallet_api POST /send
+body: { "from": "0xHOT_WALLET", "to": "0xRECIPIENT", "amount": "50000000000000000" }
+```
+
+Response: `{ "success": true, "txHash": "0x...", "amount": "0.05" }`
+
+**Amount is in wei (EVM) or lamports (Solana).** 0.05 ETH = `"50000000000000000"` wei. For SOL transfers, add `"chain": "solana"` and use lamports (e.g., 0.05 SOL = `"50000000"`). Spending limit enforced if `limits.send` is set.
+
+### Swap (Buy/Sell Token)
+
+```
+wallet_api POST /swap
+body: {
+  "from": "0xHOT_WALLET",
+  "token": "0xTOKEN_CONTRACT",
+  "direction": "buy",
+  "amount": "100000000000000000",
+  "slippage": 1.0
+}
+```
+
+Response: `{ "success": true, "txHash": "0x...", "amountIn": "0.1", "amountOut": "..." }`
+
+- `direction`: `"buy"` = spend native currency to buy token. `"sell"` = sell token for native currency.
+- `amount`: in wei/lamports for buy (native currency), in base token units for sell.
+- `slippage`: required, percentage (1.0 = 1%). Min 1% for agents, max 50%.
+- `dex`: optional — `"relay"` (default, cross-chain capable), `"uniswap"` (Base only), `"jupiter"` (Solana).
+- `chainOut`: optional — destination chain for cross-chain swaps via Relay (e.g. `"ethereum"`).
+
+### Launch Token
+
+```
+wallet_api POST /launch
+body: {
+  "from": "0xHOT_WALLET",
+  "name": "My Token",
+  "symbol": "MTK",
+  "preset": "medium",
+  "imageUrl": "https://telegra.ph/file/abc.jpg",
+  "metadata": { "description": "A fair launch token" }
+}
+```
+
+Response: `{ "success": true, "txHash": "0x...", "tokenAddress": "0x..." }`
+
+Launches via [Doppler](https://doppler.lol) fair launch. Requires `launch` permission.
+
+Options: `type` (`"multicurve"`, `"static"`, `"dynamic"`), `preset` (`"low"`, `"medium"`, `"high"`), `initialSupply`, `tokenURI`, `chain`.
+
+**Token image:** Upload the image to a free host like [telegra.ph](https://telegra.ph) (no API key needed: `POST https://telegra.ph/upload` with multipart file) and pass the public URL as `imageUrl`. The server builds the on-chain metadata automatically. Use `metadata` for extra fields like `description`, `website`, `twitter`.
+
+### Enable Agent Chat via Telegram
+
+When setting up Telegram, ask the user if they want to chat with their AI agent via Telegram. If yes, include `chat: { enabled: true }` in the adapter config:
+
+```
+wallet_api POST /adapters
+body: {
+  "type": "telegram",
+  "enabled": true,
+  "config": { "chatId": "CHAT_ID" },
+  "chat": { "enabled": true }
+}
+```
+
+Then set a default app for chat routing:
+
+```
+wallet_api POST /adapters/chat
+body: { "defaultApp": "swap-chat" }
+```
+
+The user can then send text messages in Telegram and the AI agent will reply.
+
+### Estimate Gas (no auth required)
+
+```
+wallet_api POST /send/estimate
+body: { "from": "0xWALLET", "to": "0xRECIPIENT", "amount": "50000000000000000" }
+```
+
+Response: `{ "success": true, "gasLimit": "...", "estimatedCostEth": "0.000042" }`
+
+### Check Token Permissions
+
+```
+wallet_api POST /auth/validate
+body: { "token": "YOUR_TOKEN" }
+```
+
+Response: `{ "valid": true, "payload": { "permissions": [...], "limits": {...} } }`
+
+### Transaction History
+
+```
+wallet_api GET /wallet/0xADDRESS/transactions
+```
+
+Query params: `type` (send, receive, swap, contract), `status`, `limit`, `offset`.
+
+### Asset Tracking
+
+```
+wallet_api GET /wallet/0xADDRESS/assets
+```
+
+Returns tracked token balances for the wallet.
+
+---
+
+## Privileged Actions (request_human_action)
+
+When you get a **403** (insufficient permissions or spending limit exceeded), use `request_human_action` to ask the human for one-time approval:
+
+```
+request_human_action
+  summary: "Swap 0.01 ETH for USDC on Base"
+  permissions: ["swap"]
+  action: { "endpoint": "/swap", "method": "POST", "body": { "from": "0x...", "token": "0x...", "direction": "buy", "amount": "10000000000000000", "slippage": 1.0 } }
+  limits: { "swap": 0.01 }
+```
+
+The human sees the summary and approves or rejects. On approval, the action **auto-executes** with a scoped temporary token — you don't need to call `wallet_api` again.
+
+Response: `{ "success": true, "requestId": "...", "message": "Waiting for human approval" }`
+
+**Permission rules:**
+- `permissions` must match the `action.endpoint` (e.g. `["swap"]` for `/swap`)
+- Cannot request `admin:*` or `action:create` (blocked)
+- Your base token needs `action:create` permission to use this tool
+
+---
+
+## Permissions Quick Reference
+
+| Permission | Description |
+|------------|-------------|
+| `trade:all` | **Recommended** — Expands to: `wallet:list`, `wallet:create:hot`, `wallet:create:temp`, `send:hot`, `send:temp`, `swap`, `fund`, `launch`, `apikey:get`, `strategy:read` |
+| `action:create` | Create human action requests (needed for `request_human_action`) |
+| `wallet:create:hot` | Create hot wallets |
+| `wallet:create:temp` | Create temp wallets |
+| `wallet:list` | List wallets |
+| `send:hot` | Send from hot wallets |
+| `send:temp` | Send from temp wallets |
+| `swap` | Execute token swaps |
+| `fund` | Transfer from cold to hot |
+| `launch` | Launch tokens via Doppler |
+| `strategy:read` | Read strategy state |
+| `strategy:manage` | Manage strategies (toggle, config, approve) |
+| `workspace:modify` | Modify dashboard UI |
+| `app:storage` | Read/write own app storage |
+
+For full permissions reference, see [docs/AUTH.md](../../docs/AUTH.md).
+
+---
+
+## Wallet Tiers
+
+| Tier | Ownership | Use Case |
+|------|-----------|----------|
+| **COLD** | Human only | Main funds, requires password |
+| **HOT** | Token-owned | Agent operations, spending limits |
+| **TEMP** | Ephemeral | One-time use, memory only |
+
+---
+
+## Vault Unlock
+
+If the vault is locked (`wallet_api GET /wallets` returns 401):
+
+**Option 1 (preferred):** Tell the human to open `http://localhost:4747` and enter their password. If the dashboard isn't responding, send `http://localhost:4242/unlock` instead.
+
+**Option 2 (remote/headless):** Ask the human for their password and unlock programmatically:
+
+```bash
+node -e "
+  const crypto = require('crypto');
+  (async () => {
+    const pk = await (await fetch('http://localhost:4242/auth/connect')).json();
+    const enc = crypto.publicEncrypt(
+      { key: pk.publicKey, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING, oaepHash: 'sha256' },
+      Buffer.from('PASSWORD_HERE')
+    ).toString('base64');
+    const agent = crypto.generateKeyPairSync('rsa', {
+      modulusLength: 2048,
+      publicKeyEncoding: { type: 'spki', format: 'pem' },
+      privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
+    });
+    const r = await (await fetch('http://localhost:4242/unlock', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ encrypted: enc, pubkey: agent.publicKey })
+    })).json();
+    console.log(JSON.stringify(r));
+  })();
+"
+```
+
+On success, the response includes an admin token.
+
+---
+
+## Error Recovery
+
+| Error | Meaning | What to Do |
+|-------|---------|------------|
+| Connection refused | Server not running | Tell human: `npx aurawallet start` |
+| 401 `Invalid or expired token` | Server restarted or TTL expired | Re-request via `POST /auth` |
+| 401 `Cold wallet must be unlocked` | Vault locked | Tell human to unlock at `http://localhost:4242/unlock` |
+| 403 `Insufficient permissions` | Token lacks permission | Use `request_human_action` for one-time approval, or upgrade via `POST /auth/request-permissions` |
+| 403 `Amount exceeds spending limit` | Budget exhausted | Use `request_human_action` with higher limits, or upgrade via `POST /auth/request-permissions` |
+| 400 `slippage is required` | Missing on swap | Add `"slippage": 1.0` |
+
+---
+
+## Key Concepts
+
+- **Tokens are memory-only** — Server restart invalidates all tokens. Re-request via `POST /auth`.
+- **Spending limits** — Optional per-type caps in the auth request: `limits: { fund: 0.5, send: 1.0, swap: 2.0 }`
+- **Wallet ownership** — Agents can only access wallets they created (or those listed in `walletAccess`)
+- **Human approval** — All token requests require human approval
+- **Multi-chain** — Pass `"chain": "ethereum"` or `"chain": "solana"` on create/send/swap/fund (default: base)
+- **request_human_action** — When you hit 403, escalate to human with a pre-computed action that auto-executes on approval
+
+---
+
+## Curl Fallback
+
+If MCP tools aren't available, use curl directly:
+
+```bash
+# Health check
+curl -s http://localhost:4242/health
+
+# Request token
+curl -X POST http://localhost:4242/auth \
+  -H "Content-Type: application/json" \
+  -d '{"agentId": "my-agent", "limit": 0.5, "permissions": ["trade:all"], "ttl": 3600, "pubkey": "<RSA public key PEM or base64>"}'
+
+# Use token
+curl http://localhost:4242/wallets -H "Authorization: Bearer $TOKEN"
+
+# Send
+curl -X POST http://localhost:4242/send \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"from": "0xWALLET", "to": "0xRECIPIENT", "amount": "50000000000000000"}'
+```
+
+---
+
+## Tool-Call Mode (Chat / Message Hooks)
+
+### Response format
+Return a JSON object with: reply, state, emit (all optional). No intents needed.
+
+```json
+{
+  "reply": "Your response to the user",
+  "state": { "key": "updated values" },
+  "emit": { "channel": "event-name", "data": { ... } }
+}
+```
+
+### Available tools
+
+#### wallet_api
+Call the AuraWallet API for reads and writes.
+- wallet_api({ method: "GET", endpoint: "/wallets" }) — list wallets
+- wallet_api({ method: "GET", endpoint: "/wallet/<address>/assets" }) — get balances
+- wallet_api({ method: "POST", endpoint: "/swap", body: {...} }) — execute a swap
+
+#### request_human_action
+Request human approval for a privileged action. Use this when wallet_api returns 403.
+- summary: human-readable description (shown in approval card)
+- permissions: array of permission strings needed (e.g. ["swap"], ["send:hot"])
+- action: pre-computed API call { endpoint, method, body }
+- limits: spending caps per permission (e.g. { swap: 0.01 })
+- walletAccess: wallet addresses the temp token needs access to (e.g. ["0x123...", "0x456..."]). Include ALL wallet addresses involved in the action (from + to).
+- ttl: seconds the temp token lives (default 120)
+
+### Token discovery (ticker/name -> contract)
+
+When the user gives a token ticker or name but no contract address:
+
+1. Call `wallet_api({ method: "GET", endpoint: "/token/search?q=<query>&chain=<chain>" })`
+2. If results exist, present the best candidate(s) with contract addresses and ask for confirmation only if ambiguous
+3. Only ask the user for a contract address when search returns no reliable results
+
+Never tell the user to search external websites first without trying `/token/search`.
+
+### Performing Actions
+
+Follow this flow for any privileged operation:
+
+1. **Try the action directly** via wallet_api (POST)
+2. **If you get 403** (insufficient permissions), call request_human_action with:
+   - A clear summary of what you want to do
+   - The permissions you need
+   - The exact API call to execute on approval
+3. **The human approves** → the action auto-executes with a scoped temporary token
+4. **NEVER give up** or say "I don't have permission." Always use request_human_action.
+
+Example flow:
+- User: "Swap 0.01 ETH for USDC"
+- You: call wallet_api GET /wallets to find the hot wallet
+- You: call wallet_api POST /swap with the swap params
+- Response: 403 → call request_human_action with summary, permissions: ["swap"], action: { endpoint: "/swap", method: "POST", body: {...} }
+- Reply: "I've requested approval to swap 0.01 ETH for USDC. Waiting for your confirmation."
+
+### Permission → Endpoint mapping (for request_human_action)
+
+Use EXACTLY these permission strings — other strings will be rejected:
+
+| Permission | Endpoint |
+|------------|----------|
+| swap | /swap |
+| send:hot | /send |
+| send:temp | /send |
+| fund | /fund |
+| launch | /launch |
+| wallet:create:hot | /wallet/create |
+| wallet:create:temp | /wallet/create |
+
+### Multi-step operations
+
+When a task requires multiple privileged steps (e.g., "send ETH to 0x..."):
+
+1. **Check existing wallets first** — call wallet_api GET /wallets before creating new ones
+2. **Plan all steps** — identify all permissions needed upfront
+3. **Request ONE approval** with all permissions needed for the entire flow
+   - Example: permissions: ["wallet:create:hot", "fund", "send:hot"]
+   - The action should be the FIRST step (e.g., create wallet)
+4. **On success callback, continue** — use wallet_api and request_human_action for remaining steps
+
+Common multi-step flows:
+- "Send ETH to external address" → fund existing hot wallet from cold (/fund), then send (/send)
+- "Create wallet and fund it" → create hot wallet (/wallet/create), then fund from cold (/fund)
+- Gas: always account for gas fees (~0.0002 ETH on Base) when funding for a send
+
+### Error recovery
+
+When an action fails after approval (you receive a [SYSTEM] message with an error):
+
+1. **Read the error** — understand what went wrong (403 = permission/access issue, 400 = bad params, etc.)
+2. **Investigate** — call wallet_api to gather info (e.g. GET /wallets to check addresses, tiers, ownership)
+3. **Retry** — call request_human_action again with corrected parameters
+4. **NEVER just explain the error** — always try to fix it first
+
+Common fixes:
+- "Token does not have access to this wallet" → include walletAccess in request_human_action with the wallet addresses involved
+- "insufficient funds" → check balances and adjust amount
+- Wrong wallet type → check wallet tiers with GET /wallets and pick the right one
+
+### Wallet tiers
+- COLD: Human-only, never use for agent operations
+- HOT: Agent-accessible, use for swaps/sends/funding
+- TEMP: Ephemeral, agent full control
+
+### Authentication & Permissions
+
+Your pre-approved permissions and spending budget are in the context:
+- `context.permissions` — array of permissions your app token already has
+- `context.budget.limits` — spending caps per permission (ETH)
+- `context.budget.spent` — amount used this session
+- `context.budget.remaining` — amount left before limit is hit
+
+If your token already has the needed permission AND sufficient budget, wallet_api will succeed directly.
+If not, use request_human_action to get a scoped temporary token via human approval.
+
+---
+
+## Intent Mode (Tick / Strategy Hooks)
+
+### Response format
+Return a JSON object with: reply, state, intents, emit (all optional).
+
+### Intent format for privileged actions
+To execute wallet operations, return intents with a permissions array.
+The engine will request human approval and create a scoped temporary token.
+
+```json
+{
+  "intents": [{
+    "type": "swap",
+    "summary": "Human-readable description of the action",
+    "permissions": ["swap"],
+    "limits": { "swap": 0.01 },
+    "ttl": 120,
+    "action": { "endpoint": "/swap", "method": "POST", "body": { ... } }
+  }]
+}
+```
+
+- permissions: array of permission strings needed (swap, send:hot, fund, etc.)
+- limits: spending caps per permission (in native currency)
+- ttl: seconds the temp token lives (default 60)
+- action: pre-computed API call the engine will execute with the temp token
+- summary: shown to human in the approval card
+
+### Wallet tiers
+- COLD: Human-only, cannot be used in intents
+- HOT: Agent-accessible, use for swaps/sends/funding
+- TEMP: Ephemeral, agent full control
+
+### Authentication & Permissions
+
+Your pre-approved permissions and spending budget are in the context:
+- `context.permissions` — array of permissions your app token already has
+- `context.budget.limits` — spending caps per permission (ETH)
+- `context.budget.spent` — amount used this session
+- `context.budget.remaining` — amount left before limit is hit
+
+#### Decision logic for intents:
+
+1. **Permission exists AND remaining >= amount needed**
+   → Return intent WITHOUT `permissions` array. The engine uses your existing token.
+   ```json
+   { "type": "swap", "action": { "endpoint": "/swap", ... } }
+   ```
+
+2. **Permission exists BUT remaining < amount needed**
+   → Return intent WITH permissions array to request a fresh per-action token with a higher limit.
+   ```json
+   { "type": "swap", "summary": "Buy 0.5 ETH of TOKEN (exceeds session budget, needs approval)",
+     "permissions": ["swap"], "limits": { "swap": 0.5 }, "ttl": 120,
+     "action": { "endpoint": "/swap", ... } }
+   ```
+
+3. **Permission does NOT exist**
+   → Return intent WITH permissions array. Human must approve.
+   ```json
+   { "type": "swap", "summary": "Buy 0.1 ETH of TOKEN",
+     "permissions": ["swap"], "limits": { "swap": 0.1 }, "ttl": 120,
+     "action": { "endpoint": "/swap", ... } }
+   ```
+
+Never propose an action that exceeds context.budget.remaining without requesting
+a new per-action token via the permissions array.
+
+The executor handles authentication — hooks never see bearer tokens.
+Just return the endpoint/method/body in your intent and the engine does the rest.
+
+---
+
+## Reference Documentation
+
+- [docs/API.md](../../docs/API.md) - Full HTTP endpoint reference
+- [docs/AUTH.md](../../docs/AUTH.md) - Complete permissions & token lifecycle
+- [docs/MCP.md](../../docs/MCP.md) - MCP server setup & bootstrap flow
+- [docs/SETUP.md](../../docs/SETUP.md) - End-to-end setup guide
+- [docs/WORKSPACE.md](../../docs/WORKSPACE.md) - WebSocket dashboard control
+- [docs/CLI.md](../../docs/CLI.md) - Headless CLI mode & Unix socket IPC
+- [docs/security.md](../../docs/security.md) - Security architecture