auramaxx 1.0.0-alpha.4

package/docs/API.md

@@ -0,0 +1,2679 @@
+# Wallet Server API
+
+HTTP REST API for wallet operations. Server runs on `http://localhost:4242`.
+
+---
+
+## Authentication
+
+### Agent Token
+
+Most agent endpoints require a Bearer token in the Authorization header:
+
+```bash
+Authorization: Bearer <token>
+```
+
+Tokens are obtained by requesting `agent_access` and having a human approve it.
+
+---
+
+## Public Endpoints
+
+### Health Check
+
+```http
+GET /health
+```
+
+Returns server status.
+
+### Server Public Key
+
+```http
+GET /auth/connect
+```
+
+Returns the server's ephemeral RSA public key for encrypting passwords (used by `/unlock` and `/setup`).
+
+**Response:**
+```json
+{
+  "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBI..."
+}
+```
+
+### Event Logs
+
+```http
+GET /logs
+```
+
+Returns historical event logs from the database. Supports filtering and pagination.
+
+**Query params:**
+- `type`: Filter by exact event type (e.g., `token:created`)
+- `category`: Filter by category prefix (e.g., `auth` matches `auth:unlocked`, `auth:auth_failed`, etc.)
+- `agentId`: Filter events by agent ID (searches JSON data field)
+- `since`: Start timestamp (ms epoch or ISO string)
+- `until`: End timestamp (ms epoch or ISO string)
+- `limit`: Max results (default 50, max 250)
+- `offset`: Pagination offset
+
+**Response:**
+```json
+{
+  "success": true,
+  "logs": [
+    {
+      "id": "cuid123",
+      "type": "auth:unlocked",
+      "source": "express",
+      "data": "{\"description\":\"Wallet unlocked\"}",
+      "timestamp": "2026-02-01T12:00:00.000Z"
+    }
+  ],
+  "count": 50,
+  "total": 120,
+  "pagination": { "limit": 50, "offset": 0, "hasMore": true }
+}
+```
+
+### ENS Name Resolution
+
+```http
+GET /resolve/:name
+```
+
+Resolves an ENS name (`.eth`) to an Ethereum address. Public endpoint — no authentication required. Uses Ethereum mainnet RPC for ENS resolution.
+
+**Example:**
+```bash
+GET /resolve/vitalik.eth
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "address": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
+  "name": "vitalik.eth"
+}
+```
+
+**Error:**
+```json
+{
+  "error": "Could not resolve: nonexistent.eth"
+}
+```
+
+Only `.eth` names are supported. Solana `.sol` names are out of scope.
+
+### Token Price Lookup
+
+```http
+GET /price/:address?chain=base
+```
+
+Returns USD price for any ERC-20 or SPL token. Public endpoint — no authentication required. Uses a cascading fallback of free APIs: DexScreener → CoinGecko → Alchemy (if configured). Results are cached in memory for 60 seconds.
+
+Use `native` as the address to get the native currency price (ETH or SOL).
+
+**Query params:**
+- `chain` (optional): Chain to look up price on (default: server default chain). Supported: `base`, `ethereum`, `solana`, `polygon`, `arbitrum`, `optimism`
+
+**Example — ERC-20 token:**
+```bash
+GET /price/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913?chain=base
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  "chain": "base",
+  "priceUsd": "0.9998",
+  "source": "dexscreener",
+  "cached": false
+}
+```
+
+**Example — Native currency:**
+```bash
+GET /price/native?chain=base
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "token": "native",
+  "chain": "base",
+  "priceUsd": "3200",
+  "source": "cache",
+  "cached": true
+}
+```
+
+**Error (no price found):**
+```json
+{
+  "success": false,
+  "error": "No price found for 0x... on base"
+}
+```
+
+**Error (invalid address):**
+```json
+{
+  "success": false,
+  "error": "Invalid EVM address format"
+}
+```
+
+### Token Search
+
+```http
+GET /token/search?q=PEPE&chain=base&limit=10
+```
+
+Search for tokens by ticker symbol or name. Returns deduplicated results sorted by liquidity. Uses DexScreener search API with CoinGecko fallback. Results cached for 5 minutes.
+
+**Query parameters:**
+| Param   | Required | Default | Description |
+|---------|----------|---------|-------------|
+| `q`     | Yes      | —       | Search query (ticker, name, or address) |
+| `chain` | No       | —       | Filter to specific chain (`base`, `ethereum`, `solana`, etc.) |
+| `limit` | No       | 10      | Max results (1–50) |
+
+**Response:**
+```json
+{
+  "success": true,
+  "query": "PEPE",
+  "results": [
+    {
+      "address": "0x6982508145454Ce325dDbE47a25d4ec3d2311933",
+      "chain": "ethereum",
+      "symbol": "PEPE",
+      "name": "Pepe",
+      "priceUsd": "0.00001234",
+      "liquidity": 5000000,
+      "volume24h": 12000000,
+      "marketCap": 5200000000,
+      "fdv": 5200000000,
+      "imageUrl": "https://dd.dexscreener.com/ds-data/tokens/ethereum/0x698.png",
+      "websites": ["https://pepe.vip"],
+      "socials": [{ "type": "twitter", "url": "https://twitter.com/pepecoineth" }],
+      "dexId": "uniswap",
+      "pairAddress": "0xA43fe16908251ee70EF74718545e4FE6C5cCEc9f"
+    }
+  ]
+}
+```
+
+**Error (missing query):**
+```json
+{
+  "success": false,
+  "error": "Missing required query parameter: q"
+}
+```
+
+### Token Balance Lookup
+
+```http
+GET /token/:tokenAddress/balance/:walletAddress?chain=base
+```
+
+Returns the on-chain token balance for any wallet address. Works for both registered AuraWallet wallets and arbitrary external addresses. Performs a direct RPC call — no database lookup required.
+
+**Path params:**
+- `tokenAddress` — ERC-20 contract address (EVM) or SPL mint address (Solana)
+- `walletAddress` — Wallet address to check balance for
+
+**Query params:**
+- `chain` (optional): Chain to query (default: server default chain). Supported: `base`, `ethereum`, `solana`, `solana-devnet`
+
+**Example — EVM (ERC-20):**
+```bash
+GET /token/0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913/balance/0x498581ff718922c3f8e6a244956af099b2652b2b?chain=base
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  "walletAddress": "0x498581ff718922c3f8e6a244956af099b2652b2b",
+  "chain": "base",
+  "balance": "1000000",
+  "formatted": "1.0",
+  "decimals": 6,
+  "symbol": "USDC",
+  "name": "USD Coin",
+  "priceUsd": "0.9998",
+  "valueUsd": "1.00"
+}
+```
+
+**Example — Solana (SPL):**
+```bash
+GET /token/EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v/balance/5Gh7s2...?chain=solana
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "tokenAddress": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
+  "walletAddress": "5Gh7s2...",
+  "chain": "solana",
+  "balance": "1000000",
+  "formatted": "1.0",
+  "decimals": 6,
+  "priceUsd": "0.9998",
+  "valueUsd": "1.00"
+}
+```
+
+**Error (invalid address):**
+```json
+{
+  "success": false,
+  "error": "Invalid EVM token address format"
+}
+```
+
+**Error (RPC failure):**
+```json
+{
+  "success": false,
+  "error": "Failed to query token balance from RPC"
+}
+```
+
+### Token Safety Check
+
+```http
+GET /token/safety/:address?chain=ethereum
+```
+
+Returns a safety report for a token contract via GoPlusLabs. Includes honeypot detection, tax analysis, holder data, LP info, and contract red flags. 10-minute cache.
+
+**Query parameters:**
+| Param   | Required | Default    | Description |
+|---------|----------|------------|-------------|
+| `chain` | No       | `ethereum` | Chain name (`ethereum`, `base`, `solana`, `polygon`, `arbitrum`, `optimism`) |
+
+**Response:**
+```json
+{
+  "success": true,
+  "address": "0x6982...",
+  "chain": "ethereum",
+  "safety": {
+    "tokenName": "Pepe",
+    "tokenSymbol": "PEPE",
+    "totalSupply": "420689899653542",
+    "isHoneypot": false,
+    "isMintable": false,
+    "isOpenSource": true,
+    "isProxy": false,
+    "isBlacklisted": false,
+    "buyTax": "0",
+    "sellTax": "0",
+    "holderCount": 513429,
+    "holders": [
+      { "address": "0x...", "balance": "100000000", "percent": "0.05", "isLocked": false, "isContract": true, "tag": "Uniswap V2" }
+    ],
+    "lpHolderCount": 67,
+    "lpHolders": [
+      { "address": "0x...", "balance": "500000", "percent": "0.5", "isLocked": true, "isContract": true }
+    ],
+    "dexInfo": [
+      { "name": "Uniswap V2", "liquidity": "5000000", "pair": "0x..." }
+    ]
+  }
+}
+```
+
+### Token Holders
+
+```http
+GET /token/holders/:address?chain=ethereum
+```
+
+Returns top holders for a token (convenience endpoint — subset of safety data from GoPlusLabs).
+
+**Response:**
+```json
+{
+  "success": true,
+  "address": "0x6982...",
+  "chain": "ethereum",
+  "tokenName": "Pepe",
+  "tokenSymbol": "PEPE",
+  "holderCount": 513429,
+  "holders": [
+    { "address": "0x...", "balance": "100000000", "percent": "0.05", "isLocked": false, "isContract": true, "tag": "Uniswap V2" }
+  ]
+}
+```
+
+### Batch Requests
+
+```http
+POST /batch
+Content-Type: application/json
+```
+
+Executes multiple API calls in a single HTTP request with dependency chaining. Sub-requests within the same wave execute in parallel; waves execute sequentially. Template references (`${id.json.path}`) resolve data from prior responses.
+
+**No auth on the batch endpoint itself** — authentication is enforced per-sub-request via inherited headers from the parent request.
+
+**Request body:**
+
+```json
+{
+  "requests": [
+    {
+      "id": "search",
+      "method": "GET",
+      "path": "/token/search?q=PEPE&limit=1"
+    },
+    {
+      "id": "safety",
+      "method": "GET",
+      "path": "/token/safety/${search.results.0.address}?chain=${search.results.0.chain}",
+      "dependsOn": "search"
+    }
+  ]
+}
+```
+
+**Field reference:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `requests` | array | yes | Array of sub-requests (1–20) |
+| `requests[].id` | string | yes | Unique identifier for this request |
+| `requests[].method` | string | yes | HTTP method: `GET`, `POST`, `PUT`, `DELETE` |
+| `requests[].path` | string | yes | API path including query params. May contain `${id.json.path}` template references |
+| `requests[].body` | object | no | Request body for POST/PUT. String values may contain template references |
+| `requests[].dependsOn` | string | no | ID of a request that must complete before this one executes |
+
+**Template syntax:**
+
+Templates use `${requestId.json.path}` where `json.path` is a dot-separated path into the response body:
+
+| Template | Resolves to |
+|----------|-------------|
+| `${search.results.0.address}` | First search result's address |
+| `${search.results.0.chain}` | First search result's chain |
+| `${wallets.wallets.0.address}` | First wallet's address |
+
+Array elements are accessed by numeric index: `results.0.address`, `results.1.chain`.
+
+**Response (always 200):**
+
+```json
+{
+  "responses": {
+    "search": {
+      "status": 200,
+      "body": { "success": true, "query": "PEPE", "results": [...] }
+    },
+    "safety": {
+      "status": 200,
+      "body": { "success": true, "address": "0x6982...", "safety": { ... } }
+    }
+  },
+  "meta": {
+    "total": 2,
+    "succeeded": 2,
+    "failed": 0,
+    "timings": { "search": 245, "safety": 312 }
+  }
+}
+```
+
+**Error handling:**
+
+| Scenario | Behavior |
+|----------|----------|
+| Invalid request format | `400` on the batch endpoint |
+| Circular dependency | `400` with descriptive error |
+| Unknown `dependsOn` target | `400` with descriptive error |
+| Too many requests (>20) | `400` |
+| Sub-request fails (4xx/5xx) | Other independent sub-requests still execute; dependent ones get `424` |
+| Template reference not found | Sub-request gets `422` |
+| Sub-request timeout (>30s) | Sub-request gets `504`; dependents get `424` |
+
+**Example — search + safety in one call:**
+
+```bash
+curl -X POST http://localhost:4242/batch \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "requests": [
+      { "id": "s", "method": "GET", "path": "/token/search?q=PEPE&limit=1" },
+      { "id": "safety", "method": "GET", "path": "/token/safety/${s.results.0.address}?chain=${s.results.0.chain}", "dependsOn": "s" }
+    ]
+  }'
+```
+
+**Rate limiting:** The batch request counts as 1 request against the general rate limiter. Individual sub-requests do not count against rate limits.
+
+### Setup Status
+
+```http
+GET /setup
+```
+
+Returns setup status including vault state, adapter configuration, and API key availability.
+
+**Response:**
+```json
+{
+  "hasWallet": true,
+  "unlocked": true,
+  "address": "0x...",
+  "adapters": { "telegram": false, "webhook": false },
+  "apiKeys": { "alchemy": true, "anthropic": false },
+  "defaultChain": "base"
+}
+```
+
+### Dashboard Data
+
+```http
+GET /dashboard
+```
+
+Returns pending actions, active tokens, and counts for the UI.
+
+---
+
+## Human Endpoints (Require Unlock)
+
+### Setup Cold Wallet
+
+```http
+POST /setup
+Content-Type: application/json
+
+{
+  "encrypted": "base64...",
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Creates the cold wallet with encrypted password. Only works once. Returns an admin token (vault is auto-unlocked after creation).
+
+**Response:**
+```json
+{
+  "success": true,
+  "address": "0x...",
+  "mnemonic": "word1 word2 ... word12",
+  "token": "eyJ...",
+  "message": "Cold wallet created. SAVE YOUR MNEMONIC SECURELY."
+}
+```
+
+### Change Primary Vault Password
+
+```http
+POST /setup/password
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "currentEncrypted": "base64...",
+  "newEncrypted": "base64..."
+}
+```
+
+Rotates the primary vault password by decrypting with the current password and re-encrypting with the new password.
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Primary vault password updated"
+}
+```
+
+**Errors:**
+- `400` if new password is shorter than 8 characters
+- `401` if current password is invalid
+
+### Unlock Page
+
+```http
+GET /unlock
+```
+
+Returns a self-contained HTML page for unlocking the vault in a browser. The page handles RSA-OAEP password encryption client-side and submits to `POST /unlock`. **This is a fallback for headless environments** where the dashboard (`:4747/app`) isn't running. When the dashboard is available, always direct users to `http://localhost:4747/app` instead — it provides the full UI experience including setup wizard, wallet management, and approval flows.
+
+### Unlock Vault
+
+```http
+POST /unlock
+Content-Type: application/json
+
+{
+  "encrypted": "base64...",
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Unlocks the primary vault for wallet operations.
+
+### Unlock Specific Vault
+
+```http
+POST /unlock/:vaultId
+Content-Type: application/json
+
+{
+  "encrypted": "base64...",
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Unlocks a specific vault by ID. Each vault has its own independent password. Returns:
+
+```json
+{
+  "success": true,
+  "vaultId": "vault-abc123",
+  "address": "0x...",
+  "token": "eyJhZ2VudElkIjoiYWRtaW4i..."
+}
+```
+
+### Lock Vault
+
+```http
+POST /lock
+```
+
+Locks ALL vaults, preventing further operations until unlock.
+
+### Lock Specific Vault
+
+```http
+POST /lock/:vaultId
+```
+
+Locks a specific vault by ID. Requires admin auth.
+
+### Create Additional Vault
+
+```http
+POST /setup/vault
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "encrypted": "base64...",
+  "name": "Trading Vault"
+}
+```
+
+Creates an additional vault with its own encrypted seed. Requires admin auth and an unlocked primary vault.
+
+**Request body:**
+- `encrypted` (required) - RSA-OAEP encrypted password for the new vault
+- `name` (optional) - Human-readable name for the vault
+
+**Response:**
+```json
+{
+  "id": "vault-abc123",
+  "address": "0x...",
+  "solanaAddress": "5Gh7...",
+  "mnemonic": "word1 word2 ... word12",
+  "name": "Trading Vault"
+}
+```
+
+### Import Vault from Seed
+
+```http
+POST /setup/vault/import
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "mnemonic": "word1 word2 ... word12",
+  "encrypted": "base64...",
+  "name": "Imported Vault"
+}
+```
+
+Imports a vault from an existing mnemonic seed phrase. Requires admin auth and an unlocked primary vault.
+
+**Request body:**
+- `mnemonic` (required) - BIP-39 mnemonic seed phrase to import
+- `encrypted` (required) - RSA-OAEP encrypted password for the vault
+- `name` (optional) - Human-readable name for the vault
+
+**Response:**
+```json
+{
+  "id": "vault-def456",
+  "address": "0x...",
+  "solanaAddress": "7Kx9...",
+  "name": "Imported Vault"
+}
+```
+
+### List Vaults
+
+```http
+GET /setup/vaults
+```
+
+Lists all vaults and their status.
+
+**Response:**
+```json
+{
+  "vaults": [
+    {
+      "id": "vault-primary",
+      "name": "Primary",
+      "address": "0x...",
+      "solanaAddress": "5Gh7...",
+      "isUnlocked": true,
+      "isPrimary": true,
+      "createdAt": "2026-01-15T10:00:00.000Z"
+    },
+    {
+      "id": "vault-abc123",
+      "name": "Trading Vault",
+      "address": "0x...",
+      "solanaAddress": "7Kx9...",
+      "isUnlocked": false,
+      "isPrimary": false,
+      "createdAt": "2026-02-01T12:00:00.000Z"
+    }
+  ]
+}
+```
+
+### Export Seed Phrase
+
+```http
+GET /export-seed?vaultId=vault-abc123
+POST /export-seed
+Content-Type: application/json
+
+{
+  "vaultId": "vault-abc123"
+}
+```
+
+Exports the seed phrase for a vault. The `vaultId` parameter is optional; if omitted, exports the primary vault's seed. Requires the targeted vault to be unlocked.
+
+### Create Human Action Request
+
+```http
+POST /actions
+Authorization: Bearer <token-with-action:create>
+Content-Type: application/json
+
+{
+  "summary": "Buy $DOGE2 for 0.005 ETH",
+  "pubkey": "<RSA public key PEM or base64>",
+  "permissions": ["swap"],
+  "limits": { "swap": 0.005 },
+  "walletAccess": ["0x..."],
+  "ttl": 60
+}
+```
+
+Creates a pending action request that requires human approval. On approval, a temporary scoped token is generated with the requested permissions and limits. The caller polls `GET /auth/:requestId?secret=...` to retrieve the token (same as the agent auth flow).
+
+Requires `action:create` permission. Cannot request `admin:*` or `action:create` in the `permissions` array.
+
+**Request body:**
+- `type` (optional) - Request type: `'action'` (default, requires approval) or `'notify'` (notification-only, no approval needed)
+- `summary` (required) - Human-readable description of the action
+- `pubkey` (required for `action` type) - RSA public key used for temp token issuance
+- `permissions` (required for `action` type) - Array of permissions for the temp token
+- `limits` (optional) - Spending limits for the temp token
+- `walletAccess` (optional) - Wallet addresses the temp token can access
+- `ttl` (optional) - Token lifetime in seconds (default: 60)
+- `metadata` (optional) - Arbitrary metadata. Known fields:
+  - `action` (object) - Pre-computed API call `{ endpoint, method, body }`. On approval, this action auto-executes with the scoped temp token and the result is emitted to the app via `action:executed` and `agent:message` channels
+
+**Response:**
+```json
+{
+  "success": true,
+  "requestId": "clx...",
+  "secret": "hex...",
+  "message": "Waiting for human approval"
+}
+```
+
+**Token retrieval:** Poll `GET /auth/:requestId?secret=...` — returns `{ status: "pending" }`, `{ status: "approved", token: "..." }`, or `{ status: "rejected" }`.
+
+#### Notification-Only Mode (`type: 'notify'`)
+
+When `type` is set to `'notify'`, the endpoint creates a dashboard notification without requiring human approval. No permissions, limits, or token are involved. Adapter fan-out (Telegram, webhook) is **opt-in** via the `notify` flag.
+
+```http
+POST /actions
+Authorization: Bearer <token-with-action:create>
+Content-Type: application/json
+
+{
+  "type": "notify",
+  "notify": true,
+  "summary": "$TOKEN — Risk 3/10 — MC $25K",
+  "metadata": {
+    "evaluation": "AI analysis text...",
+    "contractAddress": "0x...",
+    "symbol": "TOKEN",
+    "risk": 3
+  }
+}
+```
+
+**Request body (notify):**
+- `type` (required) - Must be `'notify'`
+- `summary` (required) - Notification text
+- `notify` (optional, default `true`) - When `true`, emits `action:created` to adapters (Telegram, webhook). Set to `false` to create a dashboard-only notification without triggering external adapters.
+- `metadata` (optional) - Arbitrary metadata passed to adapters. Known fields: `evaluation`, `contractAddress`, `symbol`, `name`, `marketCap`, `socialLinks`, `risk`
+
+**Response:**
+```json
+{
+  "success": true,
+  "id": "clx..."
+}
+```
+
+The request is created with `status: 'acknowledged'` (not `'pending'`), so it does not appear in `GET /actions/pending` and cannot be resolved.
+
+### Resolve Action (Primary)
+
+```http
+POST /actions/:id/resolve
+Content-Type: application/json
+
+{
+  "approved": true
+}
+```
+
+Approves or rejects a pending action. For `agent_access` and `permission_update` types, generates a token on approval. Set `approved` to `false` to reject. Supports optional `walletAccess` and `limits` overrides.
+
+### List Pending Actions
+
+```http
+GET /actions/pending
+```
+
+Returns all pending human actions.
+
+### Create Token (Direct)
+
+```http
+POST /actions/token
+Content-Type: application/json
+
+{
+  "agentId": "my-agent",
+  "limit": 0.5,
+  "permissions": ["wallet:create:hot", "send:hot"],
+  "ttl": 3600,
+  "credentialAccess": {
+    "read": ["vault:primary"],
+    "excludeFields": ["password"]
+  },
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Creates a signed agent token directly (admin only).
+
+`pubkey` is required for all token mints.
+
+Profile policy-pack mode is also supported:
+
+```json
+{
+  "agentId": "observer-agent",
+  "profile": "observer",
+  "profileVersion": "v1",
+  "profileOverrides": {
+    "ttlSeconds": 900,
+    "maxReads": 50
+  },
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+In profile mode, `permissions` / `credentialAccess` / `ttl` are resolved from the shared profile resolver, and the response includes `profile`, `effectivePolicyHash`, `overrideDelta`, and `warnings`.
+
+### Request Agent Token (Public Bootstrap)
+
+```http
+POST /auth
+Content-Type: application/json
+
+{
+  "agentId": "my-agent",
+  "permissions": ["wallet:list", "swap", "action:create"],
+  "limits": { "fund": 0.5, "send": 1.0, "swap": 0.5 },
+  "ttl": 3600,
+  "pubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Creates a pending auth request for human approval. Returns `requestId` and `secret` for polling `GET /auth/:requestId?secret=...`.
+
+### List Tokens
+
+```http
+GET /actions/tokens
+```
+
+Lists all agent tokens grouped by status (active, inactive, expired, revoked, depleted).
+
+### Request Permission Upgrade
+
+```http
+POST /auth/request-permissions
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "requestedPermissions": ["swap", "launch"],
+  "requestedWalletAccess": ["0x..."],
+  "requestedLimits": { "swap": 1.0 },
+  "requestedPubkey": "<RSA public key PEM or base64>"
+}
+```
+
+Requests additional permissions, wallet access, or higher spending limits for an existing token. Creates a `permission_update` pending request that requires human approval. On approval, the agent polls `GET /auth/:requestId?secret=...` to retrieve a new token with the upgraded permissions (same flow as initial token request).
+
+Requires a valid agent token. Admin tokens are rejected (already have all permissions).
+
+**Request body** (at least one required):
+- `requestedPermissions` (optional) - Additional permission strings to add
+- `requestedWalletAccess` (optional) - Additional wallet addresses to grant access to
+- `requestedLimits` (optional) - New spending limits (replaces existing limits for specified types)
+- `requestedPubkey` (required) - RSA public key for replacement token issuance
+
+**Response:**
+```json
+{
+  "success": true,
+  "requestId": "clx...",
+  "secret": "hex...",
+  "message": "Permission update request created, waiting for human approval",
+  "currentPermissions": ["trade:all"],
+  "requestedPermissions": ["swap", "launch"],
+  "requestedWalletAccess": ["0x..."],
+  "requestedLimits": { "swap": 1.0 }
+}
+```
+
+**Token retrieval:** Poll `GET /auth/:requestId?secret=...` — same as the initial auth flow.
+
+### Revoke Token
+
+```http
+POST /actions/tokens/revoke
+Content-Type: application/json
+
+{
+  "tokenHash": "abc123..."
+}
+```
+
+Revokes an active agent token. Admins can revoke any token; agents can only revoke their own.
+
+### List Backups
+
+```http
+GET /backup
+Authorization: Bearer <admin-token>
+```
+
+Lists all database backups. Requires admin permission.
+
+### Create Backup
+
+```http
+POST /backup
+Authorization: Bearer <admin-token>
+```
+
+Creates a new database backup. Keeps last 10 backups. Requires admin permission.
+
+### Restore Backup
+
+```http
+PUT /backup
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "filename": "aurawallet.db.20240201_120000.bak"
+}
+```
+
+Restores database from a backup. Requires admin permission.
+
+### Nuke (Reset)
+
+```http
+POST /nuke
+Authorization: Bearer <admin-token>
+```
+
+Resets the wallet database. Requires admin permission. **Destructive — cannot be undone.**
+
+### Import Wallet from Seed
+
+```http
+POST /nuke/import
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "mnemonic": "word1 word2 ... word12",
+  "encrypted": "base64..."
+}
+```
+
+Imports a wallet from an existing mnemonic seed phrase. Supports encrypted password transport (`encrypted`) or plaintext (`password`). Requires admin permission. Password must be at least 8 characters.
+
+---
+
+## Agent Endpoints (Require Bearer Token)
+
+### List Wallets
+
+```http
+GET /wallets
+Authorization: Bearer <token>
+```
+
+Returns all wallets the agent has access to. The response includes separate cold wallet entries per chain (e.g., one for EVM/Base and one for Solana). Each wallet includes a `chain` field and a `balance` field with the native currency balance for that chain (served from cache when available, with RPC fallback). The `balanceUpdatedAt` field indicates when the cached balance was last synced. The response also includes a `vaults` array listing all vaults and their status (see `GET /setup/vaults` for the vault object shape).
+
+### List All Transactions
+
+```http
+GET /wallets/transactions
+Authorization: Bearer <token> (optional)
+```
+
+Returns all transactions across all wallets. Without auth (human), returns all. Agents without `wallet:list` see only transactions for their own wallets. Agents with `wallet:list` see all.
+
+**Query params:**
+- `wallet`: Filter by wallet address
+- `type`: Filter by type (send, receive, swap, contract, manual)
+- `status`: Filter by status (confirmed, pending)
+- `chain`: Filter by chain
+- `token`: Filter by token address
+- `search`: Search description, txHash, from, to
+- `limit`: Max results (default 50, max 250)
+- `offset`: Pagination offset
+- `sortBy`: Sort field (default: createdAt)
+- `sortDir`: Sort direction (asc, desc)
+
+**Response:**
+```json
+{
+  "success": true,
+  "transactions": [
+    {
+      "id": "cuid123",
+      "walletAddress": "0x...",
+      "txHash": "0x...",
+      "type": "swap",
+      "status": "confirmed",
+      "amount": "0.1",
+      "tokenAddress": "0x...",
+      "description": "Bought TOKEN with 0.1 ETH",
+      "chain": "base",
+      "createdAt": "2026-02-01T12:00:00.000Z"
+    }
+  ],
+  "pagination": {
+    "total": 120,
+    "limit": 50,
+    "offset": 0,
+    "hasMore": true
+  }
+}
+```
+
+### Create Wallet
+
+```http
+POST /wallet/create
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "tier": "hot",        // or "temp"
+  "chain": "base",      // Optional: "base", "ethereum", "solana", "solana-devnet" (default: "base")
+  "name": "Trading",
+  "color": "#ff4d00",
+  "emoji": "🔥",
+  "vaultId": "vault-abc123"  // Optional: create under a specific vault (default: primary)
+}
+```
+
+Creates a new hot or temp wallet. When `vaultId` is provided, the wallet is created under the specified vault and its private key is encrypted with that vault's mnemonic. If omitted, the primary vault is used.
+
+### Search Wallets
+
+```http
+GET /wallets/search?q=trading
+Authorization: Bearer <token> (optional)
+```
+
+Searches hot wallets by name or address. Agents with tokens only see their accessible wallets. Includes balance information.
+
+**Query params:**
+- `q` (required): Search query string
+
+**Response:**
+```json
+{
+  "success": true,
+  "wallets": [
+    {
+      "address": "0x...",
+      "name": "Trading",
+      "chain": "base",
+      "tier": "hot",
+      "balance": "500000000000000000"
+    }
+  ]
+}
+```
+
+### Rename/Update Wallet
+
+```http
+POST /wallet/rename
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "address": "0x...",
+  "name": "New Name",
+  "color": "#ff4d00",
+  "emoji": "🔥",
+  "description": "Trading wallet",
+  "hidden": false
+}
+```
+
+Updates hot wallet metadata. Requires `wallet:rename` permission and wallet access. All fields except `address` are optional.
+
+### Export Wallet Private Key
+
+```http
+POST /wallet/:address/export
+Authorization: Bearer <token> (optional)
+```
+
+Exports the private key for a hot wallet. Requires the vault to be unlocked. Agents need `wallet:export` permission and wallet access. Humans (no token) can export when unlocked.
+
+**Response:**
+```json
+{
+  "success": true,
+  "address": "0x...",
+  "privateKey": "0x..."
+}
+```
+
+### Send Transaction
+
+```http
+POST /send
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "0x...",      // Hot wallet address (EVM or Solana base58)
+  "to": "0x...",        // Recipient address or ENS name (e.g. "vitalik.eth")
+  "amount": "100000000000000000",  // Amount in wei (EVM) or lamports (Solana). 0.1 ETH = 100000000000000000 wei, 0.1 SOL = 100000000 lamports.
+  "tokenAddress": "0x...",  // Optional: ERC-20/SPL token contract address for token sends
+  "chain": "base",      // Optional: chain to send on (default: configured default)
+  "description": "..."  // Optional: description for transaction history
+}
+```
+
+Sends native currency or tokens from a hot wallet. Supports both EVM chains (ETH) and Solana (SOL). **Amounts must be in wei (EVM, 18 decimals) or lamports (Solana, 9 decimals).** Send spending limit enforced for agent tokens (if `limits.send` is set). Sends to the cold wallet address bypass the limit (returning funds to vault). Admin tokens bypass all limits.
+
+**ENS resolution**: The `to` field accepts ENS names (e.g., `"vitalik.eth"`). Names are resolved to addresses before processing.
+
+#### ERC-20/SPL Token Send
+
+When `tokenAddress` is provided, the endpoint sends tokens instead of native currency:
+
+```http
+POST /send
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "0x...",
+  "to": "0x...",
+  "amount": "1000000",              // Token amount in raw units (e.g. 1 USDC = 1000000 for 6 decimals)
+  "tokenAddress": "0xA0b86991...",  // ERC-20 contract address (EVM) or SPL mint address (Solana)
+  "chain": "base"
+}
+```
+
+- **EVM**: Encodes ERC-20 `transfer(to, amount)` calldata and sends to the token contract
+- **Solana**: Uses SPL token transfer with automatic ATA creation for the recipient
+- **Spending limits**: Token sends do NOT count against the native currency send limit (tokens are spent, not ETH/SOL)
+- Auto-tracks the token after a successful send
+- Response includes `tokenAddress` and `tokenAmount` instead of `amount`/`value`
+
+#### Raw Solana Transaction
+
+For Solana chains, you can submit a pre-built `VersionedTransaction` instead of a simple transfer. This enables interaction with any Solana program (pump.fun, Tensor, Marinade, Raydium, etc.):
+
+```http
+POST /send
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "5Gh7...",              // Solana hot/temp wallet address
+  "transaction": "base64...",     // Base64-encoded VersionedTransaction
+  "chain": "solana",
+  "to": "ProgramId...",          // Optional: for logging only
+  "description": "Buy on pump.fun bonding curve"  // Optional
+}
+```
+
+When `transaction` is provided:
+- The transaction is deserialized, signed with the wallet's keypair, and submitted
+- `to` and `amount` are not required (the transaction encodes its own instructions)
+- Spending limits are not tracked (value is encoded in instructions, same tradeoff as EVM `data` field)
+- Permission checks (`send:hot`/`send:temp`, wallet access) still apply
+- Response includes `type: "program"` and the transaction is logged as type `contract`
+
+### Estimate Gas
+
+```http
+POST /send/estimate
+Content-Type: application/json
+
+{
+  "from": "0x...",
+  "to": "0x...",
+  "amount": "100000000000000000",
+  "data": "0x...",
+  "chain": "base"
+}
+```
+
+Estimates gas fees for a transaction (EVM only). No authentication required.
+
+**Response:**
+```json
+{
+  "success": true,
+  "gasLimit": "21000",
+  "gasPrice": "1000000000",
+  "maxFeePerGas": "2000000000",
+  "maxPriorityFeePerGas": "1000000",
+  "estimatedCostWei": "42000000000000",
+  "estimatedCostEth": "0.000042"
+}
+```
+
+### Fund Hot Wallet
+
+```http
+POST /fund
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "to": "0x...",        // Hot wallet to fund (EVM or Solana base58)
+  "amount": "1000000000000000000",  // Amount in wei (EVM) or lamports (Solana). 1.0 ETH = 1000000000000000000 wei.
+  "chain": "base"       // Optional: chain to fund on (default: configured default)
+}
+```
+
+Transfers native currency from cold wallet to hot wallet. Supports both EVM (ETH) and Solana (SOL). **Amounts must be in wei (EVM, 18 decimals) or lamports (Solana, 9 decimals).** Spending limit enforced for agent tokens.
+
+### Swap Tokens
+
+```http
+POST /swap
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "0x...",          // Hot wallet address (EVM or Solana base58)
+  "token": "0x...",         // Token contract/mint address
+  "direction": "buy",       // "buy" or "sell"
+  "amount": "100000000000000000",  // Amount in wei (EVM) or lamports (Solana). For buy: native currency amount. For sell: token amount in base units.
+  "slippage": 1,            // Required: slippage tolerance % (e.g. 1.0 for 1%)
+  "minOut": "...",          // Alternative to slippage: explicit minimum output amount (EVM only)
+  "dex": "relay",           // Optional: "relay" (default), "uniswap", or "jupiter" (Solana)
+  "chain": "base",          // Optional: chain to swap on (default: configured default)
+  "chainOut": "ethereum",   // Optional: destination chain for cross-chain swaps (Relay only)
+  "description": "..."      // Optional: description for transaction history
+}
+```
+
+Swaps tokens via DEX. On EVM chains, uses Relay (relay.link) as the default swap provider. Relay is an aggregator that supports all major EVM chains (Base, Ethereum, Arbitrum, Optimism, Polygon, and more). Uniswap is available as a fallback via `dex: "uniswap"` (Base only). On Solana, uses Jupiter aggregator. Creates Transaction record and auto-tracks the swapped token.
+
+**Cross-chain swaps**: Set `chainOut` to a different chain name (e.g., `"ethereum"`) to perform a cross-chain swap via Relay. Cross-chain is only supported with Relay (the default DEX). If `chainOut` is omitted, the swap stays on the origin chain.
+
+**App fee**: Relay swaps include a 1% app fee (Relay retains 25%, AuraWallet retains 75%).
+
+**Slippage protection**: Either `slippage` or `minOut` must be provided. Slippage of 0% is rejected. Minimum floor: 0.5% for admin (manual swaps), 1% for agents (automated). Maximum: 50%.
+
+### Swap Quote (Preview)
+
+```http
+POST /swap/quote
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "0x...",          // Hot wallet address
+  "token": "0x...",         // Token contract/mint address
+  "direction": "buy",       // "buy" or "sell"
+  "amount": "100000000000000000",  // Amount in wei/lamports
+  "slippage": 1,            // Optional: slippage tolerance %
+  "dex": "relay",           // Optional: DEX to quote from
+  "chain": "base",          // Optional: chain
+  "chainOut": "ethereum"    // Optional: destination chain (Relay only)
+}
+```
+
+Returns a swap quote without executing. Same auth and validation as `POST /swap` (requires `swap` permission + wallet access), but no transaction is created and no spending limit is consumed.
+
+**Response (Relay):**
+```json
+{
+  "success": true,
+  "inputAmount": "100000000000000000",
+  "inputFormatted": "0.1",
+  "inputUsd": "350.00",
+  "outputAmount": "350000000",
+  "outputFormatted": "350.0",
+  "outputUsd": "350.00",
+  "rate": "3500.0",
+  "fees": { "gas": { "amount": "21000", "amountUsd": "0.05" } },
+  "slippage": 1,
+  "dex": "relay",
+  "chain": "base"
+}
+```
+
+**Response (Jupiter/Solana):**
+```json
+{
+  "success": true,
+  "inputAmount": "100000000",
+  "outputAmount": "5000000000",
+  "priceImpact": "0.12",
+  "route": [{ "label": "Raydium", "percent": 100, "inAmount": "100000000", "outAmount": "5000000000" }],
+  "slippage": 1,
+  "dex": "jupiter",
+  "chain": "solana"
+}
+```
+
+### List Available DEXes
+
+```http
+GET /swap/dexes
+```
+
+Lists all available DEX adapters and their configurations. No authentication required.
+
+**Response:**
+```json
+{
+  "success": true,
+  "dexes": [
+    { "id": "relay", "name": "Relay", "chains": ["base", "ethereum", "arbitrum", "optimism"] },
+    { "id": "uniswap", "name": "Uniswap", "chains": ["base"] },
+    { "id": "jupiter", "name": "Jupiter", "chains": ["solana"] }
+  ]
+}
+```
+
+### Launch Token
+
+```http
+POST /launch
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "0x...",              // Hot wallet address
+  "name": "My Token",          // Token name
+  "symbol": "MTK",             // Token symbol
+  "tokenURI": "https://...",   // Optional: explicit token metadata URI (overrides imageUrl/metadata)
+  "imageUrl": "https://telegra.ph/file/abc.jpg", // Optional: public image URL for token
+  "metadata": {                // Optional: extra metadata fields (description, website, twitter, etc.)
+    "description": "A fair launch token",
+    "website": "https://example.com"
+  },
+  "type": "multicurve",        // Optional: "static", "dynamic", or "multicurve" (default)
+  "initialSupply": "1000000000", // Optional: total supply (default: 1B)
+  "numTokensToSell": "900000000", // Optional: tokens for sale (default: 90% of supply)
+  "preset": "medium",          // Optional: market cap preset ("low", "medium", "high")
+  "migration": "uniswapV2",    // Optional: "uniswapV2" (default), "uniswapV3", "uniswapV4", "noOp"
+  "vestingDuration": 31536000,  // Optional: vesting period in seconds
+  "startTime": 1707100000,     // Optional: scheduled launch (Unix timestamp, multicurve only)
+  "governance": "default",     // Optional: "default" or "noOp"
+  "beneficiaries": [           // Optional: fee recipients for the launched pool
+    { "address": "0x...", "shares": "0.5" },  // shares in ETH units (0.5 = 50%)
+    { "address": "0x...", "shares": "0.5" }
+  ],
+  "chain": "base",             // Optional: chain (default: configured default)
+  "description": "..."         // Optional: description for transaction history
+}
+```
+
+Launches a new token via the [Doppler protocol](https://doppler.lol) fair launch mechanism. Uses the Doppler SDK to create token auctions on Uniswap. Requires `launch` permission. Creates Transaction record (type: 'launch') and auto-tracks the launched token.
+
+**Auction types:**
+- `multicurve` (default): Multicurve initializer using Uniswap V4, supports market cap presets and scheduled launches
+- `static`: Fixed price range using Uniswap V3, ideal for simple price discovery
+- `dynamic`: Gradual Dutch auction using Uniswap V4 hooks
+
+**Market cap presets** (multicurve only): `low` (~$7.5k-$30k), `medium` (~$50k-$150k), `high` (~$250k-$750k).
+
+**Beneficiaries** (optional): Array of `{ address, shares }` specifying fee recipients for the launched pool. Shares are in ETH units (e.g. `"0.5"` = 50%, shares must sum to `"1.0"` = 100%). Supported on multicurve and static auction types. Ignored on dynamic auctions (SDK limitation).
+
+**Token metadata:** If `tokenURI` is not provided but `imageUrl` or `metadata` is, the server auto-builds a metadata JSON from name, symbol, imageUrl, and any extra metadata fields, then encodes it as a `data:application/json;base64,...` data URI for the on-chain tokenURI. The agent is responsible for hosting the image at a publicly accessible URL (e.g. upload to [telegra.ph](https://telegra.ph) which requires no API key or signup). If `tokenURI` is explicitly provided, it takes precedence.
+
+**Supported chains:** Base, Ethereum, Ink, Unichain (any chain supported by Doppler protocol).
+
+### Collect Fees (Single Token)
+
+```http
+POST /launch/:tokenAddress/collect-fees
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "0x...",    // Wallet address to pay gas
+  "chain": "base"     // Optional: chain (default: configured default)
+}
+```
+
+Collects accumulated trading fees from a Doppler multicurve pool and distributes them to the configured beneficiaries. The `collectFees` call is permissionless on-chain — anyone can trigger it, but fees always go to the beneficiary addresses configured at launch time. The caller only pays gas. No `launch` permission required, only valid auth token and wallet access for the gas-paying wallet.
+
+**Response:**
+```json
+{
+  "success": true,
+  "tokenAddress": "0x...",
+  "fees0": "1234567890",
+  "fees1": "9876543210",
+  "transactionHash": "0x...",
+  "chain": "base"
+}
+```
+
+### Collect Fees (All Launched Tokens)
+
+```http
+POST /launch/collect-fees
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "from": "0x...",    // Wallet address to pay gas
+  "chain": "base"     // Optional: chain (default: configured default)
+}
+```
+
+Collects fees from ALL tokens previously launched via AuraWallet on the specified chain. Iterates over all `launch` transactions in the database and calls `collectFees()` on each. Individual failures are reported per-token without failing the entire request. Same permissionless semantics as the single-token endpoint.
+
+**Response:**
+```json
+{
+  "success": true,
+  "chain": "base",
+  "total": 5,
+  "collected": 4,
+  "failed": 1,
+  "results": [
+    { "tokenAddress": "0x...", "success": true, "fees0": "...", "fees1": "...", "transactionHash": "0x..." },
+    { "tokenAddress": "0x...", "success": false, "error": "Pool not found" }
+  ]
+}
+```
+
+---
+
+## Wallet Data Endpoints
+
+### List Transactions
+
+```http
+GET /wallet/:address/transactions
+Authorization: Bearer <token> (optional for own wallets, not required for external)
+```
+
+**Two modes:**
+
+1. **DB path** (our wallets): When the address belongs to a HotWallet in our DB, returns transaction records from the database. Response includes `"source": "db"`.
+
+2. **On-chain fallback** (external addresses): When the address is not in our HotWallet table, fetches events from the chain via `eth_getLogs` (EVM) or `getSignaturesForAddress` (Solana). No auth required. Response includes `"source": "on-chain"`, `chain`, and `blockRange`.
+
+**DB path query params:**
+- `type`: Filter by type (send, receive, swap, contract, manual)
+- `status`: Filter by status (confirmed, pending)
+- `token`: Filter by token address
+- `search`: Search description, txHash, from, to
+- `limit`: Max results (default 50, max 250)
+- `offset`: Pagination offset
+- `sortBy`: Sort field (default: createdAt)
+- `sortDir`: Sort direction (asc, desc)
+
+**On-chain path query params:**
+- `chain`: Chain to query (default: base). Use `solana` or `solana-devnet` for Solana.
+- `limit`: Max results (1-100, default: 20)
+- `types`: Comma-separated event type filter (transfer, swap, swap_v2, swap_v3, swap_v4, approval, wrap)
+- `token`: Token contract address — when set, queries logs emitted BY the token contract (using the `address` field in `eth_getLogs`) instead of topic-based wallet matching. Useful for fetching all Transfer events for a specific token.
+- `fromBlock`: Start block (default: latest - 10000). EVM only.
+- `toBlock`: End block (default: latest). EVM only.
+
+**V4 swap auto-correlation:** For wallet-level queries (no `token` param), the fetcher automatically discovers Uniswap V4 Swap events. V4 Swap topics don't contain the wallet address (topic1 = poolId, topic2 = Universal Router), so the fetcher looks for Transfer events without matching swaps ("orphan transfers") and queries the V4 PoolManager at those blocks to find correlated V4 Swap events sharing the same txHash.
+
+**On-chain response format:**
+```json
+{
+  "success": true,
+  "source": "on-chain",
+  "chain": "base",
+  "blockRange": { "from": "90000", "to": "100000" },
+  "transactions": [
+    {
+      "type": "transfer",
+      "summary": "Received 500 USDC from 0x1234...abcd",
+      "txHash": "0x...",
+      "blockNumber": "99500",
+      "timestamp": 1700000000,
+      "details": { "from": "0x...", "to": "0x...", "amount": "500", "symbol": "USDC", "direction": "in" }
+    }
+  ],
+  "pagination": { "total": 42, "limit": 20, "returned": 20 }
+}
+```
+
+Supported event types: Transfer (ERC-20/721), Swap (Uniswap V2/V3/V4), WETH Wrap/Unwrap, Approval. Note: native ETH transfers are not visible via `eth_getLogs`.
+
+### Add Transaction
+
+```http
+POST /wallet/:address/transactions
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "type": "manual",         // send, receive, swap, contract, manual
+  "txHash": "0x...",        // Optional
+  "amount": "0.5",          // Optional: ETH amount
+  "tokenAddress": "0x...",  // Optional: token contract
+  "tokenAmount": "...",     // Optional: token amount
+  "from": "0x...",          // Optional
+  "to": "0x...",            // Optional
+  "description": "...",     // Optional
+  "executedAt": "..."       // Optional: ISO timestamp
+}
+```
+
+Requires `wallet:tx:add` permission.
+
+### List Tracked Assets
+
+```http
+GET /wallet/:address/assets
+Authorization: Bearer <token> (optional)
+```
+
+Returns tracked assets for a wallet with USD pricing. Each asset includes `priceUsd` (current token price) and `valueUsd` (balance × price) when price data is available. Prices are fetched via the same cascading fallback as `GET /price/:address` (DexScreener → CoinGecko → Alchemy).
+
+Query params:
+- `search`: Search symbol, name, or address
+- `includeHidden`: Include hidden assets (default: false)
+- `limit`, `offset`, `sortBy`, `sortDir`: Pagination/sorting
+
+### Add Tracked Asset
+
+```http
+POST /wallet/:address/asset
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "tokenAddress": "0x...",  // Required
+  "symbol": "TKN",          // Optional
+  "name": "Token Name",     // Optional
+  "decimals": 18,           // Optional (default: 18)
+  "chain": "base",          // Optional (default: base)
+  "isHidden": false         // Optional
+}
+```
+
+Requires `wallet:asset:add` permission. Upserts if token already tracked.
+
+### Portfolio Overview
+
+```http
+GET /portfolio
+Authorization: Bearer <token> (optional)
+```
+
+Returns an aggregated portfolio view across all wallets. Native balances are grouped by chain, token balances are grouped by token address. Includes cached ETH/SOL USD prices and per-token USD values.
+
+Agents with tokens need `wallet:list` permission to see all wallets. Without auth (human), returns all.
+
+**Query params:**
+- `token` — Filter by token contract address. Returns only that token's aggregated balance plus a `wallets` array with per-wallet breakdown.
+- `symbol` — Filter by token symbol (case-insensitive). Same behavior as `token` filter.
+- `chain` — Filter by chain name (e.g., `base`, `ethereum`, `solana`). Applies to both native and token balances.
+
+**Example — filter by token:**
+```bash
+GET /portfolio?token=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "byChain": [
+    { "chain": "base", "totalBalance": 4.0, "walletCount": 2, "valueUsd": "12002.00" },
+    { "chain": "ethereum", "totalBalance": 10.0, "walletCount": 1, "valueUsd": "30005.00" }
+  ],
+  "byToken": [
+    {
+      "tokenAddress": "0xaaa...",
+      "chain": "base",
+      "symbol": "TKN",
+      "name": "Test Token",
+      "totalBalance": 300.75,
+      "walletCount": 2,
+      "priceUsd": "1.00",
+      "valueUsd": "300.75"
+    }
+  ],
+  "prices": { "ETH": 3000.50, "SOL": 150.25 },
+  "totalValueUsd": "42307.75"
+}
+```
+
+**Response with `token` or `symbol` filter** (includes per-wallet breakdown):
+```json
+{
+  "success": true,
+  "byChain": [],
+  "byToken": [
+    {
+      "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+      "chain": "base",
+      "symbol": "USDC",
+      "name": "USD Coin",
+      "totalBalance": 800.0,
+      "walletCount": 2,
+      "priceUsd": "1.00",
+      "valueUsd": "800.00"
+    }
+  ],
+  "wallets": [
+    { "walletAddress": "0xaaa...", "chain": "base", "balance": 500, "valueUsd": "500.00" },
+    { "walletAddress": "0xbbb...", "chain": "base", "balance": 300, "valueUsd": "300.00" }
+  ],
+  "prices": { "ETH": 3000.50, "SOL": 150.25 },
+  "totalValueUsd": "800.00"
+}
+```
+
+### Remove Tracked Asset
+
+```http
+DELETE /wallet/:address/asset/:assetId
+Authorization: Bearer <token>
+```
+
+Removes a tracked asset from the wallet. Requires `wallet:asset:remove` permission.
+
+Emits `asset:changed` event with `removed: true`.
+
+---
+
+## Address Book
+
+Label external addresses with nicknames, emojis, and colors.
+
+### List Address Labels
+
+```
+GET /address-labels?q=search_term
+```
+
+Returns all labels, optionally filtered by search query (matches label or address).
+
+### Create/Update Address Label
+
+```
+POST /address-labels
+{
+  "address": "0x1234...",
+  "label": "Vitalik",
+  "emoji": "🦄",        // optional
+  "color": "#FF5733",   // optional
+  "notes": "ETH co-founder"  // optional
+}
+```
+
+Requires `addressbook:write` permission. Upserts by address (lowercased).
+
+`createdBy` is auto-set: `"human"` for admin tokens, agent ID for agent tokens.
+
+### Delete Address Label
+
+```
+DELETE /address-labels/:id
+```
+
+Requires `addressbook:write` permission.
+
+---
+
+## Bookmarks (Token Watchlist)
+
+Bookmark tokens without owning them. Creates a `TrackedAsset` row with `walletAddress: null`.
+
+### List Bookmarks
+
+```
+GET /bookmarks?chain=base&q=search_term
+```
+
+Returns all bookmarks, enriched with `TokenMetadata` when available.
+
+### Create Bookmark
+
+```
+POST /bookmarks
+{
+  "tokenAddress": "0xabcd...",
+  "chain": "base"        // optional, defaults to "base"
+}
+```
+
+Requires `bookmark:write` permission. Idempotent — re-creating the same bookmark is a no-op. Seeds `TokenMetadata` cache on creation.
+
+### Delete Bookmark
+
+```
+DELETE /bookmarks/:id
+```
+
+Requires `bookmark:write` permission. Only deletes bookmarks (null walletAddress), not wallet-tracked assets.
+
+---
+
+## System Defaults (Admin Only)
+
+Centralized management of system-wide defaults (limits, permissions, TTLs, rate limits, etc.).
+
+All endpoints require `admin:*` permission.
+
+### List Defaults
+
+```http
+GET /defaults
+Authorization: Bearer <admin-token>
+```
+
+Returns all defaults grouped by type.
+
+**Response:**
+```json
+{
+  "success": true,
+  "defaults": {
+    "financial": [
+      { "key": "limits.fund", "value": 0.1, "type": "financial", "label": "Default Fund Limit (ETH)", "description": "...", "updatedAt": "..." }
+    ],
+    "permissions": [...],
+    "ttl": [...],
+    "rate_limit": [...],
+    "swap": [...],
+    "ai_safety": [...],
+    "launch": [...],
+    "app": [...]
+  }
+}
+```
+
+### Update Default
+
+```http
+PATCH /defaults/:key
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{ "value": 0.05 }
+```
+
+Updates a single default value. Validates type against seed definition.
+
+**Response:**
+```json
+{ "success": true, "key": "limits.fund", "value": 0.05 }
+```
+
+### Reset Default
+
+```http
+POST /defaults/reset
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{ "key": "limits.fund" }
+```
+
+Resets a single key to its seed value. Use `"key": "*"` to reset all defaults.
+
+**Response:**
+```json
+{ "success": true, "key": "limits.fund", "reset": true }
+```
+
+---
+
+## Configuration Endpoints (Require Auth)
+
+### Credential Vault Management (Admin)
+
+#### List Credential Vaults
+
+```http
+GET /vaults/credential
+Authorization: Bearer <admin-token>
+```
+
+Returns wallet vaults with credential unlock status and credential counts.
+
+#### Create Credential Vault
+
+```http
+POST /vaults/credential
+Authorization: Bearer <admin-token>
+Content-Type: application/json
+
+{
+  "encrypted": "<rsa-oaep password>",
+  "name": "work"
+}
+```
+
+Creates an additional vault and unlocks it.
+
+#### Lock Credential Vault
+
+```http
+POST /vaults/credential/:id/lock
+Authorization: Bearer <admin-token>
+```
+
+Locks the vault and clears credential subkeys from memory.
+
+#### Delete Credential Vault
+
+```http
+DELETE /vaults/credential/:id
+Authorization: Bearer <admin-token>
+```
+
+Deletes the vault and all credentials assigned to it.
+
+### Credential Management
+
+#### List Credentials (Metadata)
+
+```http
+GET /credentials?vault=<id>&type=<type>&tag=<tag>&q=<query>
+Authorization: Bearer <token>
+```
+
+Requires `secret:read` (or `admin:*`). Results are scope-filtered by `credentialAccess.read`.
+
+#### Create Credential
+
+```http
+POST /credentials
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "vaultId": "primary",
+  "type": "login",
+  "name": "GitHub",
+  "meta": { "tags": ["deploy"] },
+  "fields": [
+    { "key": "username", "value": "alice", "type": "text", "sensitive": false },
+    { "key": "password", "value": "hunter2", "type": "secret", "sensitive": true }
+  ]
+}
+```
+
+Requires `secret:write` (or `admin:*`) and matching write scope.
+
+#### Read Credential (Encrypted Response)
+
+```http
+POST /credentials/:id/read
+Authorization: Bearer <token>
+```
+
+Requires `secret:read` (or `admin:*`), matching read scope, and `agentPubkey` on the token.  
+Enforces `credentialAccess.ttl` and `credentialAccess.maxReads`.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "credentialId": "cred-abc123",
+  "encrypted": "<base64 ciphertext>"
+}
+```
+
+`encrypted` may be direct RSA-OAEP ciphertext (small payloads) or a base64-encoded hybrid envelope (RSA-wrapped AES key + AES-GCM data) for larger payloads.
+
+### API Key Management
+
+#### List API Keys
+
+```http
+GET /apikeys
+Authorization: Bearer <token>
+```
+
+Permission: `apikey:get` (or `trade:all`)
+
+Returns masked API key entries served from credential vault storage (`type: "apikey"`).
+
+#### Create/Update API Key
+
+```http
+POST /apikeys
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "service": "alchemy",
+  "name": "default",
+  "key": "your-api-key"
+}
+```
+
+Permission: `apikey:set`
+
+Upserts by `service` + `name` composite key.
+The value is stored in credential vault as an encrypted `apikey` credential (legacy DB row is kept in sync for compatibility).
+
+#### Validate API Key
+
+```http
+POST /apikeys/validate
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "service": "alchemy",
+  "key": "your-api-key"
+}
+```
+
+Permission: `apikey:set`
+
+Validates an API key against its external service before saving. All validation calls have a 5-second timeout.
+
+**Supported services:**
+
+| Service | Validation | Success Info |
+|---------|-----------|--------------|
+| `alchemy` | `eth_blockNumber` JSON-RPC call | — |
+| `anthropic` | Minimal Messages API request (200 or 429 = valid) | — |
+| `openai` | OpenAI Models API (200 = valid) | — |
+| `adapter:telegram` | Telegram Bot API `getMe` | `{ botUsername }` |
+
+**Response:**
+```json
+{ "valid": true, "info": { "botUsername": "MyBot" } }
+```
+
+```json
+{ "valid": false, "error": "Invalid API key" }
+```
+
+#### Delete API Key
+
+```http
+DELETE /apikeys/:id
+Authorization: Bearer <token>
+```
+
+Permission: `apikey:set`
+
+Soft-deletes by setting `isActive = false`.
+
+### Adapter Management
+
+#### List Adapters
+
+```http
+GET /adapters
+Authorization: Bearer <token>
+```
+
+Permission: `adapter:manage`
+
+Returns configured adapters with secret status and running state.
+
+#### Save Adapter Config
+
+```http
+POST /adapters
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "type": "telegram",
+  "enabled": true,
+  "config": { "chatId": "123456789" }
+}
+```
+
+Permission: `adapter:manage`
+
+#### Test Adapter
+
+```http
+POST /adapters/test
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "type": "telegram"
+}
+```
+
+Permission: `adapter:manage`
+
+Sends a test message through a configured adapter. Returns 404 if the adapter's required config (bot token, chat ID, webhook URL) is not configured.
+
+**Supported types:**
+
+| Type | Behavior |
+|------|----------|
+| `telegram` | Sends test message via Telegram Bot API `sendMessage` |
+| `webhook` | POSTs `{ type: "test", data: {}, timestamp }` to webhook URL |
+
+**Response:**
+```json
+{ "success": true }
+```
+
+```json
+{ "success": false, "error": "Failed to send test message" }
+```
+
+#### Update Chat Config
+
+```http
+POST /adapters/chat
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "defaultApp": "swap-chat"
+}
+```
+
+Permission: `adapter:manage`
+
+Sets the default app for adapter chat routing. The `defaultApp` determines which app's AI handles incoming chat messages from adapters.
+
+**Response:**
+```json
+{ "success": true, "chat": { "defaultApp": "swap-chat" } }
+```
+
+#### Send Chat Message (Webhook Inbound)
+
+```http
+POST /adapters/:type/message
+Content-Type: application/json
+X-Signature-256: sha256=<hmac>
+
+{
+  "text": "What is my balance?",
+  "senderId": "user-123",
+  "targetApp": "swap-chat"
+}
+```
+
+Inbound chat endpoint for adapter webhooks. Routes the message to the target app's AI via `handleAppMessage()`.
+
+**Authentication:** HMAC-SHA256 signature required if the adapter has a secret stored (`POST /apikeys` with `service: "adapter:<type>"`). Uses the same `X-Signature-256` header format as webhook notifications.
+
+**Request body:**
+- `text` (required) - Message text
+- `senderId` (required) - Sender identifier
+- `targetApp` (optional) - Explicit app target. If omitted, uses `chat.defaultApp` from adapter config.
+
+**Response:**
+```json
+{
+  "success": true,
+  "reply": "You have 1.5 ETH in your hot wallet.",
+  "error": null
+}
+```
+
+#### Restart Adapters
+
+```http
+POST /adapters/restart
+Authorization: Bearer <token>
+```
+
+Permission: `adapter:manage`
+
+Restarts the approval router with current DB config.
+
+#### Delete Adapter
+
+```http
+DELETE /adapters/:type
+Authorization: Bearer <token>
+```
+
+Permission: `adapter:manage`
+
+---
+
+## Request Types
+
+When agents call endpoints that require approval:
+
+| Type | Trigger | What Happens |
+|------|---------|--------------|
+| `agent_access` | Agent requests token | Human approves → Token generated |
+| `fund` | `/fund` endpoint | If over limit → Pending approval |
+| `send` | `/send` endpoint | Send limit enforced (if `limits.send` set). Cold wallet returns bypass limit |
+| `launch` | `/launch` endpoint | Launch limit enforced (if `limits.launch` set) |
+
+---
+
+## WebSocket Events
+
+The wallet server broadcasts events to `ws://localhost:4748`:
+
+| Event | Description |
+|-------|-------------|
+| `token:created` | New agent token issued |
+| `token:revoked` | Token was revoked |
+| `token:spent` | Token spending updated |
+| `vault:unlocked` | Vault was unlocked |
+| `action:created` | New human action pending |
+| `action:resolved` | Human action approved/rejected |
+| `wallet:created` | New wallet created |
+| `wallet:changed` | Wallet data updated |
+| `asset:changed` | Token asset tracked or pool info updated |
+| `tx:created` | New transaction recorded |
+| `balance:updated` | Cached balance synced (from cron server) |
+
+### asset:changed Event
+
+Emitted when:
+- A new token is tracked for a wallet
+- Pool detection discovers DEX pool info
+- An asset is removed (`removed: true`)
+
+```json
+{
+  "type": "asset:changed",
+  "timestamp": 1707052800000,
+  "source": "express",
+  "data": {
+    "walletAddress": "0x123...",
+    "tokenAddress": "0xabc...",
+    "symbol": "TOKEN",
+    "name": "My Token",
+    "poolAddress": "0xdef...",
+    "poolVersion": "v3",
+    "removed": false
+  }
+}
+```
+
+### tx:created Event
+
+Emitted when:
+- A send transaction is recorded
+- A swap transaction is recorded
+- A manual transaction is added
+
+```json
+{
+  "type": "tx:created",
+  "timestamp": 1707052800000,
+  "source": "express",
+  "data": {
+    "walletAddress": "0x123...",
+    "id": "cuid123",
+    "type": "swap",
+    "txHash": "0x789...",
+    "amount": "0.1",
+    "tokenAddress": "0xabc...",
+    "description": "Bought TOKEN with 0.1 ETH"
+  }
+}
+```
+
+---
+
+## AI Status (Admin Only)
+
+### Get AI Provider Status
+
+```http
+GET /ai/status
+Authorization: Bearer <admin-token>
+```
+
+Returns the active AI provider, default model, and availability status of all providers. Used by the SystemDefaultsApp to populate the AI Engine settings.
+
+**Response:**
+```json
+{
+  "activeProvider": "claude-cli",
+  "defaultModel": "sonnet",
+  "providers": [
+    { "mode": "claude-cli", "label": "Claude Max (CLI)", "available": true, "reason": "claude CLI found in PATH", "models": ["haiku", "sonnet", "opus"] },
+    { "mode": "claude-api", "label": "Claude API Key", "available": false, "reason": "No Anthropic API key configured", "models": ["haiku", "sonnet", "opus"] },
+    { "mode": "codex-cli", "label": "Codex Max (CLI)", "available": false, "reason": "codex CLI not found in PATH", "models": ["codex-mini", "codex", "codex-max"] },
+    { "mode": "openai-api", "label": "OpenAI API Key", "available": false, "reason": "No OpenAI API key configured", "models": ["codex-mini", "codex", "codex-max"] }
+  ]
+}
+```
+
+Provider/model selection is configured via the system defaults `ai.provider` and `ai.default_model` (use `PATCH /defaults/:key`).
+
+---
+
+## Strategy Endpoints
+
+Strategy endpoints manage strategy templates, creation, install, lifecycle, config/state, and approvals.
+All endpoints are mounted at `/strategies`.
+
+### List Strategies
+
+```http
+GET /strategies
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:read`
+
+Returns DB-backed strategies with current runtime/status metadata.
+
+**Response:**
+```json
+{
+  "success": true,
+  "strategies": [
+    {
+      "id": "strategy-123",
+      "name": "ETH DCA Daily",
+      "enabled": true,
+      "running": false,
+      "ticker": "maintenance",
+      "lastTick": 1760000000000,
+      "lastError": null,
+      "errorCount": 0
+    }
+  ]
+}
+```
+
+### List Strategy Templates
+
+```http
+GET /strategies/templates
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:read`
+
+Returns the v1 template catalog (`recurring_buy`, `buy_on_drop`, `stop_loss`, `portfolio_report`).
+
+### Create Template Strategy
+
+```http
+POST /strategies
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "template": "recurring_buy",
+  "name": "Buy $100 BNKR Daily",
+  "mode": "headless",
+  "config": {
+    "chain": "base",
+    "wallet": "0x1111111111111111111111111111111111111111",
+    "token": "0x2222222222222222222222222222222222222222",
+    "amountUsd": "100"
+  },
+  "enabled": false
+}
+```
+
+Permission: `strategy:manage`
+
+Creates a DB-backed strategy from a supported template. `permissions`/`limits` overrides are rejected for template strategies.
+
+### Install Third-Party Strategy
+
+```http
+POST /strategies/install
+Authorization: Bearer <token>
+Content-Type: application/json
+```
+
+Permission: `strategy:manage`
+
+Provide exactly one of:
+- `source`: local path / git / tarball / zip source
+- `manifest`: inline strategy manifest
+
+Supports `enabled`, `mode`, `config`, `name`, and `approve` flags. Third-party strategies with permissions/limits require explicit install approval before enable.
+
+### Strategy Runtime Health
+
+```http
+GET /strategies/health
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:read`
+
+Returns cron runtime health for strategy execution.
+
+**Response (healthy):**
+```json
+{
+  "success": true,
+  "strategyRuntime": {
+    "owner": "cron",
+    "cronEnabled": true,
+    "apiEngineStarted": false,
+    "healthy": true,
+    "staleAfterMs": 30000,
+    "isStale": false,
+    "lastSyncAt": "2026-02-14T19:11:22.123Z",
+    "lastStatus": "ok",
+    "lastError": null,
+    "syncCount": 42
+  }
+}
+```
+
+### Enable Strategy
+
+```http
+POST /strategies/:id/enable
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:manage`
+
+Enables a strategy.
+
+**Response:**
+```json
+{
+  "success": true,
+  "enabled": true,
+  "owner": "cron-runtime"
+}
+```
+
+### Disable Strategy
+
+```http
+POST /strategies/:id/disable
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:manage`
+
+Disables a strategy.
+
+**Response:**
+```json
+{
+  "success": true,
+  "enabled": false,
+  "owner": "cron-runtime"
+}
+```
+
+### Toggle Strategy (Compatibility)
+
+```http
+POST /strategies/:id/toggle
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:manage`
+
+Compatibility endpoint that flips current enabled state.
+
+### Get Strategy Config
+
+```http
+GET /strategies/:id/config
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:read`
+
+Returns the effective config (manifest defaults merged with overrides).
+
+**Response:**
+```json
+{
+  "success": true,
+  "config": { "amount": "0.05", "interval": "daily" },
+  "manifest": { "amount": "0.01", "interval": "daily" },
+  "overrides": { "amount": "0.05" }
+}
+```
+
+### Update Strategy Config
+
+```http
+PUT /strategies/:id/config
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "amount": "0.05"
+}
+```
+
+Permission: `strategy:manage`
+
+Sets config overrides. Request body is merged on top of manifest defaults.
+
+**Response:**
+```json
+{
+  "success": true,
+  "config": { "amount": "0.05", "interval": "daily" }
+}
+```
+
+### Approve/Reject Pending Intents
+
+```http
+POST /strategies/:id/approve
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "approvalId": "approval-123",
+  "approved": true
+}
+```
+
+Permission: `strategy:manage`
+
+Resolves pending approval records (`strategy:approve` or `strategy:install:approve`). Set `approved` to `false` to reject.
+
+### Get Strategy State (Debug)
+
+```http
+GET /strategies/:id/state
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:read`
+
+Returns internal strategy state and pending approvals for debugging.
+
+**Response:**
+```json
+{
+  "success": true,
+  "state": { "lastPrice": "3200.50", "positions": [] },
+  "pendingApprovals": []
+}
+```
+
+### Strategy Action History
+
+```http
+GET /strategies/history
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:read`
+
+Query params:
+- `strategyId`: Filter by strategy ID
+- `limit`: Max results (default 50, max 250)
+- `offset`: Pagination offset
+
+Returns strategy events from the Event table (all events with `strategy:*` type prefix).
+
+### Reload Runtime Metadata
+
+```http
+POST /strategies/reload
+Authorization: Bearer <token>
+```
+
+Permission: `strategy:manage`
+
+Returns runtime reload metadata. DB-backed strategy rows remain the source of truth.
+
+---
+
+## Error Responses
+
+All endpoints return JSON with `success` field:
+
+```json
+{
+  "success": false,
+  "error": "Error message here"
+}
+```
+
+Common HTTP status codes:
+- `401` - Unauthorized (missing/invalid token)
+- `403` - Forbidden (vault locked, insufficient permissions)
+- `404` - Not found
+- `400` - Bad request (validation error)
+
+---
+
+## Frontend API Client
+
+Use the unified `api` helper from `@/lib/api` for all frontend API calls:
+
+```typescript
+import { api, Api } from '@/lib/api';
+
+// Wallet operations (Express :4242)
+const wallets = await api.get(Api.Wallet, '/wallets');
+await api.post(Api.Wallet, '/send', { from, to, amount }); // amount in wei or lamports
+await api.post(Api.Wallet, '/swap', { from, token, direction, amount });
+
+// Workspace operations (Next.js :4747)
+const workspaces = await api.get(Api.Workspace, '/workspace');
+await api.post(Api.Workspace, '/workspace', { name: 'My Workspace' });
+
+// Events (Next.js :4747)
+const events = await api.get(Api.Events, '/events', { limit: 50, category: 'auth' });
+
+// Agent dashboard (Next.js :4747)
+const dashboard = await api.get(Api.AgentDashboard, '/agent-requests');
+```
+
+### Api Enum
+
+| Target | Backend | Purpose |
+|--------|---------|---------|
+| `Api.Wallet` | Express `:4242` | Wallet operations, auth, agents, transactions |
+| `Api.Workspace` | Next.js `:4747/api` | Workspace CRUD, app management |
+| `Api.Events` | Next.js `:4747/api` | Event logs from database |
+| `Api.AgentDashboard` | Next.js `:4747/api` | Agent dashboard (requests + tokens) |
+
+### Available Methods
+
+- `api.get<T>(target, path, params?)` - GET request with optional query params
+- `api.post<T>(target, path, body?)` - POST request with optional body
+- `api.put<T>(target, path, body?)` - PUT request with optional body
+- `api.patch<T>(target, path, body?)` - PATCH request with optional body
+- `api.delete<T>(target, path)` - DELETE request
+
+The helper automatically:
+- Adds Bearer token from sessionStorage
+- Constructs the correct base URL based on target
+- Parses JSON responses and handles errors
+
+---
+
+## Next.js API Endpoints
+
+UI-specific endpoints on `:4747`:
+
+### Workspace
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/workspace` | List all workspaces |
+| POST | `/api/workspace` | Create workspace |
+| GET | `/api/workspace/:id` | Get workspace by ID |
+| PUT | `/api/workspace/:id` | Update workspace |
+| DELETE | `/api/workspace/:id` | Delete workspace |
+| GET | `/api/workspace/:id/apps` | List apps in workspace |
+| POST | `/api/workspace/:id/apps` | Add app to workspace |
+| PATCH | `/api/workspace/:id/apps/:wid` | Update app |
+| DELETE | `/api/workspace/:id/apps/:wid` | Remove app |
+| GET | `/api/workspace/:id/export` | Export workspace config |
+| POST | `/api/workspace/import` | Import workspace config |
+| GET | `/api/workspace/config` | Get global app config (chain overrides) |
+| POST | `/api/workspace/config` | Update global app config |
+
+#### App Config (`/api/workspace/config`)
+
+Global application configuration including RPC chain overrides.
+
+**GET** - Returns current config:
+```json
+{
+  "success": true,
+  "config": {
+    "chainOverrides": {
+      "base": { "rpc": "https://custom-rpc.com", "chainId": 8453, "explorer": "https://basescan.org" }
+    }
+  }
+}
+```
+
+**POST** - Update chain overrides:
+```json
+{
+  "chainOverrides": {
+    "base": { "rpc": "https://custom-rpc.com", "chainId": 8453, "explorer": "https://basescan.org" },
+    "zksync": { "rpc": "https://mainnet.era.zksync.io", "chainId": 324, "explorer": "https://explorer.zksync.io" }
+  }
+}
+```
+
+RPC resolution order: Custom override > Alchemy key (if configured) > Public fallback.
+
+### Events
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/events` | Query events from database |
+| POST | `/api/events` | Webhook for Express to broadcast events |
+
+#### GET /api/events
+
+Query parameters:
+- `type`: Filter by exact event type (e.g., `action:created`)
+- `category`: Filter by category prefix (e.g., `auth` matches `auth:*`)
+- `limit`: Max results (default 50, max 250)
+- `offset`: Pagination offset
+
+Response:
+```json
+{
+  "success": true,
+  "events": [
+    {
+      "id": "cuid123",
+      "type": "auth:unlocked",
+      "source": "express",
+      "data": { "description": "Wallet unlocked: 0x123..." },
+      "timestamp": "2024-02-01T12:00:00.000Z"
+    }
+  ],
+  "pagination": {
+    "total": 100,
+    "limit": 50,
+    "offset": 0,
+    "hasMore": true
+  }
+}
+```
+
+### Agent Keys
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/agent-requests` | Get pending actions and tokens |
+
+Proxies to Express `/dashboard` endpoint. Returns:
+- Pending approval requests
+- Active tokens (including admin tokens with `isAdmin: true`)
+- Inactive tokens (expired, revoked, or depleted)